Finish v4 cleanup and remove obsolete compatibility paths

Remove superseded pre-v4 state and rendering layers, preserve current v4 recovery semantics, and align generated contracts and guidance around one coherent architecture.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: uburuntu

.githooks/pre-push

@@ -42,28 +42,14 @@ check "CHANGELOG has VERSION entry" bash -c '
     grep -q "## \[$VERSION\]" CHANGELOG.md
 '
 
-check "App links match (template ↔ apps.json)" python3 -c "
-import json, re, sys
-def extract_template(p):
-    return sorted(set(re.findall(r'https://(?:play\.google\.com|apps\.apple\.com|github\.com/\S+/releases)[^\s\"<]*', open(p).read())))
-def extract_json(p):
-    return sorted(set(item['url'] for item in json.load(open(p)) if re.match(r'https://(?:play\.google\.com|apps\.apple\.com|github\.com/)', item['url'])))
-t = extract_template('src/meridian/templates/connection-info.html.j2')
-d = extract_json('website/src/data/apps.json')
-if t != d:
-    print(f'Template: {t}')
-    print(f'Data:     {d}')
-    sys.exit(1)
-"
+check "PWA app metadata matches apps.json" python3 tests/validate_apps_sync.py
 
 # --- Shell scripts ---
 
 if command -v shellcheck &>/dev/null; then
     check "shellcheck install.sh" shellcheck -e SC2086,SC2029,SC2087,SC2155 -S warning install.sh
-    check "shellcheck setup.sh" shellcheck -e SC2086,SC2029,SC2087,SC2155 -S warning setup.sh
 else
     check "bash -n install.sh" bash -n install.sh
-    check "bash -n setup.sh" bash -n setup.sh
 fi
 
 # --- Python quality (requires uv + dev deps) ---
@@ -72,7 +58,7 @@ if command -v uv &>/dev/null; then
     check "ruff check" uv run ruff check src/ tests/
     check "ruff format" uv run ruff format --check src/ tests/
     check "mypy" uv run mypy src/meridian/
-    check "pytest" uv run pytest tests/ -q --tb=line --ignore=tests/test_integration_3xui.py
+    check "pytest" uv run pytest tests/ -q --tb=line
     check "templates render" uv run python tests/render_templates.py
 else
     echo "  ${DIM}(uv not found — skipping Python checks)${RESET}"

.github/CODEOWNERS

@@ -2,11 +2,12 @@
 * @uburuntu
 
 # High-risk files — extra scrutiny
-# Connection info templates (must stay in sync)
+# Connection page templates
 src/meridian/templates/ @uburuntu
 
-# Credential handling (security-sensitive)
-src/meridian/credentials.py @uburuntu
+# Cluster state and secret handling (security-sensitive)
+src/meridian/cluster.py @uburuntu
+src/meridian/cluster_persistence.py @uburuntu
 src/meridian/ssh.py @uburuntu
 
 # Provisioner (server deployment logic)

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -26,7 +26,7 @@ body:
       label: Setup mode
       options:
         - Standalone (no domain)
-        - Domain mode (with Caddy + HAProxy)
+        - Domain mode (nginx + Cloudflare CDN)
         - Uninstall
         - "Not sure"
     validations:

.github/PULL_REQUEST_TEMPLATE.md

@@ -12,18 +12,18 @@
 - [ ] `make ci` passes locally
 - [ ] Updated relevant documentation surfaces (see below)
 
-### If modifying connection info templates:
-- [ ] All connection-info templates are in sync (CSS/JS/app links)
+### If modifying connection pages:
+- [ ] PWA templates, assets, and app metadata are in sync
 - [ ] Tested light and dark mode
 
 ### If adding a new CLI command:
 - [ ] Added help smoke test in `tests/test_cli.py`
 - [ ] Updated README.md commands table
 - [ ] Updated CLAUDE.md subcommands list
 
-### If modifying credential handling:
-- [ ] Tested with existing credential files (backward compat)
-- [ ] Updated `ServerCredentials` dataclass if needed
+### If modifying cluster state or secrets:
+- [ ] Tested loading and saving an existing v4 `cluster.yml`
+- [ ] Updated the relevant typed cluster model
 
 ### If modifying provisioner steps:
 - [ ] Step returns proper StepResult (ok/changed/skipped/failed)

.github/workflows/CLAUDE.md

@@ -4,7 +4,7 @@
 
 **Two-stage pipeline** — CI validates on every push/PR. Release triggers only on CI success on main via `workflow_run`. Prevents accidental releases from failed builds.
 
-**CI jobs**: Python Tests (3.10 + 3.12 matrix), Lint, Type Check, Validate (templates + app links + VERSION + CHANGELOG + deploy CLI flags + PWA demo), Shell (shellcheck), System Lab (multi-node Docker deploy), Website Build.
+**CI jobs**: Python Tests (3.11–3.13 matrix), Lint, Type Check, Validate (PWA rendering + app metadata + VERSION + CHANGELOG + deploy CLI flags), Shell (shellcheck), System Lab (multi-node Docker deploy), Website Build.
 
 **Website package manager** — website CI uses pnpm with `website/pnpm-lock.yaml`; keep supply-chain guardrails in `website/pnpm-workspace.yaml`.
 
@@ -14,7 +14,7 @@
 
 ## What's done well
 
-- **Validate job** — single job checks templates render, app links match across surfaces, VERSION is valid semver, CHANGELOG has an entry, deploy CLI flags are documented in cli-reference.md. Catches drift between docs and code.
+- **Validate job** — single job checks the PWA renders, app metadata matches across surfaces, VERSION is valid semver, CHANGELOG has an entry, and deploy CLI flags are documented in cli-reference.md. Catches drift between docs and code.
 - **System lab depends on lint+test** — syntax must be clean before spinning up Docker. Saves CI minutes on obvious failures.
 - **PWA demo validation** — CI generates a demo PWA page and verifies all required files exist, SW is disabled for static hosting, and client HTML renders correctly.
 - **Contract drift checks** — Python validate runs `scripts/export_contracts.py --check`; website build runs `pnpm run contracts:check`.

.github/workflows/ci.yml

@@ -86,28 +86,6 @@ jobs:
           pip install jinja2
           python3 tests/render_templates.py
 
-      - name: Verify connection-info app links match website data
-        run: |
-          python3 -c "
-          import json, re, sys
-          template = 'src/meridian/templates/connection-info.html.j2'
-          data_file = 'website/src/data/apps.json'
-          def extract_links(path):
-              content = open(path).read()
-              return sorted(set(re.findall(r'https://(?:play\.google\.com|apps\.apple\.com|github\.com/\S+/releases)[^\s\"<]*', content)))
-          def extract_json_links(path):
-              data = json.load(open(path))
-              return sorted(set(item['url'] for item in data if re.match(r'https://(?:play\.google\.com|apps\.apple\.com|github\.com/)', item['url'])))
-          baseline = extract_links(template)
-          data_links = extract_json_links(data_file)
-          if data_links != baseline:
-              print(f'MISMATCH between template and website/src/data/apps.json')
-              print(f'  Template: {baseline}')
-              print(f'  Data:     {data_links}')
-              sys.exit(1)
-          print(f'OK: App download links match between template and apps.json')
-          "
-
       - name: Verify VERSION file format
         run: |
           VERSION=$(cat VERSION | tr -d '[:space:]')
@@ -148,14 +126,10 @@ jobs:
       - uses: actions/checkout@v5
 
       - name: Check script syntax
-        run: |
-          bash -n install.sh
-          bash -n setup.sh
+        run: bash -n install.sh
 
       - name: Shellcheck
-        run: |
-          shellcheck -e SC2086,SC2029,SC2087,SC2155 -S warning install.sh
-          shellcheck -e SC2086,SC2029,SC2087,SC2155 -S warning setup.sh
+        run: shellcheck -e SC2086,SC2029,SC2087,SC2155 -S warning install.sh
 
   system-lab:
     name: System Lab
@@ -210,7 +184,6 @@ jobs:
 
       - name: Validate PWA demo generation
         run: |
-          sudo apt-get install -y qrencode
           uv run meridian dev preview --output website/dist/demo
           # Verify expected files exist
           test -f website/dist/demo/index.html

.github/workflows/release.yml

@@ -52,19 +52,16 @@ jobs:
         uses: astral-sh/setup-uv@v7
 
       - name: Generate PWA demo page
-        run: |
-          sudo apt-get install -y qrencode
-          uv run meridian dev preview --output website/dist/demo
+        run: uv run meridian dev preview --output website/dist/demo
 
-      - name: Add deploy artifacts
+      - name: Add website artifacts
         run: |
-          # Copy CLI files into Astro dist
+          # Copy the CLI installer into Astro dist
           cp install.sh website/dist/install.sh
-          cp setup.sh website/dist/setup.sh
           cp VERSION website/dist/version
           # Generate checksums
           cd website/dist
-          sha256sum install.sh setup.sh > SHA256SUMS
+          sha256sum install.sh > SHA256SUMS
           cd ../..
           # Bundle AI docs
           mkdir -p website/dist/ai

.gitignore

@@ -30,7 +30,6 @@ src/meridian/data/ai-reference.md
 
 # GitHub Pages build artifacts (generated by deploy workflow)
 docs/install.sh
-docs/setup.sh
 docs/version
 docs/SHA256SUMS
 docs/ai/reference.md

AGENTS.md

@@ -22,10 +22,12 @@ src/meridian/CLAUDE.md                  — Python CLI architecture
   panel_bootstrap.py                    — panel setup, node deploy, xray config
   relay_ops.py                          — relay infrastructure operations
   ssh_keys.py                           — host key utilities (shared by ssh.py + engine)
-  core/defaults.py                      — core-owned constants (DEFAULT_SNI)
-  core/errors.py                        — shared error base types
+  core/CLAUDE.md                        — transport-neutral API contracts
+    defaults.py                         — core-owned constants (DEFAULT_SNI)
+    errors.py                           — shared error base types
   commands/CLAUDE.md                    — per-subcommand pattern
     wizard.py                           — interactive deploy wizard
+  diagnostics/CLAUDE.md                 — reusable server health checks
   engine/CLAUDE.md                      — local Engine use-case boundary
     routes.py                           — FastAPI route handlers
   provision/CLAUDE.md                   — step pipeline + idempotency
@@ -55,13 +57,13 @@ CLAUDE.md files. All of these are enforced in code review.
 - **Demo data**: use RFC 5737 IPs (`198.51.100.x`) in tests, examples, and docs. Never real IPs.
 - **Privacy**: no real names, server IPs, or domains in commits, code, or public docs unless the user explicitly asks.
 - **Self-hosted**: zero external HTTP requests at runtime from connection pages, CLI update checks aside. Target users are in regions that block CDNs.
-- **Commit per change**: one logical change per commit. Footer `Refs: uburuntu/meridian#NN` when resolving an issue.
+- **Commit per change**: one logical change per commit. Footer `Refs: getmeridian/meridian#NN` when resolving an issue.
 - **Ask before posting** anything public — GitHub issues, PR descriptions, comments, discussions. Always show the text first.
 
 ## Project management
 
 - High-level direction: [ROADMAP.md](ROADMAP.md)
-- Concrete trackable work: [GitHub issues](https://github.com/uburuntu/meridian/issues)
+- Concrete trackable work: [GitHub issues](https://github.com/getmeridian/meridian/issues)
 - Shipped history: [CHANGELOG.md](CHANGELOG.md)
 - Security policy: [SECURITY.md](SECURITY.md)
 - Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)

CHANGELOG.md

@@ -4,17 +4,7 @@ All notable changes to Meridian are documented here.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
-## [Unreleased]
-
-### Added
-- **meridian-core JSON contract foundation** — Pydantic-backed `meridian.output/v1` envelopes, structured summary/error/event models, JSONL event primitives, JSON Schema export, and centralized secret redaction for automation and future UI clients
-- **`meridian api schemas` / `meridian api schema NAME`** — discover and export JSON Schemas for the public meridian-core contracts used by CLI JSON output and future UI clients
-
-### Changed
-- **`meridian plan --json`** now emits the shared envelope shape with plan details under `data`; `status` is `no_changes` or `changed`, and the process exit code remains `0` for converged and `2` for changes pending
-- **`meridian fleet status --json`** and **`meridian fleet inventory --json`** now emit the shared envelope shape while preserving stable command fields under `data`
-
-## [4.0.0] - 2026-04-12
+## [4.0.0] - Unreleased
 
 ### Remnawave compatibility matrix
 This release pins a single tested version tuple. Upgrading any one component
@@ -24,43 +14,51 @@ without the rest is not supported — move the whole set together.
 |---|---|
 | `remnawave/backend` | `2.7.4` |
 | `remnawave/node` | `2.7.0` |
-| `remnawave/subscription-page` | `7.1.8` |
+| `remnawave/subscription-page` | `7.2.1` |
 | `remnawave` Python SDK | `2.7.1` |
 | Xray-core client (test binary) | `26.3.27` |
 | Realm (relay forwarder) | `2.9.3` |
 | Pebble (system-lab ACME CA) | `2.10.0` |
 
 ### Changed
+- **`meridian plan --json`** now emits the shared envelope shape with plan details under `data`; `status` is `no_changes` or `changed`, and the process exit code remains `0` for converged and `2` for changes pending
+- **`meridian fleet status --json`** and **`meridian fleet inventory --json`** now emit the shared envelope shape while preserving stable command fields under `data`
 - **Remnawave replaces 3x-ui** — modern panel with panel/node separation (NestJS + PostgreSQL + Valkey), proper REST API, built-in subscriptions, native multi-node support
 - **Single `cluster.yml` replaces per-server `proxy.yml`** — fleet-wide manifest with panel URL, API token, nodes, relays. Client state lives in Remnawave's database, not locally
 - **`client add` is one API call** — was ~400 LOC of SSH-tunneled curl, credential sync, and per-inbound client insertion
 - **Relay = Remnawave Host entry** — enable/disable host toggles subscription inclusion automatically
 
 ### Added
+- **meridian-core JSON contract foundation** — Pydantic-backed `meridian.output/v1` envelopes, structured summary/error/event models, JSONL event primitives, JSON Schema export, and centralized secret redaction for automation and future UI clients
+- **`meridian api schemas` / `meridian api schema NAME`** — discover and export JSON Schemas for the public meridian-core contracts used by CLI JSON output and future UI clients
 - **`meridian node add/list/remove/check`** — multi-node fleet management
 - **`meridian fleet status/recover`** — panel health, node connectivity, relay status, user count, and reconstruct-from-panel when local state is lost
-- **`meridian migrate`** — guided migration from 3.x (reads old proxy.yml, prints step-by-step plan)
 - **`MeridianPanel` REST client** — wraps the official `remnawave` Python SDK (v2.7.1) with retries, credential redaction, and thread-local event loops for parallel workers
 - **Config reliability** — corrupt YAML handling, version check, backup before mutations, disk-full error messages, external-edit guard (`cluster.save()` refuses to clobber if the file mtime advanced during a long-running apply), snapshot type validation
 - **Reality keys persisted** — public_key and short_id saved in cluster.yml for connection testing
 - **Declarative plan/apply workflow** — `cluster.yml` becomes desired state (`desired_nodes`, `desired_relays`, `desired_clients`, `subscription_page`); `meridian plan` prints a Terraform-style diff; `meridian apply` converges. Imperative commands (`deploy`, `node add`, `client add`) mirror their effect into `desired_*` when the list is non-null — hybrid sync, mixing the two modes is safe
-- **Applied-state tracking** — every successful `apply` snapshots desired state into `cluster._extra["desired_*_applied"]`. The next plan distinguishes intentional removals (in applied → executes under `--yes`) from drift (not in applied → requires `--prune-extras=yes`). Closes the subtle bug where `--yes` silently skipped deliberate removals
+- **Applied-state tracking** — every successful `apply` snapshots desired state into the typed `cluster.applied_state` model. The next plan distinguishes intentional removals (in applied → executes under `--yes`) from drift (not in applied → requires `--prune-extras=yes`). Closes the subtle bug where `--yes` silently skipped deliberate removals
 - **`meridian plan --json`** — structured output for CI consumption; exit 0 = converged, 2 = changes pending, 1 = error. Stable JSON shape with typed `actions[].kind` values
 - **`--prune-extras=ask|yes|no`** — explicit control over drift handling. Under `--yes`, `ask` downgrades to `no` (safety default); destructive actions still require one confirmation unless `--yes`
-- **Parallel node provisioning** — `ThreadPoolExecutor` with `--parallel N` (default 4); per-worker `MeridianPanel` SDK instance, `threading.local()` event loops, `threading.RLock` on `cluster.save()` for safe concurrent writes
+- **Parallel node provisioning** — `ThreadPoolExecutor` with `--parallel N` (default 4); per-worker `MeridianPanel` SDK instance, `threading.local()` event loops, and serialized cluster saves
 - **SSH multiplexing (`ControlMaster`)** — connection reuse across all SSH operations
 - **Warp tri-state** — `DesiredNode.warp: None | False | True` (keep-current / disable / enable) with correct YAML round-trip (explicit `null`, not dropped; loader defaults missing key to `None`)
 - **YAML null semantics** for `desired_*` and `subscription_page` — `null` means "unmanaged" (as documented); previously `desired_clients: null` collapsed to `[]` with `manage=True` and `subscription_page: null` loaded as `enabled=True`
 - **Duplicate node-name validator** — `compute_plan`'s name→IP map and `find_node()` disagreed on duplicates, which could misroute relay `exit_node` references. Caught at load time now
 - **Real-VM test harness** — optional `tests/realvm/` provisions real cloud VMs (Hetzner via `hcloud-python` SDK), runs full deploy + tier-α verification, tears down. Local-only (never in CI), opt-in via `make real-lab`. Foundation for a future `meridian deploy --create-vm <provider>` feature. Per-cloud `CloudProvider` abstract class under `src/meridian/infra/providers/`
 - **NET_ADMIN capability** on remnawave-node container — required by panel 2.6.2+ for Torrent Blocker, IP Control, and related plugins. Without it, those features silently no-op
 - **Subscription-page lifecycle via cluster.yml** — enable/disable the Remnawave subscription container declaratively; `docker compose up -d --no-recreate` on subpage-only apply to avoid incidental panel restart
+- **Hysteria2 UDP/443 fallback** — available after the TCP transports in subscription ordering, with matching host and firewall configuration
 - **`ConfigureFail2ban` + fail2ban package wired in both pipelines** — fail2ban is now actually installed and started on every hardened deploy. Previously `build_setup_steps` had an operator-precedence trap (`InstallPackages(REQUIRED_PACKAGES + ["fail2ban"] if harden else None)` parsed as `(REQUIRED + fail2ban) if harden else None`, skipping all packages on `--no-harden`) and `build_node_steps` (used for redeploy) lacked the step entirely
 - **Smart xray readiness polling** in system-lab — polls node API port 3010 + 5s grace for Reality inbound init, replacing a blind `sleep 30`
 
+### Fixed
+- **Safe fleet recovery** — recovered inbounds now use stable protocol keys and the current cluster schema; Reality public keys are derived from preserved private keys, and redeploy refuses incomplete key material instead of silently rotating credentials
+
 ### Removed
 - **3x-ui panel** — PanelClient, ConfigurePanel, CreateInbound, all SSH-tunneled curl API calls
-- **Per-server proxy.yml** — replaced by cluster.yml (kept only for `meridian migrate` compatibility)
+- **All pre-v4 migration and compatibility paths** — v4 starts from typed `cluster.yml` and `servers.json` state; the old migrate command, installer/setup shims, per-server `proxy.yml` credentials, legacy registry import, and 3x-ui cleanup step are gone
+- **Legacy local connection-page renderer** — the server-hosted PWA is the only connection-page implementation
 - **Local client state** — no more UUID storage, credential sync, SCP rollback
 - **Legacy HAProxy + Caddy code paths** — replaced entirely by nginx (stream SNI routing + http TLS + reverse proxy)