books: land the AI bookkeeper on /v1/books (native double-entry, per-org SQLite)

A native 'books' domain in the cloud one-binary — the ERPNext Accounts SEMANTICS ported to Go, NO Postgres/Formance/ERPNext-Python. Reads commerce /v1/billing/transactions (sole posting source, read-only) and books the double-entry twin; GAAP rev-rec (Customer Wallet = deferred-revenue liability, recognized at usage); accrual P&L + Balance Sheet + export; AI Ask brain (SaaS metrics: MRR/ARR/burn/runway) + clarifying questions; bank engine with PDF (rsc.io/pdf + foot-check reconciliation), OFX/CSV, Plaid, Teller + reconciliation. Exact int64 cents, per-org Base/SQLite, ~35 tests green (built blue/red/cto). Registered in apps.go beside treasury; adds rsc.io/pdf direct dep.
merge: analytics destination adapters (Umami + PostHog + GA4/Meta ecommerce)
2026-07-24 02:04:15 -07:00 · 2026-07-24 01:51:26 -07:00 · 2026-07-24 01:44:56 -07:00 · 2026-07-24 01:24:27 -07:00 · 2026-07-24 01:10:51 -07:00 · 2026-07-24 00:57:25 -07:00
815 changed files with 151671 additions and 7055 deletions
@@ -111,6 +111,28 @@ jobs:
            echo "GOPROXY=https://proxy.golang.org,direct"
          } >> "$GITHUB_ENV"

+      - name: zen streaming-fix floor — go.mod must pin github.com/hanzoai/zen >= v1.4.1
+        # The SSE body-close fix (zen commit 50328b8, first released in zen v1.4.1)
+        # is what makes streaming completions return a body instead of an empty
+        # stream. A stale-branch merge that reverts go.mod's zen pin below the floor
+        # silently re-breaks streaming, and `next build`'s ignoreBuildErrors hides
+        # the runtime break — so no image may be cut on a regressed pin. This is the
+        # durable root-cause guard: it reads the EFFECTIVE module version (post-MVS,
+        # exactly what the build links) and fails the PR/push below the floor.
+        run: |
+          set -euo pipefail
+          FLOOR="v1.4.1"
+          V="$(go list -m -f '{{.Version}}' github.com/hanzoai/zen)"
+          echo "effective github.com/hanzoai/zen = ${V} (floor ${FLOOR})"
+          # semver-correct compare: the lowest of {V, FLOOR} under `sort -V` must be
+          # the FLOOR, i.e. V >= FLOOR. (sort -V orders v1.4.2 above v1.4.10 too.)
+          low="$(printf '%s\n%s\n' "$V" "$FLOOR" | sort -V | head -1)"
+          if [ "$low" != "$FLOOR" ]; then
+            echo "::error::github.com/hanzoai/zen is pinned at ${V}, below the streaming-fix floor ${FLOOR} — this re-breaks SSE streaming (empty completions). Re-pin zen to >= ${FLOOR} in go.mod before merging."
+            exit 1
+          fi
+          echo "OK: zen ${V} is at or above the streaming-fix floor ${FLOOR}"
+
      - name: positive proof — clients/controlplane is unreachable from the default build
        run: |
          set -euo pipefail
@@ -124,20 +124,6 @@ jobs:
          echo "sha_short=$(git rev-parse --short "$GITHUB_SHA")" >> "$GITHUB_OUTPUT"
          echo "Next release: v${version} (git_max='${git_max:-none}' container_max='${cont_max:-none}')"

-          # Console-embed cachebust. The console clone+build layer is keyed on this;
-          # prefer hanzoai/console main HEAD so a CONSOLE-ONLY change re-embeds without
-          # needing a cloud commit (cloud-sha alone froze the embed between cloud pushes).
-          # git ls-remote must CLEAR the extraheader actions/checkout installs (it carries
-          # THIS repo's GITHUB_TOKEN, which 404s the cross-repo console lookup); gh is not
-          # on the runner. If resolution yields nothing, fall back to the cloud sha — still
-          # unique per cloud commit, so the embed is never frozen. Either way THIS build
-          # busts (new value) and re-clones console main fresh.
-          console_head="$(git -c 'http.https://github.com/.extraheader=' ls-remote \
-            "https://x-access-token:${GH_PAT}@github.com/hanzoai/console.git" refs/heads/main 2>/dev/null | cut -f1 || true)"
-          cachebust="${console_head:-$GITHUB_SHA}"
-          echo "cachebust=${cachebust}" >> "$GITHUB_OUTPUT"
-          echo "console cachebust: ${cachebust} (console_head='${console_head:-none}')"
-
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
        with:
@@ -160,8 +146,12 @@ jobs:
          # Direct credential first (repo/org secret — works on private repos,
          # where the Free plan hides org KMS secrets); KMS kubeconfig fallback.
          if [ -n "${REGISTRY_USER:-}" ] && [ -n "${REGISTRY_PASSWORD:-}" ]; then
-            echo "$REGISTRY_PASSWORD" | docker login registry.hanzo.ai -u "$REGISTRY_USER" --password-stdin
-            echo "MIRROR_OK=1" >> "$GITHUB_ENV"; exit 0
+            if echo "$REGISTRY_PASSWORD" | docker login registry.hanzo.ai -u "$REGISTRY_USER" --password-stdin; then
+              echo "MIRROR_OK=1" >> "$GITHUB_ENV"
+            else
+              echo "mirror login failed (registry.hanzo.ai unreachable) — mirror skipped, release continues"
+            fi
+            exit 0
          fi
          [ -z "${KMS_CLIENT_ID:-}" ] && { echo "no KMS creds — mirror skipped"; exit 0; }
          TOKEN=$(curl -sf "$KMS_ENDPOINT/v1/kms/auth/login" -H 'Content-Type: application/json'             -d "{\"clientId\":\"$KMS_CLIENT_ID\",\"clientSecret\":\"$KMS_CLIENT_SECRET\"}" | jq -r '.accessToken // empty')
@@ -180,8 +170,11 @@ jobs:
          UP=$(echo "$CFG" | jq -r '.auths["registry.hanzo.ai"].auth // empty' | base64 -d)
          [ -z "$UP" ] && { echo "no registry auth — mirror skipped"; exit 0; }
          echo "::add-mask::${UP#*:}"
-          echo "${UP#*:}" | docker login registry.hanzo.ai -u "${UP%%:*}" --password-stdin
-          echo "MIRROR_OK=1" >> "$GITHUB_ENV"
+          if echo "${UP#*:}" | docker login registry.hanzo.ai -u "${UP%%:*}" --password-stdin; then
+            echo "MIRROR_OK=1" >> "$GITHUB_ENV"
+          else
+            echo "mirror login failed (registry.hanzo.ai unreachable) — mirror skipped, release continues"
+          fi

      - name: Log in to ghcr.io (GH_PAT — writes the cloud package despite its ai-repo linkage)
        uses: docker/login-action@v3
@@ -190,6 +183,39 @@ jobs:
          username: hanzo-dev
          password: ${{ secrets.GH_PAT }}

+      - name: Resolve decomplection artifact digests (the Go-only build's prebuilt inputs)
+        id: artifacts
+        run: |
+          set -euo pipefail
+          # cloud compiles ONLY Go; it pulls three prebuilt artifacts (console SPA,
+          # agent-skills catalog, native flags staticlib). Resolve each published
+          # :latest to an IMMUTABLE digest so THIS release is reproducible (pinned,
+          # not floating :latest) AND a console/skills/flags change is picked up —
+          # its CI republished :latest, so this resolves to the NEW digest. A MISSING
+          # artifact FAILS the release HERE, before build/smoke/push/tag: the receipt
+          # invariant means we never tag an image that couldn't embed the real console.
+          command -v crane >/dev/null 2>&1 || {
+            mkdir -p "$HOME/.local/bin"
+            curl -fsSL "https://github.com/google/go-containerregistry/releases/latest/download/go-containerregistry_Linux_x86_64.tar.gz" \
+              | tar -xz -C "$HOME/.local/bin" crane
+          }
+          export PATH="$HOME/.local/bin:$PATH"
+          resolve() {
+            local repo="$1" d
+            d="$(crane digest "ghcr.io/hanzoai/${repo}:latest" 2>/dev/null || true)"
+            [ -n "$d" ] || { echo "::error::decomplection artifact ghcr.io/hanzoai/${repo}:latest is not published — refusing to cut a release that would embed a stale/placeholder ${repo}"; return 1; }
+            printf 'ghcr.io/hanzoai/%s@%s' "$repo" "$d"
+          }
+          CONSOLE_IMAGE="$(resolve console-embed)" || exit 1
+          SKILLS_IMAGE="$(resolve agent-skills)" || exit 1
+          FLAGS_IMAGE="$(resolve cloud-flags)" || exit 1
+          {
+            echo "console_image=${CONSOLE_IMAGE}"
+            echo "skills_image=${SKILLS_IMAGE}"
+            echo "flags_image=${FLAGS_IMAGE}"
+          } >> "$GITHUB_OUTPUT"
+          echo "resolved: console=${CONSOLE_IMAGE} skills=${SKILLS_IMAGE} flags=${FLAGS_IMAGE}"
+
      - name: OCI labels
        id: meta
        uses: docker/metadata-action@v5
@@ -216,11 +242,13 @@ jobs:
          load: true
          tags: cloud:smoke
          labels: ${{ steps.meta.outputs.labels }}
-          # Bust the console clone+build layer every release (the cloud commit sha is
-          # unique per push) so the embed re-fetches console main HEAD fresh — never the
-          # frozen snapshot the persistent BuildKit cache would otherwise serve forever.
+          # cloud compiles ONLY Go: pull the three prebuilt artifacts pinned to the
+          # digests resolved above (reproducible, and fresh — a console/skills/flags
+          # change is a new digest). No node/python/rust toolchain in this build.
          build-args: |
-            CONSOLE_CACHEBUST=${{ steps.ver.outputs.cachebust }}
+            CONSOLE_IMAGE=${{ steps.artifacts.outputs.console_image }}
+            SKILLS_IMAGE=${{ steps.artifacts.outputs.skills_image }}
+            FLAGS_IMAGE=${{ steps.artifacts.outputs.flags_image }}
          # GIT_AUTH_TOKEN: BuildKit secret the Dockerfile consumes to fetch private
          # cross-org Go modules (hanzoai/*, luxfi/*) over authenticated git.
          secrets: |
@@ -462,10 +490,12 @@ jobs:
            ghcr.io/hanzoai/cloud:sha-${{ steps.ver.outputs.sha_short }}
            ghcr.io/hanzoai/cloud:latest
          labels: ${{ steps.meta.outputs.labels }}
-          # SAME cachebust as the smoke build → every layer is a cache hit from step 1
-          # and the pushed image is byte-identical to the one the smoke test proved.
+          # SAME artifact digests as the smoke build → every layer is a cache hit from
+          # step 1 and the pushed image is byte-identical to the one smoke proved.
          build-args: |
-            CONSOLE_CACHEBUST=${{ steps.ver.outputs.cachebust }}
+            CONSOLE_IMAGE=${{ steps.artifacts.outputs.console_image }}
+            SKILLS_IMAGE=${{ steps.artifacts.outputs.skills_image }}
+            FLAGS_IMAGE=${{ steps.artifacts.outputs.flags_image }}
          secrets: |
            GIT_AUTH_TOKEN=${{ secrets.GH_PAT }}

@@ -499,12 +529,25 @@ jobs:
            # newest-first and version tags are monotonic, so the highest version
            # is always among the most-recent versions; paginating the WHOLE
            # registry history is what livelocked this step as tags accumulated.
+            # Fail-CLOSED. An ORPHANED container tag — image pushed by a run that
+            # died or was cancelled after imagetools-create but before its git tag —
+            # MUST raise the floor, or a later run reassigns that same number to a
+            # different image (an ambiguous mutable prod tag; the v1.801.50 flip). A
+            # git-only floor can't see the orphan, so if the container-tag lookup
+            # ERRORS (vs legitimately returning no tags) we retry the whole attempt
+            # rather than silently proceeding — a version with a pushed image is never
+            # reused. (Reordering git-tag before imagetools-create is the WRONG fix: it
+            # reintroduces the phantom "tag ⇔ no image" this workflow exists to prevent.)
            cont_max=""
            if command -v gh >/dev/null 2>&1; then
-              cont_max="$(GH_TOKEN="$GH_PAT" gh api \
-                '/orgs/hanzoai/packages/container/cloud/versions?per_page=100' \
-                --jq '.[].metadata.container.tags[]?' 2>/dev/null \
-                | sed 's/^v//' | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1 || true)"
+              if cont_raw="$(GH_TOKEN="$GH_PAT" gh api \
+                  '/orgs/hanzoai/packages/container/cloud/versions?per_page=100' \
+                  --jq '.[].metadata.container.tags[]?' 2>/dev/null)"; then
+                cont_max="$(printf '%s\n' "$cont_raw" \
+                  | sed 's/^v//' | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1 || true)"
+              else
+                echo "  container-tag lookup failed — retry so an orphaned tag can't be reused (attempt $attempt)"; sleep 3; continue
+              fi
            fi
            max="$(printf '%s\n%s\n%s\n' "1.786.0" "$git_max" "$cont_max" \
              | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)"
@@ -534,8 +577,12 @@ jobs:
                export PATH="$HOME/.local/bin:$PATH"
              }
              for MT in "${V}" "${VER}" "${major}.${minor}"; do
-                crane copy "$SHA_IMG" "registry.hanzo.ai/hanzoai/cloud:${MT}" \
-                  || echo "::warning::mirror registry.hanzo.ai/hanzoai/cloud:${MT} failed"
+                # Bounded: registry.hanzo.ai can *hang* (not just fail), and this
+                # is best-effort — an unbounded crane copy once livelocked the whole
+                # tag step and held the serialized release lane. timeout makes the
+                # mirror truly best-effort so the git-tag receipt below always runs.
+                timeout 120 crane copy "$SHA_IMG" "registry.hanzo.ai/hanzoai/cloud:${MT}" \
+                  || echo "::warning::mirror registry.hanzo.ai/hanzoai/cloud:${MT} failed or timed out"
              done
            fi
            git tag -a "$V" -m "release $V — image ghcr.io/hanzoai/cloud:$V (retagged from sha-${{ steps.ver.outputs.sha_short }}, smoke-passed ${GITHUB_SHA})"
@@ -552,9 +599,86 @@ jobs:
          echo "::error::could not acquire a free version tag after 8 attempts"
          exit 1

-  # Deploy = a declared-tag bump in hanzoai/universe crs/cloud.yaml — Hanzo CD
-  # (the ArgoCD instance in ns hanzo-cd) syncs universe→cluster and the operator
-  # reconciles the CR. The old notify-universe repository_dispatch hub is retired
-  # (its flagged-sender dispatches were silently suppressed anyway); the native
-  # release path (release.go rolloutRelease) and deliberate promote commits own
-  # the bump.
+  # ── Promote: the declared-tag bump that makes the release DEPLOY ─────────────
+  # The tag minted above is the receipt for a pushed, smoke-passed image; THIS job
+  # records it as the desired state Hanzo CD reconciles. The universe-crs ArgoCD
+  # Application (ns hanzo-cd, `automated` sync + selfHeal) syncs
+  # infra/k8s/operator/crs/*.yaml → cluster and the operator rolls the Deployment,
+  # so a tag bump committed here reaches api.hanzo.ai with NO hand-dispatch and NO
+  # hand-edit of the CR.
+  #
+  # This is the SAME yq-bump → `deploy(<svc>): <tag>` universe commit the hanzoai/ci
+  # reusable (build.yml deploy step) does for every other service. cloud owns it
+  # HERE because its image is built by this workflow, not the ci reusable — its
+  # hanzo.yml carries no main `images:` entry and `# NO deploy`, so the shared
+  # deploy step never bumps cloud's CR. A direct in-cluster CR patch is NOT enough:
+  # ArgoCD selfHeal reverts any live edit not also recorded in git within ~45s.
+  # The retired notify-universe repository_dispatch had no receiver after the
+  # image-update.yml deploy hub was deleted in the Hanzo CD cutover; the git commit
+  # IS the sanctioned path now.
+  promote:
+    needs: build-amd64
+    # Only a real release promotes: build+smoke+push+tag all succeeded, so a
+    # proven v* image exists. A failure earlier leaves version_v empty → skipped.
+    if: ${{ needs.build-amd64.outputs.version_v != '' }}
+    runs-on: [hanzo-build-linux-amd64]
+    steps:
+      - name: Record the proven tag in universe crs/cloud.yaml (Hanzo CD rolls it)
+        env:
+          # GH_PAT already pushes this repo's git tags above (contents:write on the
+          # hanzoai org), so it writes hanzoai/universe too — the SAME token the ci
+          # reusable falls back to for the universe deploy commit.
+          GH_PAT: ${{ secrets.GH_PAT }}
+          VERSION_V: ${{ needs.build-amd64.outputs.version_v }}
+        run: |
+          set -euo pipefail
+          [ -n "${GH_PAT:-}" ] || { echo "::error::no GH_PAT — cannot record the declared-tag bump in universe"; exit 1; }
+
+          # Bare arc runners ship no yq — provision the static binary (sudo-free,
+          # same pattern the ci reusable and this workflow's kubectl/crane fetches use).
+          if ! command -v yq >/dev/null 2>&1; then
+            mkdir -p "$HOME/.local/bin"; export PATH="$HOME/.local/bin:$PATH"
+            curl -fsSL https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 \
+              -o "$HOME/.local/bin/yq" && chmod +x "$HOME/.local/bin/yq"
+          fi
+
+          git clone -q --depth 1 \
+            "https://x-access-token:${GH_PAT}@github.com/hanzoai/universe.git" \
+            "$RUNNER_TEMP/universe"
+          CR="$RUNNER_TEMP/universe/infra/k8s/operator/crs/cloud.yaml"
+          [ -f "$CR" ] || { echo "::error::crs/cloud.yaml not found in universe"; exit 1; }
+
+          CUR="$(yq -r '.spec.image.tag // ""' "$CR")"
+          echo "cloud CR: ${CUR:-<empty>} → ${VERSION_V}"
+
+          # Monotonic guard: never roll the CR BACKWARD. Release runs finish under a
+          # serialized lane but a slow older run must never overwrite a newer promote.
+          # Skip iff the CR already holds a semver >= the version we just cut.
+          CURN="${CUR#v}"; NEWN="${VERSION_V#v}"
+          if printf '%s' "$CURN" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+            top="$(printf '%s\n%s\n' "$CURN" "$NEWN" | sort -V | tail -1)"
+            if [ "$top" = "$CURN" ] && [ "$CURN" != "$NEWN" ]; then
+              echo "::notice::cloud CR already at v${CURN} (≥ ${VERSION_V}) — not rolling back"; exit 0
+            fi
+          fi
+
+          yq -i ".spec.image.tag = \"${VERSION_V}\"" "$CR"
+          if git -C "$RUNNER_TEMP/universe" diff --quiet; then
+            echo "::notice::crs/cloud.yaml already at ${VERSION_V} — nothing to record"; exit 0
+          fi
+          git -C "$RUNNER_TEMP/universe" -c user.name=hanzo-ci -c user.email=dev@hanzo.ai \
+            commit -qam "deploy(cloud): ${VERSION_V} (${GITHUB_REPOSITORY}@$(echo "${GITHUB_SHA}" | cut -c1-7))"
+
+          # Rebase-safe push: universe main advances on every service's deploy, so a
+          # concurrent commit must not make cloud's promote lose the whole roll. Retry
+          # a few times, rebasing between attempts.
+          for attempt in $(seq 1 5); do
+            if git -C "$RUNNER_TEMP/universe" push -q origin HEAD:main; then
+              echo "recorded deploy(cloud): ${VERSION_V} — Hanzo CD (universe-crs) will roll it to api.hanzo.ai"
+              exit 0
+            fi
+            echo "  universe push lost the race — rebasing (attempt ${attempt})"
+            git -C "$RUNNER_TEMP/universe" pull -q --rebase origin main || true
+            sleep 3
+          done
+          echo "::error::could not record the cloud tag bump in universe after 5 attempts"; exit 1
@@ -13,6 +13,14 @@
 coverage.txt
 coverage.html

+# cek encryption sidecars are key material — never commit one from a source tree.
+# Tests seal their stores under t.TempDir(); a sidecar in a package dir (e.g. from a
+# test that opened ":memory:") is a mistake. The cek testdata fixtures are the one
+# intentional exception.
+*.dek
+*.cek.lock
+!cek/testdata/**
+
 # Environment files
 .env
 .env.*
@@ -34,4 +42,5 @@ Thumbs.db
 .shots/

 .claude/
+.worktrees/
 native/flags/target
@@ -6,6 +6,87 @@ artifact serves `api.hanzo.ai`, `api.lux.cloud`, `api.zoo.cloud`, `api.osage.clo
 and every white-label reseller. Brand, enabled subsystems, and org scope are
 deployment configuration.

+## Open Cloud planes
+
+Spec home: HIP-0129 `hip-0129-open-cloud-planes` (hips repo). This section is a
+map, not the spec. One noun, one owner, one route family. No plane reads another
+plane's store; imports flow custody-ward only (channels -> integrations, never
+reverse).
+
+| Route | Noun | Owner | Tier |
+| --- | --- | --- | --- |
+| `/v1/connectors` | Custody: per-user BYO external accounts | `clients/integrations` (extends; user scope new) | In flight (branch `feat/connectors`) |
+| `/v1/channels` | Transport: portable message envelope, DM pairing, send + inbox | `clients/channels` (new) | Planned (branch `feat/channels` reserved; no transport code yet) |
+| `/v1/sync` | Data: bidirectional sync engine | `clients/sync` | Shipped |
+| `/v1/automations` | Workflows: flows/runs, goja piece runtime | `clients/automations` | Shipped |
+| `/v1/compute/bots` | Hosting: `@hanzo/bot` Node containers | `clients/bots` | Shipped |
+| `/v1/tasks` | Durable engine | `clients/tasks` | Shipped |
+| `/v1/gpus` + fleet | BYO GPU presence | `clients/fleet` + `clients/visor` | Shipped |
+| `/v1/cloud` | Cloud accounts: link DO/AWS/GCP/Azure, discover native k8s clusters, fold into the fleet | `clients/venue` (new) | In flight (branch `feat/cloud-account-connectors`; blue-held for red) |
+| IAM | Identity: users, orgs, roles | IAM | Shipped |
+| KMS | Secret custody: sealed secrets | `clients/kms` | Shipped |
+
+Custody invariants: secrets sealed in KMS at
+`/orgs/{org}/users/{user}/connectors/{provider}/{label}`, never in SQLite rows;
+verify before store. Refresh is single-flight with rotation resealing; the CLI
+does local browser PKCE and posts the bundle to
+`POST /v1/connectors/:provider/credential`; cloud owns device-code flows.
+
+Transport invariants: typed actions (`command|url|select|approval`), no raw
+string sniffing; pairing codes 8 chars, 1h TTL, max 3 pending per account,
+owner bootstrap on first approval.
+
+Container boundary is permanent for native-module, host-filesystem, loop-state,
+and vendor-Node work (agent loop, exec/PTY, harnesses, browser, voice, codecs,
+Node-bound channels, plugin SDK/loader). The Node plugin SDK is never ported to
+Go; cloud extensibility is connectors/automations/tools.
+
+Port roadmap (P1-P15) lives in HIP-0129; do not restate it here. Every claim
+carries its tier: Shipped (on main, named package/route), In flight (named
+pre-main branch), Planned (backlog id or named reservation).
+
+## Build & module graph — standalone module, NOT a go.work member
+
+`cloud` is a self-contained deploy unit: its own `go.mod`, `Dockerfile`, binary.
+It is intentionally NOT listed in the parent `~/work/hanzo/go.work` workspace —
+that workspace deliberately excludes the heavy modules, and merging cloud's
+k8s/otel dependency tree with `o11y`'s reintroduces `koanf`/`ugorji`
+monolith-vs-split import ambiguities (the parent workspace is itself red on the
+koanf split; that is not cloud's bug to fix).
+
+The catch: `go` auto-discovers that parent `go.work` whenever you run a bare
+`go build ./...` / `go test ./...` from inside this tree, which puts the build in
+workspace mode and SILENTLY DROPS cloud's own `go.mod` directives. Those
+directives are load-bearing and each fixes exactly one graph hazard:
+
+- `replace github.com/vulcand/oxy/v2 => github.com/traefik/oxy/v2 <pseudo>` — the
+  bare require is a placeholder (`v2.0.0-00010101000000-000000000000`); without
+  the replace it resolves to an invalid version.
+- `exclude github.com/ugorji/go <old-monolith>` — drops the pre-split monolith so
+  `github.com/ugorji/go/codec` (pulled by gin) is unambiguous.
+- the `k8s.io/*` staging replace block pins every staging module to the `v0.35.3`
+  line. `k8s.io/kubernetes` is a GRAPH-ONLY transitive require of
+  `hanzoai/deploy/gitops-engine` (clients/deploy uses its `pkg/utils/kube`); NO
+  cloud package imports `k8s.io/kubernetes`, so its staging tree never compiles —
+  do not "drop k8s.io/kubernetes", the pins keep the graph consistent and it is
+  never built. koanf resolves to the split modules; the `koanf v1.5.0` monolith
+  require is a harmless graph leaf, never imported.
+
+So: build cloud in module mode, never workspace mode. `make build`/`test`/`vet`/
+`tidy` force `GOWORK=off` (matches CI and the Dockerfile, which check out cloud
+alone with no parent go.work). For a bare `go` command from this tree, prefix
+`GOWORK=off`. `GOWORK=off go build ./...` and `go vet ./...` are green; `go mod
+tidy` is stable. Do NOT commit a `go.work` here — it would flip the Dockerfile
+(`COPY go.mod go.sum` → `go mod download` → `COPY . .`) into workspace mode after
+its `-mod=readonly` download step.
+
+Test modes: `make test` is pure-Go (`CGO_ENABLED=0`). Encrypted-at-rest OrgDB
+tests (`cek`, `CLOUD_KMS_MASTER_KEY_REF` set) REQUIRE `CGO_ENABLED=1` +
+libsqlcipher (`cek/cek.go` refuses to encrypt in pure-Go); those run only in the
+Dockerfile's dedicated `-tags libsqlite3` CGO stage, and fail under `make test`
+by design (clients/git, kms, flags, x402, cmd/kmsreseal, finance). Bundle-embed
+tests (clients/tasks/ui) need `make deploy-ui` first (real bundle is gitignored).
+
 ## Framework doctrine

 One way to do everything. Composable, orthogonal, DRY. A new subsystem is a
@@ -146,6 +227,23 @@ package under `clients/<name>` that obeys these seams — nothing more.
  curriculum is a machine-readable contract (embedded `default.yaml`; org-custom via
  PUT replaces it) so `hanzoai/marketing` can author the full `checklist.yaml`
  against the same `Step`/`Curriculum` shape.
+- **The EXPERIMENT is a composition, not a fourth engine (`clients/experiments`,
+  `/v1/experiments`).** A/B testing is ONE value whatever the variant KIND (feature
+  flag, ad creative, email subject, model id): the primitive owns only the
+  experiment registry (definition + decision); it COMPOSES three planes it never
+  duplicates. ASSIGNMENT = `flags.Assign(org,project,key,subject,props)` —
+  subject→variant is a deterministic `engineEvaluate` (sha1 rollout hash), no second
+  bucketing, no assignment store; create writes a multivariate flag def
+  (`flags.PutDef`) and decide rewrites its weights to 100% for the winner
+  (`flags.GetDef`+`PutDef`). MEASUREMENT = `analytics.Outcomes(...)` — one
+  org-scoped `hanzo.events` query (the `eventsWhere` isolation invariant), no second
+  event store; the analyze fold joins each subject's analytics outcome to its flags
+  variant by `distinct_id`. EVIDENCE = `research.Record`/`research.List` — per-variant
+  samples land as immutable `kind:"ab"` rows; significance (two-proportion z-test,
+  `math.Erfc`, no dep) is a PURE function over them. `clients/campaign` runs a
+  creative A/B by composing `experiments.Assign`/`experiments.Analyze` — it never
+  reinvents assignment or evidence. Add a new variant KIND by putting a payload on
+  the variant; the primitive does not care what it is.

 ## Identity vocabulary is IAM-native

@@ -184,3 +282,78 @@ Import path (already-incorporated orgs): Google Drive → data room, a Google Sh
 captable, via the `google` OAuth provider now completed in `clients/integrations`
 (token custodied in KMS; the automations `google` connector shares the same token).
 Runbook: `docs/company-dogfood.md`.
+
+## Deploy plane (`clients/deploy`, `/v1/deploy`)
+
+Native ArgoCD-grade GitOps console over the operator-managed fleet, parallel to
+`/v1/git`: each `hanzo.ai/v1` App CR IS the Application, and the plane OBSERVES the
+operator's reconcile — `GET /v1/deploy/applications` (fleet list), `/{name}/tree`
+(ownerRef resource tree + per-node health/sync), `/{name}/resource/{ref}` (live
+manifest + desired-vs-live diff), `/{name}/logs`; `POST /{name}/rollback` pins the CR
+image to a prior semver and `/{name}/sync` requests a reconcile. SUPERADMIN-only on
+`c.IsAdmin()`, fail-closed; Secret nodes are never surfaced. `engine.go` embeds the argo
+`gitops-engine` (`hanzoai/deploy/gitops-engine` v0.7.2, no replace) in-process for the
+reconcile half behind `DEPLOY_ENGINE_ENABLED` (default off), with a prune-safety fuse.
+
+## The `hanzo` CLI targets THIS binary — one contract, one IAM login
+
+The `hanzo` CLI (`cli/`) is the same unified binary; its control-plane verbs speak the
+routes THIS process serves, authorized off a plain `hanzo login` (the IAM access token is
+the final bearer fallback — no `--platform-token`). The ONE contract, no TS-Dokploy drift:
+
+- `hanzo apps list|get`  → `GET /v1/paas/apps[/{app}]`  (`clients/paas` fleet drift board)
+- `hanzo deploy <app>`   → `POST /v1/paas/apps/{app}/deploy` — a zero-downtime ROLLING
+  RESTART (stamps the Deployment pod-template `hanzo.ai/restartedAt` annotation; never
+  changes the declared TAG — that stays a git commit CD reconciles). `--env` picks the ns.
+- `hanzo clusters list|get` → `GET /v1/clusters`  (`clients/visor`, tenant-scoped)
+- `hanzo build`          → `POST /v1/runner`  (native buildkit fabric)
+
+`/v1/paas/*` auth mirrors `/v1/runner` (`clients/platform/runner.go`): the `guard` admits a
+validated principal who is SuperAdmin OR OrgAdmin, then each handler CONFINES a non-super
+caller to the platform namespaces its own validated org owns (`scopedNamespaces`, keyed on
+`principal.Org` — a tenant admin can never observe/restart another org's, or a platform,
+app; `?org=` cannot widen it). The rolling restart needs `patch` on `apps/deployments`
+(ClusterRole/cloud, universe `infra/k8s/cloud/rbac.yaml`). There is NO `/v1/apps`,
+`/v1/org/{org}/cluster`, or `/v1/platform/projects` CLI path — the first two never existed
+here (TS-Dokploy contract, 404), and `/v1/platform/*` needs a co-resident IAM store this
+deployment does not fold in (IAM runs as a separate svc) so it 500s; the live apps backend
+is `/v1/paas`, whose board reads k8s directly with no IAM-store dependency.
+
+## GTM: `/v1/campaign` orchestration → channels → connectors → analytics
+
+The go-to-market stack decomplects a campaign from its execution. A **Campaign is a
+VALUE** (`clients/campaign`: `{name, audience, content[], schedule, budget, channels[],
+status}`) that SPANS channels; a **Channel is an EXECUTOR** (`channel.go`, the
+`Channel` interface) it fans out to. The three channels are orthogonal and each
+CONSUMES the connector plane via `integrations.TokenFor` — the campaign object never
+touches a credential:
+
+- **paid → `/v1/ads`** — `ads.LaunchPaid/PaidSpend/PausePaid` (`clients/ads/provider.go`)
+  resolve the org's ad token (`meta_ads`/`google_ads`/… via `TokenFor(org, <id>,
+  "access_token")`) and run the campaign on the provider. Meta is executed for real;
+  fail-closed when the org has not connected (424). This is the ONLY place `/v1/ads`
+  touches the connector plane.
+- **organic → `/v1/publish`** (rename of `clients/social`) and **email → `/v1/marketing`**
+  are DESIGNED follow-ons: register their executors the same way in `apps/wire_seams.go`
+  (`campaign.RegisterChannel(campaign.NewChannel(kind, launch, spend, pause))`). Until
+  wired, a fan-out records that channel "unavailable" (honest), never fabricated.
+
+Channels are injected at the composition root (`apps/wire_seams.go`), the SAME
+injected-function decoupling the coding dispatcher uses — `campaign` never imports
+`ads`, `ads` never imports `campaign`. Fan-out (`launch.go` `fanOut`) is best-effort
+per channel; the org (the ONLY tenant key) is passed verbatim to every executor, so a
+campaign can only ever resolve its OWN org's token.
+
+**Metrics = the ONE analytics plane, not a second store.** `GET /v1/campaign/:id/metrics`
+reads the funnel from `analytics.CampaignMetrics(org, campaignID, variant, start, end)`
+(`clients/analytics/campaign.go`) — an org+`utm_campaign`(+`utm_content`)-scoped query
+over `hanzo.events`, org and campaign bound POSITIONALLY (same tenancy invariant as
+every analytics query) — joined with each channel connector's reported spend
+(`Channel.Spend`). Derived KPIs: CTR/CVR/CAC/ROAS. Honest-empty when the warehouse is
+absent.
+
+**Creative A/B composes the experiment primitive** (`experiment.go`), it does not
+reinvent it: a creative A/B is an experiment whose variant = a creative (tagged
+`utm_content`) and whose metric = the analytics read. The `AssignFunc`/`EvidenceFunc`
+seams are wired at the root to the flags-assignment + evidence primitive; nil-safe
+until it lands (single-creative honest default).
@@ -4,6 +4,18 @@
 GO              ?= go
 BIN             ?= cloud
 PKG             ?= ./cmd/cloud
+
+# cloud is a STANDALONE Go module — a self-contained deploy unit (its own go.mod,
+# Dockerfile, binary). It is intentionally NOT a member of the parent
+# ~/work/hanzo/go.work workspace (that workspace deliberately excludes the heavy
+# modules; adding cloud would merge its k8s/otel graph with o11y's and reintroduce
+# koanf/ugorji import ambiguities). But `go` auto-discovers that parent go.work
+# whenever a dev builds from inside this tree, which shadows cloud's own
+# replace/exclude directives (oxy pin, ugorji monolith exclude, k8s staging pins)
+# and breaks `go build ./...`. Force module mode so make targets build EXACTLY
+# what CI/Docker build (fresh checkout, no parent go.work). Overridable via
+# `make GOWORK=... <target>` for the rare cross-module case.
+export GOWORK := off
 DOCKER_IMAGE    ?= ghcr.io/hanzoai/cloud
 DOCKER_TAG      ?= dev
 LDFLAGS         ?= -s -w
@@ -24,7 +36,7 @@ OPENAPI_DIR    ?= ../openapi
 # forces the fork to modernc too so the whole binary registers "sqlite" once.
 CGO_ENABLED     ?= 0

-.PHONY: help native webui agentskills build build-standalone hanzo run smoke test test-cgo vet tidy docker docker-push clean
+.PHONY: help native webui deploy-ui agentskills build build-standalone run smoke test test-cgo vet tidy docker docker-push clean

 help: ## Show this help.
 	@awk 'BEGIN{FS=":.*##";printf "\nUsage: make <target>\n\nTargets:\n"} /^[a-zA-Z_-]+:.*##/{printf "  \033[36m%-16s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
@@ -40,6 +52,17 @@ webui: ## Build the real console static bundle into webui/dist (go:embed source)
 	cp -r "$(CONSOLE_DIR)/out/." webui/dist/
 	@echo ">> embedded real console bundle into webui/dist (index.html $$(wc -c < webui/dist/index.html) bytes)"

+deploy-ui: ## Build the monochrome ArgoCD dashboard bundle into clients/deploy/webui/dist (go:embed source). DEPLOY_DIR=<path to hanzoai/deploy>.
+	@command -v yarn >/dev/null 2>&1 || { echo "yarn is required to build the deploy dashboard bundle"; exit 1; }
+	@test -f "$(DEPLOY_DIR)/ui/package.json" || { echo "deploy checkout not found at $(DEPLOY_DIR) — set DEPLOY_DIR=<path to hanzoai/deploy on rebrand/hanzo-monochrome>"; exit 1; }
+	@test -d "$(DEPLOY_DIR)/ui/node_modules" || (cd "$(DEPLOY_DIR)/ui" && yarn install --frozen-lockfile)
+	cd "$(DEPLOY_DIR)/ui" && NODE_OPTIONS=--max-old-space-size=8192 yarn build
+	# Overlay the fresh bundle, keeping only the tracked fallback (.gitignore +
+	# index.html shell); the real 43MB bundle is build-time-only (gitignored).
+	find clients/deploy/webui/dist -mindepth 1 -maxdepth 1 ! -name .gitignore -exec rm -rf {} +
+	cp -r "$(DEPLOY_DIR)/ui/dist/app/." clients/deploy/webui/dist/
+	@echo ">> embedded monochrome ArgoCD bundle into clients/deploy/webui/dist (index.html $$(wc -c < clients/deploy/webui/dist/index.html) bytes)"
+
 agentskills: ## Regenerate the FULL agent-skills catalog into clients/agentskills/catalog (go:embed source) from the openapi SOT. OPENAPI_DIR=<path to openapi>.
 	@test -f "$(OPENAPI_DIR)/skills.py" || { echo "openapi checkout not found at $(OPENAPI_DIR) — set OPENAPI_DIR=<path> or clone hanzoai/openapi"; exit 1; }
 	# skills.py rewrites the whole catalog dir; the .gitignore keeps only the tiny
@@ -53,9 +76,13 @@ build: ## Build the unified cloud binary into ./bin/cloud (embeds whatever webui

 build-standalone: webui build ## Build the REAL 1-binary console: console build:embed → webui/dist → go build.

-hanzo: ## Build the hanzo control-plane CLI into ./bin/hanzo (pure Go, same mode as cmd/cloud — registers the ONE "sqlite" driver exactly once; a plain CGO_ENABLED=1 `go build ./cmd/hanzo` links the fork's mattn backend alongside the embedded modernc importers and panics, see header).
-	@mkdir -p bin
-	CGO_ENABLED=$(CGO_ENABLED) $(GO) build -ldflags="$(LDFLAGS)" -o bin/hanzo ./cmd/hanzo
+# NOTE: cloud builds ONLY the `cloud` binary — the stateless unified API. The Go
+# `hanzo` CLI (cmd/hanzo + cli/) is RETIRED: the shipped `hanzo` is the Rust CLI
+# (~/work/hanzo/cli, `curl hanzo.sh`), which talks to this API over HTTP via its
+# OpenAPI-generated command surface. The `code` wrapper (incl. the zen-tier 1M
+# mechanism) now lives in the Rust CLI. cmd/hanzo + cli/ remain only as the
+# reference for the still-to-port client-side tools (GPU fleet worker `link`,
+# `runner`, `engine`, `security`) and are no longer built here.

 run: build ## Run with iam,base,kms,gateway,o11y enabled (matches README quickstart).
 	./bin/$(BIN) --enable=iam,base,kms,gateway,o11y --brand=hanzo --domain=api.hanzo.ai
@@ -0,0 +1,64 @@
+// Copyright 2026 Hanzo AI Inc. All Rights Reserved.
+
+package cloud
+
+import (
+	"net/http"
+
+	"github.com/hanzoai/cloud/clients/principal"
+	"github.com/zap-proto/zip"
+)
+
+// AccountFromPrincipal decomplects the console's IDENTITY onto the ONE truth every
+// /v1/admin/* call already authorizes on — the validated cloud principal — instead of
+// the embedded casibase account model.
+//
+// THE COMPLECTION IT REMOVES. The operator SPA authenticates via /v1/signin (a cloud
+// PKCE session → the X-User-* principal the middleware mints) but read its IDENTITY
+// from /v1/get-account, which the embedded IAM (casibase) answers from ITS OWN session
+// cookie. A PKCE session is not a casibase session, so get-account returned
+// owner:"hanzo" (anonymous) or "Unauthorized operation" — and the SPA's SuperAdmin
+// gate (owner == "admin" && isAdmin), reading that, bounced the operator UI to login
+// even though the SAME session got 200 from every /v1/admin/* route. Two session
+// models for one surface; the identity source and the authorization source disagreed.
+//
+// THE DECOMPLECTION. Identity is now the principal: when a VALIDATED principal is
+// present (X-User-Id is set ONLY by IdentityMiddleware from a real credential, never a
+// raw client header — see middleware_identity.go), /v1/get-account reflects it. owner
+// is the HOME org (principal.Owner) so a SuperAdmin org-switched into a tenant stays a
+// SuperAdmin; isAdmin is the validated bit. With NO principal it falls through
+// (c.Next()) to the casibase account surface unchanged — the anonymous sign-in page
+// and any legacy casibase-session caller are untouched. One truth, additive, fail-open
+// to the old path. MUST be registered AFTER IdentityMiddleware (needs the minted
+// headers) and BEFORE MountAll (so it precedes the casibase /v1/get-account handler).
+func AccountFromPrincipal() zip.Handler {
+	return func(c *zip.Ctx) error {
+		if c.Method() != http.MethodGet || c.Path() != "/v1/get-account" {
+			return c.Next()
+		}
+		user := c.User() // X-User-Id — minted only from a validated credential
+		if user == "" {
+			return c.Next() // no principal → the casibase account surface (unchanged)
+		}
+		owner := principal.Owner(c) // HOME org (a SuperAdmin stays one when org-switched)
+		if owner == "" {
+			owner = c.Org()
+		}
+		name := c.Header("X-User-Name")
+		if name == "" {
+			name = user
+		}
+		return c.JSON(http.StatusOK, map[string]any{
+			"status": "ok",
+			"msg":    "",
+			"data": map[string]any{
+				"owner":       owner,
+				"name":        name,
+				"displayName": name,
+				"email":       c.Header("X-User-Email"),
+				"isAdmin":     c.IsAdmin(),
+				"type":        "normal-user",
+			},
+		})
+	}
+}
@@ -34,7 +34,6 @@ package apps
 import (
 	"context"
 	"fmt"
-	"os"

 	"github.com/hanzoai/cloud"
 	"github.com/zap-proto/zip"
@@ -51,6 +50,7 @@ import (
 	// owns process-lifetime resources, a Shutdown); Wire references them directly.
 	"github.com/hanzoai/cloud/clients/account"
 	"github.com/hanzoai/cloud/clients/admin"
+	"github.com/hanzoai/cloud/clients/admission"
 	"github.com/hanzoai/cloud/clients/ads"
 	"github.com/hanzoai/cloud/clients/affiliates"
 	"github.com/hanzoai/cloud/clients/agent"
@@ -61,22 +61,30 @@ import (
 	"github.com/hanzoai/cloud/clients/authors"
 	"github.com/hanzoai/cloud/clients/automations"
 	"github.com/hanzoai/cloud/clients/base"
+	"github.com/hanzoai/cloud/clients/benchmark"
 	"github.com/hanzoai/cloud/clients/billing"
+	"github.com/hanzoai/cloud/clients/books"
 	"github.com/hanzoai/cloud/clients/bots"
+	"github.com/hanzoai/cloud/clients/campaign"
 	"github.com/hanzoai/cloud/clients/captable"
 	"github.com/hanzoai/cloud/clients/catalogsync"
+	"github.com/hanzoai/cloud/clients/channels"
+	"github.com/hanzoai/cloud/clients/cloudflare"
 	"github.com/hanzoai/cloud/clients/code"
 	"github.com/hanzoai/cloud/clients/company"
-	"github.com/hanzoai/cloud/clients/connectorruntime"
+	"github.com/hanzoai/cloud/clients/compliance"
 	"github.com/hanzoai/cloud/clients/content"
 	"github.com/hanzoai/cloud/clients/crm"
-	"github.com/hanzoai/cloud/clients/cron"
 	"github.com/hanzoai/cloud/clients/dataroom"
 	"github.com/hanzoai/cloud/clients/deploy"
+	"github.com/hanzoai/cloud/clients/destinations"
+	"github.com/hanzoai/cloud/clients/dns"
 	"github.com/hanzoai/cloud/clients/do"
+	"github.com/hanzoai/cloud/clients/domain"
 	"github.com/hanzoai/cloud/clients/entitlements"
 	"github.com/hanzoai/cloud/clients/eval"
 	"github.com/hanzoai/cloud/clients/exec"
+	"github.com/hanzoai/cloud/clients/experiments"
 	"github.com/hanzoai/cloud/clients/flags"
 	"github.com/hanzoai/cloud/clients/framework"
 	"github.com/hanzoai/cloud/clients/functions"
@@ -84,13 +92,15 @@ import (
 	"github.com/hanzoai/cloud/clients/git"
 	"github.com/hanzoai/cloud/clients/graph"
 	"github.com/hanzoai/cloud/clients/guide"
+	"github.com/hanzoai/cloud/clients/help"
 	"github.com/hanzoai/cloud/clients/iam"
-	"github.com/hanzoai/cloud/clients/iam2"
 	"github.com/hanzoai/cloud/clients/ingress"
 	"github.com/hanzoai/cloud/clients/integrations"
 	"github.com/hanzoai/cloud/clients/kafka"
 	"github.com/hanzoai/cloud/clients/kms"
 	"github.com/hanzoai/cloud/clients/knowledge"
+	"github.com/hanzoai/cloud/clients/leaderboard"
+	"github.com/hanzoai/cloud/clients/legal"
 	"github.com/hanzoai/cloud/clients/link"
 	"github.com/hanzoai/cloud/clients/marketing"
 	"github.com/hanzoai/cloud/clients/marketplace"
@@ -108,10 +118,13 @@ import (
 	"github.com/hanzoai/cloud/clients/provisioning"
 	"github.com/hanzoai/cloud/clients/pubsub"
 	"github.com/hanzoai/cloud/clients/referrals"
+	"github.com/hanzoai/cloud/clients/research"
+	"github.com/hanzoai/cloud/clients/rollingcap"
 	"github.com/hanzoai/cloud/clients/runtime"
 	"github.com/hanzoai/cloud/clients/sbom"
 	"github.com/hanzoai/cloud/clients/security"
 	"github.com/hanzoai/cloud/clients/settings"
+	"github.com/hanzoai/cloud/clients/share"
 	"github.com/hanzoai/cloud/clients/sign"
 	"github.com/hanzoai/cloud/clients/social"
 	"github.com/hanzoai/cloud/clients/storage"
@@ -123,6 +136,8 @@ import (
 	"github.com/hanzoai/cloud/clients/tracker"
 	"github.com/hanzoai/cloud/clients/treasury"
 	"github.com/hanzoai/cloud/clients/usage"
+	"github.com/hanzoai/cloud/clients/validators"
+	"github.com/hanzoai/cloud/clients/venue"
 	"github.com/hanzoai/cloud/clients/visor"
 	"github.com/hanzoai/cloud/clients/wallets"
 	"github.com/hanzoai/cloud/clients/websearch"
@@ -130,19 +145,20 @@ import (
 	"github.com/hanzoai/cloud/clients/x402"
 	"github.com/hanzoai/cloud/clients/zt"

-	// Framework CONTENT modules — NOT mount subsystems (they carry no HTTP surface
-	// and are absent from Wire()). Each registers its DocType fixtures and, for erp,
-	// its ledger-posting lifecycle hooks into the clients/framework DocType engine
-	// from a package init() (framework.RegisterModule) — the idiomatic
-	// register-into-a-registry pattern (cf. database/sql drivers). The framework
-	// engine is mounted (always-on, /v1/framework/*) but its module registry is
-	// populated ONLY by these blank imports. Dropping one silently strips that
-	// lane's DocTypes and hooks — for erp, the immutable ledger postings — from the
-	// binary with NO mount change and NO failing mount test. #248 dropped them;
-	// TestFrameworkContentModulesLinked now guards against a recurrence. Keep.
+	// Framework CONTENT modules — pure fixture lanes that carry no HTTP surface and
+	// are absent from Wire(). Each registers its DocType fixtures and, for erp, its
+	// ledger-posting lifecycle hooks into the clients/framework DocType engine from a
+	// package init() (framework.RegisterModule) — the idiomatic register-into-a-
+	// registry pattern (cf. database/sql drivers). The framework engine is mounted
+	// (always-on, /v1/framework/*) but its module registry is populated ONLY by these
+	// blank imports. Dropping one silently strips that lane's DocTypes and hooks — for
+	// erp, the immutable ledger postings — from the binary with NO mount change and NO
+	// failing mount test. #248 dropped them; TestFrameworkContentModulesLinked now
+	// guards against a recurrence. Keep. (help is a framework lane too but ALSO mounts
+	// a thin /v1/help public plane, so it is a real import + a Wire() spec below,
+	// alongside knowledge — the other lane with a companion subsystem.)
 	_ "github.com/hanzoai/cloud/clients/cms"
 	_ "github.com/hanzoai/cloud/clients/erp"
-	_ "github.com/hanzoai/cloud/clients/help"
 )

 // init wires the cross-subsystem func seams — the composition root is the one place
@@ -163,22 +179,6 @@ func init() {
 	})
 }

-// identitySpec selects the ONE identity backend that owns /v1/iam/* (+ /login/oauth/*)
-// for this boot. CLOUD_IAM_IMPL=iam2 picks the clean-room iam2 (zip+orm, beego-free);
-// anything else — including unset, the production default — keeps the legacy beego
-// Casdoor embed, byte-for-byte today's behavior. The two impls register the SAME
-// absolute prefixes and therefore cannot co-mount, so selection (this func) stays
-// separate from activation (cfg.Enabled): exactly one spec occupies the identity slot
-// in Wire, preserving mount order either way. os.Getenv (not the unexported
-// cloud.getenv, which is unreachable from package apps) is the read — CLOUD_IAM_IMPL is
-// the deliberate, off-by-default opt-in that keeps iam2 inert until a canary flips it.
-func identitySpec() cloud.MountSpec {
-	if os.Getenv("CLOUD_IAM_IMPL") == "iam2" {
-		return cloud.MountSpec{Name: "iam2", Mount: iam2.Mount}
-	}
-	return cloud.MountSpec{Name: "iam", Mount: iam.Mount}
-}
-
 // Wire returns every linked subsystem as a cloud.MountSpec, in mount order. The
 // slice position IS the order: cloud.MountAll iterates it as-given, registering each
 // subsystem's teardown as a zip shutdown hook so teardown runs in reverse (LIFO).
@@ -210,15 +210,12 @@ func Wire() []cloud.MountSpec {
 		// /v1/commerce/topup/wallet). MUST mount before the IAM /v1/iam/* wildcard (50) so
 		// they win Fiber's first-match scan (framework-guaranteed since zip v1.3.0).
 		{Name: "account", Mount: account.MountAccount},
-		// Embedded IAM identity plane (/v1/iam/*, /.well-known/*, /login/oauth/*, /_/iam/*,
-		// /cas/*, /scim/*) — the identity authority, mounts before its dependents. STAGED:
-		// the operator adds "iam" to --enable only after IAM config + the fold are verified.
-		// Which IMPLEMENTATION owns these prefixes is selected by CLOUD_IAM_IMPL
-		// (identitySpec): the clean-room iam2 (zip+orm, beego-free) when =="iam2", else the
-		// legacy beego Casdoor embed — the default (unset = today's behavior, byte-for-byte).
-		// Both register the SAME absolute paths and cannot co-mount, so this is an either/or
-		// switch at this ONE slot, never a shadow prefix.
-		identitySpec(),
+		// Embedded IAM identity plane (/v1/iam/*, /login/oauth/*) — the identity authority,
+		// mounts before its dependents. The ONE implementation: the clean-room iam-v2
+		// (zip-native + hanzoai/orm, beego-free); the retired Casdoor iam-v1 embed is GONE.
+		// STAGED: the operator adds "iam" to --enable only after IAM config + the fold are
+		// verified (login/authorize/token/jwks + the operator SSO chain).
+		{Name: "iam", Mount: iam.Mount},
 		// Embedded Base app engine + viral waitlist (/v1/waitlist/*). STAGED behind
 		// CLOUD_BASE_EMBED. OwnsHealth: native /v1/base/health.
 		{Name: "base", Mount: base.Mount, Shutdown: base.Shutdown, OwnsHealth: true},
@@ -236,7 +233,10 @@ func Wire() []cloud.MountSpec {
 		// CommerceClient is wired directly in pickCommerceClient).
 		{Name: "commerce", Mount: mountCommerce},
 		{Name: "licensing", Mount: licensing.Mount},
-		{Name: "plans", Mount: plan.Mount, OwnsHealth: true},
+		// clients/plan.Mount. Enable id normalized "plans" -> "plan" to match the
+		// package + generated cmd/plan (one subsystem, one name). Its product routes
+		// stay /v1/plans/* (incl. the OwnsHealth /v1/plans/health probe) — unchanged.
+		{Name: "plan", Mount: plan.Mount, OwnsHealth: true},
 		{Name: "pricing", Mount: pricing.Mount, OwnsHealth: true},
 		// /v1/s3/buckets/* + /v1/s3/health. Mounts BEFORE provisioning (120) so its static
 		// routes win over provisioning's /v1/s3/:name. OwnsHealth (real fail-closed probe).
@@ -244,12 +244,22 @@ func Wire() []cloud.MountSpec {
 		// Provisioning control plane: /v1/sql,/v1/vector,/v1/datastore,/v1/kv,/v1/search,/v1/s3,/v1/docdb.
 		{Name: "provisioning", Mount: provisioning.Mount},
 		{Name: "billing", Mount: billing.Mount},
+		// Rolling AI-spend cap: installs the ai gate's per-tier trailing-window cap
+		// reader (registers no routes; its admin-editable knobs are platform switches
+		// surfaced in the /v1/admin/flags cockpit). After commerce/plan so the tier +
+		// finance globals it composes are wired.
+		{Name: "rollingcap", Mount: rollingcap.Mount},
 		// CATCH-ALL /v1/billing/* + /v1/commerce/* data bridges — AFTER clients/billing
 		// (121) + the commerce embed (100). Same clients/account package as "account" (48).
 		{Name: "account-bridge", Mount: account.MountBridge},
 		{Name: "do", Mount: do.Mount},
 		{Name: "platform", Mount: platform.Mount, OwnsHealth: true},
 		{Name: "projects", Mount: projects.Mount},
+		// The /v1/dns forward head: relays the console DNS dashboard to the DNS
+		// control plane under the caller's own validated bearer (clients/dns).
+		{Name: "dns", Mount: dns.Mount},
+		// The registrar: search/price/register domains (name.com) per org.
+		{Name: "domain", Mount: domain.Mount},
 		{Name: "prompts", Mount: prompts.Mount},
 		{Name: "agents", Mount: agents.Mount, Shutdown: agents.Shutdown},
 		// The unified AI login manager registry (/v1/links). Mounts AFTER agents so
@@ -271,6 +281,13 @@ func Wire() []cloud.MountSpec {
 		{Name: "templates", Mount: templates.Mount},
 		{Name: "framework", Mount: framework.Mount, Shutdown: ctxShutdown(framework.Shutdown)},
 		{Name: "knowledge", Mount: knowledge.Mount},
+		// Hanzo Support PUBLIC plane /v1/help/* (help center KB read + customer ticket
+		// intake) — the anonymous face the secure-by-default framework surface can't
+		// serve. A framework lane like knowledge: its DocType fixtures register via
+		// init() (help.Module), and this mounts the thin public subsystem. Owns no store
+		// (delegates to the framework in-process API), so no Shutdown. After framework
+		// (whose in-process API it calls at request time); before the AI /v1/* catch-all.
+		{Name: "help", Mount: help.Mount},
 		// Marketing content loop /v1/content/* (generate → CMS → transition → publish).
 		// After framework (its DocType store the ops read/write) + knowledge (the sibling
 		// framework lane); before the AI /v1/* catch-all so /v1/content/* resolves here.
@@ -284,6 +301,11 @@ func Wire() []cloud.MountSpec {
 		{Name: "catalogsync", Mount: catalogsync.Mount, Shutdown: catalogsync.Shutdown},
 		{Name: "ml", Mount: ml.Mount, OwnsHealth: true},
 		{Name: "usage", Mount: usage.Mount},
+		// Gamified usage analytics: /v1/usage/leaderboard + /v1/usage/activity + the
+		// per-day contribution graph, over the datastore rollup (#43). Co-owns /v1/usage/*
+		// with usage (a distinct concern — who leads + your activity graph) at its own
+		// exact paths; owns the opt-in SQLite store. Before the ai /v1/* catch-all.
+		{Name: "leaderboard", Mount: leaderboard.Mount, Shutdown: leaderboard.Shutdown},
 		{Name: "crm", Mount: crm.Mount},
 		// Native /v1/marketing/* — the in-process fold of github.com/hanzoai/marketing
 		// (per-org campaign store on Base/SQLite), twin of crm. Owns a DB handle, so
@@ -293,6 +315,18 @@ func Wire() []cloud.MountSpec {
 		// twin of crm/marketing. Owns a DB handle, so its Shutdown closes it cleanly
 		// on SIGTERM (ctxShutdown adapts func() error).
 		{Name: "ads", Mount: ads.Mount, Shutdown: ctxShutdown(ads.Shutdown)},
+		// Top-level GTM orchestration /v1/campaign/* — the capability layer that fans a
+		// campaign VALUE out to its channels (paid→ads, organic→publish, email→marketing),
+		// each CONSUMING the connector plane via integrations.TokenFor. Metrics read from
+		// the ONE analytics plane (never a second store); creative A/B composes the
+		// experiment seam. The paid channel executor is wired in wire_seams.go. Owns a DB
+		// handle, so its Shutdown closes it cleanly on SIGTERM.
+		{Name: "campaign", Mount: campaign.Mount, Shutdown: ctxShutdown(campaign.Shutdown)},
+		// GDA/SDM validator onboarding /v1/validators/* — wallet-sig + ETH-mainnet
+		// GenesisNFT ownerOf → seal luxd staking identity into KMS → write a NEW-node
+		// LuxNetwork CR (node.lux.cloud, never the live luxd) → enqueue an owner-gated
+		// registration (never auto-submitted to any P-Chain). Owns a DB handle.
+		{Name: "validators", Mount: validators.Mount, Shutdown: ctxShutdown(validators.Shutdown)},
 		// Native /v1/social/* — the in-process fold of the live social stack
 		// (github.com/hanzoai/social: social-backend/frontend/orchestrator, a Postiz-style
 		// scheduler), a per-org accounts+posts store on Base/SQLite, twin of crm. Owns a DB
@@ -305,19 +339,43 @@ func Wire() []cloud.MountSpec {
 		// DB handles, so its Shutdown closes them on SIGTERM.
 		{Name: "sync", Mount: sync.Mount, Shutdown: ctxShutdown(sync.Shutdown)},
 		{Name: "visor", Mount: visor.Mount},
+		// Connect-a-cloud-account plane /v1/cloud/*: an org links its DigitalOcean /
+		// AWS / GCP / Azure accounts (labeled, KMS-sealed, keyless where possible),
+		// Hanzo DISCOVERS each account's native Kubernetes clusters and FOLDS them into
+		// the ONE fleet (clients/fleet.Register) — so they surface in visor's
+		// /v1/clusters and run work like any BYO/managed cluster. No second registry.
+		{Name: "venue", Mount: venue.Mount},
 		// Cap table on Base via goja. STAGED behind CLOUD_ENABLE.
 		{Name: "captable", Mount: captable.Mount, Shutdown: captable.Shutdown},
 		{Name: "code", Mount: code.Mount, Shutdown: code.Shutdown},
 		{Name: "zero-trust", Mount: zt.Mount},
+		// ngrok-native public sharing: /v1/share/* provisions a per-org zrok
+		// account so `hanzo share <port>` publishes a local service to a public
+		// https://<token>.share.hanzo.ai URL. Fail-closed until ZROK_ADMIN_TOKEN.
+		{Name: "share", Mount: share.Mount},
 		// Data rooms via goja + per-tenant Base. STAGED behind CLOUD_ENABLE. OwnsHealth.
 		{Name: "dataroom", Mount: dataroom.Mount, Shutdown: dataroom.Shutdown, OwnsHealth: true},
 		{Name: "graph", Mount: graph.Mount},
 		{Name: "security", Mount: security.Mount, Shutdown: ctxShutdown(security.Shutdown), OwnsHealth: true},
 		{Name: "integrations", Mount: integrations.Mount, Shutdown: integrations.Shutdown},
+		// Marketing destinations /v1/destinations/* — the native fan-out that
+		// TRANSLATES the canonical /v1/event stream to each connected ad/analytics
+		// platform (GA4 Measurement Protocol, Meta Conversions API, X/LinkedIn/TikTok/
+		// Reddit) and forwards it server-side. Mounts AFTER analytics (whose fan-out
+		// sink it installs) and integrations (a destination may reuse an OAuth
+		// connection's token via integrations.TokenFor). Owns a DB handle → Shutdown.
+		{Name: "destinations", Mount: destinations.Mount, Shutdown: ctxShutdown(destinations.Shutdown)},
+		// First-class per-org Cloudflare asset plane /v1/cloudflare/{zones,pages,workers,
+		// ai,r2,kv,d1}/* (sibling of /v1/dns, /v1/domain). Mounts AFTER integrations
+		// because it reads the org's Cloudflare token through the integrations custody
+		// seam (integrations.TokenFor) — one token, one custody boundary. Connecting the
+		// provider stays on the integrations plane; this plane only MANAGES resources.
+		{Name: "cloudflare", Mount: cloudflare.Mount},
 		{Name: "sbom", Mount: sbom.Mount, OwnsHealth: true},
 		{Name: "team", Mount: team.Mount, Shutdown: ctxShutdown(team.Shutdown)},
 		{Name: "settings", Mount: settings.Mount, Shutdown: settings.Shutdown},
 		{Name: "notify", Mount: notify.Mount, OwnsHealth: true},
+		{Name: "channels", Mount: channels.Mount, Shutdown: channels.Shutdown},
 		{Name: "gateway", Mount: gateway.Mount},
 		{Name: "entitlements", Mount: entitlements.Mount, Shutdown: entitlements.Shutdown},
 		{Name: "exec", Mount: exec.Mount},
@@ -334,25 +392,41 @@ func Wire() []cloud.MountSpec {
 		{Name: "sign", Mount: sign.Mount, Shutdown: sign.Shutdown, OwnsHealth: true},
 		{Name: "product", Mount: product.Mount},
 		{Name: "evals", Mount: eval.Mount},
+		{Name: "benchmark", Mount: benchmark.Mount},
+		// The R&D EVIDENCE plane (HIP-0512) + its R&D Ops Board UI at /research —
+		// the arena's sibling: benchmark measures, research is the versioned diary
+		// every product's runs accrue into. Non-staged: mounts under the default.
+		{Name: "research", Mount: research.Mount, Shutdown: ctxShutdown(research.Shutdown)},
+		// The unified EXPERIMENT primitive (/v1/experiments): A/B testing as ONE value
+		// whatever the variant kind (feature | ad creative | email | model). It is a
+		// COMPOSITION — assignment via flags, measurement via analytics, evidence via
+		// research — so it mounts AFTER all three. It owns only the experiment registry
+		// store → Shutdown. clients/campaign composes it (experiments.Assign/Analyze).
+		{Name: "experiments", Mount: experiments.Mount, Shutdown: ctxShutdown(experiments.Shutdown)},
+		// The revenue BOOKS spine (/v1/books): a native double-entry general ledger that
+		// reads commerce transactions (the sole posting source) and books the accounting twin —
+		// plus bank import (PDF/OFX/CSV/Plaid/Teller), reconciliation, and the AI Ask brain.
+		{Name: "books", Mount: books.Mount, Shutdown: ctxShutdown(books.Shutdown)},
 		{Name: "treasury", Mount: treasury.Mount, Shutdown: ctxShutdown(treasury.Shutdown)},
 		{Name: "admin", Mount: admin.Mount},
-		// Launch-control (per-service waitlist mode) folded into the flags engine: the
-		// mode IS the switch waitlist.<svc>, the board is the /v1/admin/services lens,
-		// and /v1/featuregate/mode is served by flags. featuregate is no longer a mounted
-		// subsystem — it exposes only the native Enforce middleware (wired in serve.go),
-		// a consumer of flags.WaitlistModeForHost.
+		// Launch-control gate (per-service waitlist): the COMPLETE feature — host→service
+		// registry + brand seed + the waitlist.<svc> switch registration + the
+		// /v1/flags/waitlist (and /v1/admission/mode compat) mode read + the Enforce
+		// middleware — COMPOSING the flags engine one-way (flags.Bool/Register/
+		// SetPlatformSwitch; flags never imports admission). Mounts AFTER flags so the
+		// engine's platform-switch plane is installed first; the admin board is the
+		// /v1/admin/services lens over it. Owns the registry store handle → Shutdown.
+		{Name: "admission", Mount: admission.Mount, Shutdown: ctxShutdown(admission.Shutdown)},
+		// Tasks: the durable workflow/UI surface AND platform cron (durable schedules
+		// on the same shared engine, replacing every k8s CronJob). cron was a separate
+		// Wire entry; it mounts no routes and only registers schedules, so it is folded
+		// in as a sub-mount of tasks.Mount — ONE tasks subsystem.
 		{Name: "tasks", Mount: tasks.Mount},
-		// Platform cron: durable schedules on the shared tasks engine replacing
-		// every k8s CronJob — entries are cron.hanzo.ai ConfigMaps (universe git),
-		// runs visible in the Tasks console. Mounts no routes; starts after the
-		// engine is wired.
-		{Name: "cron", Mount: cron.Mount},
+		// Automations: the connector catalogue + flow engine AND native single-connector
+		// execution (POST /v1/automations/connectors/:id/run, HIP-0126). The connector
+		// runner mounts no other routes, so it is folded in as a sub-mount of
+		// automations.Mount (was a separate "connectorruntime" entry) — ONE subsystem.
 		{Name: "automations", Mount: automations.Mount, Shutdown: automations.Shutdown},
-		// Native single-connector execution (HIP-0126): runs an ActivePieces JS
-		// connector action in-process via goja (clients/connectorruntime), retiring
-		// the standalone auto Node engine. Mounts POST /v1/automations/connectors/:id/run,
-		// paired with the automations catalogue above; STAGED like the rest.
-		{Name: "connectorruntime", Mount: connectorruntime.Mount},
 		// Unified tool plane: /v1/tools/* — the ONE registry (connectors, functions,
 		// agents, skills, external MCP servers, full-cloud-control /v1 routes), per-org
 		// activation, and the unified MCP endpoint. Sources register into it from their
@@ -373,6 +447,14 @@ func Wire() []cloud.MountSpec {
 		// google token custody; captable/dataroom facades) and before the /v1/* AI
 		// catch-all so its routes resolve here.
 		{Name: "company", Mount: company.Mount, Shutdown: company.Shutdown},
+		// The corporate back-office surfaces — orthogonal to company/captable/billing:
+		// Hanzo Compliance (/v1/compliance) orchestrates KYC/KYB verification providers
+		// + tracks accreditation state + surfaces the SOC 2 audit posture; Hanzo Legal
+		// (/v1/legal) is the versioned template + generation engine + e-sign/filing seams.
+		// Both are TOOLING with providers/professionals in the loop, never advice or
+		// certification. They mount before the /v1/* AI catch-all so their routes resolve.
+		{Name: "compliance", Mount: compliance.Mount, Shutdown: ctxShutdown(compliance.Shutdown), OwnsHealth: true},
+		{Name: "legal", Mount: legal.Mount, Shutdown: ctxShutdown(legal.Shutdown), OwnsHealth: true},
 		// Chat orchestrator — POST /v1/chat: ONE LLM tool-calling round over the tool
 		// plane. It COMPOSES the ai completion path (in-process, so per-org billing
 		// runs) + the unified tool registry, and splits the model's tool calls into
@@ -21,15 +21,23 @@ import (
 	"net/http"
 	"path/filepath"
 	"strings"
+	"time"

 	"github.com/hanzoai/cloud"
+	accountclient "github.com/hanzoai/cloud/clients/account"
 	"github.com/hanzoai/cloud/clients/commerceclient"
 	"github.com/hanzoai/cloud/clients/commerceinproc"
+	financeclient "github.com/hanzoai/cloud/clients/finance"
+	"github.com/hanzoai/cloud/clients/principal"
 	"github.com/hanzoai/commerce"
 	commercebilling "github.com/hanzoai/commerce/api/billing"
+	catalogapi "github.com/hanzoai/commerce/api/catalog"
+	planapi "github.com/hanzoai/commerce/api/plan"
 	commercestore "github.com/hanzoai/commerce/api/store"
+	commercedatastore "github.com/hanzoai/commerce/datastore"
 	commercemid "github.com/hanzoai/commerce/middleware"
 	"github.com/hanzoai/commerce/middleware/iammiddleware"
+	commercensctx "github.com/hanzoai/commerce/util/nscontext"
 	log "github.com/luxfi/log"
 	"github.com/zap-proto/zip"
 )
@@ -60,6 +68,21 @@ var commercePrefixes = []string{
 	// whose prepaid BALANCE gate 402'd every store read (a store-metadata read
 	// must never require an LLM balance).
 	"/v1/store",
+	// Platform-admin catalog CMS: GET/POST/PUT/DELETE /v1/catalog/entries +
+	// POST /v1/catalog/seed — the SuperAdmin CRUD admin.hanzo.ai's editor drives.
+	// commerce's setupRoutes wires only the PUBLIC read (/v1/commerce/catalog);
+	// the CRUD lives on the standalone /v1 bundle (api.Route → catalogApi.AdminRoute),
+	// which the co-resident embed skips, so mountCommerce mounts it below on the
+	// same /v1 gate chain. Own the prefix here so it reaches commerce (each handler
+	// is requireSuperAdmin-gated) instead of the AI /v1/* balance catch-all.
+	"/v1/catalog",
+	// Platform-admin subscription/DNS plan authority CMS: GET/POST/PUT/DELETE
+	// /v1/plans/entries + POST /v1/plans/seed (increment 3a) — the SuperAdmin CRUD
+	// the console plan editor drives. The PUBLIC read stays GET /v1/billing/plans;
+	// this CRUD rides the /v1 bundle (api.Route → planApi.AdminRoute), which the
+	// embed skips, so mountCommerce mounts it below. Own the prefix so it reaches
+	// commerce (each handler requireSuperAdmin-gated), not the AI /v1/* 402 gate.
+	"/v1/plans",
 	// Payment-provider webhook receiver (POST /v1/billing/webhooks/:provider —
 	// Square et al). The provider's HMAC over the registered notification URL +
 	// body IS the auth; a bearer gate is impossible for provider callbacks.
@@ -140,6 +163,26 @@ func mountCommerce(app *zip.App, deps cloud.Deps) error {
 	storeV1.Use(iammiddleware.IAMTokenRequired())
 	commercestore.Route(storeV1, commercemid.TokenRequired())

+	// Platform-admin catalog CMS on the SAME /v1 bundle: GET/POST/PUT/DELETE
+	// /v1/catalog/entries + POST /v1/catalog/seed. setupRoutes wires only the
+	// public read (/v1/commerce/catalog); the CRUD rides the standalone /v1 bundle
+	// (api.Route → catalogApi.AdminRoute), which the co-resident embed skips — so
+	// register it here, exactly as the standalone does. storeV1's IAMTokenRequired
+	// populates the claims each handler's requireSuperAdmin reads (anon → 403, a
+	// platform admin edits); it is cross-tenant data, never org-scoped.
+	catalogapi.AdminRoute(storeV1)
+
+	// Platform-admin subscription/DNS plan authority CRUD on the SAME /v1 bundle:
+	// GET/POST/PUT/DELETE /v1/plans/entries + POST /v1/plans/seed (increment 3a).
+	// Mirrors the catalog mount: the standalone wires it on the /v1 bundle
+	// (api.Route → planApi.AdminRoute), which the co-resident embed skips. The
+	// embed seed SOURCE is injected here (the composition root) — commercebilling.
+	// SeedRows, the SAME @hanzo/plans embed the boot seed + resolveSubscriptionPlan
+	// read — so api/plan never imports api/billing. Each handler is
+	// requireSuperAdmin-gated (anon → 403); prices are admin-editable but the mint
+	// gates score the IMMUTABLE embed, so an edit never moves a charge gate.
+	planapi.AdminRoute(storeV1, commercebilling.SeedRows)
+
 	// Provider webhook intake at the LIVE registered path. Chain mirrors the
 	// commerce-standalone posture: gated request context, then the sessionless
 	// HMAC-verified handler.
@@ -156,6 +199,214 @@ func mountCommerce(app *zip.App, deps cloud.Deps) error {
 		commercebilling.RunAutoRechargeAllOrgs,
 	)

+	// GET /v1/billing/plans — the public tier catalog the console renders. commerce's
+	// legacy api.Route() billing bundle (ListPlans, invoices, subscriptions, …) is NOT
+	// registered by the co-resident embed: setupRoutes wires only /v1/commerce/*, so
+	// /v1/billing/plans has NO handler in this binary. The account bridge's
+	// /v1/billing/* wildcard (order 122) then forwards the read BACK to commerce at
+	// COMMERCE_URL — which defaults to the public api.hanzo.ai edge — re-entering the
+	// same bridge in an unbounded self-dispatch loop that surfaces as a 502
+	// ("commerce unreachable: Get https://api.hanzo.ai/v1/billing/plans"). Registering
+	// the static ListPlans handler HERE (order 100, ahead of the bridge) shadows that
+	// wildcard and serves plans in-process — the same co-resident move billing.go makes
+	// for usage/balance. RequestContext supplies the namespaced context promo.Active reads.
+	app.Get("/v1/billing/plans", commercemid.RequestContext(), commercebilling.ListPlans)
+
+	// The rest of the console's billing READS, served co-resident for the SAME reason
+	// plans is: commerce's api.Route() billing bundle is never compiled here, so without
+	// these registrations every one of them falls through to the account bridge's
+	// /v1/billing/* wildcard, which forwards to COMMERCE_URL — the public api.hanzo.ai
+	// edge, which is THIS binary — and self-dispatches into a 502 loop. In prod there is
+	// no separate commerce backend to point COMMERCE_URL at (the in-cluster `commerce`
+	// Service selects the cloud pods), so co-residence is the only way to break the loop.
+	//
+	// Chain: RequestContext (gated context) → IAMTokenRequired (resolves the org from the
+	// gateway-validated X-Org-Id into Locals("organization"), the namespace commerce's
+	// GetOrganization reads) → PinBillingSubject (pins the caller's OWN billing subject
+	// into the query — the SAME isolation the bridge applies, so a read can never widen
+	// past the caller; fail-closed for an unvalidated caller) → the commerce handler. The
+	// specific paths shadow the bridge wildcard (order 100 < 122). payment-config is
+	// org-scoped, not subject-scoped, but PinBillingSubject is still the auth gate that
+	// keeps an unvalidated caller from reaching GetOrganization; its pinned (unused)
+	// subject params are ignored by that handler.
+	billingRead := []struct {
+		path string
+		h    zip.Handler
+	}{
+		{"/v1/billing/invoices", commercebilling.ListInvoices},
+		{"/v1/billing/invoices/:id/pdf", commercebilling.DownloadInvoicePDF},
+		{"/v1/billing/subscriptions", commercebilling.ListBillingSubscriptions},
+		{"/v1/billing/spend-alerts", commercebilling.ListSpendAlerts},
+		{"/v1/billing/payouts", commercebilling.ListPayouts},
+		{"/v1/billing/payment-config", commercebilling.GetPaymentConfig},
+	}
+	for _, r := range billingRead {
+		app.Get(r.path,
+			commercemid.RequestContext(),
+			iammiddleware.IAMTokenRequired(),
+			accountclient.PinBillingSubject(),
+			r.h,
+		)
+	}
+
+	// GET /v1/billing/spend-alerts/authorize — the per-request per-scope spend-CAP
+	// VERDICT the request-edge metering gate consumes (clients/metering scopeAuthorize,
+	// pathLimitsAuthorize). It is a SERVICE-token S2S read (COMMERCE_SERVICE_TOKEN +
+	// X-Org-Id), NOT a browser/IAM read — so it needs its OWN registration, distinct from
+	// the console billingRead block above: without a co-resident handler this authorize
+	// fell through to the account bridge's /v1/billing/* wildcard (order 122), which — being
+	// service-token-forwardable (billing.go billingForwardable) — re-forwarded it to
+	// COMMERCE_URL (the public api.hanzo.ai edge = THIS binary) over commerceinproc's
+	// self-routing transport, re-entering the same wildcard until the depth-8 guard refused
+	// → 502 → the gate fails OPEN (the cap is a policy overlay, so no traffic was blocked,
+	// but ~135 502s/30m spammed the money path and each burned 8 full-app dispatches). The
+	// plain GET /v1/billing/spend-alerts (registered above) already broke this loop for the
+	// CRUD read; this closes the /authorize sibling the metering gate hits on every call.
+	//
+	// Chain mirrors commerce's OWN gate on this route (api/billing/handlers.go: the `billing`
+	// group's userRequired = TokenRequired) plus the RequestContext the standalone supplies
+	// globally — NOT the IAM/PinBillingSubject console chain: a raw service token is not an
+	// IAM JWT, so IAMTokenRequired would leave GetOrganization unset and AuthorizeSpendCap
+	// would 500. TokenRequired authenticates the service token AND resolves the tenant from
+	// the gateway-pinned X-Org-Id into Locals("organization"), which AuthorizeSpendCap reads.
+	// The specific route shadows the bridge wildcard (order 100 < 122). No PlatformOnly:
+	// authorize is a per-org cap read, not a cross-org mint (unlike auto-recharge/run-all).
+	app.Get("/v1/billing/spend-alerts/authorize",
+		commercemid.RequestContext(),
+		commercemid.TokenRequired(),
+		commercebilling.AuthorizeSpendCap,
+	)
+
+	// Self-service spend-cap CRUD WRITES — the customer half of the cap: a customer
+	// (or the admin S2S) CREATES / EDITS / REMOVES their own usage caps. These are the
+	// write siblings of the co-resident GET /v1/billing/spend-alerts list; without their
+	// own registration they too fell through the account bridge's /v1/billing/* wildcard
+	// (billingForwardable includes POST spend-alerts) into the SAME 502 self-dispatch loop
+	// authorize hit — so a customer could not set a cap AT ALL in the unified binary
+	// (POST/PATCH/DELETE all 502'd). Same chain commerce's own route table gates them with
+	// (api/billing/handlers.go:322-325, the `user` group's userRequired = TokenRequired) +
+	// the global RequestContext — an IAM JWT OR the COMMERCE_SERVICE_TOKEN, org resolved
+	// from the gateway-pinned X-Org-Id into Locals("organization"). Org-scoped by that
+	// namespace (a caller only ever writes their OWN org's caps; a foreign :id is a
+	// not-found miss in the caller's namespace), so no PinBillingSubject — spend-alerts are
+	// org-level, not billing-subject-level. Shadow the bridge wildcard (order 100 < 122).
+	// A spend cap is a FINANCIAL SAFETY control, so its writes are gated to an ORG ADMIN
+	// (or SuperAdmin, or the trusted S2S service token for the SuperAdmin cap-oversight
+	// Forward) — never any authenticated member. commerce's own `user` group admits any
+	// member, which would let a compromised member key DELETE the org's cap (→ unbounded
+	// spend) or POST a 1¢ enforce cap (→ org-wide 402 DoS). requireSpendCapAdmin closes that.
+	app.Post("/v1/billing/spend-alerts",
+		commercemid.RequestContext(),
+		commercemid.TokenRequired(),
+		requireSpendCapAdmin(),
+		commercebilling.CreateSpendAlert,
+	)
+	app.Patch("/v1/billing/spend-alerts/:id",
+		commercemid.RequestContext(),
+		commercemid.TokenRequired(),
+		requireSpendCapAdmin(),
+		commercebilling.UpdateSpendAlert,
+	)
+	app.Delete("/v1/billing/spend-alerts/:id",
+		commercemid.RequestContext(),
+		commercemid.TokenRequired(),
+		requireSpendCapAdmin(),
+		commercebilling.DeleteSpendAlert,
+	)
+
+	// POST /v1/billing/topup/token — the INLINE Square card top-up (the console's
+	// "Billing → Credits → add credits": the Square Web Payments SDK tokenizes the card
+	// IN THE BROWSER → a single-use nonce → this endpoint charges it and credits the
+	// caller's balance). commerce's api.Route() billing bundle is NOT compiled into the
+	// co-resident embed, so — exactly like plans/invoices/spend-alerts above — without
+	// this registration the POST fell through to the account bridge's /v1/billing/*
+	// wildcard (order 122). That wildcard is service-token-forwardable for topup/token
+	// (billing.go billingForwardable), so billingData re-forwarded it to COMMERCE_URL
+	// (default the public api.hanzo.ai edge = THIS binary) over commerceinproc's
+	// self-routing transport, re-entering the SAME wildcard until the depth-8 guard
+	// refused → the "commerceinproc: in-process dispatch depth 8 exceeded" 502 that broke
+	// top-up outright. Registering commerce's real TopupWithToken co-resident here
+	// (order 100 < 122) shadows the wildcard and serves the charge in-process at depth 1
+	// — no HTTP hop, no self-dispatch. topup/token STAYS in billingForwardable as the
+	// split-deploy fallback (a standalone commerce still serves it); co-residence just
+	// wins first.
+	//
+	// Chain — the browser money-WRITE posture, byte-for-byte what the bridge applied:
+	//   RequireCSRF        — the ambient-cookie anti-CSRF gate the bridge's requireCSRF
+	//                        wrapped POST /v1/billing/* with (a Bearer/gateway caller is
+	//                        not CSRF-able; an ambient-cookie write needs the token).
+	//   RequestContext     — the gated request context commerce's handler + ledger read.
+	//   IAMTokenRequired   — resolves the org from the gateway-validated X-Org-Id into
+	//                        Locals("organization"), which TopupWithToken.GetOrganization
+	//                        + topupDestination read as the org billing key.
+	//   PinBillingSubject  — pins ?user= to the caller's OWN account.Payer subject (the
+	//                        SAME rule the ai spend-gate debits and billingData pins), so
+	//                        the credit lands on the caller's subject (person=org/name) and
+	//                        can never be widened; fail-closed for an unvalidated caller —
+	//                        the IDOR boundary stays exactly where billingData put it.
+	// The card PAN never touches this binary: TopupWithToken charges the Square nonce only,
+	// and the settled charge itself is the mint authority (mintauth.WithAuthorized).
+	app.Post("/v1/billing/topup/token",
+		accountclient.RequireCSRF(),
+		commercemid.RequestContext(),
+		iammiddleware.IAMTokenRequired(),
+		accountclient.PinBillingSubject(),
+		commercebilling.TopupWithToken,
+	)
+
+	// The remaining console billing WRITES that share topup/token's self-dispatch loop
+	// class — each is a POST the console makes (billingForwardable in billing.go), each had
+	// NO co-resident handler, so each fell through to the account bridge's /v1/billing/*
+	// wildcard (order 122) and re-entered it over commerceinproc until the depth-8 guard
+	// refused (the same "in-process dispatch depth 8 exceeded" 502 that broke top-up). Each
+	// commerce handler exists in the vendored module (v1.49.13); registering them co-resident
+	// (order 100 < 122) shadows the wildcard and serves the write in-process at depth 1. They
+	// STAY in billingForwardable as the split-deploy fallback (same precedent as topup/token
+	// + spend-alerts). Chain matches the bridge's write posture byte-for-byte:
+	//
+	//   - RequireCSRF        — the ambient-cookie anti-CSRF gate the bridge wrapped POST
+	//                          /v1/billing/* with (Bearer/gateway callers are not CSRF-able).
+	//   - RequestContext     — the gated request context commerce's handlers read.
+	//   - IAMTokenRequired   — resolves the org from the gateway-validated X-Org-Id into
+	//                          Locals("organization") — the namespace GetOrganization reads.
+	//   - PinBillingSubject  — pins the caller's OWN account.Payer subject into BOTH query and
+	//                          body AND fail-closes an unvalidated caller. It is the auth gate
+	//                          on every one, and the IDOR control on the subject-scoped one.
+	//
+	// payment-methods (save a card-on-file / vault a Square nonce) is SUBJECT-scoped: commerce's
+	// CreatePaymentMethod reads `customerId` from the BODY, so PinBillingSubject's body-pin is
+	// load-bearing here — a member can only vault a card for their OWN subject, exactly the
+	// boundary billingData's scopedBillingBody enforced. The Square nonce goes to Square; the
+	// PAN never touches this binary.
+	app.Post("/v1/billing/payment-methods",
+		accountclient.RequireCSRF(),
+		commercemid.RequestContext(),
+		iammiddleware.IAMTokenRequired(),
+		accountclient.PinBillingSubject(),
+		commercebilling.CreatePaymentMethod,
+	)
+
+	// subscriptions/:id/{cancel,reactivate} are org-NAMESPACE-scoped: commerce's handlers
+	// resolve the subscription by `:id` WITHIN the caller's org namespace (a foreign org's id
+	// is a 404 miss), so tenancy is the namespace IAMTokenRequired resolves and PinBillingSubject
+	// is the fail-closed-anon auth gate — its pinned subject params are ignored by these
+	// handlers (the SAME role it plays for the org-scoped payment-config read). The bridge's
+	// subject-pin was likewise a no-op for these, so nothing is dropped.
+	app.Post("/v1/billing/subscriptions/:id/cancel",
+		accountclient.RequireCSRF(),
+		commercemid.RequestContext(),
+		iammiddleware.IAMTokenRequired(),
+		accountclient.PinBillingSubject(),
+		commercebilling.CancelBillingSubscription,
+	)
+	app.Post("/v1/billing/subscriptions/:id/reactivate",
+		accountclient.RequireCSRF(),
+		commercemid.RequestContext(),
+		iammiddleware.IAMTokenRequired(),
+		accountclient.PinBillingSubject(),
+		commercebilling.ReactivateBillingSubscription,
+	)
+
 	// In-process seams:
 	//   - commerceinproc routes the S2S billing byte-stream into the co-resident
 	//     app (the metering debit path) instead of a socket to a standalone pod.
@@ -164,6 +415,19 @@ func mountCommerce(app *zip.App, deps cloud.Deps) error {
 	commerceinproc.SetApp(app)
 	commerceclient.PublishEmbedded(embedded)

+	// Usage-cap enforcement on the FINANCE path. The unified binary records usage in
+	// the finance ledger (fin.RecordUsage), NOT commerce's transaction store — which
+	// it leaves empty — so the cap must read spend from, and fire alerts on, the
+	// finance ledger. Two seams, both org-wide (the finance Entry carries no scope;
+	// per-scope caps are a follow-up):
+	//   - SetPeriodSpendReader: AuthorizeSpendCap's scopeSpentCents reads the org's
+	//     finance period spend instead of the empty commerce transaction ledger, so
+	//     a real LLM request increments the cap's `spent` and trips the 402.
+	//   - SetUsageHook: after each finance debit, fire the org's spend-alerts on the
+	//     SAME crossing (the alert half), reading the same finance spend + debouncing.
+	commercebilling.SetPeriodSpendReader(financePeriodSpend)
+	financeclient.SetUsageHook(fireCapAlert)
+
 	lg.Info("commerce embedded natively (hanzoai/commerce module on the shared zip app)",
 		"data_dir", dataDir,
 		"brand", deps.Brand,
@@ -215,3 +479,57 @@ func mountCommerceFailClosed(app *zip.App) {
 		app.All(p+"/*", failed)
 	}
 }
+
+// financePeriodSpend is the usage-cap's period-spend source (injected into commerce
+// via SetPeriodSpendReader). It returns the org's finance-ledger usage in cents since
+// the start of the CURRENT UTC month — the window the cap resets on (mirrors
+// commerce periodStartUTC). Org-wide: the finance Entry carries no project/service,
+// so scope args are ignored and the org total is returned (what the covering
+// org-wide spend-alert row binds on). A finance impl without the sum capability, or a
+// split deploy (no co-resident finance), reports 0 — the cap can never over-count.
+func financePeriodSpend(ctx context.Context, org string, test bool, _, _ string) (int64, error) {
+	fin := financeclient.Current()
+	if fin == nil {
+		return 0, nil
+	}
+	summer, ok := fin.(interface {
+		SumUsageSince(context.Context, string, bool, int64) (int64, error)
+	})
+	if !ok {
+		return 0, nil
+	}
+	n := time.Now().UTC()
+	since := time.Date(n.Year(), n.Month(), 1, 0, 0, 0, 0, time.UTC).Unix()
+	return summer.SumUsageSince(ctx, org, test, since)
+}
+
+// fireCapAlert fires the org's spend-alerts after a finance usage debit — the alert
+// half of the cap on the finance path (wired via finance.SetUsageHook). It resolves
+// the org's commerce datastore (where the spend-alert rows live) and calls the
+// exported commerce trigger, which reads the org's period spend via financePeriodSpend
+// and stamps/debounces. Detached + best-effort; never blocks the money path. Runs in
+// its own goroutine (the hook is invoked with `go`), so a background context is right.
+func fireCapAlert(org string, test bool, project, service string) {
+	if strings.TrimSpace(org) == "" {
+		return
+	}
+	ctx := commercensctx.WithNamespace(context.Background(), org)
+	db := commercedatastore.New(ctx)
+	commercebilling.FireSpendAlerts(ctx, db, org, test, project, service, nil)
+}
+
+// requireSpendCapAdmin gates a spend-alert WRITE to a validated ORG ADMIN or platform
+// SuperAdmin (the unforgeable SanitizeIdentity-minted X-User-IsOrgAdmin / isAdmin bits),
+// OR the trusted in-proc S2S service token (the SuperAdmin cap-oversight Forward + internal
+// automation). A validated non-admin MEMBER is REFUSED (403): a spend cap is a financial
+// safety boundary — a member must not be able to delete the org's cap (→ unbounded spend)
+// or set a punitive 1¢ cap (→ org-wide 402 DoS). The read paths (list/authorize) stay
+// member/S2S-open; only the mutations require admin.
+func requireSpendCapAdmin() zip.Handler {
+	return func(c *zip.Ctx) error {
+		if principal.IsSuperAdmin(c) || principal.IsOrgAdmin(c) || accountclient.IsServiceToken(c) {
+			return c.Next()
+		}
+		return zip.ErrForbidden("org admin required to change spend caps")
+	}
+}
@@ -32,6 +32,8 @@ func TestCommercePrefixesPinned(t *testing.T) {
 		"/v1/billing/auto-recharge": false,
 		"/v1/billing/webhooks":      false,
 		"/v1/store":                 false,
+		"/v1/catalog":               false,
+		"/v1/plans":                 false,
 	}
 	for _, p := range commercePrefixes {
 		if _, ok := want[p]; ok {
@@ -84,6 +86,25 @@ func TestStoreSurfaceRoutedToCommerceNotAIGate(t *testing.T) {
 	if code, _ := doReq(t, app, http.MethodPut, "/v1/store/karma-store/listing/valentina"); code == http.StatusPaymentRequired {
 		t.Fatalf("PUT /v1/store/:id/listing/:slug fell through to the AI balance gate (402) — the whole store surface must be commerce-owned")
 	}
+
+	// The platform-admin catalog CMS (admin.hanzo.ai's editor) must reach commerce —
+	// where each handler is requireSuperAdmin-gated (anon → 401/403) — never the AI
+	// /v1/* balance gate, which would 402 the editor's list/edit instead.
+	if code, _ := doReq(t, app, http.MethodGet, "/v1/catalog/entries"); code == http.StatusPaymentRequired {
+		t.Fatalf("GET /v1/catalog/entries fell through to the AI balance gate (402) — /v1/catalog must be a commercePrefix so the SuperAdmin CMS reaches commerce")
+	}
+	if code, _ := doReq(t, app, http.MethodPut, "/v1/catalog/entries/cloud-starter"); code == http.StatusPaymentRequired {
+		t.Fatalf("PUT /v1/catalog/entries/:slug fell through to the AI balance gate (402) — the whole catalog CMS must be commerce-owned")
+	}
+
+	// The platform-admin plan authority CMS (increment 3a) must also reach commerce —
+	// requireSuperAdmin-gated (anon → 401/403) — never the AI /v1/* 402 gate.
+	if code, _ := doReq(t, app, http.MethodGet, "/v1/plans/entries"); code == http.StatusPaymentRequired {
+		t.Fatalf("GET /v1/plans/entries fell through to the AI balance gate (402) — /v1/plans must be a commercePrefix so the plan authority CMS reaches commerce")
+	}
+	if code, _ := doReq(t, app, http.MethodPut, "/v1/plans/entries/pro"); code == http.StatusPaymentRequired {
+		t.Fatalf("PUT /v1/plans/entries/:slug fell through to the AI balance gate (402) — the whole plan authority CMS must be commerce-owned")
+	}
 }

 // doReq drives one request through the mounted app and returns (status, body).
@@ -7,13 +7,15 @@ import (
 )

 // TestFrameworkContentModulesLinked guards the framework CONTENT modules
-// (cms/erp/help) against silent removal. They are not mount subsystems, so they
-// never appear in Wire(); they register their DocTypes and — for erp — the
-// ledger-posting lifecycle hooks into the framework engine from a package
-// init(), reached ONLY via the blank imports in apps.go. #248 dropped
-// those imports, which stripped the erp ledger hooks from the binary with no
-// mount change and no failing mount test. This asserts the engine's module
-// registry carries each lane, so that money-adjacent regression cannot recur.
+// (cms/erp/help) against silent removal. cms/erp are pure fixture lanes reached
+// ONLY via blank imports in apps.go; help is a real import + a Wire() spec (it also
+// mounts the /v1/help public plane) but still contributes its DocTypes the SAME way,
+// from a package init() (framework.RegisterModule). #248 dropped the blank imports,
+// which stripped the erp ledger hooks from the binary with no mount change and no
+// failing mount test. This asserts the engine's module registry carries each lane,
+// so that money-adjacent regression cannot recur — for help, dropping the import
+// would also drop its Wire() spec and fail TestWireOrderMatchesFrozen, but this keeps
+// the fixture-linkage guard uniform across all three lanes.
 func TestFrameworkContentModulesLinked(t *testing.T) {
 	got := make(map[string]bool)
 	for _, m := range framework.RegisteredModules() {
@@ -1,9 +1,20 @@
 package apps

 import (
+	"context"
+	"encoding/json"
+	"time"
+
+	"github.com/hanzoai/cloud/clients/ads"
+	"github.com/hanzoai/cloud/clients/automations"
+	"github.com/hanzoai/cloud/clients/campaign"
 	"github.com/hanzoai/cloud/clients/coding"
+	"github.com/hanzoai/cloud/clients/experiments"
+	"github.com/hanzoai/cloud/clients/framework"
 	"github.com/hanzoai/cloud/clients/git"
+	"github.com/hanzoai/cloud/clients/guide"
 	"github.com/hanzoai/cloud/clients/integrations"
+	"github.com/hanzoai/cloud/clients/principal"
 )

 // wire_seams.go wires cross-subsystem in-process seams that cannot be a MountSpec
@@ -20,4 +31,92 @@ import (
 // failures are non-fatal and dropped).
 func init() {
 	integrations.SetCodingDispatcher(coding.NewDispatcher(git.CloneURL, git.VerifyRef, nil))
+
+	// Guide growth-OBSERVE seam: the /v1/guide/profile observe layer reads the org's
+	// real platform truth through injected, org-scoped, honest-degrading probes.
+	// clients/guide imports NONE of these subsystems (decomplected), so the
+	// composition root — the ONE place that imports them all — binds the reads, the
+	// same injected-function pattern the coding dispatcher above uses. Each probe is
+	// PROVABLY org-scoped: framework.ModuleInstalled keys GetDocType on the org;
+	// integrations.Connected keys store.Get on the org and never surfaces the token.
+	// HasDeployment/RevenueCents/RecordCount are LEFT NIL: deploy is cluster/admin-
+	// scoped (not per-org) and commerce-revenue-of-record + the crm record count have
+	// no clean per-org in-process read yet — binding a read whose org-scoping we
+	// cannot guarantee would be the bug. Until a provably-org-scoped read lands their
+	// signals honest-degrade to not-present (the vocabulary is the contract; a nil
+	// seam can never be a spurious true).
+	guide.BindSignals(guide.Signals{
+		ModuleInstalled:  framework.ModuleInstalled,
+		ConnectorPresent: integrations.Connected,
+	})
+
+	// Inbound-event seam: a verified provider webhook (or chat channel) in
+	// clients/integrations fires the automations engine's Deliver here — the ONE place
+	// that imports both, so integrations never has to import automations (which imports
+	// it, for credential custody). A primitive-typed adapter keeps the seam free of the
+	// automations types.
+	integrations.SetAutomationTrigger(func(ctx context.Context, org, source, name, dedupeKey string, depth int, payload map[string]any) (int, error) {
+		return automations.Deliver(ctx, org, automations.TriggerEvent{
+			Source: source, Name: name, DedupeKey: dedupeKey, Depth: depth, Payload: payload,
+		})
+	})
+
+	// GTM PAID channel: the /v1/campaign orchestrator fans out to executors that
+	// satisfy campaign.Channel; the composition root is the ONE place that imports
+	// both campaign and the ad plane, so it adapts ads' connector-consuming
+	// execution funcs (provider.go — each resolves the org's ad token through
+	// integrations.TokenFor and fails closed) onto the primitive-typed channel
+	// seam. campaign never imports ads and ads never imports campaign — the same
+	// injected-function decoupling the coding dispatcher above uses.
+	campaign.RegisterChannel(campaign.NewChannel(campaign.KindPaid,
+		func(ctx context.Context, org string, p campaign.Plan) (campaign.Ref, error) {
+			r, err := ads.LaunchPaid(ctx, org, ads.PaidPlan{
+				Platform: p.Platform, Account: p.Account, Name: p.Name,
+				Objective: p.Objective, BudgetCents: p.BudgetCents, ScheduleAt: p.ScheduleAt,
+			})
+			return campaign.Ref{Platform: r.Platform, Account: r.Account, ExternalID: r.ExternalID, Status: r.Status, Detail: r.Detail}, err
+		},
+		func(ctx context.Context, org string, ref campaign.Ref) (int64, error) {
+			return ads.PaidSpend(ctx, org, ads.PaidRef{Platform: ref.Platform, Account: ref.Account, ExternalID: ref.ExternalID})
+		},
+		func(ctx context.Context, org string, ref campaign.Ref) error {
+			return ads.PausePaid(ctx, org, ads.PaidRef{Platform: ref.Platform, Account: ref.Account, ExternalID: ref.ExternalID})
+		},
+	))
+
+	// GTM creative A/B composes the merged EXPERIMENT primitive (clients/experiments)
+	// — campaign never reinvents bucketing or measurement. Assign resolves the
+	// subject's variant (creative) from the experiment's flag; Analyze is pull-model
+	// (it reads the metric from analytics itself), returned as opaque JSON so
+	// campaign stays decoupled from the analysis type. Campaign-linked experiments
+	// live in the org's default project. Both are nil-safe upstream: an org that
+	// never created a "campaign:<id>" experiment runs a single creative (Assign
+	// errors → "" → Content[0]).
+	campaign.SetExperiment(
+		func(ctx context.Context, org, experimentID, subject string) (string, error) {
+			a, err := experiments.Assign(ctx, org, principal.DefaultProject, experimentID, subject, nil)
+			if err != nil {
+				return "", err
+			}
+			return a.Variant, nil
+		},
+		func(ctx context.Context, org, experimentID string, start, end time.Time) (json.RawMessage, error) {
+			an, err := experiments.Analyze(ctx, org, principal.DefaultProject, experimentID, start, end, 0.05)
+			if err != nil {
+				return nil, err
+			}
+			return json.Marshal(an)
+		},
+	)
+
+	// GTM ORGANIC + EMAIL channels wire HERE the same way once their executors land
+	// (designed follow-ons — the publish rename + marketing email-connector wiring):
+	//
+	//   campaign.RegisterChannel(campaign.NewChannel(campaign.KindOrganic,
+	//       publish.Syndicate, publish.NoSpend, publish.Unpublish))   // social connectors
+	//   campaign.RegisterChannel(campaign.NewChannel(campaign.KindEmail,
+	//       marketing.Broadcast, marketing.NoSpend, marketing.Halt))  // email connectors
+	//
+	// Until wired, those channels record "unavailable" on a fan-out (honest) and a
+	// campaign runs a single creative — never a fabricated launch or variant.
 }
@@ -23,92 +23,107 @@ var frozen = []struct {
 	ownsHealth  bool
 	hasShutdown bool
 }{
-	{"pubsub", false, true},            // was order 5
-	{"kafka", false, true},             // was order 6
-	{"agentskills", false, false},      // was order 8
-	{"flags", true, true},              // was order 9; native engine: /v1/flags health + store shutdown
-	{"kms", true, false},               // was order 10
-	{"metrics", false, false},          // was order 40
-	{"ingress", false, true},           // was order 42
-	{"account", false, false},          // was order 48
-	{"iam", false, false},              // was order 50
-	{"base", true, true},               // was order 60; per-org embed added Shutdown (#298)
-	{"o11y", false, true},              // ONE observability subsystem (was co-owned orders 69+70): read plane + the hanzoai/o11y module wildcard folded in as MountO11y's terminal sub-mount. OwnsHealth=false keeps /v1/o11y/health the generic always-ok route the module co-entry used to trigger.
-	{"authz", false, false},            // was order 70
-	{"commerce", false, false},         // was order 100
-	{"licensing", false, false},        // was order 110
-	{"plans", true, false},             // was order 111
-	{"pricing", true, false},           // was order 112
-	{"storage", true, false},           // was order 118
-	{"provisioning", false, false},     // was order 120
-	{"billing", false, false},          // was order 121
-	{"account-bridge", false, false},   // was order 122
-	{"do", false, false},               // was order 123
-	{"platform", true, false},          // was order 124
-	{"projects", false, false},         // was order 125
-	{"prompts", false, false},          // was order 126
-	{"agents", false, true},            // was order 127
-	{"link", false, true},              // new: unified AI login manager (/v1/links), after agents
-	{"wallets", false, true},           // was order 127
-	{"x402", false, true},              // new: x402 pay-per-use settlement (after wallets)
-	{"paas", true, false},              // was order 128
-	{"deploy", true, false},            // after paas (release seam), before functions
-	{"functions", false, false},        // was order 128
-	{"tracker", false, false},          // was order 129
-	{"templates", false, false},        // was order 129
-	{"framework", false, true},         // was order 129
-	{"knowledge", false, false},        // was order 130
-	{"content", false, true},           // new: marketing content loop (after knowledge)
-	{"catalogsync", false, true},       // new: reverse loop (product.created → render) after content
-	{"ml", true, false},                // was order 130
-	{"usage", false, false},            // was order 131
-	{"crm", false, false},              // was order 131
-	{"marketing", false, true},         // new: marketing domain fold (after crm)
-	{"ads", false, true},               // new: ads domain fold (after crm)
-	{"social", false, true},            // new: /v1/social fold (after crm)
-	{"analytics", true, false},         // was order 132
-	{"git", false, false},              // was order 132
-	{"sync", false, true},              // /v1/sync engine (owns per-org DB handles → Shutdown)
-	{"visor", false, false},            // was order 133
-	{"captable", false, true},          // was order 133
-	{"code", false, true},              // was order 134
-	{"zero-trust", false, false},       // was order 134
-	{"dataroom", true, true},           // was order 134
-	{"graph", false, false},            // was order 135
-	{"security", true, true},           // was order 136
-	{"integrations", false, true},      // was order 137
-	{"sbom", true, false},              // was order 137
-	{"team", false, true},              // was order 138
-	{"settings", false, true},          // was order 138
-	{"notify", true, false},            // was order 139
-	{"gateway", false, false},          // was order 139
-	{"entitlements", false, true},      // was order 139
-	{"exec", false, false},             // was order 140
-	{"websearch", false, false},        // was order 141
-	{"world", false, true},             // was order 142
-	{"runtime", false, false},          // was order 143; was "bot" until the transport was named for what it is
-	{"authors", false, true},           // was order 143
-	{"bots", false, false},             // was order 143
-	{"audit", false, false},            // was order 144
-	{"affiliates", false, false},       // was order 144
-	{"sign", true, true},               // was order 145
-	{"product", false, false},          // was order 145
-	{"evals", false, false},            // was order 145
-	{"treasury", false, true},          // was order 146
-	{"admin", false, false},            // was order 146
-	{"tasks", false, false},            // was order 147
-	{"cron", false, false},             // durable platform cron on the shared engine (post-freeze add)
-	{"automations", false, true},       // was order 148
-	{"connectorruntime", false, false}, // new: native single-connector exec via goja (after automations, HIP-0126)
-	{"tools", false, true},             // new: unified tool plane (after automations)
-	{"marketplace", false, true},       // new: marketplace over the tool plane (after tools)
-	{"referrals", false, false},        // was order 149
-	{"guide", false, true},             // new: Business AI Guide (after referrals, before ai)
-	{"company", false, true},           // new: Hanzo Company formation state machine (after guide)
-	{"agent", false, false},             // new: /v1/agent tool-calling round (before zen/ai catch-all)
-	{"zen", false, false},              // zen* claim middleware before ai's catch-all (hip-00NN)
-	{"ai", false, false},               // was order 150
-	{"plugins", false, false},          // was order 900
+	{"pubsub", false, true},          // was order 5
+	{"kafka", false, true},           // was order 6
+	{"agentskills", false, false},    // was order 8
+	{"flags", true, true},            // was order 9; native engine: /v1/flags health + store shutdown
+	{"kms", true, false},             // was order 10
+	{"metrics", false, false},        // was order 40
+	{"ingress", false, true},         // was order 42
+	{"account", false, false},        // was order 48
+	{"iam", false, false},            // was order 50
+	{"base", true, true},             // was order 60; per-org embed added Shutdown (#298)
+	{"o11y", false, true},            // ONE observability subsystem (was co-owned orders 69+70): read plane + the hanzoai/o11y module wildcard folded in as MountO11y's terminal sub-mount. OwnsHealth=false keeps /v1/o11y/health the generic always-ok route the module co-entry used to trigger.
+	{"authz", false, false},          // was order 70
+	{"commerce", false, false},       // was order 100
+	{"licensing", false, false},      // was order 110
+	{"plan", true, false},            // was order 111; enable id normalized plans->plan (routes stay /v1/plans/*)
+	{"pricing", true, false},         // was order 112
+	{"storage", true, false},         // was order 118
+	{"provisioning", false, false},   // was order 120
+	{"billing", false, false},        // was order 121
+	{"rollingcap", false, false},     // rolling spend-cap gate (after billing); golden drifted — refrozen
+	{"account-bridge", false, false}, // was order 122
+	{"do", false, false},             // was order 123
+	{"platform", true, false},        // was order 124
+	{"projects", false, false},       // was order 125
+	{"dns", false, false},            // new: /v1/dns zone plane (after projects)
+	{"domain", false, false},         // new: Hanzo Domains registrar (/v1/domain), after dns
+	{"prompts", false, false},        // was order 126
+	{"agents", false, true},          // was order 127
+	{"link", false, true},            // new: unified AI login manager (/v1/links), after agents
+	{"wallets", false, true},         // was order 127
+	{"x402", false, true},            // new: x402 pay-per-use settlement (after wallets)
+	{"paas", true, false},            // was order 128
+	{"deploy", true, false},          // after paas (release seam), before functions
+	{"functions", false, false},      // was order 128
+	{"tracker", false, false},        // was order 129
+	{"templates", false, false},      // was order 129
+	{"framework", false, true},       // was order 129
+	{"knowledge", false, false},      // was order 130
+	{"help", false, false},           // new: Hanzo Support public plane /v1/help (after knowledge; framework lane with a companion subsystem, no store → no Shutdown)
+	{"content", false, true},         // new: marketing content loop (after knowledge)
+	{"catalogsync", false, true},     // new: reverse loop (product.created → render) after content
+	{"ml", true, false},              // was order 130
+	{"usage", false, false},          // was order 131
+	{"leaderboard", false, true},     // new: gamified usage analytics (after usage), owns opt-in SQLite (Shutdown)
+	{"crm", false, false},            // was order 131
+	{"marketing", false, true},       // new: marketing domain fold (after crm)
+	{"ads", false, true},             // new: ads domain fold (after crm)
+	{"campaign", false, true},        // new: /v1/campaign GTM orchestration (after ads); fans out to channels
+	{"validators", false, true},      // new: NFT-gated node provisioning (after ads); golden refrozen
+	{"social", false, true},          // new: /v1/social fold (after crm)
+	{"analytics", true, false},       // was order 132
+	{"git", false, false},            // was order 132
+	{"sync", false, true},            // /v1/sync engine (owns per-org DB handles → Shutdown)
+	{"visor", false, false},          // was order 133
+	{"venue", false, false},          // new: /v1/cloud connect-a-cloud-account plane (after visor); folds discovered clusters into the fleet
+	{"captable", false, true},        // was order 133
+	{"code", false, true},            // was order 134
+	{"zero-trust", false, false},     // was order 134
+	{"dataroom", true, true},         // was order 134
+	{"graph", false, false},          // was order 135
+	{"security", true, true},         // was order 136
+	{"integrations", false, true},    // was order 137
+	{"destinations", false, true},    // new: /v1/destinations CDP fan-out (after integrations, before cloudflare)
+	{"cloudflare", false, false},     // new: /v1/cloudflare edge plane (after integrations)
+	{"sbom", true, false},            // was order 137
+	{"team", false, true},            // was order 138
+	{"settings", false, true},        // was order 138
+	{"notify", true, false},          // was order 139
+	{"channels", false, true},        // new: /v1/channels transport plane (after notify; must mount after integrations so RegisterIngress installs before webhooks emit)
+	{"gateway", false, false},        // was order 139
+	{"entitlements", false, true},    // was order 139
+	{"exec", false, false},           // was order 140
+	{"websearch", false, false},      // was order 141
+	{"world", false, true},           // was order 142
+	{"runtime", false, false},        // was order 143; was "bot" until the transport was named for what it is
+	{"authors", false, true},         // was order 143
+	{"bots", false, false},           // was order 143
+	{"audit", false, false},          // was order 144
+	{"affiliates", false, false},     // was order 144
+	{"sign", true, true},             // was order 145
+	{"product", false, false},        // was order 145
+	{"evals", false, false},          // was order 145
+	{"benchmark", false, false},      // benchmark plane (after evals, before treasury)
+	{"research", false, true},        // R&D evidence plane + /research board (HIP-0512), arena sibling after benchmark; Shutdown closes per-org stores
+	{"experiments", false, true},     // unified A/B EXPERIMENT primitive: composes flags(assign)+analytics(measure)+research(evidence); Shutdown closes the registry stores
+	{"treasury", false, true},        // was order 146
+	{"admin", false, false},          // was order 146
+	{"admission", false, true},       // launch-control gate: composes flags (registry+seed+mode route+Enforce); Shutdown closes the registry store
+	{"tasks", false, false},          // was order 147; platform cron folded in as a sub-mount of tasks.Mount (was a separate entry)
+	{"automations", false, true},     // was order 148; connectorruntime (POST /v1/automations/connectors/:id/run) folded in as a sub-mount of automations.Mount
+	{"tools", false, true},           // new: unified tool plane (after automations)
+	{"marketplace", false, true},     // new: marketplace over the tool plane (after tools)
+	{"referrals", false, false},      // was order 149
+	{"guide", false, true},           // new: Business AI Guide (after referrals, before ai)
+	{"company", false, true},         // new: Hanzo Company formation state machine (after guide)
+	{"compliance", true, true},       // new: Hanzo Compliance — KYC/KYB + accreditation + audit posture (after company)
+	{"legal", true, true},            // new: Hanzo Legal — template + generation engine + e-sign/filing (after compliance)
+	{"agent", false, false},          // new: /v1/agent tool-calling round (before zen/ai catch-all)
+	{"zen", false, false},            // zen* claim middleware before ai's catch-all (hip-00NN)
+	{"ai", false, false},             // was order 150
+	{"plugins", false, false},        // was order 900
 }

 // TestWireOrderMatchesFrozen proves the composition root's mount order is
@@ -0,0 +1,64 @@
+// Copyright 2026 Hanzo AI Inc. All Rights Reserved.
+
+package apps
+
+import (
+	"context"
+	"errors"
+	"testing"
+)
+
+// stubKMS is a KMSClient whose GetSecret returns a sealed value when present or a
+// not-found error otherwise — mirroring the co-resident store that, in production,
+// holds no upstream provider keys (they are provisioned as KMS-injected env).
+type stubKMS struct{ sealed map[string]string }
+
+func (s stubKMS) GetSecret(_ context.Context, ref string) ([]byte, error) {
+	if v, ok := s.sealed[ref]; ok {
+		return []byte(v), nil
+	}
+	return nil, errors.New("secret not found")
+}
+func (stubKMS) PutSecret(context.Context, string, []byte) error      { return nil }
+func (stubKMS) Sign(context.Context, string, []byte) ([]byte, error) { return nil, nil }
+
+// TestZenKeyResolver_EnvFallback pins the production wiring: the upstream provider
+// key is provisioned as env (from the cloud-api-llm-keys secret), NOT sealed in the
+// co-resident KMS store, so a KMS miss must resolve to the env value rather than
+// returning "" (which would send an empty bearer upstream → provider 401).
+func TestZenKeyResolver_EnvFallback(t *testing.T) {
+	const env = "DO_AI_API_KEY"
+	t.Setenv(env, "env-provisioned-key")
+
+	// KMS store has no upstream keys (the real deployment state) — resolve from env.
+	if got := zenKeyResolver(stubKMS{})(context.Background(), env); got != "env-provisioned-key" {
+		t.Fatalf("KMS-miss: got %q, want env value", got)
+	}
+
+	// A nil KMS client (KMS disabled) — still resolve from env.
+	if got := zenKeyResolver(nil)(context.Background(), env); got != "env-provisioned-key" {
+		t.Fatalf("nil-KMS: got %q, want env value", got)
+	}
+}
+
+// TestZenKeyResolver_EnvTakesPrecedence pins the resolution ORDER: env is read
+// FIRST, then KMS — the same order ai uses on the prod hot path. The operator
+// injects provider keys as env from the KMS-synced secret, so the env is the live
+// value; the co-resident store is the fallback. A key present in BOTH surfaces
+// resolves to the env value.
+func TestZenKeyResolver_EnvTakesPrecedence(t *testing.T) {
+	const env = "ANTHROPIC_API_KEY"
+	t.Setenv(env, "env-key")
+	got := zenKeyResolver(stubKMS{sealed: map[string]string{env: "sealed-key"}})(context.Background(), env)
+	if got != "env-key" {
+		t.Fatalf("got %q, want env-key (env precedence)", got)
+	}
+}
+
+// TestZenKeyResolver_AbsentEverywhere keeps the fail-fast contract: absent from both
+// surfaces resolves to "" so zen refuses rather than serving for free.
+func TestZenKeyResolver_AbsentEverywhere(t *testing.T) {
+	if got := zenKeyResolver(stubKMS{})(context.Background(), "MISSING_KEY_XYZ"); got != "" {
+		t.Fatalf("got %q, want empty", got)
+	}
+}
@@ -1,50 +0,0 @@
-// Copyright 2026 The Hanzo Authors. All Rights Reserved.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//      http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package cloud
-
-import (
-	"os"
-	"testing"
-)
-
-// TestJWTAudiences_AcceptsAdminGuard is the operator-cockpit keystone. The
-// admin.hanzo.ai forward-auth guard is the confidential client `hanzo-admin-guard`,
-// so IAM mints its access tokens with aud=hanzo-admin-guard (each app's aud is its
-// client_id). The guard forwards that bearer to cloud-api /v1/admin/*; the identity
-// sanitizer only grants SuperAdmin (owner==adminOrg) to a VALIDATED principal, and
-// validation enforces this audience allowlist. If hanzo-admin-guard is not accepted
-// the token resolves anonymous and the SuperAdmin gate reads false -> 403, even
-// though the token's owner IS admin. Pin the client_id into the baked default so the
-// forwarded bearer validates.
-func TestJWTAudiences_AcceptsAdminGuard(t *testing.T) {
-	os.Unsetenv("CLOUD_JWT_AUDIENCES")
-	os.Unsetenv("GATEWAY_ALLOWED_AUDIENCES")
-
-	has := func(list []string, v string) bool {
-		for _, s := range list {
-			if s == v {
-				return true
-			}
-		}
-		return false
-	}
-
-	if !has(defaultJWTAudiences, "hanzo-admin-guard") {
-		t.Fatalf("defaultJWTAudiences must include hanzo-admin-guard (the admin-cockpit guard client_id); got %v", defaultJWTAudiences)
-	}
-	if !has(jwtAudiencesFromEnv(), "hanzo-admin-guard") {
-		t.Fatalf("resolved JWT audiences must include hanzo-admin-guard; got %v", jwtAudiencesFromEnv())
-	}
-}
@@ -1,47 +0,0 @@
-// Copyright 2026 The Hanzo Authors. All Rights Reserved.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//      http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package cloud
-
-import (
-	"os"
-	"testing"
-)
-
-// TestJWTAudiences_AcceptsHanzoWorld pins the world.hanzo.ai OIDC client. IAM
-// mints world's access tokens with aud=hanzo-world (each app's aud is its
-// client_id). Those bearers hit cloud-api; the identity sanitizer only trusts a
-// principal whose aud is in this allowlist. If hanzo-world is not accepted the
-// token resolves anonymous and the analyst's api.hanzo.ai calls 401. Pin the
-// client_id into the baked default so the forwarded bearer validates.
-func TestJWTAudiences_AcceptsHanzoWorld(t *testing.T) {
-	os.Unsetenv("CLOUD_JWT_AUDIENCES")
-	os.Unsetenv("GATEWAY_ALLOWED_AUDIENCES")
-
-	has := func(list []string, v string) bool {
-		for _, s := range list {
-			if s == v {
-				return true
-			}
-		}
-		return false
-	}
-
-	if !has(defaultJWTAudiences, "hanzo-world") {
-		t.Fatalf("defaultJWTAudiences must include hanzo-world (the world.hanzo.ai client_id); got %v", defaultJWTAudiences)
-	}
-	if !has(jwtAudiencesFromEnv(), "hanzo-world") {
-		t.Fatalf("resolved JWT audiences must include hanzo-world; got %v", jwtAudiencesFromEnv())
-	}
-}
@@ -37,10 +37,10 @@ type keyResolver interface {
 // A brief cache keeps the hot auth path off the network; it caches misses too, so a
 // bad key cannot hammer IAM.
 type iamKeys struct {
-	base   string
-	auth   string // client_secret_basic, or "" when unconfigured
-	http   *http.Client
-	cache  cache[string, *idClaims]
+	base  string
+	auth  string // client_secret_basic, or "" when unconfigured
+	http  *http.Client
+	cache cache[string, *idClaims]
 }

 // newIAMKeys reads the same IAM env clients/account does. With no confidential
@@ -55,6 +55,52 @@ func newIAMKeys() *iamKeys {
 	}
 }

+// sharedKeys memoizes ONE API-key resolver (and its 60s cache) for the whole
+// binary. The identity boundary (SanitizeIdentity, via newIdentityValidator) and
+// any subsystem that must resolve a key OUT-OF-BAND of the Authorization header
+// (analytics capture: a project key posted in the SDK body/query) both go through
+// this ONE seam, so a key resolves to the SAME org either way and IAM sees one
+// warm cache — never a second, drifting resolver.
+var (
+	sharedKeysOnce sync.Once
+	sharedKeysInst *iamKeys
+)
+
+func sharedKeys() *iamKeys {
+	sharedKeysOnce.Do(func() { sharedKeysInst = newIAMKeys() })
+	return sharedKeysInst
+}
+
+// maxKeyOrgLen bounds a resolved org key the same way principal.MaxOrgLen does: the
+// org becomes a warehouse partition key, so an over-long value (malformed / hostile)
+// is refused rather than stored.
+const maxKeyOrgLen = 128
+
+// OrgForKey resolves an opaque Hanzo API key (hk-/sk-/pk-/fw_/hz_) to the org it
+// belongs to — the SAME owner org SanitizeIdentity mints when that key arrives as a
+// bearer — through the ONE IAM key seam (get-user?accessKey). It is the exported
+// door a keyed, bearer-less SDK path uses to attribute a project key to a tenant.
+//
+// FAILS CLOSED: ("", false) for a non-key-shaped string, an unknown/unresolvable
+// key, an unconfigured resolver, or an out-of-bounds org — never a fabricated or
+// default tenant, so a bad key can never be written into another org's partition.
+// The isAPIKey prefix gate keeps garbage strings off the IAM network path.
+func OrgForKey(ctx context.Context, key string) (string, bool) {
+	key = strings.TrimSpace(key)
+	if !isAPIKey(key) {
+		return "", false
+	}
+	claims := sharedKeys().resolve(ctx, key)
+	if claims == nil {
+		return "", false
+	}
+	owner := strings.TrimSpace(claims.Owner)
+	if owner == "" || len(owner) > maxKeyOrgLen {
+		return "", false
+	}
+	return owner, true
+}
+
 // iamHost is the standalone IAM origin cloud talks to; iamCred is the service
 // credential (client_secret_basic) it presents — the ONE IAM identity, shared by
 // the API-key resolver here and the /v1/iam edge (iam_edge.go), so both
@@ -33,6 +33,7 @@ import (
 	"github.com/go-jose/go-jose/v4/jwt"

 	"github.com/hanzoai/cloud/clients/principal"
+	model "github.com/hanzoai/iam/pkg/model"
 )

 // idClaims is the subset of Hanzo IAM JWT claims the identity sanitizer needs.
@@ -40,12 +41,14 @@ import (
 type idClaims struct {
 	jwt.Claims

-	Owner             string `json:"owner"`              // org slug (the org)
-	Project           string `json:"project"`            // org SUB-SCOPE within owner (empty ⟹ default project)
-	Name              string `json:"name"`               // display name (id fallback)
-	PreferredUsername string `json:"preferred_username"` // id fallback
-	Email             string `json:"email"`
-	IsAdmin           bool   `json:"isAdmin"`
+	Owner             string       `json:"owner"`              // org slug (the org)
+	Project           string       `json:"project"`            // org SUB-SCOPE within owner (empty ⟹ default project)
+	BillingAccount    string       `json:"billing_account"`    // WHO PAYS, stated by IAM (empty ⟹ pre-claim token)
+	Name              string       `json:"name"`               // display name (id fallback)
+	PreferredUsername string       `json:"preferred_username"` // id fallback
+	Email             string       `json:"email"`
+	IsAdmin           bool         `json:"isAdmin"`
+	Orgs              []model.OrgRef `json:"orgs"` // membership SET (home first); empty on legacy tokens
 }

 // mintedProject returns the project id to stamp into X-Project-Id, or "" when the
@@ -62,6 +65,20 @@ func (c *idClaims) mintedProject() string {
 	return strings.TrimSpace(c.Project)
 }

+// mintedBillingAccount returns the funding account to stamp into
+// X-Billing-Account-Id, or "" when the header must be OMITTED (a token minted
+// before IAM shipped the claim, or one IAM could not attribute).
+//
+// WHO PAYS IS NOT A CLIENT'S TO NAME. This rides the validated `billing_account`
+// claim — IAM's signed statement, resolved at the identity boundary from the real
+// grant context — exactly like `owner` and `project`. It mirrors the edge
+// (iamauth.Claims.MintedBillingAccount) byte-for-byte, so the in-binary path binds
+// the same header the gateway would, and ai/object.Payer reads the same payer on
+// both. The raw client copy is deleted on ingress and NEVER restored.
+func (c *idClaims) mintedBillingAccount() string {
+	return strings.TrimSpace(c.BillingAccount)
+}
+
 // userID resolves the canonical user id: sub, then preferred_username, then
 // name. IAM may leave sub empty. This is the STABLE identifier (a UUID when IAM
 // sets sub) stamped as X-User-Id and consumed as the attribution key everywhere.
@@ -108,43 +125,41 @@ var jwtSigAlgs = []gojose.SignatureAlgorithm{
 // (cert-hanzo/cert-lux/cert-zoo/...), keyed by the token kid, so a single
 // jwksURL verifies all brands. Only the issuer-string comparison had to widen.
 type identityValidator struct {
-	issuers   []string
-	audiences []string
-	cache     *jwksCache
-	keys      keyResolver // resolves an opaque API key to a principal; nil ⟹ keys stay anonymous
+	issuers []string
+	cache   *jwksCache
+	keys    keyResolver // resolves an opaque API key to a principal; nil ⟹ keys stay anonymous
 }

 // newIdentityValidator builds a validator whose trusted-issuer set is the primary
 // issuer UNIONED with every white-label brand issuer (BrandIssuers) plus any
 // WHITELABEL_ISSUERS override. ttl<=0 uses the 15m JWKS default. The union is
 // fail-secure: it only ADDS the known-good brand issuers, never an arbitrary one.
-func newIdentityValidator(issuer, jwksURL string, audiences []string, ttl time.Duration) *identityValidator {
+//
+// Trust is IAM-native: signature (JWKS) + issuer (this set) + expiry. There is NO
+// per-app audience allowlist — the `aud` (a minting app's client_id) is IAM's to
+// assign, not cloud's to mirror, so a new first-party app needs zero cloud change.
+func newIdentityValidator(issuer, jwksURL string, ttl time.Duration) *identityValidator {
 	return &identityValidator{
-		issuers:   trustedIssuers(issuer),
-		audiences: audiences,
-		cache:     newJWKSCache(jwksURL, ttl),
-		keys:      newIAMKeys(),
+		issuers: trustedIssuers(issuer),
+		cache:   newJWKSCache(jwksURL, ttl),
+		keys:    sharedKeys(), // ONE resolver+cache, shared with OrgForKey (analytics capture)
 	}
 }

 // kmsMachineAudSuffix is the fixed suffix of a per-org PaaS-KMS sync machine
-// identity's audience. Each org's KMS sync authenticates as a dedicated,
-// NON-shared IAM application named "<org>-platform-kms" (Organization=<org>,
-// client_credentials grant), so IAM stamps the token's aud == the app's own
-// clientId == "<org>-platform-kms" (a non-shared app's audience is its clientId,
-// object/token_jwt.go tokenAudience) and owner == <org>
-// (object/token_oauth.go GetClientCredentialsToken sets owner = app.Organization).
+// identity's audience. Each org's KMS sync authenticates as a dedicated, NON-shared
+// IAM application named "<org>-platform-kms" (Organization=<org>, client_credentials
+// grant), so IAM stamps the token's aud == the app's own clientId == "<org>-platform-kms"
+// (object/token_jwt.go tokenAudience) and owner == <org> (object/token_oauth.go
+// GetClientCredentialsToken sets owner = app.Organization).
 //
-// That audience is, by construction, absent from CLOUD_JWT_AUDIENCES — it is
-// per-org, not a fixed app — which is EXACTLY why the sync stayed pending: the
-// machine token failed the audience check below, SanitizeIdentity treated it as
-// anonymous, and the /v1/kms org-scope guard 403'd it before the store. The fix is
-// to accept this one audience, but ONLY when it equals the token's OWN owner claim
-// plus this suffix, so it certifies "the KMS sync identity for its own org" and
-// grants nothing wider. Org-scoping is still enforced downstream by owner at the guard
-// (owner == :org); this only lets a legitimately-minted, owner-scoped machine token
-// clear validation. A per-org application means a per-org clientSecret — never
-// a shared platform-wide reader, which would be a cross-org hole.
+// Validation no longer consults the audience at all (trust is signature + issuer +
+// expiry), so a machine token clears validate() like any other. This suffix survives
+// for the OPPOSITE reason: to RECOGNISE a machine principal (isKMSMachinePrincipal) so
+// SanitizeIdentity can DENY it SuperAdmin even when it carries owner==adminOrg — a
+// client_credentials machine identity must never wield platform-admin. The match is
+// bound to the token's OWN owner claim (<owner>-platform-kms), so it certifies "the
+// KMS sync identity for its own org" and grants nothing wider.
 const kmsMachineAudSuffix = "-platform-kms"

 // kmsMachineAudience returns the audience an org org's PaaS-KMS sync identity
@@ -197,6 +212,15 @@ func (v *identityValidator) validate(raw string) (*idClaims, error) {
 		return nil, err
 	}

+	// Fail SECURE on a misconfigured (empty) trust set: with no trusted issuer every
+	// token must be REJECTED, never silently admitted. In production the set is always
+	// non-empty (the primary issuer + BrandIssuers, unioned in config.go so it is
+	// "never empty"), so this fires ONLY on an operator misconfiguration — and then it
+	// denies, it never admits (I2).
+	if len(v.issuers) == 0 {
+		return nil, fmt.Errorf("identity validator misconfigured: empty issuer set")
+	}
+
 	// Reject a missing issuer: an empty issuer must never pass the set check.
 	if claims.Issuer == "" {
 		return nil, fmt.Errorf("missing issuer")
@@ -207,29 +231,22 @@ func (v *identityValidator) validate(raw string) (*idClaims, error) {
 	if claims.Expiry == nil {
 		return nil, fmt.Errorf("missing expiry")
 	}
-	// Issuer must be one of the trusted brand issuers. go-jose's jwt.Expected
-	// checks a SINGLE issuer, so the issuer is validated here against the set and
-	// left out of Expected (audience + expiry stay with Expected).
+	// Issuer must be one of the trusted brand issuers. go-jose's jwt.Expected checks a
+	// SINGLE issuer, so the issuer is validated here against the set and left out of
+	// Expected (only expiry/not-before stay with Expected).
 	if !issuerAllowed(claims.Issuer, v.issuers) {
 		return nil, fmt.Errorf("untrusted issuer %q", claims.Issuer)
 	}
-	// Audience: the static allowlist (CLOUD_JWT_AUDIENCES / brand app client_ids)
-	// PLUS the per-org PaaS-KMS sync machine audience bound to THIS token's own
-	// owner (<owner>-platform-kms). The machine audience is added only when the
-	// allowlist is active (non-empty — always so in production) and only for the
-	// token's own org, so accepting it never widens org-scoping: the /v1/kms guard still
-	// gates on owner == :org. Without this, a real client_credentials machine token
-	// (aud == its per-org clientId, never in the allowlist) fails here and the
-	// sync silently stays pending — the activation blocker.
-	expected := jwt.Expected{}
-	if len(v.audiences) > 0 {
-		auds := v.audiences
-		if mach := kmsMachineAudience(claims.Owner); mach != "" {
-			auds = append(append(make([]string, 0, len(v.audiences)+1), v.audiences...), mach)
-		}
-		expected.AnyAudience = jwt.Audience(auds)
-	}
-	if err := claims.Claims.ValidateWithLeeway(expected, 2*time.Minute); err != nil {
+	// Audience is NOT an access gate. A valid signature from a trusted issuer (both
+	// checked above) proves IAM minted this token for one of ITS OWN registered apps;
+	// the `aud` merely names which app. Cloud does not keep a per-app allowlist to
+	// mirror IAM's registry — that mirror drifted and silently 401'd every new
+	// first-party app until hand-edited. Org scope is the `owner` claim, enforced by
+	// every downstream guard; SuperAdmin is owner==adminOrg AND !isKMSMachinePrincipal
+	// (SanitizeIdentity). Expiry + not-before are STILL enforced here: Expected{} with a
+	// zero Time validates against time.Now(); an empty AnyAudience skips ONLY the
+	// audience match (go-jose/v4 jwt/validation.go).
+	if err := claims.Claims.ValidateWithLeeway(jwt.Expected{}, 2*time.Minute); err != nil {
 		return nil, fmt.Errorf("claims: %w", err)
 	}
 	return &claims, nil
@@ -425,14 +442,11 @@ func trustedIssuers(primary string) []string {
 	return out
 }

-// issuerAllowed reports whether iss is one of the trusted issuers. An empty set
-// (no primary, no brands — never the case in production) skips the check, matching
-// the prior "empty issuer disables the check" behavior; a non-empty set is
-// fail-secure (a token whose iss is not in the set is rejected).
+// issuerAllowed reports whether iss is one of the trusted issuers. It is
+// fail-secure in BOTH directions: an empty trusted set matches NOTHING (deny), so
+// a misconfiguration that empties the issuer allowlist rejects every token instead
+// of silently disabling the check (I2); a non-empty set rejects any iss not in it.
 func issuerAllowed(iss string, trusted []string) bool {
-	if len(trusted) == 0 {
-		return true
-	}
 	for _, t := range trusted {
 		if iss == t {
 			return true
@@ -0,0 +1,52 @@
+package cloud
+
+import (
+	"crypto/rand"
+	"crypto/rsa"
+	"testing"
+	"time"
+)
+
+// TestValidate_AudienceIsNotAGate proves the IAM-native trust model: a token signed
+// by a trusted issuer validates REGARDLESS of its `aud` (the minting app's client_id).
+// Cloud keeps no per-app audience allowlist mirroring IAM's registry — so a brand-new
+// first-party app works with zero cloud change, and the specific app tokens the old
+// per-app tests pinned (admin-guard, world, team, commerce) are accepted by the SAME
+// rule as everything else. Trust is signature + issuer + expiry; org scope is the
+// owner claim, enforced downstream. Replaces the three audience_*_test.go files that
+// asserted a static allowlist which no longer exists.
+func TestValidate_AudienceIsNotAGate(t *testing.T) {
+	key, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("genkey: %v", err)
+	}
+	jwks := jwksServer(t, &key.PublicKey)
+	v := newIdentityValidator(testIssuer, jwks.URL, 0)
+	future := time.Now().Add(time.Hour)
+
+	// Every audience — the apps the deleted per-app tests pinned AND a never-registered
+	// one — validates identically, because aud is not an access gate.
+	for _, aud := range []string{
+		"hanzo-admin-guard", // admin.hanzo.ai forward-auth cockpit
+		"hanzo-world",       // world.hanzo.ai analyst tokens
+		"hanzo-team",        // hanzo.team wallet page
+		"hanzo-commerce",    // commerce.hanzo.ai admin AI assistant
+		"a-brand-new-first-party-app-never-listed-anywhere",
+	} {
+		tok := signWith(t, key, tokenClaims(aud, "acme", "", false, future))
+		id, err := v.validate(tok)
+		if err != nil {
+			t.Fatalf("aud=%q from a trusted issuer must validate (no allowlist), got %v", aud, err)
+		}
+		if id.Owner != "acme" {
+			t.Errorf("aud=%q: owner must be carried through, got %q", aud, id.Owner)
+		}
+	}
+
+	// Expiry is STILL enforced (dropping the aud gate must not disable time checks):
+	// a token expired beyond the 2m leeway is rejected whatever its aud.
+	expired := signWith(t, key, tokenClaims("hanzo-commerce", "acme", "", false, time.Now().Add(-time.Hour)))
+	if _, err := v.validate(expired); err == nil {
+		t.Error("expired token must be REJECTED even though audience is no longer gated")
+	}
+}
@@ -1,15 +1,15 @@
 package cloud

-// V6 (the activation blocker) — the identity validator must accept a per-org
-// PaaS-KMS sync machine token: a client_credentials JWT whose aud is the org's
-// own IAM application clientId "<owner>-platform-kms" (a per-org value, NEVER in
-// CLOUD_JWT_AUDIENCES) — but ONLY when that audience is bound to the token's OWN
-// owner claim. Before the fix the machine token failed the audience check,
-// SanitizeIdentity resolved anonymous, and the /v1/kms guard 403'd it, so the sync
-// silently stayed pending. These are white-box unit tests of validate() itself;
-// the end-to-end proof through SanitizeIdentity + the real guard lives in
-// clients/kms (v6_aud_e2e_test.go). Reuses the jwksServer/signWith/tokenClaims
-// helpers from middleware_identity_test.go (same package).
+// The per-org PaaS-KMS sync identity authenticates as its own IAM application
+// "<owner>-platform-kms" (client_credentials), so its token carries owner=<org> and
+// aud=<owner>-platform-kms. Validation no longer gates on the audience at all (trust
+// is signature + issuer + expiry), so a machine token clears validate() like any
+// other. The owner-bound machine aud survives only to IDENTIFY such a principal
+// (isKMSMachinePrincipal) so SanitizeIdentity can DENY it SuperAdmin even in the admin
+// org — a client_credentials machine identity must never wield platform-admin. These
+// are white-box unit tests of that identification; the end-to-end proof through
+// SanitizeIdentity + the real guard lives in clients/kms (v6_aud_e2e_test.go). Reuses
+// the jwksServer/signWith/tokenClaims helpers from middleware_identity_test.go.

 import (
 	"crypto/rand"
@@ -18,19 +18,16 @@ import (
 	"time"
 )

-func TestIdentityValidator_KMSMachineAudience(t *testing.T) {
+func TestIdentityValidator_KMSMachinePrincipal(t *testing.T) {
 	key, err := rsa.GenerateKey(rand.Reader, 2048)
 	if err != nil {
 		t.Fatalf("genkey: %v", err)
 	}
 	jwks := jwksServer(t, &key.PublicKey)
-	// The static allowlist deliberately contains NO *-platform-kms audience, so any
-	// acceptance below can come ONLY from the owner-bound machine-aud rule, not the
-	// allowlist — this is what makes it a fix and not a config workaround.
-	v := newIdentityValidator(testIssuer, jwks.URL, []string{"hanzo-console"}, 0)
+	v := newIdentityValidator(testIssuer, jwks.URL, 0)
 	future := time.Now().Add(time.Hour)

-	t.Run("machine token for its own org is accepted", func(t *testing.T) {
+	t.Run("own-org machine token validates and is recognised as a machine principal", func(t *testing.T) {
 		c, err := v.validate(signWith(t, key, tokenClaims("maxpower-platform-kms", "maxpower", "", false, future)))
 		if err != nil {
 			t.Fatalf("machine token rejected: %v", err)
@@ -38,34 +35,51 @@ func TestIdentityValidator_KMSMachineAudience(t *testing.T) {
 		if c.Owner != "maxpower" {
 			t.Fatalf("owner=%q, want maxpower", c.Owner)
 		}
-	})
-
-	t.Run("machine aud for a DIFFERENT org is rejected (owner-bound)", func(t *testing.T) {
-		// owner=maxpower but aud=acme-platform-kms: the accepted machine aud is bound
-		// to the token's OWN owner (maxpower-platform-kms), so this must fail — it is
-		// not a blanket "*-platform-kms" wildcard.
-		if _, err := v.validate(signWith(t, key, tokenClaims("acme-platform-kms", "maxpower", "", false, future))); err == nil {
-			t.Fatal("cross-org machine audience must be rejected (owner-bound)")
+		if !isKMSMachinePrincipal(c) {
+			t.Fatal("aud==<owner>-platform-kms must be recognised as a machine principal")
 		}
 	})

-	t.Run("arbitrary audience still rejected (fix is scoped, not a disable)", func(t *testing.T) {
-		if _, err := v.validate(signWith(t, key, tokenClaims("some-random-app", "maxpower", "", false, future))); err == nil {
-			t.Fatal("an arbitrary audience must still be rejected")
+	t.Run("admin-org machine token is recognised so SuperAdmin is denied", func(t *testing.T) {
+		c, err := v.validate(signWith(t, key, tokenClaims("admin-platform-kms", "admin", "", true, future)))
+		if err != nil {
+			t.Fatalf("admin machine token rejected: %v", err)
+		}
+		if !isKMSMachinePrincipal(c) {
+			t.Fatal("admin-org machine token must be recognised (SanitizeIdentity denies it SuperAdmin)")
 		}
 	})

-	t.Run("machine aud with empty owner is rejected (fail closed)", func(t *testing.T) {
-		// aud="-platform-kms" with owner="": kmsMachineAudience("")=="" so no machine
-		// audience is granted and the bare suffix is not in the allowlist.
-		if _, err := v.validate(signWith(t, key, tokenClaims("-platform-kms", "", "", false, future))); err == nil {
-			t.Fatal("machine aud with empty owner must be rejected")
+	t.Run("machine aud bound to a DIFFERENT org is not this owner's machine principal", func(t *testing.T) {
+		// owner=maxpower, aud=acme-platform-kms: the machine-principal match is bound to
+		// the token's OWN owner (maxpower-platform-kms), not a "*-platform-kms" wildcard.
+		// It validates (aud is not gated) and is owner-scoped to maxpower downstream.
+		c, err := v.validate(signWith(t, key, tokenClaims("acme-platform-kms", "maxpower", "", false, future)))
+		if err != nil {
+			t.Fatalf("token rejected: %v", err)
+		}
+		if isKMSMachinePrincipal(c) {
+			t.Fatal("a cross-org machine aud must not count as this owner's machine principal")
 		}
 	})

-	t.Run("normal static-allowlist token still accepted (regression)", func(t *testing.T) {
-		if _, err := v.validate(signWith(t, key, tokenClaims("hanzo-console", "maxpower", "", false, future))); err != nil {
-			t.Fatalf("static-allowlist token rejected: %v", err)
+	t.Run("ordinary app token is not a machine principal", func(t *testing.T) {
+		c, err := v.validate(signWith(t, key, tokenClaims("hanzo-console", "maxpower", "", false, future)))
+		if err != nil {
+			t.Fatalf("token rejected: %v", err)
+		}
+		if isKMSMachinePrincipal(c) {
+			t.Fatal("an ordinary app token is not a machine principal")
+		}
+	})
+
+	t.Run("empty-owner token is never a machine principal (fail closed)", func(t *testing.T) {
+		c, err := v.validate(signWith(t, key, tokenClaims("-platform-kms", "", "", false, future)))
+		if err != nil {
+			t.Fatalf("token rejected: %v", err)
+		}
+		if isKMSMachinePrincipal(c) {
+			t.Fatal(`empty-owner token must never be a machine principal (kmsMachineAudience("")=="")`)
 		}
 	})

@@ -1,10 +1,40 @@
 package cloud

 import (
+	"crypto/rand"
+	"crypto/rsa"
 	"os"
 	"testing"
+	"time"
 )

+// TestValidate_FailSecureOnEmptyTrustSet proves I2: a validator whose resolved
+// issuer set is empty REJECTS an otherwise-valid, correctly signed token — the axis
+// is never silently disabled. Production always resolves a non-empty set; this
+// guards the misconfiguration path (an empty issuer set), which must fail closed,
+// not open.
+func TestValidate_FailSecureOnEmptyTrustSet(t *testing.T) {
+	key, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatalf("genkey: %v", err)
+	}
+	jwks := jwksServer(t, &key.PublicKey)
+	future := time.Now().Add(time.Hour)
+	tok := signWith(t, key, tokenClaims("hanzo-console", "acme", "", false, future))
+
+	// Sanity: a properly configured validator accepts the token.
+	if _, err := newIdentityValidator(testIssuer, jwks.URL, 0).validate(tok); err != nil {
+		t.Fatalf("baseline valid token must be accepted, got %v", err)
+	}
+
+	// Empty issuer set → deny (construct directly; trustedIssuers never yields empty
+	// with a primary, so bypass it to exercise the guard).
+	vEmptyIss := &identityValidator{issuers: nil, cache: newJWKSCache(jwks.URL, 0), keys: newIAMKeys()}
+	if _, err := vEmptyIss.validate(tok); err == nil {
+		t.Error("empty issuer set must REJECT (fail-secure), not accept")
+	}
+}
+
 // TestTrustedIssuers_WhiteLabel proves the in-binary validator's trusted-issuer
 // set is the primary issuer UNIONED with every white-label brand issuer plus the
 // WHITELABEL_ISSUERS override, deduped, primary-first.
@@ -40,7 +70,8 @@ func TestTrustedIssuers_WhiteLabel(t *testing.T) {
 }

 // TestIssuerAllowed proves the set membership check: brand issuers pass, an
-// outsider is rejected, and an empty set (never in prod) skips the check.
+// outsider is rejected, and an empty set is fail-secure — it matches NOTHING (I2),
+// so a misconfiguration that empties the allowlist denies every token.
 func TestIssuerAllowed(t *testing.T) {
 	set := []string{"https://hanzo.id", "https://lux.id"}
 	if !issuerAllowed("https://lux.id", set) {
@@ -49,8 +80,8 @@ func TestIssuerAllowed(t *testing.T) {
 	if issuerAllowed("https://attacker.id", set) {
 		t.Error("attacker.id must be rejected")
 	}
-	if !issuerAllowed("anything", nil) {
-		t.Error("empty set must skip the check (matches prior empty-issuer behavior)")
+	if issuerAllowed("anything", nil) {
+		t.Error("empty set must DENY (fail-secure), never skip the check")
 	}
 }

@@ -76,7 +107,7 @@ func TestBrandIssuers(t *testing.T) {
 // full brand set, so a lux token would pass the issuer gate on the hanzo binary.
 func TestNewIdentityValidator_MultiIssuer(t *testing.T) {
 	os.Unsetenv("WHITELABEL_ISSUERS")
-	v := newIdentityValidator("https://hanzo.id", "http://iam.hanzo.svc/v1/iam/.well-known/jwks", []string{"hanzo-cloud", "lux-cloud"}, 0)
+	v := newIdentityValidator("https://hanzo.id", "http://iam.hanzo.svc/v1/iam/.well-known/jwks", 0)
 	if !issuerAllowed("https://lux.id", v.issuers) {
 		t.Fatalf("validator must trust the lux issuer, set=%v", v.issuers)
 	}
@@ -87,64 +118,3 @@ func TestNewIdentityValidator_MultiIssuer(t *testing.T) {
 		t.Fatalf("validator must reject an untrusted issuer, set=%v", v.issuers)
 	}
 }
-
-// TestBrandAudiences proves every brand's cloud audience (<brand>-cloud) is derived
-// from the brands registry — one source of truth, mirroring BrandIssuers.
-func TestBrandAudiences(t *testing.T) {
-	got := BrandAudiences()
-	for _, want := range []string{"hanzo-cloud", "lux-cloud", "zoo-cloud", "pars-cloud", "bootnode-cloud"} {
-		found := false
-		for _, g := range got {
-			if g == want {
-				found = true
-				break
-			}
-		}
-		if !found {
-			t.Errorf("BrandAudiences()=%v missing %q", got, want)
-		}
-	}
-}
-
-// TestJWTAudiencesFromEnv_BrandUnion proves the resolved audience allowlist ALWAYS
-// includes every brand's <brand>-cloud aud (so a lux token validates), whether the
-// list comes from the baked default or a hanzo-only env override — and that an
-// env-supplied entry is not duplicated.
-func TestJWTAudiencesFromEnv_BrandUnion(t *testing.T) {
-	has := func(list []string, v string) bool {
-		for _, s := range list {
-			if s == v {
-				return true
-			}
-		}
-		return false
-	}
-
-	// Baked default path (no env).
-	os.Unsetenv("CLOUD_JWT_AUDIENCES")
-	os.Unsetenv("GATEWAY_ALLOWED_AUDIENCES")
-	def := jwtAudiencesFromEnv()
-	for _, want := range []string{"hanzo-cloud", "lux-cloud", "zoo-cloud", "pars-cloud"} {
-		if !has(def, want) {
-			t.Errorf("baked audiences %v missing brand aud %q", def, want)
-		}
-	}
-
-	// A legacy hanzo-only env override must STILL accept lux-cloud (brand union),
-	// with no duplicate of the env-supplied hanzo-cloud.
-	os.Setenv("GATEWAY_ALLOWED_AUDIENCES", "hanzo-app,hanzo-console,hanzo-cloud")
-	defer os.Unsetenv("GATEWAY_ALLOWED_AUDIENCES")
-	got := jwtAudiencesFromEnv()
-	if !has(got, "lux-cloud") {
-		t.Fatalf("hanzo-only env override must still accept lux-cloud, got %v", got)
-	}
-	n := 0
-	for _, s := range got {
-		if s == "hanzo-cloud" {
-			n++
-		}
-	}
-	if n != 1 {
-		t.Fatalf("hanzo-cloud must appear exactly once (no duplicate), got %d in %v", n, got)
-	}
-}
@@ -137,19 +137,3 @@ func BrandIssuers() []string {
 	}
 	return out
 }
-
-// BrandAudiences returns the OAuth `aud` (== IAM client_id == app name) of every
-// white-label brand's cloud login app: `<brand>-cloud` (hanzo-cloud, lux-cloud,
-// zoo-cloud, pars-cloud, bootnode-cloud). A brand's session token carries
-// aud=<brand>-cloud (HIP-0111: client_id == app == aud), so the audience allowlist
-// must include each to accept a lux/zoo/pars token on the ONE binary. Derived from
-// the same `brands` registry as BrandIssuers — one source of truth, no hand-listing.
-func BrandAudiences() []string {
-	out := make([]string, 0, len(brands))
-	for id := range brands {
-		if id != "" {
-			out = append(out, id+"-cloud")
-		}
-	}
-	return out
-}
@@ -2,19 +2,24 @@ package cloud

 import (
 	"context"
+	"encoding/base64"
 	"fmt"
 	"os"
 	"strings"
+	"time"

 	aiobject "github.com/hanzoai/ai/object"
+	"github.com/hanzoai/cloud/cek"
 	"github.com/hanzoai/cloud/clients/commerceinproc"
 	"github.com/hanzoai/cloud/clients/metering"
+	"github.com/hanzoai/cloud/internal/org"
+	s3 "github.com/hanzoai/s3-go"
 	luxlog "github.com/luxfi/log"
 	"github.com/zap-proto/zip"

 	"github.com/hanzoai/cloud/clients"
 	"github.com/hanzoai/cloud/clients/finance"
-	"github.com/hanzoai/cloud/clients/gatewaypolicy"
+	"github.com/hanzoai/cloud/clients/gateway/edge"
 	"github.com/hanzoai/cloud/clients/money"
 	"github.com/hanzoai/cloud/clients/s3admin"
 	"github.com/hanzoai/cloud/types"
@@ -63,14 +68,15 @@ func BuildDeps(cfg *Config) Deps {
 	)

 	deps := Deps{
-		Logger:         logger,
-		Brand:          cfg.Brand,
-		Version:        cfg.Version,
-		Env:            cfg.Env,
-		Domain:         cfg.Domain,
-		IAMIssuer:      cfg.IAMIssuer,
-		DataDir:        cfg.DataDir,
-		AIDefaultModel: cfg.AIDefaultModel,
+		Logger:          logger,
+		Brand:           cfg.Brand,
+		Version:         cfg.Version,
+		Env:             cfg.Env,
+		Domain:          cfg.Domain,
+		IAMIssuer:       cfg.IAMIssuer,
+		DataDir:         cfg.DataDir,
+		AIDefaultModel:  cfg.AIDefaultModel,
+		AIFallbackModel: cfg.AIFallbackModel,
 	}

 	// For each subsystem: enabled → leave nil (Mount fills it); not
@@ -90,11 +96,19 @@ func BuildDeps(cfg *Config) Deps {
 	// commerce URL yields a !Enabled() client, so the wrap is a transparent
 	// pass-through and a dev deployment is never blocked.
 	deps.Metering = buildMeteringClient(cfg, logger)
-	deps.AI = meteredAIClient(pickAIClient(cfg, logger), deps)
+	wireTierReader(deps.Metering, logger)
+	// AI (completions, WRITE) and Embed (embeddings, READ-ONLY) are DISTINCT
+	// credentials by concern: completions never ride the read-only publishable
+	// (pk-) key — the gateway 403s a pk- key on any write endpoint — so deps.AI
+	// resolves to the M2M identity, while deps.Embed keeps the pk- key (correct
+	// least-privilege for a read-only call). Both meter through the ONE commerce path.
+	deps.AI = meteredAIClient(pickCompletionsClient(cfg, logger), deps)
+	deps.Embed = meteredAIClient(pickEmbedClient(cfg, logger), deps)
 	wireFinance(cfg, logger)
 	deps.O11y = pick(cfg, logger, "o11y", "O11y", cfg.O11yZAPAddr, clients.O11yRPCAt, clients.DisabledO11y)
 	deps.VFS = pickVFSClient(cfg, logger)
 	deps.MQ = pick(cfg, logger, "mq", "MQ", cfg.MQZAPAddr, clients.MQRPCAt, clients.DisabledMQ)
+	deps.Durable = buildDurability(cfg, logger)

 	// Payments and Vault never co-resident. Disabled stub when no
 	// endpoint, otherwise RPC.
@@ -107,7 +121,7 @@ func BuildDeps(cfg *Config) Deps {
 	// working *Store (static-only if the SQLite file can't open), so the edge
 	// middleware is never left without a policy source — a store-open error is
 	// logged, not fatal.
-	gp, err := gatewaypolicy.New(cfg.DataDir, cfg.AdminOrg, staticEdgePolicy(cfg))
+	gp, err := edge.New(cfg.DataDir, cfg.AdminOrg, staticEdgePolicy(cfg))
 	if err != nil {
 		logger.Warn("gateway policy store degraded to static-only", "err", err)
 	}
@@ -117,10 +131,10 @@ func BuildDeps(cfg *Config) Deps {
 }

 // staticEdgePolicy projects the static env/flag edge config into the boot-default
-// policy the gatewaypolicy.Store layers runtime overrides on top of. A disabled
+// policy the edge.Store layers runtime overrides on top of. A disabled
 // per-IP limiter (CLOUD_EDGE_RATELIMIT=false) maps to PerIPRPM 0 (a live no-op).
-func staticEdgePolicy(cfg *Config) gatewaypolicy.Policy {
-	p := gatewaypolicy.Policy{
+func staticEdgePolicy(cfg *Config) edge.Policy {
+	p := edge.Policy{
 		CORSOrigins: cfg.CORSOrigins,
 		WindowSec:   cfg.EdgeRateWindowSec,
 	}
@@ -157,9 +171,15 @@ func buildMeteringClient(cfg *Config, log luxlog.Logger) *metering.Client {
 		httpClient = commerceinproc.Client(0) // in-process dispatch; no network timeout
 	}
 	m, err := metering.New(metering.Config{
-		BaseURL:    base,
-		Token:      cfg.CommerceServiceToken,
-		Org:        cfg.Brand, // X-Org-Id default for S2S; per-request org overrides.
+		BaseURL: base,
+		Token:   cfg.CommerceServiceToken,
+		Org:     cfg.Brand, // X-Org-Id default for S2S; per-request org overrides.
+		// Honor the documented METERING_TEST env: when "true", route every debit to
+		// commerce's TEST/sandbox books (fin.RecordUsage in.Test=true) so a staging /
+		// canary deployment records NO real money — and the usage-cap read (org.TestMode
+		// via SQUARE_ENVIRONMENT=sandbox) sees the SAME test books. Unset in prod → live,
+		// unchanged. Without this the flag was silently ignored (always live).
+		Test:       strings.EqualFold(strings.TrimSpace(os.Getenv(metering.EnvTest)), "true"),
 		FailOpen:   cfg.BillingFailOpen,
 		HTTPClient: httpClient, // nil off the co-resident path → metering builds its own
 	})
@@ -169,6 +189,11 @@ func buildMeteringClient(cfg *Config, log luxlog.Logger) *metering.Client {
 		log.Error("billing: invalid commerce URL, gate disabled", "err", err)
 		m, _ = metering.New(metering.Config{})
 	}
+	// Observe every cap-check fail-open (timeout / slow / broken commerce) — a cap that
+	// silently allows must never be silent. The completion still proceeds (fail-open).
+	metering.OnCapError = func(err error) {
+		log.Warn("spend-cap check failed open (allowing completion) — commerce authorize slow/unavailable", "err", err)
+	}
 	if m.Enabled() {
 		log.Info("billing gate enabled", "commerce", boolStr(inProcess, "in-process", "http:"+base), "fail_open", cfg.BillingFailOpen)
 	} else {
@@ -184,6 +209,28 @@ func boolStr(b bool, t, f string) string {
 	return f
 }

+// wireTierReader installs the embedded ai module's per-tier SKU gate reader so it
+// resolves the caller's commerce subscription tier through the SAME co-resident
+// commerce client the metering gate bills over — in-process (commerceinproc) when
+// commerce is folded in, S2S HTTP with the service token otherwise — NEVER an authed
+// self-call to the cloud edge. That self-call is the toothless-gate bug: the edge
+// 401/403s a service call to /v1/billing/*, so the ai module's own HTTP lookup always
+// returned "" in-cluster and every tier-gated SKU failed OPEN. This mirrors
+// wireFinance's SetBalanceReader: cloud owns the co-resident read, ai stays
+// transport-agnostic. Fail-safe is preserved — Client.Tier folds a commerce error or
+// an unknown plan to "", which the gate treats as ALLOW, so a commerce blip never
+// locks out a paying caller. No-op when commerce is unreachable (metering !Enabled),
+// leaving ai's standalone HTTP fallback in place.
+func wireTierReader(m *metering.Client, log luxlog.Logger) {
+	if m == nil || !m.Enabled() {
+		return
+	}
+	aiobject.SetTierReader(func(ctx context.Context, subject, namespace string) (string, error) {
+		return m.Tier(ctx, subject, namespace)
+	})
+	log.Info("ai per-tier SKU gate wired to co-resident commerce (in-process tier read, fail-safe)")
+}
+
 // wireFinance constructs the ONE in-process finance ledger (per-org SQLite
 // double-entry prepaid wallet), publishes it for every money consumer to resolve by
 // the narrow finance.Client, and installs the embedded ai router's balance-read +
@@ -545,44 +592,76 @@ func RegisterCommerceClientFactory(f func(cfg *Config, log luxlog.Logger) Commer
 	commerceClientFactory = f
 }

-// pickAIClient resolves deps.AI — the client the agents subsystem runs chat
-// completions through. Unlike the co-resident subsystems, there is NO in-process
-// "ai" mount that fills a nil deps.AI: inference is an external gateway, so this
-// must return a concrete client, never nil. (A nil deps.AI was the live bug —
-// the default all-enabled config returned nil here and nothing ever filled it,
-// so every /v1/agents/:name/run 503'd "inference is not configured".)
+// publishableKey reports whether apiKey is a read-only PUBLISHABLE key (pk-). The
+// Hanzo gateway 403s a publishable key on any WRITE endpoint — "Publishable keys
+// can only access read-only endpoints … use a secret key (sk-)". So the COMPLETIONS
+// resolver must refuse it (it would only 403 chat), while the EMBED resolver accepts
+// it (embeddings ARE read-only). pk- is the IAM key family's read-only member
+// (hk-/sk-/pk-/fw_/hz_; clients/admission). This ONE predicate is the split's crux:
+// it kept the intermittent-403 bug — a pk- embed key riding the shared completions
+// client — from ever recurring, wherever the key comes from.
+func publishableKey(apiKey string) bool {
+	return strings.HasPrefix(strings.TrimSpace(apiKey), "pk-")
+}
+
+// pickCompletionsClient resolves deps.AI — the client the agents run path (and
+// guide/crm/content/sitegen/code /ask) execute CHAT COMPLETIONS through. There is
+// NO in-process "ai" mount that fills a nil deps.AI: inference is an external
+// gateway, so this returns a concrete client, never nil.
 //
+// Completions are a WRITE endpoint: a read-only publishable (pk-) key 403s them. So
+// this resolver NEVER rides a pk- key — that is the embed credential (pickEmbedClient).
 // Preference order:
-//  1. Static-key HTTP gateway when a base URL AND a static key are configured —
-//     an operator override / pre-provisioned key. The key is a KMS-injected
-//     secret; only the base URL and default model are ever logged.
+//  1. Static SECRET-key HTTP gateway when a base URL AND a completions-capable
+//     (non-pk-) static key are configured — an explicit operator override (sk-/hk-).
+//     A pk- key here is REFUSED (it would only 403 chat) and the resolver falls
+//     through to M2M — THE fix for the intermittent publishable-key 403 on bot replies.
 //  2. M2M HTTP gateway when a base URL AND the binary's IAM identity are present
-//     (the durable Hanzo default): the client mints+refreshes a client-
-//     credentials token from IAM_CLIENT_ID/SECRET — no static key to rotate. The
-//     secret is never logged.
+//     (the durable Hanzo default): the client mints+refreshes a client-credentials
+//     token from IAM_CLIENT_ID/SECRET — no static key to rotate. Secret never logged.
 //  3. ZAP RPC when an addr is configured (split-deploy of a future ai subsystem).
 //  4. Fail-closed stub otherwise — a run records an honest error, never fakes one.
-func pickAIClient(cfg *Config, log luxlog.Logger) AIClient {
-	if cfg.AIBaseURL != "" && cfg.AIAPIKey != "" {
-		log.Info("deps.AI → HTTP gateway (static key)", "base_url", cfg.AIBaseURL, "default_model", cfg.AIDefaultModel)
+func pickCompletionsClient(cfg *Config, log luxlog.Logger) AIClient {
+	if cfg.AIBaseURL != "" && cfg.AIAPIKey != "" && !publishableKey(cfg.AIAPIKey) {
+		log.Info("deps.AI (completions) → HTTP gateway (static secret key)", "base_url", cfg.AIBaseURL, "default_model", cfg.AIDefaultModel)
 		return clients.AIHTTPAt(cfg.AIBaseURL, cfg.AIAPIKey, cfg.AIDefaultModel)
 	}
+	if cfg.AIAPIKey != "" && publishableKey(cfg.AIAPIKey) {
+		log.Info("deps.AI (completions) → refusing read-only publishable (pk-) key for chat; using M2M", "base_url", cfg.AIBaseURL)
+	}
 	if cfg.AIBaseURL != "" && cfg.AIAuthClientID != "" && cfg.AIAuthClientSecret != "" {
 		tokenURL := aiM2MTokenURL(cfg)
 		if tokenURL != "" {
-			log.Info("deps.AI → HTTP gateway (IAM M2M)", "base_url", cfg.AIBaseURL,
+			log.Info("deps.AI (completions) → HTTP gateway (IAM M2M)", "base_url", cfg.AIBaseURL,
 				"token_url", tokenURL, "client_id", cfg.AIAuthClientID, "default_model", cfg.AIDefaultModel)
 			return clients.AIHTTPM2M(cfg.AIBaseURL, tokenURL, cfg.AIAuthClientID, cfg.AIAuthClientSecret, cfg.AIDefaultModel)
 		}
 	}
 	if cfg.AIZAPAddr != "" {
-		log.Info("deps.AI → ZAP RPC", "addr", cfg.AIZAPAddr)
+		log.Info("deps.AI (completions) → ZAP RPC", "addr", cfg.AIZAPAddr)
 		return clients.AIRPCAt(cfg.AIZAPAddr)
 	}
-	log.Info("deps.AI → disabled (no CLOUD_AI_API_KEY, no IAM M2M identity, no gateway configured)")
+	log.Info("deps.AI (completions) → disabled (no secret key, no IAM M2M identity, no gateway configured)")
 	return clients.DisabledAI()
 }

+// pickEmbedClient resolves deps.Embed — the client code-index + KB knowledge run
+// EMBEDDINGS through. Embeddings are a READ-ONLY endpoint, so the read-only
+// publishable (pk-) key (CLOUD_AI_API_KEY ← cloud-ai-embed-key) is the CORRECT
+// least-privilege credential here, and is used UNCHANGED — this path is deliberately
+// not rewired. Preference order:
+//  1. Static-key HTTP gateway when a base URL AND a static key are configured. The
+//     key (pk- or sk-) is a KMS-injected secret; only base URL + model are logged.
+//  2. Otherwise share the completions resolution (M2M / ZAP / fail-closed) so a
+//     deploy with no dedicated embed key still indexes — no regression.
+func pickEmbedClient(cfg *Config, log luxlog.Logger) AIClient {
+	if cfg.AIBaseURL != "" && cfg.AIAPIKey != "" {
+		log.Info("deps.Embed → HTTP gateway (static embed key)", "base_url", cfg.AIBaseURL, "default_model", cfg.AIDefaultModel)
+		return clients.AIHTTPAt(cfg.AIBaseURL, cfg.AIAPIKey, cfg.AIDefaultModel)
+	}
+	return pickCompletionsClient(cfg, log)
+}
+
 // aiM2MTokenURL resolves IAM's client_credentials endpoint the agent runner mints
 // its M2M inference token at. It MUST be reachable FROM INSIDE THE CLUSTER: the
 // runner runs in-cluster and the public issuer host (https://hanzo.id) is fronted
@@ -640,6 +719,148 @@ func pickVFSClient(cfg *Config, log luxlog.Logger) VFSClient {
 	return clients.DisabledVFS()
 }

+// durableBucket holds every org's HA-SQLite snapshot (and its writer lease). One
+// bucket, keys laid out orgs/<slug>[/…]/<subsystem>.db per HIP-0302 — the durable
+// twin of the on-disk DataDir layout.
+//
+// OPERATIONAL REQUIREMENTS the fence depends on (enforce in the SeaweedFS deployment,
+// not in code):
+//
+//   - Object versioning + a no-expiry / no-lifecycle-deletion policy on this prefix.
+//     The writer lease (orgs/<slug>/.owner) is the round's system of record; if the
+//     gateway silently drops or rolls back that object, a monotone round can reset and
+//     un-fence a zombie writer (Red M4). A local high-water-round floor per pod is the
+//     future in-process defense; the object lifecycle is the operational one.
+//   - RWO, per-writer PVCs for DataDir — NEVER an RWX shared volume (Red M5). Two pods
+//     on one DataDir corrupt SQLite regardless of this fence; single-writer here is the
+//     durable-copy fence, and per-pod RWO is the local-file guarantee the shard router
+//     already relies on (see shardrouter.go).
+const durableBucket = "org-db"
+
+// buildDurability constructs the deployment's HA-durability factory, or nil when the
+// deployment has no object store to be durable against (dev/single-node — every
+// OrgStore then stays local-only). It composes the SeaweedFS S3 If-Match
+// ConditionalStore (the SAME s3admin identity deps.VFS uses), the writer membership
+// over CLOUD_PEERS (the SAME set the shard router elects on, so the store-layer owner
+// and the routed owner agree), and the per-org envelope Cipher rooted at the KMS
+// master. Any construction failure fails SAFE to nil (local-only) rather than crash
+// the boot; an encryption-capable build with no usable cipher is REFUSED — a build
+// that promises encryption never ships plaintext snapshots to the object store.
+func buildDurability(cfg *Config, log luxlog.Logger) *Durability {
+	// A multi-replica deployment REQUIRES the durable plane: with >1 writer, a per-org
+	// store that is not hydrate-on-open + fenced is the outage this exists to fix.
+	// disabledDurability logs at the severity the replica count warrants, so a
+	// misconfigured prod deployment is never SILENTLY non-durable (Red L2).
+	multiReplica := len(parsePeers(cfg.ShardPeers)) > 1
+
+	// Explicit opt-in: the object-store fence rests on the deployed SeaweedFS enforcing
+	// conditional-PUT (If-Match) atomically, which must be validated against the deployed
+	// version before it fences real tenant data (the takeover-fence staging gate). Until
+	// CLOUD_RESEARCH_DURABLE is set the store runs local-only — the shard router still
+	// pins each org to one writer, so this is not the rolling-deploy outage; only the
+	// cross-restart object-store snapshot waits for the opt-in.
+	if !cfg.ResearchDurable {
+		disabledDurability(log, multiReplica, "CLOUD_RESEARCH_DURABLE not set — HA object-store durability is opt-in pending the SeaweedFS conditional-PUT atomicity gate")
+		return nil
+	}
+
+	admin := s3admin.New()
+	if !admin.Configured() {
+		disabledDurability(log, multiReplica, "no S3 admin creds (S3_ADMIN_* unset)")
+		return nil
+	}
+	client, err := admin.Client()
+	if err != nil {
+		disabledDurability(log, multiReplica, fmt.Sprintf("S3 client construction failed: %v", err))
+		return nil
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	if err := ensureDurableBucket(ctx, admin, client); err != nil {
+		// Non-fatal: the bucket likely already exists; a later ship/hydrate retries.
+		log.Warn("durability bucket ensure failed (continuing)", "bucket", durableBucket, "err", err)
+	}
+	cancel()
+
+	// Membership: CLOUD_PEERS (the shard router's set). A single-pod deployment with
+	// no peers is its own sole writer — still hydrate-on-open + fenced ship across a
+	// rolling restart.
+	self := firstNonEmptyStr(strings.TrimSpace(cfg.ShardSelf), hostnameOr("cloud-0"))
+	peers := parsePeers(cfg.ShardPeers)
+	if len(peers) == 0 {
+		peers = []org.Member{{ID: self, Addr: self}}
+	}
+	members := org.NewMembership(self, org.StaticSource(peers...), 5*time.Second)
+	_ = members.Start(context.Background()) // static source: the initial refresh populates Members()
+
+	cipher := durableCipher(cfg, log)
+	if cipher == nil && cek.Encrypting() {
+		// The master that satisfied cek must decode here too, so this is a genuine
+		// misconfig, not a dev path: never ship plaintext snapshots AND never silently
+		// drop durability — fail closed and log LOUDLY for the replica count.
+		disabledDurability(log, multiReplica, "encryption-capable build but no durable cipher (would ship plaintext snapshots)")
+		return nil
+	}
+
+	log.Info("durability enabled", "bucket", durableBucket, "self", self, "peers", len(peers), "encrypted", cipher != nil)
+	return org.NewDurability(org.NewS3ConditionalStore(client, durableBucket), members, cipher)
+}
+
+// disabledDurability records that the durable plane is OFF, at ERROR when the
+// deployment is multi-replica (per-org stores then survive only via shard routing +
+// per-pod RWO PVC; a lost/rescheduled PVC loses committed data — the operator MUST
+// configure S3) and at INFO when single-replica/dev (local-only is the expected
+// posture). One place, so no disabled path is silent on a deployment that needs HA.
+func disabledDurability(log luxlog.Logger, multiReplica bool, why string) {
+	if multiReplica {
+		log.Error("DURABILITY DISABLED on a MULTI-REPLICA deployment — per-org stores survive only via shard routing + per-pod RWO PVC; a lost/rescheduled PVC loses committed data. Configure S3_ADMIN_* to enable the durable plane.", "reason", why)
+		return
+	}
+	log.Info("durability disabled — single-replica/dev, per-org stores stay local-only", "reason", why)
+}
+
+// ensureDurableBucket creates the durable bucket if absent (idempotent).
+func ensureDurableBucket(ctx context.Context, admin s3admin.Admin, client *s3.Client) error {
+	ok, err := client.BucketExists(ctx, durableBucket)
+	if err != nil {
+		return err
+	}
+	if ok {
+		return nil
+	}
+	return client.MakeBucket(ctx, durableBucket, s3.MakeBucketOptions{Region: admin.Region()})
+}
+
+// durableCipher builds the per-org envelope Cipher from the base64 KMS master
+// (CLOUD_KMS_MASTER_KEY_REF — the SAME key cek derives from). nil when no valid
+// 32-byte master is configured (pure-Go dev → plaintext durable object, matching the
+// plaintext local file).
+func durableCipher(cfg *Config, log luxlog.Logger) *org.Cipher {
+	ref := strings.TrimSpace(cfg.KMSMasterKeyRef)
+	if ref == "" {
+		return nil
+	}
+	master, err := base64.StdEncoding.DecodeString(ref)
+	if err != nil {
+		log.Warn("durable cipher: KMS master key ref is not valid base64", "err", err)
+		return nil
+	}
+	c, err := org.NewCipher(master)
+	if err != nil {
+		log.Warn("durable cipher: invalid KMS master key", "err", err)
+		return nil
+	}
+	return c
+}
+
+// hostnameOr returns the OS hostname, or def when unavailable — a stable self id for
+// a single-pod deployment that sets no CLOUD_POD_NAME.
+func hostnameOr(def string) string {
+	if h, err := os.Hostname(); err == nil && h != "" {
+		return h
+	}
+	return def
+}
+
 func pickPaymentsClient(cfg *Config, log luxlog.Logger) PaymentsClient {
 	if cfg.PaymentsZAPAddr != "" {
 		log.Info("deps.Payments → ZAP RPC", "addr", cfg.PaymentsZAPAddr)
@@ -0,0 +1,51 @@
+package cloud
+
+import (
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	luxlog "github.com/luxfi/log"
+	"github.com/zap-proto/zip"
+)
+
+// CallerBearer relays the caller's OWN validated JWT bearer and nothing else: a JWT
+// passes through unchanged, an opaque API key is not relayable, and no credential
+// yields "". This is the token a downstream org-scoped service (the DNS forward
+// head) re-validates to enforce tenant isolation across the hop.
+func TestCallerBearer(t *testing.T) {
+	app := zip.New(zip.Config{Logger: luxlog.New("test")})
+	app.Get("/probe", func(c *zip.Ctx) error { return c.Bytes(200, []byte(CallerBearer(c))) })
+
+	probe := func(setup func(*http.Request)) string {
+		req := httptest.NewRequest(http.MethodGet, "/probe", nil)
+		if setup != nil {
+			setup(req)
+		}
+		res, err := app.Fiber().Test(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		b, _ := io.ReadAll(res.Body)
+		_ = res.Body.Close()
+		return string(b)
+	}
+
+	cases := []struct {
+		name  string
+		setup func(*http.Request)
+		want  string
+	}{
+		{"jwt bearer relayed unchanged", func(r *http.Request) { r.Header.Set("Authorization", "Bearer jwt.header.sig") }, "jwt.header.sig"},
+		{"X-Authorization fallback", func(r *http.Request) { r.Header.Set("X-Authorization", "Bearer x.y.z") }, "x.y.z"},
+		{"opaque hk- api key is NOT relayable", func(r *http.Request) { r.Header.Set("Authorization", "Bearer hk-secret") }, ""},
+		{"opaque sk- api key is NOT relayable", func(r *http.Request) { r.Header.Set("Authorization", "Bearer sk-secret") }, ""},
+		{"no credential yields empty", nil, ""},
+	}
+	for _, c := range cases {
+		if got := probe(c.setup); got != c.want {
+			t.Errorf("%s: CallerBearer = %q, want %q", c.name, got, c.want)
+		}
+	}
+}
@@ -63,7 +63,9 @@ var controlCommands = map[string]string{
 	"k8s":      "deploy-target helpers (current target)",
 	"config":   "view/edit ~/.hanzo/config preferences",
 	"security": "scan files for hardcoded secrets (local guardrail; no server/auth)",
-	"gpu":      "connect this machine's GPU to the Hanzo cloud fleet (connect/status/disconnect)",
+	"link":     "bring this machine into the Hanzo cloud fleet as a node (fabric + compute worker)",
+	"unlink":   "take this machine out of the fleet (deregister + stop hanzod)",
+	"status":   "show the org's fleet — every node with each of its GPUs",
 	"engine":   "run a local hanzo-engine (OpenAI + Anthropic model server)",
 	"code":     "launch a coding agent (claude, codex, dev) on a Hanzo cloud model",
 	"runner":   "run this machine as a JIT CI runner for your org (GitHub Actions)",
@@ -474,11 +476,14 @@ func (e *Env) freshAccessToken() string {
 	return tok
 }

-// platformToken resolves the platform control-plane service token. The
-// platform REST surface is machine-to-machine (it cannot validate IAM user
-// tokens), so apps/clusters/redeploy authenticate with this, sourced from
-// (in precedence) the bound --platform-token flag, the environment, then the
-// credential store. Never hardcoded.
+// platformToken resolves the bearer the platform control plane authenticates
+// apps/clusters/redeploy with. ONE identity authorizes everything: after a plain
+// `hanzo login` the IAM access token is the FINAL fallback, so no separate
+// --platform-token is needed — the platform verifies the IAM JWT (signature,
+// issuer, expiry) and org-scopes the caller. A dedicated service token still
+// wins when present (flag > env > credential store > IAM login), so purpose-minted
+// machine tokens keep their precedence and internal automation is unchanged.
+// Never hardcoded.
 func (e *Env) platformToken(flagVal string) string {
 	return firstNonEmpty(
 		flagVal,
@@ -486,17 +491,22 @@ func (e *Env) platformToken(flagVal string) string {
 		os.Getenv("PLATFORM_SERVICE_TOKEN"),
 		os.Getenv("PAAS_SERVICE_TOKEN"),
 		e.creds.PlatformToken,
+		e.accessToken(), // IAM login is the one identity that authorizes control-plane ops
 	)
 }

-// buildToken resolves the platform build-enqueue token (a distinct credential
-// from the service token — see /v1/runner).
+// buildToken resolves the bearer `hanzo build` sends to the platform build
+// enqueue (/v1/runner). Same unify-infra contract as platformToken: a dedicated
+// build token wins when present, but a plain IAM login is the FINAL fallback, so
+// `hanzo build` works off the one identity with no separate --build-token — the
+// platform verifies the IAM JWT and authorizes the build by org + role.
 func (e *Env) buildToken(flagVal string) string {
 	return firstNonEmpty(
 		flagVal,
 		os.Getenv("HANZO_BUILD_TOKEN"),
 		os.Getenv("PLATFORM_BUILD_CALLBACK_TOKEN"),
 		e.creds.BuildToken,
+		e.accessToken(), // IAM login is the one identity that authorizes builds
 	)
 }

@@ -588,10 +598,11 @@ func newRootCmd() *cobra.Command {
 		newDeployCmd(envOf, &f),
 		newClustersCmd(envOf, &f),
 		newBuildCmd(envOf, &f),
-		newK8sCmd(envOf, &f),
 		newConfigCmd(),
 		newSecurityCmd(envOf),
-		newGPUCmd(envOf, &f),
+		newLinkCmd(envOf, &f),
+		newUnlinkCmd(envOf, &f),
+		newStatusCmd(envOf, &f),
 		newEngineCmd(envOf, &f),
 		newCodeCmd(envOf, &f),
 		newRunnerCmd(envOf, &f),
@@ -141,6 +141,29 @@ func TestPlatformTokenPrecedence(t *testing.T) {
 	}
 }

+// TestPlatformTokenFallsBackToIAM is the UNIFY-INFRA contract for the control
+// plane: after a plain `hanzo login`, the IAM access token is the FINAL fallback
+// so `hanzo apps`/`hanzo deploy` authorize off the one identity. An explicit
+// platform service token (creds/env/flag) still wins.
+func TestPlatformTokenFallsBackToIAM(t *testing.T) {
+	sandbox(t)
+	// Only an IAM login: no platform token anywhere ⇒ the IAM access token is sent.
+	e := resolve(&Config{}, &Credentials{AccessToken: "iam-jwt"}, globalFlags{})
+	if got := e.platformToken(""); got != "iam-jwt" {
+		t.Fatalf("IAM access token should be the final platform-token fallback: %q", got)
+	}
+	// A dedicated platform service token still beats the IAM token.
+	e = resolve(&Config{}, &Credentials{AccessToken: "iam-jwt", PlatformToken: "svc"}, globalFlags{})
+	if got := e.platformToken(""); got != "svc" {
+		t.Fatalf("dedicated platform token must beat the IAM fallback: %q", got)
+	}
+	// No login at all ⇒ empty (caller surfaces "run `hanzo login`").
+	e = resolve(&Config{}, &Credentials{}, globalFlags{})
+	if got := e.platformToken(""); got != "" {
+		t.Fatalf("no token and no login should resolve empty: %q", got)
+	}
+}
+
 func TestBuildTokenPrecedence(t *testing.T) {
 	sandbox(t)
 	e := resolve(&Config{}, &Credentials{BuildToken: "creds"}, globalFlags{})
@@ -156,6 +179,37 @@ func TestBuildTokenPrecedence(t *testing.T) {
 	}
 }

+// TestBuildTokenFallsBackToIAM is the UNIFY-INFRA contract: after a plain
+// `hanzo login` (no --build-token), the IAM access token is the FINAL fallback,
+// so `hanzo build` authorizes off the one identity. An explicit build token
+// (creds/env/flag) still wins — the IAM token is the LAST resort, never an
+// override of a purpose-minted machine token.
+func TestBuildTokenFallsBackToIAM(t *testing.T) {
+	sandbox(t)
+	// Only an IAM login: no build token anywhere ⇒ the IAM access token is sent.
+	e := resolve(&Config{}, &Credentials{AccessToken: "iam-jwt"}, globalFlags{})
+	if got := e.buildToken(""); got != "iam-jwt" {
+		t.Fatalf("IAM access token should be the final build-token fallback: %q", got)
+	}
+	// A dedicated build token still beats the IAM token (precedence preserved).
+	e = resolve(&Config{}, &Credentials{AccessToken: "iam-jwt", BuildToken: "creds"}, globalFlags{})
+	if got := e.buildToken(""); got != "creds" {
+		t.Fatalf("dedicated build token must beat the IAM fallback: %q", got)
+	}
+	// HANZO_TOKEN (the env form of the IAM token) is also honored via accessToken().
+	e = resolve(&Config{}, &Credentials{}, globalFlags{})
+	t.Setenv("HANZO_TOKEN", "iam-env")
+	if got := e.buildToken(""); got != "iam-env" {
+		t.Fatalf("HANZO_TOKEN should back the build-token fallback: %q", got)
+	}
+	// No login at all ⇒ empty, so the caller can surface "run `hanzo login`".
+	t.Setenv("HANZO_TOKEN", "")
+	e = resolve(&Config{}, &Credentials{}, globalFlags{})
+	if got := e.buildToken(""); got != "" {
+		t.Fatalf("no token and no login should resolve empty: %q", got)
+	}
+}
+
 func TestAccessTokenFromEnvOverCreds(t *testing.T) {
 	sandbox(t)
 	e := resolve(&Config{}, &Credentials{AccessToken: "creds"}, globalFlags{})
@@ -147,9 +147,10 @@ type codeAgent struct {
 	bin          string                     // executable to exec
 	wire         wire                       // how it finds the cloud
 	fullAuto     []string                   // flags that bypass approval prompts
+	continueArgs []string                   // harness-native form of Hanzo -c/--continue
 	modelArg     []string                   // how the model is passed on argv (empty: via env)
 	carrier      func(model string) string  // maps the resolved model to a client-recognized id (claude: zen→carrier); nil = pass through
-	provider     func(base string) []string // agents that need the endpoint declared, not just env'd
+	provider     func(base, model string) []string // agents that need the endpoint declared, not just env'd
 	clear        []string                   // env that would shadow the wire (a stale key in the shell)
 	configHome   string                     // env var that relocates the agent's config dir to ~/.hanzo ("" = share the user's own install)
 	seed         func(dir string) error     // one-time defaults for the isolated config dir
@@ -158,22 +159,46 @@ type codeAgent struct {
 	install      string                     // hint when the binary is missing
 }

+// codeContextWindow is the input context (tokens) the served coding model
+// budgets from. The enso and zen5 flagship tiers serve 1M; the flash tiers
+// serve 131072. Codex is told this so it sizes context to the real window
+// instead of a flat 256K cap — the cause of "maximum context exceeded" at
+// 262144 even on a 1M-capable model. This wrapper only launches Hanzo coding
+// models (default zen5), so non-flash defaults to the 1M flagship window.
+func codeContextWindow(model string) int {
+	if strings.Contains(strings.ToLower(model), "flash") {
+		return 131072
+	}
+	return 1000000
+}
+
 // codex and @hanzo/dev share a lineage (dev is a Codex fork), hence a wire.
 // They also ignore OPENAI_BASE_URL and talk to chatgpt.com unless a provider is
 // declared, so declare Hanzo as the provider and select it.
 func codexLike(bin, install string) codeAgent {
 	return codeAgent{
-		bin:      bin,
-		wire:     openaiWire,
-		fullAuto: []string{"--dangerously-bypass-approvals-and-sandbox"},
-		modelArg: []string{"-m"},
-		provider: func(base string) []string {
+		bin:          bin,
+		wire:         openaiWire,
+		fullAuto:     []string{"--dangerously-bypass-approvals-and-sandbox"},
+		continueArgs: []string{"resume", "--last"},
+		modelArg:     []string{"-m"},
+		provider: func(base, model string) []string {
+			// api.hanzo.ai exposes the standard OpenAI /v1/models shape, not
+			// Codex's private remote model-catalog schema, so skip that refresh
+			// and supply the model's window here — sized to the SERVED model
+			// (enso / zen5 flagship = 1M, flash tiers = 131072) so Codex budgets
+			// the real context instead of a flat 256K cap (the "maximum context
+			// exceeded at 262144" bug). Auto-compact at 90% leaves headroom.
+			win := codeContextWindow(model)
 			return []string{
 				"-c", "model_provider=hanzo",
 				"-c", `model_providers.hanzo.name="Hanzo"`,
 				"-c", fmt.Sprintf(`model_providers.hanzo.base_url="%s/v1"`, strings.TrimSuffix(base, "/")),
 				"-c", `model_providers.hanzo.env_key="OPENAI_API_KEY"`,
 				"-c", `model_providers.hanzo.wire_api="responses"`,
+				"-c", `features.remote_models=false`,
+				"-c", fmt.Sprintf("model_context_window=%d", win),
+				"-c", fmt.Sprintf("model_auto_compact_token_limit=%d", win*9/10),
 			}
 		},
 		install: install,
@@ -190,9 +215,10 @@ const zenIdentityPrompt = "You are running through the Hanzo AI cloud as a Hanzo

 var codeAgents = map[string]codeAgent{
 	"claude": {
-		bin:      "claude",
-		wire:     anthropicWire,
-		fullAuto: []string{"--dangerously-skip-permissions"},
+		bin:          "claude",
+		wire:         anthropicWire,
+		fullAuto:     []string{"--dangerously-skip-permissions"},
+		continueArgs: []string{"--continue"},
 		// --model forces the session model on argv. Claude Code persists the
 		// user's last /model selection (e.g. the reserved word "best"), and that
 		// persisted choice OVERRIDES ANTHROPIC_MODEL — so the env var alone cannot
@@ -246,9 +272,12 @@ func newCodeCmd(envOf func() *Env, _ *globalFlags) *cobra.Command {
 		Long: "Run @hanzo/dev, Claude Code, or Codex against api.hanzo.ai with the endpoint,\n" +
 			"credential and model injected — no env vars to remember. `hanzo code` alone runs\n" +
 			"dev (the Hanzo agent); name an agent to pick another. Model ids resolve fuzzily\n" +
-			"(glm5.2 -> glm-5.2) and agents run full-auto unless you pass --safe.",
+			"(glm5.2 -> glm-5.2), -c resumes either harness, and agents run full-auto unless\n" +
+			"you pass --safe. Unknown options pass through; -- forces verbatim passthrough.",
 		Example: "  hanzo code                 # dev, the default agent\n" +
 			"  hanzo code claude\n" +
+			"  hanzo code claude -c\n" +
+			"  hanzo code codex -c\n" +
 			"  hanzo code codex deepseek-v4-pro\n" +
 			"  hanzo code dev glm5.2 -- --resume\n" +
 			"  hanzo code ls",
@@ -320,19 +349,10 @@ func runCode(env *Env, agent codeAgent, args []string) error {
 	}
 	base := strings.TrimSuffix(firstNonEmpty(env.CloudURL, "https://api.hanzo.ai"), "/")

-	// First non-flag arg is the model; --safe is ours; the rest is the agent's.
-	model, safe, rest := "", false, make([]string, 0, len(args))
-	for _, a := range args {
-		switch {
-		case a == "--": // the separator is ours; the agent must not see it
-		case a == "--safe" || a == "--ask":
-			safe = true
-		case model == "" && !strings.HasPrefix(a, "-") && len(rest) == 0:
-			model = a
-		default:
-			rest = append(rest, a)
-		}
-	}
+	// First non-flag arg before -- is the model; --safe and --continue are ours.
+	// Unknown options pass through unchanged. Everything after -- belongs to the
+	// agent, including positional subcommands and raw Codex -c config overrides.
+	model, safe, continueLast, rest := splitCodeArgs(args)
 	if model == "" {
 		model = defaultCodeModel
 	}
@@ -382,7 +402,7 @@ func runCode(env *Env, agent codeAgent, args []string) error {
 		}
 	}

-	argv := codeArgv(agent, base, model, safe, rest)
+	argv := codeArgv(agent, base, model, safe, codeAgentRest(agent, continueLast, rest))

 	for k, v := range agent.wire(base, token, model) {
 		if err := os.Setenv(k, v); err != nil {
@@ -397,6 +417,45 @@ func runCode(env *Env, agent codeAgent, args []string) error {
 	return execEngine(bin, argv) // exec: signals + exit code flow straight through
 }

+// splitCodeArgs pulls the launcher-owned tokens (the model, --safe, -c/--continue)
+// out of the raw args; everything else is the agent's. The `--` separator is ours
+// and switches on verbatim passthrough — every token after it goes to the agent
+// untouched, including positional subcommands (`codex exec`) and raw Codex -c
+// config overrides that would otherwise look like our --continue.
+func splitCodeArgs(args []string) (model string, safe, continueLast bool, rest []string) {
+	rest = make([]string, 0, len(args))
+	passthrough := false
+	for _, a := range args {
+		switch {
+		case passthrough:
+			rest = append(rest, a)
+		case a == "--": // the separator is ours; the agent must not see it
+			passthrough = true
+		case a == "--safe" || a == "--ask":
+			safe = true
+		case a == "-c" || a == "--continue":
+			continueLast = true
+		case model == "" && !strings.HasPrefix(a, "-") && len(rest) == 0:
+			model = a
+		default:
+			rest = append(rest, a)
+		}
+	}
+	return model, safe, continueLast, rest
+}
+
+// codeAgentRest prepends the agent's harness-native resume tokens when -c/--continue
+// was given, so one Hanzo flag resumes the last session on either harness (`--continue`
+// for Claude Code, `resume --last` for Codex/dev).
+func codeAgentRest(agent codeAgent, continueLast bool, rest []string) []string {
+	if !continueLast {
+		return rest
+	}
+	args := make([]string, 0, len(agent.continueArgs)+len(rest))
+	args = append(args, agent.continueArgs...)
+	return append(args, rest...)
+}
+
 // codeArgv builds the final agent command line. Permission bypass is the
 // launcher default for every agent; --safe is the single explicit opt-out.
 func codeArgv(agent codeAgent, base, model string, safe bool, rest []string) []string {
@@ -405,7 +464,7 @@ func codeArgv(agent codeAgent, base, model string, safe bool, rest []string) []s
 		argv = append(argv, agent.fullAuto...)
 	}
 	if agent.provider != nil {
-		argv = append(argv, agent.provider(base)...)
+		argv = append(argv, agent.provider(base, model)...)
 	}
 	if len(agent.modelArg) > 0 { // claude takes the model via env, codex/dev on argv
 		argv = append(argv, agent.modelArg...)
@@ -18,6 +18,7 @@ import (
 	"encoding/json"
 	"os"
 	"path/filepath"
+	"reflect"
 	"slices"
 	"testing"
 	"time"
@@ -48,6 +49,95 @@ func TestCodeAgentsBypassPermissionsByDefault(t *testing.T) {
 	}
 }

+func TestCodeArgsSeparatorPreservesAgentSubcommand(t *testing.T) {
+	model, safe, continueLast, rest := splitCodeArgs([]string{"--safe", "--", "exec", "--ephemeral", "do it"})
+	if model != "" || !safe || continueLast {
+		t.Fatalf("model=%q safe=%v continue=%v, want default model and safe mode", model, safe, continueLast)
+	}
+	if want := []string{"exec", "--ephemeral", "do it"}; !reflect.DeepEqual(rest, want) {
+		t.Fatalf("agent args = %q, want %q", rest, want)
+	}
+}
+
+func TestCodeArgsExplicitModelBeforeSeparator(t *testing.T) {
+	model, safe, continueLast, rest := splitCodeArgs([]string{"zen5-max", "--", "exec"})
+	if model != "zen5-max" || safe || continueLast || !reflect.DeepEqual(rest, []string{"exec"}) {
+		t.Fatalf("model=%q safe=%v continue=%v rest=%q", model, safe, continueLast, rest)
+	}
+}
+
+func TestCodeContinueIsNormalizedForBothHarnesses(t *testing.T) {
+	for _, tt := range []struct {
+		name string
+		want []string
+	}{
+		{name: "claude", want: []string{"--continue"}},
+		{name: "codex", want: []string{"resume", "--last"}},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			model, safe, continueLast, rest := splitCodeArgs([]string{"-c"})
+			if model != "" || safe || !continueLast || len(rest) != 0 {
+				t.Fatalf("model=%q safe=%v continue=%v rest=%q", model, safe, continueLast, rest)
+			}
+			if got := codeAgentRest(codeAgents[tt.name], continueLast, rest); !reflect.DeepEqual(got, tt.want) {
+				t.Fatalf("normalized continue args = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestCodeUnknownOptionsAndPostSeparatorArgsPassThrough(t *testing.T) {
+	unknown := []string{"--mystery", "value", "--other=1"}
+	model, safe, continueLast, rest := splitCodeArgs(unknown)
+	if model != "" || safe || continueLast || !reflect.DeepEqual(rest, unknown) {
+		t.Fatalf("unknown options changed: model=%q safe=%v continue=%v rest=%q", model, safe, continueLast, rest)
+	}
+
+	_, _, continueLast, rest = splitCodeArgs([]string{"--", "-c", "model=x"})
+	if continueLast || !reflect.DeepEqual(rest, []string{"-c", "model=x"}) {
+		t.Fatalf("post-separator Codex config must pass verbatim: continue=%v rest=%q", continueLast, rest)
+	}
+}
+
+func TestCodexProviderUsesNativeResponsesMetadata(t *testing.T) {
+	// defaultCodeModel is zen5 — a 1M flagship tier — so the window must be 1M,
+	// NOT the old flat 262144 cap that surfaced as "maximum context exceeded"
+	// even on a 1M-capable model. Auto-compact is 90% of the window.
+	argv := codeArgv(codeAgents["codex"], "https://api.hanzo.ai", defaultCodeModel, false, nil)
+	for _, want := range []string{
+		`model_provider=hanzo`,
+		`model_providers.hanzo.base_url="https://api.hanzo.ai/v1"`,
+		`model_providers.hanzo.wire_api="responses"`,
+		`features.remote_models=false`,
+		`model_context_window=1000000`,
+		`model_auto_compact_token_limit=900000`,
+	} {
+		if !slices.Contains(argv, want) {
+			t.Errorf("Codex argv %q does not contain %q", argv, want)
+		}
+	}
+	// A flash tier budgets its smaller real window, not 1M.
+	flash := codeArgv(codeAgents["codex"], "https://api.hanzo.ai", "zen5-flash", false, nil)
+	if !slices.Contains(flash, `model_context_window=131072`) {
+		t.Errorf("zen5-flash argv %q must budget 131072, not the flagship 1M", flash)
+	}
+}
+
+// TestCodeContextWindowSizing pins the model→window map: every non-flash tier
+// gets the 1M flagship window; only flash tiers drop to 131072.
+func TestCodeContextWindowSizing(t *testing.T) {
+	for _, m := range []string{"zen5", "zen5-pro", "zen5-coder", "enso", "enso-ultra"} {
+		if w := codeContextWindow(m); w != 1000000 {
+			t.Errorf("codeContextWindow(%q) = %d, want 1000000", m, w)
+		}
+	}
+	for _, m := range []string{"zen5-flash", "enso-flash"} {
+		if w := codeContextWindow(m); w != 131072 {
+			t.Errorf("codeContextWindow(%q) = %d, want 131072", m, w)
+		}
+	}
+}
+
 // TestCodeTokenPrecedence locks in the 402 unblock: a fresh `hanzo login` JWT
 // (which carries owner/project/sub on EVERY deployment) beats the hk- API key
 // (which only mints a billing principal where the server has IAM_MINT_CLIENT_*).
@@ -60,10 +150,10 @@ func TestCodeTokenPrecedence(t *testing.T) {
 	freshExpiry := time.Now().Add(1 * time.Hour).Unix()

 	cases := []struct {
-		name    string
-		envKey  string // HANZO_API_KEY override
-		creds   Credentials
-		want    string
+		name   string
+		envKey string // HANZO_API_KEY override
+		creds  Credentials
+		want   string
 	}{
 		{
 			name:  "fresh JWT beats hk- key",
@@ -81,16 +171,16 @@ func TestCodeTokenPrecedence(t *testing.T) {
 			want:  "hk-stored",
 		},
 		{
-			name:  "HANZO_API_KEY overrides everything (deliberate operator override)",
+			name:   "HANZO_API_KEY overrides everything (deliberate operator override)",
 			envKey: "hk-explicit",
-			creds: Credentials{AccessToken: "jwt-live", Expiry: freshExpiry},
-			want:  "hk-explicit",
+			creds:  Credentials{AccessToken: "jwt-live", Expiry: freshExpiry},
+			want:   "hk-explicit",
 		},
 		{
-			name:  "HANZO_API_KEY overrides even an expired JWT",
+			name:   "HANZO_API_KEY overrides even an expired JWT",
 			envKey: "hk-explicit",
-			creds: Credentials{AccessToken: "jwt-dead", Expiry: time.Now().Add(-1 * time.Hour).Unix()},
-			want:  "hk-explicit",
+			creds:  Credentials{AccessToken: "jwt-dead", Expiry: time.Now().Add(-1 * time.Hour).Unix()},
+			want:   "hk-explicit",
 		},
 	}

@@ -3,6 +3,7 @@ package cli
 import (
 	"fmt"
 	"io"
+	"strings"
 	"text/tabwriter"

 	"github.com/spf13/cobra"
@@ -15,12 +16,12 @@ func (e *Env) platform(gf *globalFlags) *Platform {
 	return newPlatform(e.PlatformURL, e.platformToken(gf.platformToken))
 }

-// deref renders a *string for a table cell, "-" when nil/empty.
-func deref(p *string) string {
-	if p == nil || *p == "" {
+// dashIfEmpty renders a string cell, "-" when empty.
+func dashIfEmpty(s string) string {
+	if s == "" {
 		return "-"
 	}
-	return *p
+	return s
 }

 // yesno renders a bool for a table cell.
@@ -37,7 +38,8 @@ func newTab(w io.Writer) *tabwriter.Writer {
 }

 // ---------------------------------------------------------------------------
-// apps — the observe surface.
+// apps — the fleet drift board (GET /v1/paas/apps). Org-confined server-side by
+// the IAM identity: a superadmin sees the whole fleet, an org-admin only its own.
 // ---------------------------------------------------------------------------

 func newAppsCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
@@ -56,7 +58,6 @@ func newAppsCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			e := envOf()
 			res, err := e.platform(gf).Apps(cmd.Context(), AppsQuery{
-				Org:    e.Org, // empty == all (single-tenant default)
 				Env:    envFilter,
 				Health: healthFilter,
 				Drift:  driftOnly,
@@ -69,8 +70,8 @@ func newAppsCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
 				fmt.Fprintln(tw, "ORG\tAPP\tENV\tDECLARED\tRUNNING\tHEALTH\tDRIFT")
 				for _, a := range res.Apps {
 					fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%s\t%s\t%s\n",
-						a.Org, a.App, a.Env, deref(a.DeclaredTag), deref(a.RunningTag),
-						deref(a.Health), driftSeverity(a.Drift))
+						a.Org, a.App, a.Env, dashIfEmpty(a.DeclaredTag), dashIfEmpty(a.RunningTag),
+						dashIfEmpty(a.Health), driftSeverity(a.Drift))
 				}
 				tw.Flush()
 				fmt.Fprintf(w, "\n%d apps  (ok=%d yellow=%d red=%d)\n",
@@ -79,17 +80,17 @@ func newAppsCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
 			})
 		},
 	}
-	list.Flags().StringVar(&envFilter, "env", "", "filter by env: dev|test|main")
+	list.Flags().StringVar(&envFilter, "env", "", "filter by env: main|test|dev")
 	list.Flags().StringVar(&healthFilter, "health", "", "filter by health: green|yellow|red")
 	list.Flags().BoolVar(&driftOnly, "drift", false, "only rows that are drifting")

 	get := &cobra.Command{
-		Use:   "get <org/app/env>",
-		Short: "Get one app row by its <org>/<app>/<env> id",
+		Use:   "get <app>",
+		Short: "Get one app row by its CR name (production by default)",
 		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			e := envOf()
-			a, err := e.platform(gf).App(cmd.Context(), args[0], e.Org)
+			a, err := e.platform(gf).App(cmd.Context(), args[0])
 			if err != nil {
 				return err
 			}
@@ -101,109 +102,93 @@ func newAppsCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
 				fmt.Fprintf(tw, "env:\t%s\n", a.Env)
 				fmt.Fprintf(tw, "repo:\t%s\n", a.Repo)
 				fmt.Fprintf(tw, "registry:\t%s\n", a.Registry)
-				fmt.Fprintf(tw, "declared:\t%s\n", deref(a.DeclaredTag))
-				fmt.Fprintf(tw, "running:\t%s\n", deref(a.RunningTag))
-				fmt.Fprintf(tw, "latest:\t%s\n", deref(a.LatestTag))
-				fmt.Fprintf(tw, "health:\t%s\n", deref(a.Health))
+				fmt.Fprintf(tw, "declared:\t%s\n", dashIfEmpty(a.DeclaredTag))
+				fmt.Fprintf(tw, "running:\t%s\n", dashIfEmpty(a.RunningTag))
+				fmt.Fprintf(tw, "health:\t%s\n", dashIfEmpty(a.Health))
+				fmt.Fprintf(tw, "phase:\t%s\n", dashIfEmpty(a.Phase))
 				fmt.Fprintf(tw, "drift:\t%s\n", driftSeverity(a.Drift))
-				fmt.Fprintf(tw, "cluster:\t%s\n", deref(a.Cluster))
-				fmt.Fprintf(tw, "namespace:\t%s\n", deref(a.Namespace))
-				fmt.Fprintf(tw, "updated:\t%s\n", a.UpdatedAt)
+				fmt.Fprintf(tw, "cluster:\t%s\n", dashIfEmpty(a.Cluster))
+				fmt.Fprintf(tw, "namespace:\t%s\n", dashIfEmpty(a.Namespace))
+				if len(a.Endpoints) > 0 {
+					fmt.Fprintf(tw, "endpoints:\t%s\n", strings.Join(a.Endpoints, ", "))
+				}
 				tw.Flush()
 			})
 		},
 	}

-	sync := &cobra.Command{
-		Use:   "sync",
-		Short: "Trigger an inventory refresh of the apps board",
-		Args:  cobra.NoArgs,
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			e := envOf()
-			if err := e.platform(gf).SyncApps(cmd.Context()); err != nil {
-				return err
-			}
-			fmt.Fprintln(cmd.OutOrStdout(), "apps sync triggered")
-			return nil
-		},
-	}
-
-	cmd.AddCommand(list, get, sync)
+	cmd.AddCommand(list, get)
 	return cmd
 }

 // ---------------------------------------------------------------------------
-// deploy — the drive surface (rolling restart, zero-downtime).
+// deploy — POST /v1/paas/apps/{app}/deploy: a zero-downtime rolling restart.
 // ---------------------------------------------------------------------------

 func newDeployCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
-	var project, environment string
+	var environment string
 	cmd := &cobra.Command{
-		Use:   "deploy <container>",
-		Short: "Redeploy a container (rolling restart, zero-downtime)",
-		Long: "Drive a platform redeploy: a rolling restart of the container's k8s\n" +
-			"Deployment (re-pulls the image, recreates pods, zero downtime). Coordinates\n" +
-			"are exact — org (--org/config), project (--project), env (--env) and the\n" +
-			"container id (positional). This is the canonical PaaS-driven deploy.",
+		Use:   "deploy <app>",
+		Short: "Redeploy an app (rolling restart, zero-downtime) — requires --env",
+		Long: "Drive a platform redeploy: a rolling restart of the app's k8s Deployment\n" +
+			"(re-pulls the declared image, recreates pods, zero downtime). The app is the\n" +
+			"operator App CR name; the org comes from your IAM identity. --env is REQUIRED\n" +
+			"(main|test|dev) — deploy never silently targets production. Restarting a shared\n" +
+			"platform service is a platform-operator action, so this needs a superadmin\n" +
+			"identity. A TAG change is still a git commit — this restarts what is declared.",
 		Args: cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
+			if strings.TrimSpace(environment) == "" {
+				return fmt.Errorf("--env is required (main|test|dev) — deploy will not default to production")
+			}
 			e := envOf()
-			org, err := e.requireOrg()
+			res, err := e.platform(gf).Redeploy(cmd.Context(), args[0], environment)
 			if err != nil {
 				return err
 			}
-			if project == "" || environment == "" {
-				return fmt.Errorf("--project and --env are required (the container's project/environment ids)")
-			}
-			container := args[0]
-			if err := e.platform(gf).Redeploy(cmd.Context(), org, project, environment, container); err != nil {
-				return err
-			}
-			fmt.Fprintf(cmd.OutOrStdout(), "redeployed %s (org=%s project=%s env=%s)\n", container, org, project, environment)
-			return nil
+			return e.emit(res, func(w io.Writer) {
+				fmt.Fprintf(w, "restarted %s (namespace=%s env=%s at %s)\n",
+					res.App, res.Namespace, dashIfEmpty(res.Env), res.RestartedAt)
+			})
 		},
 	}
-	cmd.Flags().StringVar(&project, "project", "", "project id")
-	cmd.Flags().StringVar(&environment, "env", "", "environment id")
+	cmd.Flags().StringVar(&environment, "env", "", "lifecycle env: main|test|dev (REQUIRED)")
 	return cmd
 }

 // ---------------------------------------------------------------------------
-// clusters — dedicated DOKS cluster lifecycle.
+// clusters — GET /v1/clusters: the org's compute fleet (Visor-managed + BYO),
+// tenant-scoped server-side by the IAM identity.
 // ---------------------------------------------------------------------------

 func newClustersCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "clusters",
 		Aliases: []string{"cluster"},
-		Short:   "Provision/list/select dedicated DOKS clusters",
+		Short:   "List the org's clusters (managed + BYO)",
 	}

 	list := &cobra.Command{
 		Use:   "list",
-		Short: "List the org's dedicated clusters",
+		Short: "List the org's clusters",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			e := envOf()
-			org, err := e.requireOrg()
-			if err != nil {
-				return err
-			}
-			cs, err := e.platform(gf).Clusters(cmd.Context(), org)
+			cs, err := e.platform(gf).Clusters(cmd.Context())
 			if err != nil {
 				return err
 			}
 			return e.emit(cs, func(w io.Writer) {
 				tw := newTab(w)
-				fmt.Fprintln(tw, "NAME\tID\tREGION\tSTATUS\tPHASE\tACTIVE\tOPERATOR\tBASELINE")
+				fmt.Fprintln(tw, "NAME\tID\tREGION\tSTATUS\tKIND\tNODES\tSIZE\tGPUS")
 				for _, c := range cs {
-					fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n",
-						c.Name, c.DoksClusterID, c.Region, c.Status, c.Phase,
-						yesno(c.Active), yesno(c.OperatorInstalled), yesno(c.BaselineInstalled))
+					fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%s\t%d\t%s\t%s\n",
+						c.Name, dashIfEmpty(c.ID()), dashIfEmpty(c.Region), dashIfEmpty(c.Status),
+						dashIfEmpty(c.Kind), c.NodeCount, dashIfEmpty(c.NodeSize), gpuCell(c))
 				}
 				tw.Flush()
 				if len(cs) == 0 {
-					fmt.Fprintln(w, "(no dedicated clusters)")
+					fmt.Fprintln(w, "(no clusters)")
 				}
 			})
 		},
@@ -215,151 +200,51 @@ func newClustersCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
 		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			e := envOf()
-			org, err := e.requireOrg()
-			if err != nil {
-				return err
-			}
-			cs, err := e.platform(gf).Clusters(cmd.Context(), org)
+			cs, err := e.platform(gf).Clusters(cmd.Context())
 			if err != nil {
 				return err
 			}
 			for _, c := range cs {
-				if c.DoksClusterID == args[0] || c.Name == args[0] {
+				if c.ID() == args[0] || c.Name == args[0] {
 					return e.emit(c, func(w io.Writer) { printCluster(w, c) })
 				}
 			}
-			return fmt.Errorf("cluster %q not found in org %s", args[0], org)
+			return fmt.Errorf("cluster %q not found", args[0])
 		},
 	}

-	var region, nodeSize string
-	var ha bool
-	var nodeCount int
-	create := &cobra.Command{
-		Use:   "create",
-		Short: "Provision a new dedicated DOKS cluster for the org",
-		Args:  cobra.NoArgs,
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			e := envOf()
-			org, err := e.requireOrg()
-			if err != nil {
-				return err
-			}
-			c, err := e.platform(gf).ProvisionCluster(cmd.Context(), org, ProvisionReq{
-				Region: region, HA: ha, NodeSize: nodeSize, NodeCount: nodeCount,
-			})
-			if err != nil {
-				return err
-			}
-			return e.emit(c, func(w io.Writer) {
-				fmt.Fprintf(w, "provisioning cluster %s (%s)\n", c.Name, c.DoksClusterID)
-				printCluster(w, *c)
-			})
-		},
-	}
-	create.Flags().StringVar(&region, "region", "", "DO region (default sfo3)")
-	create.Flags().BoolVar(&ha, "ha", false, "highly-available control plane")
-	create.Flags().StringVar(&nodeSize, "node-size", "", "node size slug (e.g. s-2vcpu-4gb)")
-	create.Flags().IntVar(&nodeCount, "node-count", 0, "node count")
-
-	var shared bool
-	selectCmd := &cobra.Command{
-		Use:   "select <cluster-id>",
-		Short: "Set the org's active deploy target (or --shared to revert)",
-		Args:  cobra.MaximumNArgs(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			e := envOf()
-			org, err := e.requireOrg()
-			if err != nil {
-				return err
-			}
-			var clusterID *string
-			switch {
-			case shared:
-				clusterID = nil
-			case len(args) == 1:
-				clusterID = &args[0]
-			default:
-				return fmt.Errorf("give a cluster id, or --shared to revert to the shared cluster")
-			}
-			t, err := e.platform(gf).SelectTarget(cmd.Context(), org, clusterID)
-			if err != nil {
-				return err
-			}
-			return e.emit(t, func(w io.Writer) { printTarget(w, t) })
-		},
-	}
-	selectCmd.Flags().BoolVar(&shared, "shared", false, "revert to the shared cluster")
-
-	installBaseline := &cobra.Command{
-		Use:   "install-baseline <cluster-id>",
-		Short: "Install the hanzo-operator + per-tenant baseline on a cluster",
-		Args:  cobra.ExactArgs(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			e := envOf()
-			org, err := e.requireOrg()
-			if err != nil {
-				return err
-			}
-			if err := e.platform(gf).InstallBaseline(cmd.Context(), org, args[0]); err != nil {
-				return err
-			}
-			fmt.Fprintf(cmd.OutOrStdout(), "baseline install requested for %s\n", args[0])
-			return nil
-		},
-	}
-
-	target := &cobra.Command{
-		Use:   "target",
-		Short: "Show the org's current resolved deploy target",
-		Args:  cobra.NoArgs,
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			e := envOf()
-			org, err := e.requireOrg()
-			if err != nil {
-				return err
-			}
-			t, err := e.platform(gf).Target(cmd.Context(), org)
-			if err != nil {
-				return err
-			}
-			return e.emit(t, func(w io.Writer) { printTarget(w, t) })
-		},
-	}
-
-	cmd.AddCommand(list, get, create, selectCmd, installBaseline, target)
+	cmd.AddCommand(list, get)
 	return cmd
 }

+// gpuCell renders the live GPU inventory of a cluster ("-" when none).
+func gpuCell(c Cluster) string {
+	var parts []string
+	if c.NvidiaGPU > 0 {
+		parts = append(parts, fmt.Sprintf("%d nvidia", c.NvidiaGPU))
+	}
+	if c.AmdGPU > 0 {
+		parts = append(parts, fmt.Sprintf("%d amd", c.AmdGPU))
+	}
+	if len(parts) == 0 {
+		return "-"
+	}
+	return strings.Join(parts, "+")
+}
+
 func printCluster(w io.Writer, c Cluster) {
 	tw := newTab(w)
-	fmt.Fprintf(tw, "id:\t%s\n", c.DoksClusterID)
+	fmt.Fprintf(tw, "id:\t%s\n", dashIfEmpty(c.ID()))
 	fmt.Fprintf(tw, "name:\t%s\n", c.Name)
-	fmt.Fprintf(tw, "region:\t%s\n", c.Region)
-	fmt.Fprintf(tw, "status:\t%s\n", c.Status)
-	fmt.Fprintf(tw, "phase:\t%s\n", c.Phase)
-	fmt.Fprintf(tw, "active:\t%s\n", yesno(c.Active))
-	fmt.Fprintf(tw, "operatorInstalled:\t%s\n", yesno(c.OperatorInstalled))
-	fmt.Fprintf(tw, "baselineInstalled:\t%s\n", yesno(c.BaselineInstalled))
-	fmt.Fprintf(tw, "endpoint:\t%s\n", deref(c.Endpoint))
-	fmt.Fprintf(tw, "k8sVersion:\t%s\n", deref(c.K8sVersion))
-	fmt.Fprintf(tw, "created:\t%s\n", c.CreatedAt)
-	if c.BaselineError != nil && *c.BaselineError != "" {
-		fmt.Fprintf(tw, "baselineError:\t%s\n", *c.BaselineError)
-	}
-	tw.Flush()
-}
-
-func printTarget(w io.Writer, t *Target) {
-	tw := newTab(w)
-	kind := "shared"
-	if t.Dedicated {
-		kind = "dedicated"
-	}
-	fmt.Fprintf(tw, "cluster:\t%s\n", t.Cluster)
-	fmt.Fprintf(tw, "kind:\t%s\n", kind)
-	for ns, env := range t.Namespaces {
-		fmt.Fprintf(tw, "namespace:\t%s -> %s\n", ns, env)
+	fmt.Fprintf(tw, "region:\t%s\n", dashIfEmpty(c.Region))
+	fmt.Fprintf(tw, "status:\t%s\n", dashIfEmpty(c.Status))
+	fmt.Fprintf(tw, "kind:\t%s\n", dashIfEmpty(c.Kind))
+	fmt.Fprintf(tw, "nodeCount:\t%d\n", c.NodeCount)
+	fmt.Fprintf(tw, "nodeSize:\t%s\n", dashIfEmpty(c.NodeSize))
+	fmt.Fprintf(tw, "gpus:\t%s\n", gpuCell(c))
+	fmt.Fprintf(tw, "created:\t%s\n", dashIfEmpty(c.CreatedAt))
+	for _, np := range c.NodePools {
+		fmt.Fprintf(tw, "pool:\t%s (%s x%d, autoscale=%s)\n", np.Name, np.Size, np.Count, yesno(np.AutoScale))
 	}
 	tw.Flush()
 }
@@ -387,6 +272,10 @@ func newBuildCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
 			if br.Repo == "" || br.SHA == "" || br.Image == "" {
 				return fmt.Errorf("--repo (or positional), --sha and --image are required")
 			}
+			// The platform build muscle clones an https git URL; accept the
+			// idiomatic `owner/name` shorthand and expand it to GitHub (the host
+			// for every hanzoai/luxfi/zooai repo). A full URL passes through.
+			br.Repo = normalizeRepoURL(br.Repo)
 			if br.OrganizationID == "" {
 				br.OrganizationID = e.Org // optional; server defaults to DEFAULT_BUILD_ORG_ID
 			}
@@ -419,32 +308,24 @@ func newBuildCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
 	return cmd
 }

-// ---------------------------------------------------------------------------
-// k8s — deploy-target helpers.
-// ---------------------------------------------------------------------------
-
-func newK8sCmd(envOf func() *Env, gf *globalFlags) *cobra.Command {
-	cmd := &cobra.Command{
-		Use:   "k8s",
-		Short: "Kubernetes deploy-target helpers",
+// normalizeRepoURL expands the idiomatic `owner/name` shorthand to a full GitHub
+// https URL (the platform build muscle clones https), and leaves an explicit URL
+// (http/https/git/ssh scheme, or a scp-style git@host:owner/name) untouched. Only
+// a bare single-segment `owner/name` — two path parts, no scheme, no host — is
+// expanded; anything else is the caller's explicit choice and passes through.
+func normalizeRepoURL(repo string) string {
+	r := strings.TrimSpace(repo)
+	if r == "" {
+		return r
 	}
-	target := &cobra.Command{
-		Use:   "target",
-		Short: "Show the org's current resolved deploy target (cluster + namespaces)",
-		Args:  cobra.NoArgs,
-		RunE: func(cmd *cobra.Command, _ []string) error {
-			e := envOf()
-			org, err := e.requireOrg()
-			if err != nil {
-				return err
-			}
-			t, err := e.platform(gf).Target(cmd.Context(), org)
-			if err != nil {
-				return err
-			}
-			return e.emit(t, func(w io.Writer) { printTarget(w, t) })
-		},
+	// Already a URL or scp-style remote → leave as-is.
+	if strings.Contains(r, "://") || strings.Contains(r, "@") {
+		return r
 	}
-	cmd.AddCommand(target)
-	return cmd
+	// Bare owner/name (exactly two non-empty segments, no host dot in the first).
+	parts := strings.Split(strings.Trim(r, "/"), "/")
+	if len(parts) == 2 && parts[0] != "" && parts[1] != "" && !strings.Contains(parts[0], ".") {
+		return "https://github.com/" + parts[0] + "/" + parts[1]
+	}
+	return r
 }
@@ -8,6 +8,24 @@ import (
 	"testing"
 )

+func TestNormalizeRepoURL(t *testing.T) {
+	cases := map[string]string{
+		"luxfi/wallet":                    "https://github.com/luxfi/wallet",
+		"hanzoai/cloud":                   "https://github.com/hanzoai/cloud",
+		"https://github.com/luxfi/wallet": "https://github.com/luxfi/wallet", // full URL untouched
+		"git@github.com:luxfi/wallet.git": "git@github.com:luxfi/wallet.git", // scp-style untouched
+		"https://gitlab.com/org/repo":     "https://gitlab.com/org/repo",     // non-github URL untouched
+		"owner/name/extra":                "owner/name/extra",                // not a bare owner/name
+		"single":                          "single",                          // not two segments
+		"":                                "",                                // empty
+	}
+	for in, want := range cases {
+		if got := normalizeRepoURL(in); got != want {
+			t.Errorf("normalizeRepoURL(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
 // withPlatform points the CLI at an httptest platform via env (HANZO_PLATFORM_URL
 // + HANZO_PLATFORM_TOKEN), the same resolution path the real binary uses.
 func withPlatform(t *testing.T, h http.HandlerFunc) string {
@@ -20,11 +38,15 @@ func withPlatform(t *testing.T, h http.HandlerFunc) string {
 	return srv.URL
 }

+// apps list hits the LIVE board path /v1/paas/apps and renders the fleet table.
 func TestAppsListCommandTable(t *testing.T) {
-	withPlatform(t, func(w http.ResponseWriter, _ *http.Request) {
+	withPlatform(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/paas/apps" {
+			t.Errorf("apps path = %s, want /v1/paas/apps", r.URL.Path)
+		}
 		_ = json.NewEncoder(w).Encode(AppsList{
 			Apps: []AppView{
-				{Org: "hanzoai", App: "iam", Env: "main", DeclaredTag: strptr("v1.2.3"), RunningTag: strptr("v1.2.3"), Health: strptr("green"), Drift: json.RawMessage(`{"severity":"ok"}`)},
+				{Org: "hanzoai", App: "iam", Env: "main", DeclaredTag: "v1.2.3", RunningTag: "v1.2.3", Health: "green", Drift: json.RawMessage(`{"severity":"ok"}`)},
 			},
 			Summary: struct {
 				Total   int            `json:"total"`
@@ -43,6 +65,20 @@ func TestAppsListCommandTable(t *testing.T) {
 	}
 }

+// apps list honors --env/--health/--drift as server query params (the board filters).
+func TestAppsListCommandFilters(t *testing.T) {
+	withPlatform(t, func(w http.ResponseWriter, r *http.Request) {
+		q := r.URL.Query()
+		if q.Get("env") != "main" || q.Get("health") != "red" || q.Get("drift") != "1" {
+			t.Errorf("filters not forwarded: %s", r.URL.RawQuery)
+		}
+		_ = json.NewEncoder(w).Encode(AppsList{})
+	})
+	if _, err := runRoot(t, "", "apps", "list", "--env", "main", "--health", "red", "--drift"); err != nil {
+		t.Fatalf("apps list filters: %v", err)
+	}
+}
+
 func TestAppsListCommandJSON(t *testing.T) {
 	withPlatform(t, func(w http.ResponseWriter, _ *http.Request) {
 		_ = json.NewEncoder(w).Encode(AppsList{Apps: []AppView{{Org: "hanzoai", App: "iam", Env: "main"}}})
@@ -60,69 +96,112 @@ func TestAppsListCommandJSON(t *testing.T) {
 	}
 }

+// apps get hits /v1/paas/apps/{app}.
+func TestAppsGetCommand(t *testing.T) {
+	withPlatform(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/paas/apps/iam" {
+			t.Errorf("path = %s, want /v1/paas/apps/iam", r.URL.Path)
+		}
+		_ = json.NewEncoder(w).Encode(AppView{ID: "hanzoai/iam/main", Org: "hanzoai", App: "iam", Env: "main", DeclaredTag: "v1.2.3", Health: "green", Phase: "Running"})
+	})
+	out, err := runRoot(t, "", "apps", "get", "iam")
+	if err != nil {
+		t.Fatalf("apps get: %v", err)
+	}
+	for _, want := range []string{"hanzoai/iam/main", "Running", "v1.2.3"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("apps get missing %q in:\n%s", want, out)
+		}
+	}
+}
+
+// deploy hits /v1/paas/apps/{app}/deploy — a rolling restart, org from identity.
 func TestDeployCommand(t *testing.T) {
 	withPlatform(t, func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path != "/v1/org/acme/project/p1/env/e1/container/app-x/redeploy" {
-			t.Errorf("redeploy path = %s", r.URL.Path)
+		if r.URL.Path != "/v1/paas/apps/app-x/deploy" || r.URL.Query().Get("env") != "main" {
+			t.Errorf("redeploy request = %s?%s", r.URL.Path, r.URL.RawQuery)
 		}
-		_ = json.NewEncoder(w).Encode(map[string]bool{"ok": true})
+		w.WriteHeader(202)
+		_ = json.NewEncoder(w).Encode(DeployResult{OK: true, App: "app-x", Namespace: "hanzo", Env: "main", RestartedAt: "2026-07-18T12:00:00Z"})
 	})
-	out, err := runRoot(t, "", "deploy", "app-x", "--org", "acme", "--project", "p1", "--env", "e1")
+	out, err := runRoot(t, "", "deploy", "app-x", "--env", "main")
 	if err != nil {
 		t.Fatalf("deploy: %v", err)
 	}
-	if !strings.Contains(out, "redeployed app-x") {
+	if !strings.Contains(out, "restarted app-x") || !strings.Contains(out, "namespace=hanzo") {
 		t.Fatalf("deploy output: %q", out)
 	}
 }

-func TestDeployRequiresProjectEnv(t *testing.T) {
-	withPlatform(t, func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(200) })
-	if _, err := runRoot(t, "", "deploy", "app-x", "--org", "acme"); err == nil {
-		t.Fatalf("deploy must require --project/--env")
+// deploy REQUIRES --env — a bare deploy errors CLI-side, never silently prod.
+func TestDeployRequiresEnv(t *testing.T) {
+	withPlatform(t, func(w http.ResponseWriter, _ *http.Request) {
+		t.Error("deploy without --env must not reach the server")
+		w.WriteHeader(202)
+	})
+	if _, err := runRoot(t, "", "deploy", "app-x"); err == nil {
+		t.Fatalf("deploy must require --env")
 	}
 }

-func TestDeployRequiresOrg(t *testing.T) {
-	withPlatform(t, func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(200) })
-	if _, err := runRoot(t, "", "deploy", "app-x", "--project", "p1", "--env", "e1"); err == nil {
-		t.Fatalf("deploy must require an org")
+// deploy --env selects the lifecycle namespace via the ?env query param.
+func TestDeployCommandEnv(t *testing.T) {
+	withPlatform(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/paas/apps/chat/deploy" || r.URL.Query().Get("env") != "test" {
+			t.Errorf("deploy env request = %s?%s", r.URL.Path, r.URL.RawQuery)
+		}
+		w.WriteHeader(202)
+		_ = json.NewEncoder(w).Encode(DeployResult{OK: true, App: "chat", Namespace: "hanzo-testnet", Env: "test", RestartedAt: "2026-07-18T12:00:00Z"})
+	})
+	if _, err := runRoot(t, "", "deploy", "chat", "--env", "test"); err != nil {
+		t.Fatalf("deploy --env: %v", err)
 	}
 }

+// A non-ok deploy response is surfaced as an error.
+func TestDeployNotOK(t *testing.T) {
+	withPlatform(t, func(w http.ResponseWriter, _ *http.Request) {
+		_ = json.NewEncoder(w).Encode(DeployResult{OK: false})
+	})
+	if _, err := runRoot(t, "", "deploy", "app-x", "--env", "main"); err == nil {
+		t.Fatalf("deploy must error when the server does not report ok")
+	}
+}
+
+// clusters list hits the LIVE /v1/clusters (org from identity, not the path).
 func TestClustersListCommand(t *testing.T) {
 	withPlatform(t, func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path != "/v1/org/acme/cluster" {
-			t.Errorf("path = %s", r.URL.Path)
+		if r.URL.Path != "/v1/clusters" {
+			t.Errorf("path = %s, want /v1/clusters", r.URL.Path)
 		}
 		_ = json.NewEncoder(w).Encode(map[string]any{"clusters": []Cluster{
-			{DoksClusterID: "c1", Name: "hanzo-acme", Region: "sfo3", Status: "running", Phase: "ready", Active: true, OperatorInstalled: true, BaselineInstalled: true},
+			{DoksClusterID: "c1", Name: "hanzo-acme", Region: "sfo3", Status: "running", Kind: "managed", NodeCount: 3, NodeSize: "s-2vcpu-4gb", NvidiaGPU: 2},
 		}})
 	})
-	out, err := runRoot(t, "", "clusters", "list", "--org", "acme")
+	out, err := runRoot(t, "", "clusters", "list")
 	if err != nil {
 		t.Fatalf("clusters list: %v", err)
 	}
-	for _, want := range []string{"NAME", "hanzo-acme", "c1", "ready", "yes"} {
+	for _, want := range []string{"NAME", "hanzo-acme", "c1", "managed", "2 nvidia"} {
 		if !strings.Contains(out, want) {
 			t.Fatalf("clusters list missing %q in:\n%s", want, out)
 		}
 	}
 }

-func TestK8sTargetCommand(t *testing.T) {
-	withPlatform(t, func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path != "/v1/org/acme/cluster/select" {
-			t.Errorf("path = %s", r.URL.Path)
-		}
-		_ = json.NewEncoder(w).Encode(map[string]any{"target": Target{Cluster: "hanzo-k8s", Dedicated: false, Namespaces: map[string]string{"hanzo": "main"}}})
+// clusters get filters the live list client-side by id or name.
+func TestClustersGetCommand(t *testing.T) {
+	withPlatform(t, func(w http.ResponseWriter, _ *http.Request) {
+		_ = json.NewEncoder(w).Encode(map[string]any{"clusters": []Cluster{
+			{DoksClusterID: "c1", Name: "hanzo-acme", Region: "sfo3", Status: "running", Kind: "byo", NodeCount: 1},
+		}})
 	})
-	out, err := runRoot(t, "", "k8s", "target", "--org", "acme")
+	out, err := runRoot(t, "", "clusters", "get", "c1")
 	if err != nil {
-		t.Fatalf("k8s target: %v", err)
+		t.Fatalf("clusters get: %v", err)
 	}
-	if !strings.Contains(out, "hanzo-k8s") || !strings.Contains(out, "shared") {
-		t.Fatalf("k8s target output: %q", out)
+	if !strings.Contains(out, "hanzo-acme") || !strings.Contains(out, "byo") {
+		t.Fatalf("clusters get output: %q", out)
 	}
 }

@@ -167,5 +246,3 @@ func TestConfigSetGetCommand(t *testing.T) {
 		t.Fatalf("config get = %q", out)
 	}
 }
-
-func strptr(s string) *string { return &s }
@@ -8,7 +8,7 @@ package cli
 // cosign-signed binary from the latest github.com/hanzoai/engine release), so the
 // CLI never re-implements platform detection or verification. `serve` launches the
 // installed binary (`hanzoai --port P run -m MODEL`); `status` probes it, reusing
-// the same /v1/models probe `hanzo gpu connect --serve-engine` advertises with.
+// the same /v1/models probe `hanzo link --serve-engine` advertises with.

 import (
 	"context"
@@ -0,0 +1,157 @@
+package cli
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// TestParseRocmSmiCSV — the AMD GPU inventory names a card from its marketing
+// series + gfx target, exactly as `rocm-smi --showproductname --csv` reports on
+// evo's gfx1151 Radeon 8060S. This is the primary AMD detection path.
+func TestParseRocmSmiCSV(t *testing.T) {
+	// Real evo output (header + one card row).
+	csv := []byte("device,Card Series,Card Model,Card Vendor,Card SKU,Subsystem ID,Device Rev,Node ID,GUID,GFX Version\n" +
+		"card0,Radeon 8060S Graphics,0x1586,Advanced Micro Devices Inc. [AMD/ATI],STRXLGEN,-0x7fe3,0xc1,1,49819,gfx1151\n")
+	gpus := parseRocmSmiCSV(csv)
+	if len(gpus) != 1 {
+		t.Fatalf("want 1 AMD GPU, got %d (%+v)", len(gpus), gpus)
+	}
+	if got, want := gpus[0].Name, "AMD Strix Halo \u00b7 Radeon 8060S Graphics (gfx1151)"; got != want {
+		t.Errorf("name = %q, want %q", got, want)
+	}
+}
+
+// TestGfxNameDecodesTargetVersion — the kfd fallback decodes gfx_target_version.
+func TestGfxNameDecodesTargetVersion(t *testing.T) {
+	for _, c := range []struct {
+		v    int
+		want string
+	}{
+		{110501, "gfx1151"}, // evo Radeon 8060S / Strix Halo
+		{90012, "gfx9012"},  // sanity: MI-class encoding shape
+		{100300, "gfx1030"}, // RDNA2
+	} {
+		if got := gfxName(c.v); got != c.want {
+			t.Errorf("gfxName(%d) = %q, want %q", c.v, got, c.want)
+		}
+	}
+}
+
+// TestParseKfdTopology — the driver-only fallback (no rocm-smi) still finds the GPU
+// from /sys/class/kfd: node 0 is the CPU (simd_count 0, skipped), node 1 is the
+// gfx1151 GPU. Built against a fixture tree mirroring evo's real properties files.
+func TestParseKfdTopology(t *testing.T) {
+	root := t.TempDir()
+	writeNode(t, root, "0", "simd_count 0\ngfx_target_version 0\n")
+	writeNode(t, root, "1", "cpu_cores_count 0\nsimd_count 80\ngfx_target_version 110501\n")
+	gpus := parseKfdTopology(root)
+	if len(gpus) != 1 {
+		t.Fatalf("want 1 GPU node (CPU node 0 skipped), got %d (%+v)", len(gpus), gpus)
+	}
+	if got, want := gpus[0].Name, "AMD Strix Halo (gfx1151)"; got != want {
+		t.Errorf("name = %q, want %q", got, want)
+	}
+	if got, want := gpus[0].Arch, "gfx1151"; got != want {
+		t.Errorf("arch = %q, want %q", got, want)
+	}
+}
+
+// TestParseVulkaninfoSummary — the last resort keeps only AMD/Radeon devices so it
+// never double-counts a card another vendor path already reported.
+func TestParseVulkaninfoSummary(t *testing.T) {
+	out := []byte("GPU0:\n\tdeviceName = AMD Radeon Graphics (RADV GFX1151)\n" +
+		"GPU1:\n\tdeviceName = llvmpipe (LLVM 18.1.0, 256 bits)\n")
+	gpus := parseVulkaninfoSummary(out)
+	if len(gpus) != 1 {
+		t.Fatalf("want 1 AMD device (llvmpipe filtered), got %d (%+v)", len(gpus), gpus)
+	}
+	if got := gpus[0].Name; got != "AMD Radeon Graphics (RADV GFX1151)" {
+		t.Errorf("name = %q", got)
+	}
+}
+
+func writeNode(t *testing.T, root, id, props string) {
+	t.Helper()
+	dir := filepath.Join(root, id)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "properties"), []byte(props), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// TestPickAmdMemUnified — an APU whose VRAM is a token carve-out reports the
+// machine's unified RAM snapped to hardware capacity (evo: 1 GiB VRAM, 118 GiB
+// GTT, 124.4 GiB kernel-visible of 128 GiB physical → 128 GiB); a discrete card
+// keeps its VRAM.
+func TestPickAmdMemUnified(t *testing.T) {
+	if miB, unified := pickAmdMem(1024, 120832, 127411); !unified || miB != 131072 {
+		t.Errorf("APU: got (%d, %v), want (131072, true)", miB, unified)
+	}
+	if miB, unified := pickAmdMem(24576, 8192, 127411); unified || miB != 24576 {
+		t.Errorf("discrete: got (%d, %v), want (24576, false)", miB, unified)
+	}
+}
+
+// TestSnapUnified — a small firmware gap snaps up to the DIMM capacity; a big
+// carve-out is real lost capacity and stays as-is; exact multiples stand.
+func TestSnapUnified(t *testing.T) {
+	for _, c := range []struct{ in, want int64 }{
+		{127411, 131072}, // evo: 124.4 GiB visible of 128 GiB physical
+		{124610, 131072}, // spark GB10: 121.7 GiB visible of 128 GiB physical (~6.3 GiB firmware)
+		{131072, 131072}, // exact 128 GiB
+		{119194, 119194}, // ~116 GiB visible (16 GiB BIOS carve) — 11.6 GiB gap, keep honest
+		{63488, 65536},   // 62 GiB visible of 64 GiB
+	} {
+		if got := snapUnified(c.in); got != c.want {
+			t.Errorf("snapUnified(%d) = %d, want %d", c.in, got, c.want)
+		}
+	}
+}
+
+// TestAmdAPUName — the board renders the APU as the processor the owner bought,
+// normalized from the BIOS shouting; non-Ryzen hosts opt out.
+func TestAmdAPUName(t *testing.T) {
+	if got, want := amdAPUName("AMD RYZEN AI MAX+ 395 w/ Radeon 8060S"), "AMD Ryzen AI Max+ 395 w/ Radeon 8060S"; got != want {
+		t.Errorf("amdAPUName = %q, want %q", got, want)
+	}
+	if got := amdAPUName("Intel(R) Core(TM) i9-14900K"); got != "" {
+		t.Errorf("non-Ryzen host must opt out, got %q", got)
+	}
+}
+
+// TestApuProcessorNames — only unified-memory cards are renamed; a discrete
+// card on the same host keeps its own identity.
+func TestApuProcessorNames(t *testing.T) {
+	gpus := []gpuInfo{
+		{Name: "AMD Strix Halo \u00b7 Radeon 8060S Graphics (gfx1151)", Arch: "gfx1151", Unified: true},
+		{Name: "Radeon RX 7900 XTX (gfx1100)", Arch: "gfx1100"},
+	}
+	out := apuProcessorNames(gpus, "AMD RYZEN AI MAX+ 395 w/ Radeon 8060S")
+	if got, want := out[0].Name, "AMD Ryzen AI Max+ 395 w/ Radeon 8060S (gfx1151)"; got != want {
+		t.Errorf("APU name = %q, want %q", got, want)
+	}
+	if got, want := out[1].Name, "Radeon RX 7900 XTX (gfx1100)"; got != want {
+		t.Errorf("discrete name = %q, want %q", got, want)
+	}
+}
+
+// TestParseNvidiaSmiCSV — a GB10-class unified SoC ("[N/A]" VRAM) reports the
+// machine RAM snapped to capacity + its sm arch; a discrete card keeps its VRAM.
+func TestParseNvidiaSmiCSV(t *testing.T) {
+	out := []byte("NVIDIA GB10, [N/A], 12.1\n")
+	gpus := parseNvidiaSmiCSV(out, 124610)
+	if len(gpus) != 1 {
+		t.Fatalf("want 1 GPU, got %d", len(gpus))
+	}
+	g := gpus[0]
+	if g.Name != "NVIDIA GB10" || g.MemoryTotal != "131072 MiB" || !g.Unified || g.Arch != "sm_121" {
+		t.Errorf("GB10 = %+v", g)
+	}
+	disc := parseNvidiaSmiCSV([]byte("NVIDIA GeForce RTX 4090, 24564 MiB, 8.9\n"), 124610)
+	if d := disc[0]; d.MemoryTotal != "24564 MiB" || d.Unified || d.Arch != "sm_89" {
+		t.Errorf("discrete = %+v", d)
+	}
+}
@@ -109,6 +109,7 @@ func TestBuildRegistrationCarriesEngine(t *testing.T) {
 		jobsNS:       "gpu-jobs",
 		gpus:         []gpuInfo{{Name: "NVIDIA GB10", MemoryTotal: "122880 MiB"}},
 		serveEngine:  true,
+		studioReady:  true,
 		engineURL:    srv.URL,
 		engineAdvURL: "http://node.example:1234",
 	}
@@ -136,7 +137,7 @@ func TestBuildRegistrationCarriesEngine(t *testing.T) {
 }

 func TestCapabilitiesWithoutEngine(t *testing.T) {
-	w := &worker{serveEngine: false}
+	w := &worker{serveEngine: false, studioReady: true}
 	caps := w.capabilities()
 	if len(caps) != 1 || caps[0] != studioCap {
 		t.Fatalf("capabilities = %v, want just [%q] when not serving an engine", caps, studioCap)
@@ -0,0 +1,75 @@
+package cli
+
+import (
+	"encoding/json"
+	"os/exec"
+	"strings"
+	"testing"
+)
+
+// TestFnValidate — payload bounds: script required, flag-injection via
+// requirements refused, timeout defaulted and capped.
+func TestFnValidate(t *testing.T) {
+	if _, err := fnValidate(json.RawMessage(`{}`)); err == nil {
+		t.Error("empty script must be refused")
+	}
+	if _, err := fnValidate(json.RawMessage(`{"script":"print(1)","requirements":["--index-url=evil"]}`)); err == nil {
+		t.Error("flag-shaped requirement must be refused")
+	}
+	in, err := fnValidate(json.RawMessage(`{"script":"print(1)"}`))
+	if err != nil || in.TimeoutSeconds != 3600 {
+		t.Errorf("default timeout: got %d, err %v", in.TimeoutSeconds, err)
+	}
+	in, _ = fnValidate(json.RawMessage(`{"script":"print(1)","timeoutSeconds":999999}`))
+	if in.TimeoutSeconds != 21600 {
+		t.Errorf("timeout cap: got %d, want 21600", in.TimeoutSeconds)
+	}
+}
+
+// TestTailBuffer — a chatty training loop keeps only the LAST bytes, flagged.
+func TestTailBuffer(t *testing.T) {
+	tb := &tailBuffer{cap: 8}
+	tb.Write([]byte("0123456789"))
+	if string(tb.buf) != "23456789" || !tb.truncated {
+		t.Errorf("tail = %q truncated=%v", tb.buf, tb.truncated)
+	}
+	tb2 := &tailBuffer{cap: 8}
+	tb2.Write([]byte("abc"))
+	if string(tb2.buf) != "abc" || tb2.truncated {
+		t.Errorf("small write mangled: %q %v", tb2.buf, tb2.truncated)
+	}
+}
+
+// TestHasNonRenderLane — echo and studio.render alone keep the render-only
+// poison guard; a registered fn.run lane lifts it.
+func TestHasNonRenderLane(t *testing.T) {
+	w := &worker{handlers: map[string]jobHandler{"echo": echoHandler, studioCap: nil}}
+	if w.hasNonRenderLane() {
+		t.Error("render-only worker must report no extra lane")
+	}
+	w.handlers[fnCap] = fnRunHandler
+	if !w.hasNonRenderLane() {
+		t.Error("fn.run lane must lift the guard")
+	}
+}
+
+// TestFnRunSmoke — the real handler end-to-end against the local uv: a script
+// that prints and exits 0. Skipped where uv is absent.
+func TestFnRunSmoke(t *testing.T) {
+	if !uvPresent() {
+		t.Skip("uv not installed")
+	}
+	res, err := fnRunHandler(t.Context(), json.RawMessage(`{"script":"print(2+2)","timeoutSeconds":120}`))
+	if err != nil {
+		t.Fatalf("fn.run: %v", err)
+	}
+	m := res.(map[string]any)
+	if !strings.Contains(m["output"].(string), "4") {
+		t.Errorf("output = %q, want it to contain 4", m["output"])
+	}
+}
+
+func uvPresent() bool {
+	_, err := exec.LookPath("uv")
+	return err == nil
+}
@@ -0,0 +1,291 @@
+package cli
+
+// gpu_queue_test.go — the per-GPU claim contract: a job pinned to THIS machine's
+// lane ("gpu:<identity>") is claimed BEFORE the shared any-GPU lane ("gpu-jobs"),
+// both within the gpu-jobs namespace. A stub cloud records the taskQueue of every
+// claim so the ORDER is the assertion.
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+// stubJobsCloud records the taskQueue of every claim and serves the queued job (if
+// any) on the matching lane, once. A lane with no job (or already drained) answers
+// 204; complete/fail/heartbeat answer 200.
+func stubJobsCloud(t *testing.T, claims *[]string, jobsByLane map[string]*claimedActivity) *httptest.Server {
+	t.Helper()
+	return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == http.MethodPost && strings.HasSuffix(r.URL.Path, "/activities/claim") {
+			var body struct {
+				TaskQueue string `json:"taskQueue"`
+			}
+			_ = json.NewDecoder(r.Body).Decode(&body)
+			*claims = append(*claims, body.TaskQueue)
+			if job := jobsByLane[body.TaskQueue]; job != nil {
+				jobsByLane[body.TaskQueue] = nil // deliver once
+				_ = json.NewEncoder(w).Encode(job)
+				return
+			}
+			w.WriteHeader(http.StatusNoContent)
+			return
+		}
+		w.WriteHeader(http.StatusOK) // complete / fail / heartbeat
+	}))
+}
+
+// echoJob is a GPU-free job the worker's echo handler runs to completion instantly,
+// so a claim test never needs a real render backend.
+func echoJob(id string) *claimedActivity {
+	a := &claimedActivity{Input: json.RawMessage(`{}`)}
+	a.Execution.WorkflowId, a.Execution.RunId = id, id
+	a.Type.Name = "echo"
+	return a
+}
+
+func testWorker(t *testing.T, url string) *worker {
+	t.Helper()
+	t.Setenv("HANZO_TOKEN", "test-token") // ensureToken honors this; no `hanzo login`
+	return &worker{
+		env:         &Env{CloudURL: url},
+		http:        &http.Client{Timeout: 5 * time.Second},
+		baseURL:     url,
+		identity:    "spark",
+		hostname:    "spark",
+		jobsNS:      "gpu-jobs",
+		handlers:    map[string]jobHandler{"echo": echoHandler},
+		studioReady: true, // a render-capable node (preflight passed)
+	}
+}
+
+func TestGPUQueueLaneName(t *testing.T) {
+	w := &worker{identity: "spark"}
+	if got := w.gpuQueue(); got != "gpu:spark" {
+		t.Fatalf("gpuQueue() = %q, want gpu:spark", got)
+	}
+}
+
+// A job pinned to THIS GPU's lane is claimed first — the shared lane is not even
+// polled that cycle.
+func TestClaimPrefersTargetedLane(t *testing.T) {
+	var claims []string
+	srv := stubJobsCloud(t, &claims, map[string]*claimedActivity{"gpu:spark": echoJob("j1")})
+	defer srv.Close()
+	if err := testWorker(t, srv.URL).claimAndRun(context.Background(), io.Discard); err != nil {
+		t.Fatalf("claimAndRun: %v", err)
+	}
+	if len(claims) != 1 || claims[0] != "gpu:spark" {
+		t.Fatalf("claims = %v, want exactly [gpu:spark] (targeted first; shared not polled)", claims)
+	}
+}
+
+// With its own lane empty, the worker falls through to the shared any-GPU lane.
+func TestClaimFallsBackToSharedLane(t *testing.T) {
+	var claims []string
+	srv := stubJobsCloud(t, &claims, map[string]*claimedActivity{"gpu-jobs": echoJob("j2")})
+	defer srv.Close()
+	if err := testWorker(t, srv.URL).claimAndRun(context.Background(), io.Discard); err != nil {
+		t.Fatalf("claimAndRun: %v", err)
+	}
+	if len(claims) != 2 || claims[0] != "gpu:spark" || claims[1] != "gpu-jobs" {
+		t.Fatalf("claims = %v, want [gpu:spark gpu-jobs] (targeted, then shared)", claims)
+	}
+}
+
+// Both lanes empty polls targeted THEN shared and runs nothing.
+func TestClaimBothLanesEmpty(t *testing.T) {
+	var claims []string
+	srv := stubJobsCloud(t, &claims, map[string]*claimedActivity{})
+	defer srv.Close()
+	if err := testWorker(t, srv.URL).claimAndRun(context.Background(), io.Discard); err != nil {
+		t.Fatalf("claimAndRun: %v", err)
+	}
+	if len(claims) != 2 || claims[0] != "gpu:spark" || claims[1] != "gpu-jobs" {
+		t.Fatalf("claims = %v, want [gpu:spark gpu-jobs]", claims)
+	}
+}
+
+// The render submit seam is the gated worker-mode execute path, not the open /prompt
+// — the shared contract with the studio's --worker-mode gate.
+func TestWorkerExecuteSeamIsGated(t *testing.T) {
+	if localWorkerExecute != "http://127.0.0.1:8188/v1/worker/execute" {
+		t.Fatalf("localWorkerExecute = %q, want the gated /v1/worker/execute seam", localWorkerExecute)
+	}
+}
+
+// A HUNG nvidia-smi (blocks until its bounded context fires) must NOT block the
+// caller: reportSample detaches the probe+POST onto a goroutine and returns at once,
+// so the worker's select loop keeps heartbeating and claiming. Guards the
+// worker-wedge regression (a synchronous probe that stalls the loop under GPU/driver
+// pressure → the machine flaps offline mid-render).
+func TestReportSampleNeverBlocksLoop(t *testing.T) {
+	orig := nvidiaSmi
+	defer func() { nvidiaSmi = orig }()
+	probing := make(chan struct{})
+	release := make(chan struct{})
+	nvidiaSmi = func(ctx context.Context) ([]byte, error) {
+		close(probing) // entered the probe (the nvidiaSmi var read already happened)
+		select {
+		case <-release: // the test lets us finish
+		case <-ctx.Done(): // or the bounded probe timeout fires
+		}
+		return nil, ctx.Err()
+	}
+	t.Setenv("HANZO_TOKEN", "t")
+	w := &worker{identity: "spark", hostname: "spark", http: &http.Client{Timeout: time.Second}, env: &Env{}, baseURL: "http://127.0.0.1:0"}
+
+	done := make(chan struct{})
+	go func() { w.reportSample(context.Background()); close(done) }()
+	select {
+	case <-done: // returned immediately — the select loop is never wedged
+	case <-time.After(500 * time.Millisecond):
+		t.Fatal("reportSample blocked the caller — a hung sampler would wedge the worker loop")
+	}
+	select {
+	case <-probing: // the probe really ran, on the detached goroutine (off the critical path)
+	case <-time.After(2 * time.Second):
+		t.Fatal("probe never started")
+	}
+	close(release)
+}
+
+// A node that can't serve renders (preflight failed) claims NOTHING — it must never
+// pull a render job onto a box that will only refuse it on the gated seam (poison
+// loop). It still heartbeats presence; it just stays idle.
+func TestNotStudioReadyClaimsNothing(t *testing.T) {
+	var claims []string
+	srv := stubJobsCloud(t, &claims, map[string]*claimedActivity{"gpu:spark": echoJob("j1")})
+	defer srv.Close()
+	w := testWorker(t, srv.URL)
+	w.studioReady = false
+	if err := w.claimAndRun(context.Background(), io.Discard); err != nil {
+		t.Fatalf("claimAndRun: %v", err)
+	}
+	if len(claims) != 0 {
+		t.Fatalf("a not-ready node claimed %v; want zero claims", claims)
+	}
+}
+
+// The terminal report must hit the RIGHT activity — namespace gpu-jobs, the CLAIMED
+// workflow+run ids, the correct verb. A stub that 200s every path lets an ns/id
+// routing regression pass, so assert the exact paths for both complete and fail.
+func TestTerminalReportsHitCorrectActivityPath(t *testing.T) {
+	t.Setenv("HANZO_TOKEN", "t")
+	var mu sync.Mutex
+	terminal := map[string]string{}
+	served := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case strings.HasSuffix(r.URL.Path, "/activities/claim"):
+			var body struct {
+				TaskQueue string `json:"taskQueue"`
+			}
+			_ = json.NewDecoder(r.Body).Decode(&body)
+			if body.TaskQueue != "gpu:spark" {
+				w.WriteHeader(http.StatusNoContent)
+				return
+			}
+			mu.Lock()
+			n := served
+			served++
+			mu.Unlock()
+			switch n {
+			case 0:
+				_ = json.NewEncoder(w).Encode(echoJob("wf1")) // echo handler → complete
+			case 1:
+				j := echoJob("wf2")
+				j.Type.Name = "nope" // no handler → fail
+				_ = json.NewEncoder(w).Encode(j)
+			default:
+				w.WriteHeader(http.StatusNoContent)
+			}
+		case strings.HasSuffix(r.URL.Path, "/complete"):
+			mu.Lock()
+			terminal["complete"] = r.URL.Path
+			mu.Unlock()
+			w.WriteHeader(http.StatusOK)
+		case strings.HasSuffix(r.URL.Path, "/fail"):
+			mu.Lock()
+			terminal["fail"] = r.URL.Path
+			mu.Unlock()
+			w.WriteHeader(http.StatusOK)
+		default:
+			w.WriteHeader(http.StatusOK)
+		}
+	}))
+	defer srv.Close()
+	w := testWorker(t, srv.URL)
+	if err := w.claimAndRun(context.Background(), io.Discard); err != nil {
+		t.Fatalf("run1 (echo→complete): %v", err)
+	}
+	if err := w.claimAndRun(context.Background(), io.Discard); err != nil {
+		t.Fatalf("run2 (unknown→fail): %v", err)
+	}
+	if got := terminal["complete"]; got != "/v1/tasks/namespaces/gpu-jobs/activities/wf1/wf1/complete" {
+		t.Fatalf("complete path = %q, want the claimed activity's exact ns+ids", got)
+	}
+	if got := terminal["fail"]; got != "/v1/tasks/namespaces/gpu-jobs/activities/wf2/wf2/fail" {
+		t.Fatalf("fail path = %q, want the claimed activity's exact ns+ids", got)
+	}
+}
+
+// SharePolicy.reject's fallback: an ABSENT or unparseable input field skips its gate
+// (permissive), never a hard error, so a policy only ever narrows on fields it can read.
+func TestSharePolicyRejectFallback(t *testing.T) {
+	var nilp *SharePolicy
+	if r := nilp.reject("studio.render", nil); r != "" {
+		t.Fatalf("nil policy must allow everything: %q", r)
+	}
+	p := &SharePolicy{AllowedJobTypes: []string{"studio.render"}}
+	if p.reject("echo", nil) == "" {
+		t.Fatal("a disallowed job type must be rejected")
+	}
+	if r := p.reject("studio.render", nil); r != "" {
+		t.Fatalf("an allowed job type must pass: %q", r)
+	}
+	p2 := &SharePolicy{AllowedOrgs: []string{"acme"}}
+	if r := p2.reject("studio.render", json.RawMessage(`{}`)); r != "" {
+		t.Fatalf("absent org must SKIP the org gate (fallback), not reject: %q", r)
+	}
+	if r := p2.reject("studio.render", json.RawMessage(`{"org":"acme"}`)); r != "" {
+		t.Fatalf("a matching org must pass: %q", r)
+	}
+	if p2.reject("studio.render", json.RawMessage(`{"org":"other"}`)) == "" {
+		t.Fatal("a non-allowed org must be rejected")
+	}
+	if r := p2.reject("studio.render", json.RawMessage(`not json`)); r != "" {
+		t.Fatalf("unparseable input must skip input gates, not reject: %q", r)
+	}
+}
+
+// studioCap is advertised ONLY when the node can actually render: a missing worker
+// token is never ready (the gated seam would 403), and the block reason is explicit.
+func TestStudioReadyGatesCapability(t *testing.T) {
+	t.Setenv("STUDIO_WORKER_TOKEN", "")
+	w := &worker{launchesStudio: true, http: &http.Client{}}
+	w.refreshStudioReady(context.Background())
+	if w.studioReady {
+		t.Fatal("no token must never be studio-ready")
+	}
+	if contains(w.capabilities(), studioCap) {
+		t.Fatalf("studioCap advertised without a token: %v", w.capabilities())
+	}
+	if w.studioBlockReason() == "" {
+		t.Fatal("a not-ready node must explain why it won't render")
+	}
+	// Token present + we launch the studio ⇒ ready ⇒ studioCap advertised.
+	t.Setenv("STUDIO_WORKER_TOKEN", "tok")
+	if changed := w.refreshStudioReady(context.Background()); !changed {
+		t.Fatal("adding the token should flip readiness")
+	}
+	if !w.studioReady || !contains(w.capabilities(), studioCap) {
+		t.Fatalf("token + launchesStudio must be ready + advertise studioCap: ready=%v caps=%v", w.studioReady, w.capabilities())
+	}
+}
@@ -0,0 +1,88 @@
+package cli
+
+// gpu_spec_test.go — the host static-spec a `hanzo link` node reports so
+// GET /v1/fleet can show its CPU arch, core count and total RAM (the fields a
+// code-linked box already carries). Real telemetry only: arch is `uname -m`, cores
+// are runtime.NumCPU, RAM is parsed from the OS — never a hardcoded machine.
+
+import (
+	"os/exec"
+	"runtime"
+	"strings"
+	"testing"
+)
+
+func TestParseMemTotalKB(t *testing.T) {
+	// A real /proc/meminfo head from a 128 GiB box. MemTotal is in kB; we report bytes.
+	meminfo := []byte("MemTotal:       131923980 kB\nMemFree:         1048576 kB\nMemAvailable:  120000000 kB\n")
+	if got, want := parseMemTotalKB(meminfo), int64(131923980)*1024; got != want {
+		t.Fatalf("parseMemTotalKB = %d, want %d bytes", got, want)
+	}
+	// Absent / malformed input is reported as 0 (unknown), never a guess.
+	for name, in := range map[string]string{
+		"empty":       "",
+		"no-memtotal": "MemFree: 100 kB\n",
+		"malformed":   "MemTotal: notanumber kB\n",
+		"no-value":    "MemTotal:\n",
+	} {
+		if got := parseMemTotalKB([]byte(in)); got != 0 {
+			t.Fatalf("%s: parseMemTotalKB = %d, want 0", name, got)
+		}
+	}
+}
+
+// detectMemTotal reads the real host, so on Linux/macOS CI it must return a positive
+// byte count — proof the reporter reads actual RAM rather than shipping 0.
+func TestDetectMemTotalIsReal(t *testing.T) {
+	if runtime.GOOS != "linux" && runtime.GOOS != "darwin" {
+		t.Skipf("no MemTotal source on %s", runtime.GOOS)
+	}
+	got := detectMemTotal()
+	if got <= 0 {
+		t.Fatalf("detectMemTotal = %d, want the host's real RAM (>0)", got)
+	}
+	// Evidence: what THIS host actually reports (never hardcoded). On the GB10 spark
+	// box this prints aarch64 + ~128 GiB read from /proc/meminfo.
+	t.Logf("real host spec: arch=%s cpus=%d memory=%d bytes (%.1f GiB)",
+		detectArch(), runtime.NumCPU(), got, float64(got)/(1<<30))
+}
+
+// detectArch must match the fleet's `uname -m` convention (aarch64 | x86_64 | arm64),
+// NOT runtime.GOARCH (arm64 | amd64) — so a machine that appears as both a run-target
+// and a linked worker shows ONE arch string on the board. On Linux uname -m is
+// aarch64/x86_64; assert the real host agrees and is never GOARCH's amd64.
+func TestDetectArchMatchesUnameConvention(t *testing.T) {
+	got := detectArch()
+	if got == "" {
+		t.Fatal("detectArch returned empty; must fall back to runtime.GOARCH")
+	}
+	if out, err := exec.Command("uname", "-m").Output(); err == nil {
+		if want := strings.TrimSpace(string(out)); want != "" && got != want {
+			t.Fatalf("detectArch = %q, want `uname -m` %q (fleet convention)", got, want)
+		}
+	}
+	// Guard the regression this test exists for: on Linux amd64 the value must be
+	// x86_64, never GOARCH's "amd64".
+	if runtime.GOOS == "linux" && runtime.GOARCH == "amd64" && got == "amd64" {
+		t.Fatal("arch is GOARCH 'amd64'; the fleet convention is 'x86_64'")
+	}
+	t.Logf("detectArch=%q (GOARCH=%q)", got, runtime.GOARCH)
+}
+
+// buildRegistration must carry this host's detected arch (uname -m), cores (NumCPU)
+// and RAM — so spark reports aarch64 and evo-2 reports x86_64, both ~128 GB, matching
+// how the same machines already report as code-linked run-targets.
+func TestBuildRegistrationCarriesHostSpec(t *testing.T) {
+	const mem = int64(137438953472) // 128 GiB
+	w := &worker{hostname: "spark", jobsNS: "gpu-jobs", arch: "aarch64", memory: mem}
+	reg := w.buildRegistration()
+	if reg.Arch != "aarch64" {
+		t.Fatalf("Arch = %q, want the worker's detected arch %q", reg.Arch, "aarch64")
+	}
+	if reg.CPUs != runtime.NumCPU() {
+		t.Fatalf("CPUs = %d, want runtime.NumCPU %d", reg.CPUs, runtime.NumCPU())
+	}
+	if reg.Memory != mem {
+		t.Fatalf("Memory = %d, want the detected total %d", reg.Memory, mem)
+	}
+}
@@ -0,0 +1,200 @@
+package cli
+
+// link.go — `hanzo link | unlink | status`: bring THIS machine into the Hanzo
+// cloud fleet AS A NODE, take it back out, and view the fleet.
+//
+// A node is two orthogonal memberships, composed under one verb:
+//
+//  1. The FABRIC — hanzod on hanzo.network. `link` starts it by invoking the
+//     canonical fabric verb `hanzo node up` (the Rust node CLI: resolve a hanzod
+//     binary, spawn it detached, record its pid). link does NOT reimplement hanzod
+//     supervision — there is exactly one way to start hanzod, and this composes it.
+//     Best-effort: a node with no hanzod still joins the compute fleet (CPU-only
+//     boxes and dev machines link fine); `--no-fabric` skips it outright.
+//
+//  2. The COMPUTE fleet — this machine's inventory (CPU cores + model, memory, and
+//     each GPU as its own resource) registered as a heartbeating presence in the
+//     org's `fleet` namespace, running the outbound worker loop that claims jobs
+//     from `gpu-jobs`. That machinery lives in gpu.go (runConnect); `link` runs it.
+//
+// `unlink` reverses both: it deregisters the worker (drops the fleet row), then
+// stops the fabric (`hanzo node stop`). `status` is the fleet view — every machine
+// with each of its GPUs shown distinctly, this box highlighted.
+//
+// One identity: the IAM token `hanzo login` mints authorizes every cloud call; the
+// server derives the tenant from the token. No secrets on the box.
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"time"
+
+	"github.com/spf13/cobra"
+)
+
+// ---------------------------------------------------------------------------
+// link / unlink / status — the node-level command surface.
+// ---------------------------------------------------------------------------
+
+func newLinkCmd(envOf func() *Env, _ *globalFlags) *cobra.Command {
+	var opts connectOpts
+	var daemon bool
+	var noFabric bool
+
+	cmd := &cobra.Command{
+		Use:   "link",
+		Short: "Bring this machine into the Hanzo cloud fleet as a node",
+		Long: "Link this machine into the Hanzo cloud as a node: join the fabric (start\n" +
+			"hanzod on hanzo.network) and register as a compute worker — advertising this\n" +
+			"host's CPU (cores + model), memory, and each GPU as its own resource, then\n" +
+			"heartbeating and claiming jobs from your org's queue. The node shows up in the\n" +
+			"console (Machines + GPUs) and on `hanzo status`. Works on a CPU-only box.\n" +
+			"Authentication reuses the `hanzo login` token; the org is taken from its claims.",
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			if daemon {
+				return installDaemon(cmd, opts)
+			}
+			// 1. Fabric: start hanzod via the canonical `hanzo node up` (best-effort).
+			startFabric(cmd, noFabric)
+			// 2. Compute fleet: register inventory, heartbeat, claim jobs (foreground).
+			return runConnect(cmd, envOf(), opts)
+		},
+	}
+
+	f := cmd.Flags()
+	f.StringVar(&opts.jobsNS, "jobs-namespace", defaultJobsNS, "tasks namespace to claim jobs from")
+	f.BoolVar(&noFabric, "no-fabric", false, "join the compute fleet only; do not start hanzod")
+	f.BoolVar(&daemon, "daemon", false, "install a systemd --user unit (Restart=always) instead of running in the foreground")
+	f.BoolVar(&opts.serveEngine, "serve-engine", false, "also advertise a hanzo-engine model server (OpenAI + Anthropic) running on this node")
+	f.StringVar(&opts.engineURL, "engine-url", defaultEngineURL, "local URL where hanzo-engine is probed (GET /v1/models)")
+	f.StringVar(&opts.engineEndpoint, "engine-endpoint", "", "public URL to advertise for gateway routing (defaults to --engine-url; a node behind NAT needs a reachable URL/tunnel)")
+	f.BoolVar(&opts.registerProvider, "register-provider", false, "auto-register the engine endpoint as an org model provider (POST /v1/add-provider)")
+	f.StringVar(&opts.studioDir, "studio-dir", os.Getenv("HANZO_STUDIO_DIR"), "local Hanzo Studio checkout; when set, link launches and supervises the render backend on 127.0.0.1:8188")
+	f.StringVar(&opts.studioURL, "studio-url", firstNonEmpty(os.Getenv("HANZO_STUDIO_UPLOAD_URL"), defaultStudioUploadURL), "studio base URL the render mirror uploads finished images to (POST /v1/library/upload)")
+	f.BoolVar(&opts.mirror, "mirror", true, "sweep local renders into the org studio library; --mirror=false serves jobs only")
+	return cmd
+}
+
+func newUnlinkCmd(envOf func() *Env, _ *globalFlags) *cobra.Command {
+	return &cobra.Command{
+		Use:   "unlink",
+		Short: "Take this machine out of the fleet (deregister + stop hanzod)",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			// Reverse of link, both best-effort: drop the compute-fleet row, then
+			// ALWAYS stop the fabric so a deregister error never leaves hanzod
+			// running. The deregister error is reported, not short-circuited.
+			derr := runDisconnect(cmd, envOf())
+			stopFabric(cmd)
+			return derr
+		},
+	}
+}
+
+func newStatusCmd(envOf func() *Env, _ *globalFlags) *cobra.Command {
+	return &cobra.Command{
+		Use:   "status",
+		Short: "Show the org's fleet — every machine with each of its GPUs (this box highlighted)",
+		Args:  cobra.NoArgs,
+		RunE:  func(cmd *cobra.Command, _ []string) error { return runFleetStatus(cmd, envOf()) },
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Fabric — compose the canonical `hanzo node up` / `node stop`.
+// ---------------------------------------------------------------------------
+
+// fabricCLI resolves the Hanzo node CLI that owns hanzod supervision — the Rust
+// fabric/dev CLI with `node up/stop`. In the canonical layout the Go unified binary
+// takes the `hanzo` name and the Rust CLI is installed alongside it as `hanzo-node`,
+// so `link` composes `node up` without shelling into itself (this binary has no
+// `node`). Resolution order: HANZO_FABRIC_CLI, then `hanzo-node`, then a
+// self-guarded `hanzo` (for boxes where the Rust CLI still holds the `hanzo` name).
+// Returns "" when none is resolvable.
+func fabricCLI() string {
+	if p := os.Getenv("HANZO_FABRIC_CLI"); p != "" {
+		return p
+	}
+	if p, err := exec.LookPath("hanzo-node"); err == nil {
+		return p
+	}
+	p, err := exec.LookPath("hanzo")
+	if err != nil {
+		return ""
+	}
+	if self, err := os.Executable(); err == nil {
+		if sp, _ := os.Readlink(p); sp == self || p == self {
+			return ""
+		}
+	}
+	return p
+}
+
+// Passthrough delegates a verb this binary does not own — node, dev, wallet,
+// network, … — to the Rust fabric/dev CLI (resolved by fabricCLI, installed as
+// `hanzo-node`), so the single `hanzo` name is a SUPERSET: Go verbs served natively,
+// everything else handed through unchanged. `hanzo node up` (the fabric `link`
+// itself composes) works for users too. It runs the delegate to completion with
+// inherited stdio and exits with its code; it returns false only when no fabric CLI
+// is resolvable, so the caller can report unknown-subcommand.
+func Passthrough(args []string) bool {
+	bin := fabricCLI()
+	if bin == "" {
+		return false
+	}
+	c := exec.Command(bin, args...)
+	c.Stdin, c.Stdout, c.Stderr = os.Stdin, os.Stdout, os.Stderr
+	if err := c.Run(); err != nil {
+		var ee *exec.ExitError
+		if errors.As(err, &ee) {
+			os.Exit(ee.ExitCode())
+		}
+		fmt.Fprintf(os.Stderr, "hanzo: delegating %v to %s: %v\n", args, bin, err)
+		os.Exit(1)
+	}
+	os.Exit(0)
+	return true
+}
+
+// startFabric starts hanzod by invoking `hanzo node up` — the one canonical way to
+// join the fabric. Best-effort by design: a missing CLI or a missing hanzod prints
+// a clear note and the node still joins the compute fleet. `--no-fabric` skips it.
+func startFabric(cmd *cobra.Command, skip bool) {
+	out := cmd.OutOrStdout()
+	if skip {
+		fmt.Fprintln(out, "fabric: skipped (--no-fabric); joining the compute fleet only")
+		return
+	}
+	bin := fabricCLI()
+	if bin == "" {
+		fmt.Fprintln(out, "fabric: hanzo node CLI not found — joining the compute fleet only")
+		fmt.Fprintln(out, "        (install the `hanzo` node CLI or set HANZO_FABRIC_CLI to start hanzod)")
+		return
+	}
+	ctx, cancel := context.WithTimeout(cmd.Context(), 60*time.Second)
+	defer cancel()
+	c := exec.CommandContext(ctx, bin, "node", "up")
+	c.Stdout, c.Stderr = out, cmd.ErrOrStderr()
+	if err := c.Run(); err != nil {
+		fmt.Fprintf(out, "fabric: `%s node up` did not start hanzod (%v) — joining the compute fleet only\n", bin, err)
+	}
+}
+
+// stopFabric stops the hanzod this box started, via the canonical `hanzo node stop`.
+// Best-effort — nothing to stop is not an error.
+func stopFabric(cmd *cobra.Command) {
+	out := cmd.OutOrStdout()
+	bin := fabricCLI()
+	if bin == "" {
+		return
+	}
+	ctx, cancel := context.WithTimeout(cmd.Context(), 30*time.Second)
+	defer cancel()
+	c := exec.CommandContext(ctx, bin, "node", "stop")
+	c.Stdout, c.Stderr = out, cmd.ErrOrStderr()
+	_ = c.Run()
+}
@@ -0,0 +1,58 @@
+package cli
+
+import (
+	"bytes"
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+// TestUnlinkIdempotent — a repeat `hanzo unlink` is a no-op. The deregister POST
+// hitting an already-terminal (409) or absent (404) fleet row is the desired end
+// state, so runDisconnect returns nil (not an error) and says so, letting `unlink`
+// be run twice safely.
+func TestUnlinkIdempotent(t *testing.T) {
+	for _, code := range []int{http.StatusConflict, http.StatusNotFound} {
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+			w.WriteHeader(code)
+			_, _ = w.Write([]byte(`{"error":"activity terminal"}`))
+		}))
+
+		t.Setenv("HANZO_TOKEN", "test-token") // ensureToken honors this; no login needed
+		var out bytes.Buffer
+		cmd := &cobra.Command{}
+		cmd.SetContext(context.Background())
+		cmd.SetOut(&out)
+
+		if err := runDisconnect(cmd, &Env{CloudURL: srv.URL}); err != nil {
+			t.Errorf("HTTP %d: runDisconnect should be idempotent (nil), got %v", code, err)
+		}
+		if !strings.Contains(out.String(), "already unlinked") {
+			t.Errorf("HTTP %d: want 'already unlinked' notice, got %q", code, out.String())
+		}
+		srv.Close()
+	}
+}
+
+// TestUnlinkDeregisterErrorSurfaces — a non-terminal deregister failure (e.g. 500)
+// is a real error and must be returned, not swallowed as idempotent success.
+func TestUnlinkDeregisterErrorSurfaces(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+		_, _ = w.Write([]byte(`{"error":"boom"}`))
+	}))
+	defer srv.Close()
+
+	t.Setenv("HANZO_TOKEN", "test-token")
+	cmd := &cobra.Command{}
+	cmd.SetContext(context.Background())
+	cmd.SetOut(&bytes.Buffer{})
+
+	if err := runDisconnect(cmd, &Env{CloudURL: srv.URL}); err == nil {
+		t.Fatal("a 500 deregister must surface an error, got nil")
+	}
+}
@@ -12,11 +12,13 @@ import (
 	"time"
 )

-// Platform is a thin client over the platform.hanzo.ai /v1 control plane. That
-// surface is machine-to-machine (service-token, "No OIDC" — it cannot validate
-// IAM user tokens), so the token here is the platform service token, resolved
-// from flag/env/credential store by the caller; the build endpoint takes its
-// own token per call.
+// Platform is a thin client over the LIVE Hanzo Cloud control plane
+// (platform.hanzo.ai / api.hanzo.ai → svc `cloud`, the Go binary). Every route it
+// calls is served by that one binary and authorized off ONE IAM identity: after
+// `hanzo login` the CLI sends the IAM access token as the bearer, and the cloud's
+// identity middleware (SanitizeIdentity) validates the JWT and org-scopes the
+// caller — no separate platform/service token. A purpose-minted machine token
+// still works (flag > env > credential store > IAM login) for automation.
 type Platform struct {
 	baseURL string
 	token   string
@@ -45,8 +47,8 @@ func (e *apiError) Error() string {
 		msg = http.StatusText(e.status)
 	}
 	hint := ""
-	if e.status == http.StatusUnauthorized {
-		hint = " (set the platform service token: --platform-token, HANZO_PLATFORM_TOKEN, or `hanzo login --platform-token`)"
+	if e.status == http.StatusUnauthorized || e.status == http.StatusForbidden {
+		hint = " (run `hanzo login` — your IAM identity authorizes the platform; admin ops need an org-admin or superadmin identity)"
 	}
 	return fmt.Sprintf("platform %s: HTTP %d: %s%s", e.path, e.status, msg, hint)
 }
@@ -55,7 +57,7 @@ func (e *apiError) Error() string {
 // into out (when non-nil) and mapping a non-2xx into an *apiError.
 func (p *Platform) do(ctx context.Context, method, path, token string, body, out any) error {
 	if token == "" {
-		return fmt.Errorf("no platform token: pass --platform-token, set HANZO_PLATFORM_TOKEN, or run `hanzo login --platform-token <tok>`")
+		return fmt.Errorf("not authenticated: run `hanzo login` (an IAM login now authorizes the platform; a --platform-token / HANZO_PLATFORM_TOKEN still works for machine automation)")
 	}
 	var rdr io.Reader
 	if body != nil {
@@ -94,8 +96,8 @@ func (p *Platform) do(ctx context.Context, method, path, token string, body, out
 	return nil
 }

-// serverMessage pulls the `{ "message": … }` field platform errors use, falling
-// back to the raw (truncated) body.
+// serverMessage pulls the `{ "message": … }` / `{ "error": … }` field the cloud's
+// errors use, falling back to the raw (truncated) body.
 func serverMessage(raw []byte) string {
 	var e struct {
 		Message string `json:"message"`
@@ -117,33 +119,35 @@ func serverMessage(raw []byte) string {
 }

 // ---------------------------------------------------------------------------
-// Apps board — GET /v1/apps, GET /v1/apps/{id}, POST /v1/apps/sync.
+// Apps board — GET /v1/paas/apps, GET /v1/paas/apps/{app}. The live Go cloud's
+// fleet drift board (clients/paas): the operator App CRs across the platform
+// namespaces, declared/running/latest tags + health + the drift verdict. It is
+// org-confined server-side (a SuperAdmin sees the fleet; an OrgAdmin only its own
+// org), so the CLI sends NO org filter — identity scopes the view.
 // ---------------------------------------------------------------------------

-// AppView mirrors the platform apps-lifecycle DTO. Nullable columns are *string
-// so JSON null round-trips; Drift is kept raw so --json is byte-faithful and
-// the drift schema can evolve without a client bump.
+// AppView mirrors clients/paas.AppView (the LIVE board DTO). Tags/health are plain
+// strings ("" == unknown, rendered "-"); Drift is kept raw so --json is
+// byte-faithful and the drift schema can evolve without a client bump.
 type AppView struct {
-	ID            string          `json:"id"`
-	Org           string          `json:"org"`
-	App           string          `json:"app"`
-	Env           string          `json:"env"`
-	Repo          string          `json:"repo"`
-	Registry      string          `json:"registry"`
-	DeclaredTag   *string         `json:"declaredTag"`
-	RunningTag    *string         `json:"runningTag"`
-	LatestTag     *string         `json:"latestTag"`
-	ReleaseURL    *string         `json:"releaseUrl"`
-	ReleaseAssets int             `json:"releaseAssets"`
-	Health        *string         `json:"health"`
-	Cluster       *string         `json:"cluster"`
-	Namespace     *string         `json:"namespace"`
-	LastObserved  *string         `json:"lastObserved"`
-	UpdatedAt     string          `json:"updatedAt"`
-	Drift         json.RawMessage `json:"drift"`
+	ID          string          `json:"id"`  // <org>/<app>/<env>, e.g. hanzoai/iam/main
+	Org         string          `json:"org"` // image namespace, e.g. hanzoai
+	App         string          `json:"app"`
+	Env         string          `json:"env"`
+	Repo        string          `json:"repo"`
+	Registry    string          `json:"registry"`
+	DeclaredTag string          `json:"declaredTag"`
+	RunningTag  string          `json:"runningTag"`
+	LatestTag   string          `json:"latestTag"`
+	Health      string          `json:"health"`
+	Phase       string          `json:"phase"`
+	Cluster     string          `json:"cluster"`
+	Namespace   string          `json:"namespace"`
+	Endpoints   []string        `json:"endpoints"`
+	Drift       json.RawMessage `json:"drift"`
 }

-// AppsList is the /v1/apps envelope: ordered rows + a drift summary.
+// AppsList is the /v1/paas/apps envelope: ordered rows + a drift summary.
 type AppsList struct {
 	Apps    []AppView `json:"apps"`
 	Summary struct {
@@ -152,9 +156,10 @@ type AppsList struct {
 	} `json:"summary"`
 }

-// AppsQuery are the optional /v1/apps filters.
+// AppsQuery are the optional /v1/paas/apps filters (server-honored). Env/Health/
+// Drift narrow the board; there is deliberately no org filter — the board is
+// confined to the caller's org by the validated identity, never a client value.
 type AppsQuery struct {
-	Org    string
 	Env    string
 	Health string
 	Drift  bool
@@ -162,9 +167,6 @@ type AppsQuery struct {

 func (p *Platform) Apps(ctx context.Context, q AppsQuery) (*AppsList, error) {
 	v := url.Values{}
-	if q.Org != "" {
-		v.Set("org", q.Org)
-	}
 	if q.Env != "" {
 		v.Set("env", q.Env)
 	}
@@ -174,7 +176,7 @@ func (p *Platform) Apps(ctx context.Context, q AppsQuery) (*AppsList, error) {
 	if q.Drift {
 		v.Set("drift", "1")
 	}
-	path := "/v1/apps"
+	path := "/v1/paas/apps"
 	if len(v) > 0 {
 		path += "?" + v.Encode()
 	}
@@ -182,17 +184,11 @@ func (p *Platform) Apps(ctx context.Context, q AppsQuery) (*AppsList, error) {
 	return out, p.do(ctx, http.MethodGet, path, p.token, nil, out)
 }

-func (p *Platform) App(ctx context.Context, id, org string) (*AppView, error) {
-	path := "/v1/apps/" + id
-	if org != "" {
-		path += "?org=" + url.QueryEscape(org)
-	}
+// App gets one app row by its <app> CR name (production by default; the server
+// scans the caller's authorized namespaces main→test→dev).
+func (p *Platform) App(ctx context.Context, app string) (*AppView, error) {
 	out := &AppView{}
-	return out, p.do(ctx, http.MethodGet, path, p.token, nil, out)
-}
-
-func (p *Platform) SyncApps(ctx context.Context) error {
-	return p.do(ctx, http.MethodPost, "/v1/apps/sync", p.token, nil, nil)
+	return out, p.do(ctx, http.MethodGet, "/v1/paas/apps/"+url.PathEscape(app), p.token, nil, out)
 }

 // driftSeverity extracts the severity string from the raw drift object.
@@ -207,110 +203,92 @@ func driftSeverity(raw json.RawMessage) string {
 }

 // ---------------------------------------------------------------------------
-// Dedicated clusters — /v1/org/{org}/cluster[ /select | /{id}/install-baseline ].
+// Clusters — GET /v1/clusters. The live Go cloud's compute fleet (clients/visor):
+// Visor-managed node pools + the org's BYO clusters, tenant-scoped server-side by
+// the validated org (?owner is the caller's IAM org). No org in the path.
 // ---------------------------------------------------------------------------

-// Cluster mirrors a doks_cluster record. `status` is DigitalOcean state; `phase`
-// is the platform provisioning lifecycle — orthogonal (a DO-running cluster is
-// not a usable target until phase=ready).
+// NodePool mirrors clients/visor.nodePoolView.
+type NodePool struct {
+	PoolID    string `json:"poolId"`
+	Name      string `json:"name"`
+	Size      string `json:"size"`
+	Count     int    `json:"count"`
+	MinNodes  int    `json:"minNodes"`
+	MaxNodes  int    `json:"maxNodes"`
+	AutoScale bool   `json:"autoScale"`
+}
+
+// Cluster mirrors clients/visor.clusterView — the LIVE cluster DTO. `kind` is
+// "managed" (Visor-provisioned) or "byo" (attached kubeconfig).
 type Cluster struct {
-	DoksClusterID     string          `json:"doksClusterId"`
-	Name              string          `json:"name"`
-	DoClusterID       *string         `json:"doClusterId"`
-	Region            string          `json:"region"`
-	Status            string          `json:"status"`
-	Endpoint          *string         `json:"endpoint"`
-	K8sVersion        *string         `json:"k8sVersion"`
-	HA                bool            `json:"ha"`
-	Phase             string          `json:"phase"`
-	OperatorInstalled bool            `json:"operatorInstalled"`
-	BaselineInstalled bool            `json:"baselineInstalled"`
-	Active            bool            `json:"active"`
-	BaselineError     *string         `json:"baselineError"`
-	OrganizationID    string          `json:"organizationId"`
-	CreatedAt         string          `json:"createdAt"`
-	Tags              []string        `json:"tags"`
-	MaintenancePolicy json.RawMessage `json:"maintenancePolicy,omitempty"`
+	DoksClusterID string     `json:"doksClusterId"`
+	DoClusterID   string     `json:"doClusterId"`
+	Name          string     `json:"name"`
+	Region        string     `json:"region"`
+	Status        string     `json:"status"`
+	NodePools     []NodePool `json:"nodePools"`
+	NodeSize      string     `json:"nodeSize"`
+	NodeCount     int        `json:"nodeCount"`
+	CreatedAt     string     `json:"createdAt"`
+	Kind          string     `json:"kind"`
+	NvidiaGPU     int        `json:"nvidiaGpu"`
+	AmdGPU        int        `json:"amdGpu"`
 }

-// ProvisionReq is the dedicated-cluster provisioning body (org forced by path).
-type ProvisionReq struct {
-	Region    string `json:"region,omitempty"`
-	HA        bool   `json:"ha,omitempty"`
-	NodeSize  string `json:"nodeSize,omitempty"`
-	NodeCount int    `json:"nodeCount,omitempty"`
+// ID is the stable cluster identifier for display/lookup: the DOKS id when managed,
+// else the name (a BYO cluster keys on its attached name).
+func (c Cluster) ID() string {
+	if c.DoksClusterID != "" {
+		return c.DoksClusterID
+	}
+	return c.Name
 }

-// Target is the redacted ClusterTargetView — the kubeconfig is never present.
-type Target struct {
-	Cluster    string            `json:"cluster"`
-	Namespaces map[string]string `json:"namespaces"`
-	Dedicated  bool              `json:"dedicated"`
-}
-
-func (p *Platform) Clusters(ctx context.Context, org string) ([]Cluster, error) {
+func (p *Platform) Clusters(ctx context.Context) ([]Cluster, error) {
 	var out struct {
 		Clusters []Cluster `json:"clusters"`
 	}
-	err := p.do(ctx, http.MethodGet, "/v1/org/"+url.PathEscape(org)+"/cluster", p.token, nil, &out)
+	err := p.do(ctx, http.MethodGet, "/v1/clusters", p.token, nil, &out)
 	return out.Clusters, err
 }

-func (p *Platform) ProvisionCluster(ctx context.Context, org string, req ProvisionReq) (*Cluster, error) {
-	var out struct {
-		Cluster Cluster `json:"cluster"`
-	}
-	err := p.do(ctx, http.MethodPost, "/v1/org/"+url.PathEscape(org)+"/cluster", p.token, req, &out)
-	return &out.Cluster, err
-}
-
-func (p *Platform) Target(ctx context.Context, org string) (*Target, error) {
-	var out struct {
-		Target Target `json:"target"`
-	}
-	err := p.do(ctx, http.MethodGet, "/v1/org/"+url.PathEscape(org)+"/cluster/select", p.token, nil, &out)
-	return &out.Target, err
-}
-
-// SelectTarget activates a dedicated cluster as the org's deploy target, or
-// reverts to the shared cluster when clusterID is nil.
-func (p *Platform) SelectTarget(ctx context.Context, org string, clusterID *string) (*Target, error) {
-	var out struct {
-		Target Target `json:"target"`
-	}
-	body := map[string]any{"doksClusterId": clusterID}
-	err := p.do(ctx, http.MethodPost, "/v1/org/"+url.PathEscape(org)+"/cluster/select", p.token, body, &out)
-	return &out.Target, err
-}
-
-func (p *Platform) InstallBaseline(ctx context.Context, org, clusterID string) error {
-	path := "/v1/org/" + url.PathEscape(org) + "/cluster/" + url.PathEscape(clusterID) + "/install-baseline"
-	return p.do(ctx, http.MethodPost, path, p.token, nil, nil)
-}
-
 // ---------------------------------------------------------------------------
-// Deploy — POST …/container/{id}/redeploy (rolling restart, zero-downtime).
+// Deploy — POST /v1/paas/apps/{app}/deploy: a zero-downtime ROLLING RESTART of the
+// app's Deployment (re-pulls the declared image, recreates pods). Org-confined
+// server-side; an optional env selects the lifecycle namespace (main|test|dev).
 // ---------------------------------------------------------------------------

-// Redeploy triggers a rolling restart of the container's k8s Deployment. The
-// coordinates are exact (the platform validates org+project+env+container scope).
-func (p *Platform) Redeploy(ctx context.Context, org, project, env, container string) error {
-	path := fmt.Sprintf("/v1/org/%s/project/%s/env/%s/container/%s/redeploy",
-		url.PathEscape(org), url.PathEscape(project), url.PathEscape(env), url.PathEscape(container))
-	var out struct {
-		OK bool `json:"ok"`
+// Redeploy triggers a rolling restart of the named app. env is optional
+// (main|test|dev); empty targets production (the first match, main→test→dev).
+func (p *Platform) Redeploy(ctx context.Context, app, env string) (*DeployResult, error) {
+	path := "/v1/paas/apps/" + url.PathEscape(app) + "/deploy"
+	if env != "" {
+		path += "?env=" + url.QueryEscape(env)
 	}
-	if err := p.do(ctx, http.MethodPost, path, p.token, nil, &out); err != nil {
-		return err
+	out := &DeployResult{}
+	if err := p.do(ctx, http.MethodPost, path, p.token, nil, out); err != nil {
+		return nil, err
 	}
 	if !out.OK {
-		return fmt.Errorf("redeploy did not report ok")
+		return nil, fmt.Errorf("redeploy did not report ok")
 	}
-	return nil
+	return out, nil
+}
+
+// DeployResult is the /deploy acceptance (202): the restarted app + its namespace.
+type DeployResult struct {
+	OK          bool   `json:"ok"`
+	App         string `json:"app"`
+	Namespace   string `json:"namespace"`
+	Env         string `json:"env"`
+	RestartedAt string `json:"restartedAt"`
 }

 // ---------------------------------------------------------------------------
-// Build — POST /v1/runner (platform-native CI, no GitHub builders).
+// Build — POST /v1/runner (platform-native CI, no GitHub builders). Authorized off
+// the IAM login exactly like the surfaces above (or a dedicated build token for
+// machine automation). Unchanged wire contract.
 // ---------------------------------------------------------------------------

 // BuildReq is the direct-enqueue body. Repo/SHA/Image are required.
@@ -337,11 +315,11 @@ type BuildJob struct {
 	Target     string `json:"target"`
 }

-// EnqueueBuild enqueues a native build. It authenticates with the dedicated
-// build-callback token, not the service token.
+// EnqueueBuild enqueues a native build. buildToken is resolved by the caller (IAM
+// login is the final fallback; a dedicated build token wins when present).
 func (p *Platform) EnqueueBuild(ctx context.Context, req BuildReq, buildToken string) (*BuildJob, error) {
 	if buildToken == "" {
-		return nil, fmt.Errorf("no build token: set HANZO_BUILD_TOKEN / PLATFORM_BUILD_CALLBACK_TOKEN or `hanzo login --build-token <tok>`")
+		return nil, fmt.Errorf("not authenticated: run `hanzo login` (an IAM login now authorizes builds; HANZO_BUILD_TOKEN / --build-token still works for machine automation)")
 	}
 	out := &BuildJob{}
 	return out, p.do(ctx, http.MethodPost, "/v1/runner", buildToken, req, out)
@@ -18,17 +18,22 @@ func platformStub(t *testing.T, token string, h http.HandlerFunc) (*Platform, fu
 	return newPlatform(srv.URL, token), srv.Close
 }

+// Apps hits the LIVE board /v1/paas/apps with the IAM bearer; it sends NO org
+// filter (the board is org-confined server-side by the validated identity).
 func TestPlatformAuthHeaderAndApps(t *testing.T) {
 	p, done := platformStub(t, "svc-tok", func(w http.ResponseWriter, r *http.Request) {
 		if got := r.Header.Get("Authorization"); got != "Bearer svc-tok" {
 			t.Errorf("auth header = %q", got)
 		}
-		if r.URL.Path != "/v1/apps" {
-			t.Errorf("path = %s", r.URL.Path)
+		if r.URL.Path != "/v1/paas/apps" {
+			t.Errorf("path = %s, want /v1/paas/apps", r.URL.Path)
 		}
 		if r.URL.Query().Get("env") != "main" || r.URL.Query().Get("drift") != "1" {
 			t.Errorf("query = %s", r.URL.RawQuery)
 		}
+		if r.URL.Query().Has("org") {
+			t.Errorf("client must NOT send an org filter (identity confines the board): %s", r.URL.RawQuery)
+		}
 		_ = json.NewEncoder(w).Encode(AppsList{
 			Apps: []AppView{{ID: "hanzoai/iam/main", Org: "hanzoai", App: "iam", Env: "main", Drift: json.RawMessage(`{"severity":"red"}`)}},
 		})
@@ -47,126 +52,75 @@ func TestPlatformAuthHeaderAndApps(t *testing.T) {
 	}
 }

+// App hits /v1/paas/apps/{app}; no org query (identity scopes it).
 func TestPlatformApp(t *testing.T) {
 	p, done := platformStub(t, "t", func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path != "/v1/apps/hanzoai/iam/main" {
-			t.Errorf("path = %s", r.URL.Path)
+		if r.URL.Path != "/v1/paas/apps/iam" {
+			t.Errorf("path = %s, want /v1/paas/apps/iam", r.URL.Path)
 		}
-		if r.URL.Query().Get("org") != "hanzoai" {
-			t.Errorf("org query = %s", r.URL.RawQuery)
+		if r.URL.RawQuery != "" {
+			t.Errorf("app get must carry no query, got %s", r.URL.RawQuery)
 		}
-		_ = json.NewEncoder(w).Encode(AppView{ID: "hanzoai/iam/main", App: "iam"})
+		_ = json.NewEncoder(w).Encode(AppView{ID: "hanzoai/iam/main", App: "iam", Phase: "Running"})
 	})
 	defer done()
-	a, err := p.App(context.Background(), "hanzoai/iam/main", "hanzoai")
+	a, err := p.App(context.Background(), "iam")
 	if err != nil || a.App != "iam" {
 		t.Fatalf("App: %v %+v", err, a)
 	}
 }

-func TestPlatformSyncApps(t *testing.T) {
+// Clusters hits the LIVE /v1/clusters (org from identity, not the path).
+func TestPlatformClusters(t *testing.T) {
 	p, done := platformStub(t, "t", func(w http.ResponseWriter, r *http.Request) {
-		if r.Method != http.MethodPost || r.URL.Path != "/v1/apps/sync" {
-			t.Errorf("sync = %s %s", r.Method, r.URL.Path)
-		}
-		w.WriteHeader(200)
-	})
-	defer done()
-	if err := p.SyncApps(context.Background()); err != nil {
-		t.Fatalf("SyncApps: %v", err)
-	}
-}
-
-func TestPlatformClustersAndProvision(t *testing.T) {
-	p, done := platformStub(t, "t", func(w http.ResponseWriter, r *http.Request) {
-		switch {
-		case r.Method == http.MethodGet && r.URL.Path == "/v1/org/acme/cluster":
-			_ = json.NewEncoder(w).Encode(map[string]any{"clusters": []Cluster{{DoksClusterID: "c1", Name: "hanzo-acme", Region: "sfo3", Status: "running", Phase: "ready", Active: true}}})
-		case r.Method == http.MethodPost && r.URL.Path == "/v1/org/acme/cluster":
-			body, _ := io.ReadAll(r.Body)
-			var req ProvisionReq
-			_ = json.Unmarshal(body, &req)
-			if req.Region != "sfo3" || !req.HA {
-				t.Errorf("provision body = %+v", req)
-			}
-			w.WriteHeader(201)
-			_ = json.NewEncoder(w).Encode(map[string]any{"cluster": Cluster{DoksClusterID: "c2", Name: "new", Phase: "requested"}})
-		default:
-			t.Errorf("unexpected %s %s", r.Method, r.URL.Path)
+		if r.Method != http.MethodGet || r.URL.Path != "/v1/clusters" {
+			t.Errorf("clusters = %s %s, want GET /v1/clusters", r.Method, r.URL.Path)
 		}
+		_ = json.NewEncoder(w).Encode(map[string]any{"clusters": []Cluster{
+			{DoksClusterID: "c1", Name: "hanzo-acme", Region: "sfo3", Status: "running", Kind: "managed", NodeCount: 3},
+		}})
 	})
 	defer done()

-	cs, err := p.Clusters(context.Background(), "acme")
-	if err != nil || len(cs) != 1 || cs[0].DoksClusterID != "c1" {
+	cs, err := p.Clusters(context.Background())
+	if err != nil || len(cs) != 1 || cs[0].ID() != "c1" || cs[0].Kind != "managed" {
 		t.Fatalf("Clusters: %v %+v", err, cs)
 	}
-	c, err := p.ProvisionCluster(context.Background(), "acme", ProvisionReq{Region: "sfo3", HA: true})
-	if err != nil || c.DoksClusterID != "c2" {
-		t.Fatalf("ProvisionCluster: %v %+v", err, c)
-	}
 }

-func TestPlatformTargetAndSelect(t *testing.T) {
-	p, done := platformStub(t, "t", func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path != "/v1/org/acme/cluster/select" {
-			t.Errorf("path = %s", r.URL.Path)
-		}
-		if r.Method == http.MethodPost {
-			body, _ := io.ReadAll(r.Body)
-			var m map[string]any
-			_ = json.Unmarshal(body, &m)
-			if m["doksClusterId"] != "c1" {
-				t.Errorf("select body = %v", m)
-			}
-		}
-		_ = json.NewEncoder(w).Encode(map[string]any{"target": Target{Cluster: "hanzo-acme", Dedicated: true, Namespaces: map[string]string{"acme": "main"}}})
-	})
-	defer done()
-
-	tg, err := p.Target(context.Background(), "acme")
-	if err != nil || tg.Cluster != "hanzo-acme" || !tg.Dedicated {
-		t.Fatalf("Target: %v %+v", err, tg)
-	}
-	id := "c1"
-	if _, err := p.SelectTarget(context.Background(), "acme", &id); err != nil {
-		t.Fatalf("SelectTarget: %v", err)
-	}
-}
-
-func TestPlatformInstallBaseline(t *testing.T) {
-	p, done := platformStub(t, "t", func(w http.ResponseWriter, r *http.Request) {
-		if r.Method != http.MethodPost || r.URL.Path != "/v1/org/acme/cluster/c1/install-baseline" {
-			t.Errorf("install-baseline = %s %s", r.Method, r.URL.Path)
-		}
-		w.WriteHeader(200)
-	})
-	defer done()
-	if err := p.InstallBaseline(context.Background(), "acme", "c1"); err != nil {
-		t.Fatalf("InstallBaseline: %v", err)
+// A BYO cluster with no DOKS id keys on its name via ID().
+func TestClusterIDFallsBackToName(t *testing.T) {
+	c := Cluster{Name: "byo-1", Kind: "byo"}
+	if c.ID() != "byo-1" {
+		t.Fatalf("ID() = %q, want byo-1", c.ID())
 	}
 }

+// Redeploy hits /v1/paas/apps/{app}/deploy (rolling restart), org from identity.
 func TestPlatformRedeploy(t *testing.T) {
 	p, done := platformStub(t, "t", func(w http.ResponseWriter, r *http.Request) {
-		want := "/v1/org/acme/project/p1/env/e1/container/app-x/redeploy"
-		if r.Method != http.MethodPost || r.URL.Path != want {
-			t.Errorf("redeploy path = %s %s", r.Method, r.URL.Path)
+		if r.Method != http.MethodPost || r.URL.Path != "/v1/paas/apps/app-x/deploy" {
+			t.Errorf("redeploy = %s %s, want POST /v1/paas/apps/app-x/deploy", r.Method, r.URL.Path)
 		}
-		_ = json.NewEncoder(w).Encode(map[string]bool{"ok": true})
+		if r.URL.Query().Get("env") != "test" {
+			t.Errorf("env query = %s", r.URL.RawQuery)
+		}
+		w.WriteHeader(202)
+		_ = json.NewEncoder(w).Encode(DeployResult{OK: true, App: "app-x", Namespace: "hanzo-testnet", Env: "test", RestartedAt: "2026-07-18T00:00:00Z"})
 	})
 	defer done()
-	if err := p.Redeploy(context.Background(), "acme", "p1", "e1", "app-x"); err != nil {
-		t.Fatalf("Redeploy: %v", err)
+	res, err := p.Redeploy(context.Background(), "app-x", "test")
+	if err != nil || res.Namespace != "hanzo-testnet" {
+		t.Fatalf("Redeploy: %v %+v", err, res)
 	}
 }

 func TestPlatformRedeployNotOK(t *testing.T) {
 	p, done := platformStub(t, "t", func(w http.ResponseWriter, _ *http.Request) {
-		_ = json.NewEncoder(w).Encode(map[string]bool{"ok": false})
+		_ = json.NewEncoder(w).Encode(DeployResult{OK: false})
 	})
 	defer done()
-	if err := p.Redeploy(context.Background(), "o", "p", "e", "c"); err == nil {
+	if _, err := p.Redeploy(context.Background(), "c", ""); err == nil {
 		t.Fatalf("expected error when ok=false")
 	}
 }
@@ -207,14 +161,16 @@ func TestPlatformError401Hint(t *testing.T) {
 	})
 	defer done()
 	_, err := p.Apps(context.Background(), AppsQuery{})
-	if err == nil || !strings.Contains(err.Error(), "HTTP 401") || !strings.Contains(err.Error(), "platform service token") {
-		t.Fatalf("401 error should carry a token hint, got %v", err)
+	if err == nil || !strings.Contains(err.Error(), "HTTP 401") || !strings.Contains(err.Error(), "hanzo login") {
+		t.Fatalf("401 error should point at `hanzo login`, got %v", err)
 	}
 }

 func TestPlatformNoTokenError(t *testing.T) {
 	p := newPlatform("https://platform.hanzo.ai", "")
-	if _, err := p.Apps(context.Background(), AppsQuery{}); err == nil || !strings.Contains(err.Error(), "no platform token") {
-		t.Fatalf("expected no-token error, got %v", err)
+	// After unify-infra, the "no credential" error points at `hanzo login` — the one
+	// identity that authorizes the platform — not a separate platform token.
+	if _, err := p.Apps(context.Background(), AppsQuery{}); err == nil || !strings.Contains(err.Error(), "hanzo login") {
+		t.Fatalf("expected a `hanzo login` hint, got %v", err)
 	}
 }
@@ -6,7 +6,7 @@ package cli
 // org for queued workflow jobs and spawns ephemeral, auto-exiting actions-runner
 // subprocesses tagged with this box's labels (GPU / vulkan aware). Outbound only —
 // nothing listens for inbound. Completes the trifecta: `engine` serves models,
-// `gpu connect` shares compute, `runner` claims CI — one binary, one org login.
+// `link` shares compute, `runner` claims CI — one binary, one org login.

 import (
 	"os/signal"
@@ -1,5 +1,5 @@
-// studio.go — local Hanzo Studio render-backend supervision for `hanzo gpu
-// connect --studio-dir <checkout>`. The gpu-jobs claim loop renders on the
+// studio.go — local Hanzo Studio render-backend supervision for `hanzo link
+// --studio-dir <checkout>`. The gpu-jobs claim loop renders on the
 // LOCAL studio server (127.0.0.1:8188); this keeps that server alive so the
 // box needs no separate watchdog script or hand-rolled systemd unit — the
 // hanzo CLI is the one way a BYO box joins the fleet, render backend included.
@@ -12,6 +12,7 @@ package cli

 import (
 	"context"
+	"encoding/json"
 	"fmt"
 	"io"
 	"net"
@@ -20,6 +21,7 @@ import (
 	"os/exec"
 	"path/filepath"
 	"strconv"
+	"sync/atomic"
 	"syscall"
 	"time"
 )
@@ -65,9 +67,22 @@ func launchStudio(dir string) (*exec.Cmd, error) {
 	if err != nil {
 		return nil, err
 	}
+	// --listen 127.0.0.1 (loopback only) + --worker-mode: the render backend serves
+	// the fleet worker on this box and nothing else. The worker dials loopback
+	// (localComfyUI) so binding wider bought nothing but an open, unauthenticated
+	// /prompt — the hidden-run hole. --worker-mode makes the studio gate its submit
+	// seam (/v1/worker/execute + X-Worker-Token) so only the worker can start a render.
+	// VRAM mode: default --normalvram (safe for smaller BYO GPUs); override with
+	// HANZO_STUDIO_VRAM (e.g. "--highvram") on big-memory boxes (GB10 128G unified) so
+	// the Qwen text-encoder stays resident on-GPU instead of non-deterministically
+	// offloading to CPU — offload makes renders CPU-bound and ~8x slower.
+	vramMode := os.Getenv("HANZO_STUDIO_VRAM")
+	if vramMode == "" {
+		vramMode = "--normalvram"
+	}
 	cmd := exec.Command(studioPython(dir), "main.py",
-		"--listen", "0.0.0.0", "--port", "8188",
-		"--normalvram", "--disable-auto-launch",
+		"--listen", "127.0.0.1", "--port", "8188", "--worker-mode",
+		vramMode, "--disable-auto-launch",
 		"--output-directory", filepath.Join(dir, "output"))
 	cmd.Dir = dir
 	cmd.Env = append(os.Environ(),
@@ -107,6 +122,48 @@ func stopStudio(cmd *exec.Cmd) {
 	}
 }

+// studioRecycle carries at most one pending recycle request; the render
+// handler signals it after each completed render (see gpu.go).
+var studioRecycle = make(chan struct{}, 1)
+
+// staging guards the claim-to-submit window: a claimed job is real work the
+// engine queue cannot see yet, so the supervisor must never recycle over it
+// (observed: jobs claimed during a recycle failed staging on a dead engine
+// and were consumed).
+var staging atomic.Int32
+
+func requestStudioRecycle() {
+	select {
+	case studioRecycle <- struct{}{}:
+	default:
+	}
+}
+
+// studioBusy reports whether the engine holds queued or running prompts.
+// A generous timeout: a saturated GB10 answers slowly mid-render — slow is
+// alive, and killing a live render costs 8-70 minutes of GPU work.
+func studioBusy(ctx context.Context) (busy, ok bool) {
+	ctx, cancel := context.WithTimeout(ctx, 20*time.Second)
+	defer cancel()
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, "http://"+studioAddr+"/queue", nil)
+	if err != nil {
+		return false, false
+	}
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return false, false
+	}
+	defer resp.Body.Close()
+	var q struct {
+		Running []json.RawMessage `json:"queue_running"`
+		Pending []json.RawMessage `json:"queue_pending"`
+	}
+	if err := json.NewDecoder(io.LimitReader(resp.Body, 32<<20)).Decode(&q); err != nil {
+		return false, false
+	}
+	return len(q.Running)+len(q.Pending) > 0, true
+}
+
 // superviseStudio keeps the local render backend on :8188 alive until ctx
 // ends. Quiet by design: one line per restart event, not a probe firehose.
 func superviseStudio(ctx context.Context, dir string, out io.Writer) {
@@ -138,6 +195,12 @@ func superviseStudio(ctx context.Context, dir string, out io.Writer) {

 	tick := time.NewTicker(studioProbeEvery)
 	defer tick.Stop()
+	// recyclePending defers the post-render recycle until the queue is EMPTY:
+	// short jobs complete while a long render is mid-sample, and recycling on
+	// their completion killed the live render (observed: every direct render
+	// died within ~6 minutes while probe jobs cycled).
+	recyclePending := false
+	unhealthy := 0
 	for {
 		select {
 		case <-ctx.Done():
@@ -145,19 +208,32 @@ func superviseStudio(ctx context.Context, dir string, out io.Writer) {
 				_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGTERM)
 			}
 			return
+		case <-studioRecycle:
+			recyclePending = true
 		case <-tick.C:
+			busy, ok := studioBusy(ctx)
+			if recyclePending && ok && !busy && staging.Load() == 0 {
+				recyclePending = false
+				unhealthy = 0
+				restart("recycle")
+				continue
+			}
 			if studioHealthy(ctx) {
+				unhealthy = 0
 				continue
 			}
-			// Grace re-check: it may be momentarily busy mid-render.
-			select {
-			case <-ctx.Done():
+			if ok && busy {
+				// Alive-busy: slow health under render load is not death.
+				unhealthy = 0
 				continue
-			case <-time.After(studioGraceWait):
 			}
-			if !studioHealthy(ctx) {
-				restart("unresponsive")
+			// Sustained silence with an idle or unreadable queue = actually dead.
+			unhealthy++
+			if unhealthy < 3 {
+				continue
 			}
+			unhealthy = 0
+			restart("unresponsive")
 		}
 	}
 }
@@ -50,6 +50,7 @@
 package account

 import (
+	"context"
 	"encoding/base64"
 	"errors"
 	"fmt"
@@ -367,18 +368,58 @@ func onboard(s *cloud.Service[state], c *zip.Ctx) error {
 		return herr
 	}

-	// Create the org (cloning the caller's current org for password/locale
-	// compatibility), then — first-run only — move the zero-org user in as admin.
+	// ADDITIONAL org (caller already has a home): create it WITHOUT moving them —
+	// they reach it via the OrgSwitcher (a move would strip their SuperAdmin / orphan
+	// their current org).
+	if additional {
+		org := buildOrg(s, c, slug, displayName, body.Personal, cr.owner)
+		if err := s.State.iam.createOrganization(c.Context(), org); err != nil {
+			return zip.Errorf(http.StatusBadGateway, "could not create the organization: %v", err)
+		}
+		return c.JSON(http.StatusOK, onboardResp{Org: slug, DisplayName: displayName, Additional: true})
+	}
+
+	// FIRST-RUN: drive the ONE atomic IAM provision (org + admin move + hashed
+	// org-scoped credential), replacing the create-org + move-user pair — a mid-flight
+	// retry now converges on the founder's own org instead of orphaning it. The org
+	// starts at a zero balance (usage is pre-paid). Prefer it whenever the
+	// service-token path is wired; fall back to the legacy pair only when it is not,
+	// so a partial deploy still onboards.
+	if s.State.iam.provisionReady() {
+		resp, err := onboardFirstRun(c.Context(), s.State.iam, cr.id, slug, displayName, body.Personal)
+		if err != nil {
+			return err
+		}
+		return c.JSON(http.StatusOK, resp)
+	}
+
+	// Legacy fallback (service token unset): create then move — the non-atomic pair.
 	org := buildOrg(s, c, slug, displayName, body.Personal, cr.owner)
 	if err := s.State.iam.createOrganization(c.Context(), org); err != nil {
 		return zip.Errorf(http.StatusBadGateway, "could not create the organization: %v", err)
 	}
-	if !additional {
-		if err := s.State.iam.moveUserToOrg(c.Context(), cr.id, slug); err != nil {
-			return zip.Errorf(http.StatusBadGateway, "org created but could not assign you to it: %v", err)
-		}
+	if err := s.State.iam.moveUserToOrg(c.Context(), cr.id, slug); err != nil {
+		return zip.Errorf(http.StatusBadGateway, "org created but could not assign you to it: %v", err)
 	}
-	return c.JSON(http.StatusOK, onboardResp{Org: slug, DisplayName: displayName, Additional: additional})
+	return c.JSON(http.StatusOK, onboardResp{Org: slug, DisplayName: displayName, Additional: false})
+}
+
+// onboardFirstRun drives the ONE atomic IAM provision for a zero-org caller (create
+// org + move them in as admin + mint the hashed org-scoped credential), replacing
+// the create-org + move-user pair so a mid-flight retry converges on the founder's
+// own org instead of orphaning it. The org starts at a ZERO balance — usage is
+// pre-paid, so there is no signup grant. Split out so the provisioning glue is
+// unit-tested against mock IAM without the CSRF/routing/principal shell.
+func onboardFirstRun(ctx context.Context, iam *iamClient, callerID, slug, displayName string, personal bool) (onboardResp, error) {
+	row, err := iam.getUserRow(ctx, callerID)
+	if err != nil {
+		return onboardResp{}, zip.Errorf(http.StatusBadGateway, "could not resolve the user: %v", err)
+	}
+	res, err := iam.provision(ctx, row.Owner, row.Name, slug, personal)
+	if err != nil {
+		return onboardResp{}, zip.Errorf(http.StatusBadGateway, "could not provision the organization: %v", err)
+	}
+	return onboardResp{Org: res.Org, DisplayName: displayName, Additional: false}, nil
 }

 // resolveOnboardName derives the base slug + display name from the request, or a
@@ -30,6 +30,7 @@ package account

 import (
 	"bytes"
+	"crypto/subtle"
 	"encoding/json"
 	"net/http"
 	"net/url"
@@ -39,6 +40,7 @@ import (
 	"github.com/hanzoai/account"

 	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/principal"
 	"github.com/zap-proto/zip"
 )

@@ -107,6 +109,7 @@ var billingForwardable = map[string][]string{
 		"subscriptions",
 		"payment-methods",
 		"spend-alerts",
+		"spend-alerts/authorize", // the S2S cap-verdict read (metering gate); 2 segments need their own entry
 		"payment-config",
 		"plans",
 		"payouts",
@@ -241,9 +244,26 @@ func commerceCreds() (base, token string) {
 func billingData(s *cloud.Service[state], c *zip.Ctx) error {
 	// IDOR boundary: the subject is the VALIDATED caller's own org/user, never a client
 	// value. requireOwner=true — billing is always org-scoped (a zero-org user has none).
+	// Auth. A browser caller is the VALIDATED principal (customer path — subject-pinned
+	// below). An IN-PROC S2S caller carries the verified COMMERCE_SERVICE_TOKEN (the
+	// metering cap-gate's authorize + the SuperAdmin cap-oversight Forward). The gateway
+	// 401s a public Bearer that is not an IAM JWT / hk-|pk-|sk- key (the 64-hex service
+	// token fails JWT parse at the edge), so an EXTERNAL client can NEVER present it here —
+	// an unauthenticated caller still hits the 403 below. On the S2S path the caller
+	// legitimately names its own subject, so its query is forwarded as-is (no pin), scoped
+	// only by the EdgeAuth-controlled X-Org-Id.
 	cr, ok := resolveCaller(c, true)
+	s2s := false
+	owner := cr.owner
 	if !ok {
-		return zip.ErrForbidden("sign in to view billing")
+		if !s2sBillingCall(c) {
+			return zip.ErrForbidden("sign in to view billing")
+		}
+		owner = strings.TrimSpace(c.Org()) // trusted X-Org-Id (never a client value on a public call)
+		if owner == "" {
+			return zip.ErrForbidden("sign in to view billing")
+		}
+		s2s = true
 	}

 	method := c.Method()
@@ -277,20 +297,32 @@ func billingData(s *cloud.Service[state], c *zip.Ctx) error {

 	// Scope EVERY request to the caller's OWN subject — query AND write body — so
 	// commerce's per-tenant isolation can never be crossed from the browser. The
-	// subject comes from the ONE rule (ai/object.Payer), keyed on the IAM username
-	// (cr.username = X-User-Name) the gate also keys on — so a top-up credits the
-	// SAME account the gate debits. Keying on cr.name (X-User-Id, a UUID on the
-	// direct-bearer path) would fund an account the gate never reads: the split.
-	subject := account.Payer(account.Credential{Owner: cr.owner, Name: cr.username}).Subject()
+	// subject comes from the ONE rule (ai/object.Payer), fed the account the
+	// credential NAMES (the validated `billing_account` claim) — the same claim the
+	// ai gate reads, so a top-up credits the SAME account the gate debits. Feeding
+	// Payer a different credential here than the gate gets is the modern shape of
+	// the old split: money landing in an account the gate never reads.
 	inQuery, _ := url.ParseQuery(string(c.Fiber().Request().URI().QueryString()))
-	q := scopedBillingSearch(inQuery, subject)
-
+	var q url.Values
 	var body []byte
-	if method == http.MethodPost {
-		body = scopedBillingBody(c.Body(), subject)
+	if s2s {
+		// Trusted S2S caller: forward its query/body VERBATIM — it legitimately names the
+		// subject (e.g. the metering gate's ?user=<org>&amount=). Scoped by X-Org-Id.
+		q = inQuery
+		if method == http.MethodPost {
+			body = c.Body()
+		}
+	} else {
+		// Browser customer: pin EVERY subject key to the caller's OWN account so commerce's
+		// per-tenant isolation can never be crossed from the client.
+		subject := account.Payer(account.Credential{Owner: cr.owner, Name: cr.username, Account: principal.BillingAccount(c)}).Subject()
+		q = scopedBillingSearch(inQuery, subject)
+		if method == http.MethodPost {
+			body = scopedBillingBody(c.Body(), subject)
+		}
 	}

-	raw, status, err := commerceDo(c.Context(), base, token, method, "/v1/billing/"+sub, q, cr.owner, body)
+	raw, status, err := commerceDo(c.Context(), base, token, method, "/v1/billing/"+sub, q, owner, body)
 	if err != nil {
 		return zip.Errorf(http.StatusBadGateway, "billing upstream unreachable: %v", err)
 	}
@@ -300,3 +332,27 @@ func billingData(s *cloud.Service[state], c *zip.Ctx) error {
 	c.SetHeader("Cache-Control", "no-store, must-revalidate")
 	return c.Bytes(status, raw)
 }
+
+// s2sBillingCall reports whether the request carries the verified COMMERCE_SERVICE_TOKEN
+// as its Bearer — a trusted IN-PROC service-to-service caller (the metering cap-gate's
+// authorize, the SuperAdmin cap-oversight Forward). It is the SAME secret this bridge
+// already forwards WITH, so admitting a caller who already holds it grants no authority it
+// could not otherwise wield. Safety rests on the edge: the gateway 401s a public Bearer
+// that is not an IAM JWT / hk-|pk-|sk- API key (the 64-hex service token is a JWT
+// candidate that fails to parse), so an EXTERNAL client can never reach this handler
+// holding it — only in-proc commerceinproc dispatch does. Constant-time compare; the token
+// is never logged.
+func s2sBillingCall(c *zip.Ctx) bool {
+	_, token := commerceCreds()
+	if token == "" {
+		return false
+	}
+	bearer := strings.TrimSpace(strings.TrimPrefix(c.Header("Authorization"), "Bearer "))
+	return bearer != "" && subtle.ConstantTimeCompare([]byte(bearer), []byte(token)) == 1
+}
+
+// IsServiceToken is the exported view of s2sBillingCall — whether the request is a trusted
+// in-proc S2S caller bearing the verified COMMERCE_SERVICE_TOKEN. Used by co-resident route
+// gates (e.g. the spend-alert admin gate) that must admit the metering cap-gate and the
+// SuperAdmin cap-oversight Forward alongside org admins, while refusing a plain member.
+func IsServiceToken(c *zip.Ctx) bool { return s2sBillingCall(c) }
@@ -0,0 +1,89 @@
+// billing_coresident.go — PinBillingSubject, the subject-pinning middleware that lets
+// commerce's OWN billing READ handlers serve co-resident in the unified cloud binary.
+//
+// WHY IT EXISTS. Co-resident, commerce is EMBEDDED (apps/commerce.go mountCommerce →
+// commerce.Embed on the shared zip app), and in prod there is NO standalone commerce
+// backend — the in-cluster `commerce` Service selects the cloud pods themselves. So the
+// /v1/billing/* bridge (billing.go), which forwards to COMMERCE_URL, has nowhere to send
+// a read but back into cloud: the default base (the public api.hanzo.ai edge) re-enters
+// the same bridge in an unbounded self-dispatch loop that surfaces as a 502
+// ("billing upstream unreachable: Get https://api.hanzo.ai/v1/billing/<path>"). The fix
+// is to serve those reads co-resident from the embedded commerce — the same co-resident
+// move mountCommerce already makes for GET /v1/billing/plans — so the specific route
+// shadows the bridge wildcard (order 100 < 122) and never leaves the process.
+//
+// WHAT IT GUARANTEES. commerce's read handlers scope to the org by NAMESPACE (from the
+// gateway-validated X-Org-Id via iammiddleware) but filter finer scope (the billing
+// subject) only from a query param — an UNPINNED ListInvoices returns every user's rows
+// in the org namespace. The /v1/billing/* bridge is what pins that subject today; this
+// middleware carries the SAME pin onto the co-resident route so the isolation is
+// byte-for-byte the shipped behavior. It is the ONE subject rule (account.Payer, the same
+// function the ai spend-gate and the top-up resolve), fed the account the credential NAMES
+// — so a read scopes to exactly the account the gate debits, never wider.
+package account
+
+import (
+	"net/url"
+
+	"github.com/hanzoai/account"
+
+	"github.com/hanzoai/cloud/clients/principal"
+	"github.com/zap-proto/zip"
+)
+
+// PinBillingSubject pins every billing subject key in the request query to the VALIDATED
+// caller's own subject (dropping ?org), so a co-resident commerce read handler downstream
+// can only ever return the caller's OWN rows. It is the co-resident twin of billingData's
+// subject-pinning, reusing the SAME resolveCaller → account.Payer rule and the SAME
+// scopedBillingSearch, so the two paths scope identically.
+//
+// Three cases, mirroring billingData exactly:
+//   - Browser customer (a validated principal with an org): OVERWRITE the subject keys
+//     with the caller's own subject and drop ?org. The client cannot widen scope.
+//   - Trusted in-proc S2S (the verified COMMERCE_SERVICE_TOKEN bearer, carrying its own
+//     X-Org-Id): pass the query through VERBATIM — it legitimately names its own subject,
+//     scoped by the EdgeAuth-controlled org.
+//   - Neither: refuse. A bearer-less request with a forged X-Org-Id has no validated
+//     principal and is fail-closed here, before the read handler runs.
+//
+// The pin rewrites the request URI's query string AND (on a write) the JSON body in place;
+// fasthttp's SetQueryString resets the parsed-args cache and SetBody replaces the body
+// bytes, so the handler's later c.Query() / c.Bind() read the pinned values. Pinning the
+// body is what keeps a co-resident WRITE handler that reads its subject from the body
+// (commerce's CreatePaymentMethod reads customerId from the JSON body) IDOR-safe — query-only
+// pinning would leave a client-named customerId/userId in the body untouched.
+func PinBillingSubject() zip.Handler {
+	return func(c *zip.Ctx) error {
+		inQuery, _ := url.ParseQuery(string(c.Fiber().Request().URI().QueryString()))
+
+		cr, ok := resolveCaller(c, true)
+		if !ok {
+			// Not a validated customer — admit ONLY a trusted in-proc S2S caller that
+			// names its own org (same admission billingData makes), leaving its query
+			// untouched. Everything else is refused before the read runs.
+			if s2sBillingCall(c) && c.Org() != "" {
+				return c.Next()
+			}
+			return zip.ErrForbidden("sign in to view billing")
+		}
+
+		subject := account.Payer(account.Credential{
+			Owner:   cr.owner,
+			Name:    cr.username,
+			Account: principal.BillingAccount(c),
+		}).Subject()
+
+		// Pin the subject on BOTH the query AND the write body — the SAME two-helper
+		// scoping billingData applies (scopedBillingSearch + scopedBillingBody). A
+		// co-resident WRITE handler that reads its subject from the body (commerce's
+		// CreatePaymentMethod → customerId) is only IDOR-safe if the body is pinned too.
+		// scopedBillingBody overwrites the subject keys and preserves every other field
+		// (card, type, sourceId, …); a non-JSON / empty body is returned unchanged, so a
+		// GET read carries no body and is unaffected.
+		c.Fiber().Request().URI().SetQueryString(scopedBillingSearch(inQuery, subject).Encode())
+		if len(c.Body()) > 0 {
+			c.Fiber().Request().SetBody(scopedBillingBody(c.Body(), subject))
+		}
+		return c.Next()
+	}
+}
@@ -0,0 +1,150 @@
+package account
+
+import (
+	"encoding/json"
+	"net/http"
+	"testing"
+
+	"github.com/hanzoai/cloud"
+	luxlog "github.com/luxfi/log"
+	"github.com/zap-proto/zip"
+)
+
+// billing_coresident_test.go — proves PinBillingSubject carries the SAME tenant scoping
+// onto a co-resident commerce read handler that billingData applies on the bridge: the
+// caller's own subject is pinned into the query (dropping ?org), an unvalidated caller is
+// refused before the handler runs, and a trusted in-proc S2S caller passes through
+// verbatim. This is what lets commerce's ListInvoices/ListBillingSubscriptions/... serve
+// in-process without leaking another subject's rows.
+
+// echoQuery is the downstream stand-in for a commerce read handler: it reports exactly the
+// query it observes AFTER the pin, so a test can assert the subject the handler would filter on.
+func echoQuery(c *zip.Ctx) error {
+	return c.JSON(200, map[string]any{
+		"user":       c.Query("user"),
+		"userId":     c.Query("userId"),
+		"customerId": c.Query("customerId"),
+		"org":        c.Query("org"),
+		"status":     c.Query("status"),
+	})
+}
+
+// echoBody is the downstream stand-in for a commerce WRITE handler (e.g. CreatePaymentMethod)
+// that reads its subject from the JSON BODY: it reports the body it observes AFTER the pin, so
+// a test can assert the subject the handler would persist and that non-subject fields survive.
+func echoBody(c *zip.Ctx) error {
+	var got map[string]any
+	if len(c.Body()) > 0 {
+		_ = json.Unmarshal(c.Body(), &got)
+	}
+	return c.JSON(200, got)
+}
+
+func pinApp(t *testing.T) *zip.App {
+	t.Helper()
+	app := zip.New(zip.Config{Logger: luxlog.New("test")})
+	// MountAccount installs the identity middleware PinBillingSubject relies on; mounting
+	// it keeps the probe on the same trust plane as the real co-resident registration.
+	if err := MountAccount(app, cloud.Deps{Logger: luxlog.New("test"), Brand: "hanzo"}); err != nil {
+		t.Fatalf("MountAccount: %v", err)
+	}
+	app.Get("/probe", PinBillingSubject(), echoQuery)
+	app.Post("/probe", PinBillingSubject(), echoBody)
+	return app
+}
+
+// TestPinBillingSubject_PinsCallerAndDropsOrg — a validated customer's forged subject
+// keys are overwritten with its OWN subject and ?org is dropped, exactly like the bridge.
+func TestPinBillingSubject_PinsCallerAndDropsOrg(t *testing.T) {
+	app := pinApp(t)
+	code, body := callH(t, app, http.MethodGet,
+		"/probe?userId=victim&customerId=victim&user=victim&org=othercorp&status=open", alice, "")
+	if code != http.StatusOK {
+		t.Fatalf("want 200, got %d (%s)", code, body)
+	}
+	var got map[string]string
+	if err := json.Unmarshal(body, &got); err != nil {
+		t.Fatalf("bad body: %s", body)
+	}
+	for _, k := range billingSubjectKeys {
+		if got[k] != "acme" { // alice/acme resolves to the org subject "acme"
+			t.Fatalf("handler must see %s=acme (caller's own subject), got %q", k, got[k])
+		}
+	}
+	if got["org"] != "" {
+		t.Fatalf("org must be dropped, handler saw org=%q", got["org"])
+	}
+	if got["status"] != "open" {
+		t.Fatalf("non-subject filter must survive, got status=%q", got["status"])
+	}
+}
+
+// TestPinBillingSubject_PinsBodyForWrites — a POST whose JSON body names a FOREIGN subject
+// (customerId/userId/user) has every subject key overwritten with the caller's OWN subject
+// before the handler binds it, while non-subject fields survive. This is the boundary
+// commerce's CreatePaymentMethod (which reads customerId from the body) relies on to be
+// IDOR-safe co-resident — byte-identical to billingData's scopedBillingBody on the bridge.
+func TestPinBillingSubject_PinsBodyForWrites(t *testing.T) {
+	app := pinApp(t)
+	code, body := callH(t, app, http.MethodPost, "/probe", alice,
+		`{"customerId":"victim","userId":"victim","user":"victim","card":{"last4":"4242"}}`)
+	if code != http.StatusOK {
+		t.Fatalf("want 200, got %d (%s)", code, body)
+	}
+	var got map[string]any
+	if err := json.Unmarshal(body, &got); err != nil {
+		t.Fatalf("bad body: %s", body)
+	}
+	for _, k := range billingSubjectKeys {
+		if got[k] != "acme" { // alice/acme resolves to the org subject "acme"
+			t.Fatalf("handler must see body %s=acme (caller's own subject), got %v", k, got[k])
+		}
+	}
+	card, ok := got["card"].(map[string]any)
+	if !ok || card["last4"] != "4242" {
+		t.Fatalf("non-subject body field must survive the pin, got card=%v", got["card"])
+	}
+}
+
+// TestPinBillingSubject_RefusesUnvalidated — a forged X-Org-Id with NO validated
+// X-User-Id (and no service token) is refused before the read handler runs: no
+// cross-tenant billing read is possible.
+func TestPinBillingSubject_RefusesUnvalidated(t *testing.T) {
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := pinApp(t)
+	code, _ := callH(t, app, http.MethodGet, "/probe?userId=victim",
+		map[string]string{"X-Org-Id": "victim"}, "")
+	if code != http.StatusForbidden {
+		t.Fatalf("unvalidated caller: want 403, got %d", code)
+	}
+}
+
+// TestPinBillingSubject_S2SForwardsVerbatim — the trusted in-proc S2S caller (verified
+// COMMERCE_SERVICE_TOKEN + its own X-Org-Id, no validated user) is admitted and its query
+// is left UNTOUCHED, so it can name its own subject (the cap-gate's authorize read).
+func TestPinBillingSubject_S2SForwardsVerbatim(t *testing.T) {
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := pinApp(t)
+	code, body := callH(t, app, http.MethodGet, "/probe?user=acme&status=open",
+		map[string]string{"Authorization": "Bearer svc-tok", "X-Org-Id": "acme"}, "")
+	if code != http.StatusOK {
+		t.Fatalf("S2S: want 200, got %d (%s)", code, body)
+	}
+	var got map[string]string
+	_ = json.Unmarshal(body, &got)
+	if got["user"] != "acme" || got["status"] != "open" {
+		t.Fatalf("S2S query must pass through verbatim, got %+v", got)
+	}
+}
+
+// TestPinBillingSubject_S2SNoOrgRefused — the service token with NO X-Org-Id has no org
+// to scope the privileged read and is refused (matches billingData's s2s org requirement).
+func TestPinBillingSubject_S2SNoOrgRefused(t *testing.T) {
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := pinApp(t)
+	code, _ := callH(t, app, http.MethodGet, "/probe",
+		map[string]string{"Authorization": "Bearer svc-tok"}, "")
+	if code != http.StatusForbidden {
+		t.Fatalf("S2S without X-Org-Id: want 403, got %d", code)
+	}
+}
@@ -232,3 +232,65 @@ func TestBilling_RejectsTraversalSegment(t *testing.T) {
 		t.Fatalf("a traversal must never reach commerce, but upstream saw %q", f.path)
 	}
 }
+
+// ── S2S service-token admission (the auth fix; 4 security invariants) ─────────
+
+// Invariant #4 — THE SECURITY GATE: a public/unauthenticated caller (no validated
+// principal AND not the service token) STILL gets 403 on the spend-alert routes, incl.
+// a WRONG bearer. The fix must NEVER open billing to the world.
+func TestBilling_S2S_PublicStill403(t *testing.T) {
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := mountApp(t, "http://iam.invalid", "", "")
+	for _, path := range []string{
+		"/v1/billing/spend-alerts",
+		"/v1/billing/spend-alerts/authorize?user=acme&amount=1",
+	} {
+		// forged X-Org-Id, no validated principal, no service token
+		if code, body := callH(t, app, http.MethodGet, path, map[string]string{"X-Org-Id": "victim"}, ""); code != http.StatusForbidden {
+			t.Fatalf("public caller to %s: want 403, got %d (%s)", path, code, body)
+		}
+	}
+	// a WRONG bearer is still just a public caller → 403
+	if code, _ := callH(t, app, http.MethodGet, "/v1/billing/spend-alerts/authorize?user=acme&amount=1",
+		map[string]string{"X-Org-Id": "acme", "Authorization": "Bearer not-the-token"}, ""); code != http.StatusForbidden {
+		t.Fatalf("wrong bearer: want 403")
+	}
+}
+
+// The trusted in-proc S2S caller (verified COMMERCE_SERVICE_TOKEN + X-Org-Id) is admitted
+// and its authorize query is forwarded to commerce VERBATIM (a trusted caller names its
+// own subject), scoped by X-Org-Id — this is what lets the cap gate reach AuthorizeSpendCap.
+func TestBilling_S2S_ServiceTokenForwardsVerbatim(t *testing.T) {
+	f := &fakeBilling{}
+	t.Setenv("COMMERCE_URL", f.server(t).URL)
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := mountApp(t, "http://iam.invalid", "", "")
+
+	code, body := callH(t, app, http.MethodGet,
+		"/v1/billing/spend-alerts/authorize?user=acme&amount=100&project=P",
+		map[string]string{"Authorization": "Bearer svc-tok", "X-Org-Id": "acme"}, "")
+	if code != http.StatusOK {
+		t.Fatalf("S2S authorize: want 200, got %d (%s)", code, body)
+	}
+	if f.path != "/v1/billing/spend-alerts/authorize" {
+		t.Fatalf("forwarded path = %q", f.path)
+	}
+	// VERBATIM: the S2S caller's ?user/?amount/?project reach commerce un-pinned.
+	if f.query.Get("user") != "acme" || f.query.Get("amount") != "100" || f.query.Get("project") != "P" {
+		t.Fatalf("S2S query must forward verbatim, got %v", f.query)
+	}
+	if f.org != "acme" || f.auth != "Bearer svc-tok" {
+		t.Fatalf("S2S must send X-Org-Id=acme + service token, got org=%q auth=%q", f.org, f.auth)
+	}
+}
+
+// S2S with the verified token but NO X-Org-Id → 403 (no org to scope the privileged
+// forward to; never fall back to a client value).
+func TestBilling_S2S_NoOrg403(t *testing.T) {
+	t.Setenv("COMMERCE_SERVICE_TOKEN", "svc-tok")
+	app := mountApp(t, "http://iam.invalid", "", "")
+	if code, _ := callH(t, app, http.MethodGet, "/v1/billing/spend-alerts/authorize?user=acme&amount=1",
+		map[string]string{"Authorization": "Bearer svc-tok"}, ""); code != http.StatusForbidden {
+		t.Fatalf("S2S without X-Org-Id: want 403")
+	}
+}
@@ -173,6 +173,23 @@ func requireCSRF(s *cloud.Service[state], next zip.Handler) zip.Handler {
 	}
 }

+// RequireCSRF exposes the ambient-cookie anti-CSRF gate as a STANDALONE middleware for a
+// co-resident money-WRITE route registered OUTSIDE this package — specifically
+// apps/commerce.go's POST /v1/billing/topup/token, which shadows the account-bridge's
+// POST /v1/billing/* wildcard (order 100 < 122) that would otherwise have wrapped the
+// write in requireCSRF. Moving the route co-resident to break the commerceinproc
+// self-dispatch loop must NOT silently drop that anti-CSRF gate, so the identical
+// enforcement rides along as its own handler. It binds to the SAME process-wide key
+// (sharedCSRFKey) the GET /v1/csrf issuer and the bridge verifier use, so a token minted
+// at /v1/csrf verifies here byte-identically. Enforces ONLY on the ambient-cookie path (a
+// Bearer/gateway/API caller is not CSRF-able); on success it c.Next()s into the rest of
+// the chain. The minimal Service carries only the shared key — requireCSRF/verifyCSRF
+// read nothing else off it.
+func RequireCSRF() zip.Handler {
+	s := &cloud.Service[state]{State: state{csrfKey: sharedCSRFKey(nil)}}
+	return requireCSRF(s, func(c *zip.Ctx) error { return c.Next() })
+}
+
 // issueCSRFToken serves GET /v1/csrf: for a VALIDATED caller, a fresh token
 // bound to their identity. no-store so it is never cached by a shared proxy. This is
 // the same-origin endpoint the embedded SPA reads (its response body is unreadable to
@@ -44,6 +44,7 @@ const iamMaxBody = 4 << 20
 // iamClient is the confidential-client caller. clientID/clientSecret authenticate
 // as the `hanzo-console` app; an empty pair means "not configured" (handlers 501).
 type iamClient struct {
+	serviceToken string // IAM_SERVICE_TOKEN — the Bearer for the admin provision endpoint
 	base         string
 	clientID     string
 	clientSecret string
@@ -56,10 +57,91 @@ func newIAMClient() *iamClient {
 		base:         base,
 		clientID:     strings.TrimSpace(os.Getenv("IAM_MINT_CLIENT_ID")),
 		clientSecret: strings.TrimSpace(os.Getenv("IAM_MINT_CLIENT_SECRET")),
+		serviceToken: strings.TrimSpace(os.Getenv("IAM_SERVICE_TOKEN")),
 		http:         &http.Client{Timeout: 15 * time.Second},
 	}
 }

+// provisionResult is the /v1/iam/admin/provision response: the converged org and its
+// hashed credential (accessSecret shown ONCE on first mint). The org starts at a zero
+// balance — usage is pre-paid, no signup grant.
+type provisionResult struct {
+	Org          string `json:"org"`
+	AccessKey    string `json:"accessKey"`
+	AccessSecret string `json:"accessSecret"`
+	Error        string `json:"error"`
+}
+
+// provisionReady reports whether the service-token provisioning path is wired.
+func (c *iamClient) provisionReady() bool { return c != nil && c.serviceToken != "" }
+
+// provision drives the ONE atomic IAM onboarding op: create the org, move the named
+// user in as its admin, and mint its hashed org-scoped credential — the service-token
+// endpoint that replaces the create-org + move-user pair, so there is no orphan
+// between two writes and a mid-flight retry converges. orgSlug is the caller's
+// already-resolved slug (IAM honors it verbatim). The org starts at a zero balance.
+func (c *iamClient) provision(ctx context.Context, owner, name, orgSlug string, personal bool) (provisionResult, error) {
+	if !c.provisionReady() {
+		return provisionResult{}, errNotConfigured
+	}
+	body, err := json.Marshal(map[string]any{
+		"owner": owner, "name": name, "orgSlug": orgSlug, "personal": personal,
+	})
+	if err != nil {
+		return provisionResult{}, err
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.base+"/v1/iam/admin/provision", strings.NewReader(string(body)))
+	if err != nil {
+		return provisionResult{}, err
+	}
+	req.Header.Set("Authorization", "Bearer "+c.serviceToken)
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Accept", "application/json")
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return provisionResult{}, fmt.Errorf("iam unreachable: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	raw, err := io.ReadAll(io.LimitReader(resp.Body, iamMaxBody))
+	if err != nil {
+		return provisionResult{}, err
+	}
+	var out provisionResult
+	if err := json.Unmarshal(raw, &out); err != nil {
+		return provisionResult{}, fmt.Errorf("iam provision non-json response (%d)", resp.StatusCode)
+	}
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 || out.Error != "" {
+		msg := out.Error
+		if msg == "" {
+			msg = fmt.Sprintf("iam status %d", resp.StatusCode)
+		}
+		return provisionResult{}, fmt.Errorf("iam provision: %s", msg)
+	}
+	return out, nil
+}
+
+// userRow is the subset of an IAM user the onboarding path reads to resolve the
+// caller's authoritative (owner, name) — a zero-org caller's owner is not on its
+// token, so provision needs it from the row.
+type userRow struct {
+	Owner string `json:"owner"`
+	Name  string `json:"name"`
+}
+
+// getUserRow resolves the user by the caller's id (the same read the move did) into
+// its authoritative (owner, name).
+func (c *iamClient) getUserRow(ctx context.Context, id string) (userRow, error) {
+	raw, err := c.getUser(ctx, id)
+	if err != nil {
+		return userRow{}, err
+	}
+	var row userRow
+	if err := json.Unmarshal(raw, &row); err != nil {
+		return userRow{}, fmt.Errorf("iam get-user: decode: %w", err)
+	}
+	return row, nil
+}
+
 // configured reports whether the confidential client is wired. Handlers 501 when
 // false — the deployment simply lacks the `hanzo-console` credential (the honest
 // "not configured on this deployment" state, never a fabricated result).
@@ -0,0 +1,64 @@
+package account
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+// TestOnboardFirstRun_ProvisionsOnce proves the production signup path drives ONE
+// atomic IAM provision (not the old create-org + move-user pair): it resolves the
+// zero-org caller's authoritative (owner, name) and provisions the org + hashed
+// credential in a single call. No trial credit is granted — the org starts at a zero
+// balance and usage is pre-paid.
+func TestOnboardFirstRun_ProvisionsOnce(t *testing.T) {
+	var provisionCalls int
+	var provBody map[string]any
+
+	iamSrv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/v1/iam/get-user":
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"status": "ok",
+				"data":   map[string]any{"owner": "landing", "name": "dave"},
+			})
+		case "/v1/iam/admin/provision":
+			provisionCalls++
+			b, _ := io.ReadAll(r.Body)
+			_ = json.Unmarshal(b, &provBody)
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"org": "dave", "accessKey": "hk-x", "accessSecret": "sk-x",
+			})
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer iamSrv.Close()
+
+	iam := &iamClient{base: iamSrv.URL, clientID: "c", clientSecret: "s", serviceToken: "svc", http: &http.Client{}}
+
+	resp, err := onboardFirstRun(context.Background(), iam, "dave", "dave", "Dave", true)
+	if err != nil {
+		t.Fatalf("onboardFirstRun: %v", err)
+	}
+	if resp.Org != "dave" || resp.Additional {
+		t.Fatalf("resp = %+v, want org=dave additional=false", resp)
+	}
+	if provisionCalls != 1 {
+		t.Fatalf("provision calls = %d, want 1 (ONE atomic op, not create+move)", provisionCalls)
+	}
+	if provBody["owner"] != "landing" || provBody["name"] != "dave" || provBody["orgSlug"] != "dave" {
+		t.Fatalf("provision body = %v, want owner=landing name=dave orgSlug=dave", provBody)
+	}
+
+	// Retry converges: provision is idempotent (same org), no orphan.
+	if _, err := onboardFirstRun(context.Background(), iam, "dave", "dave", "Dave", true); err != nil {
+		t.Fatalf("retry: %v", err)
+	}
+	if provisionCalls != 2 {
+		t.Fatalf("provision calls = %d, want 2 (retried, converges)", provisionCalls)
+	}
+}
@@ -38,7 +38,10 @@ import (
 	"github.com/hanzoai/cloud/clients/admin/finance"
 	"github.com/hanzoai/cloud/clients/admin/health"
 	"github.com/hanzoai/cloud/clients/admin/iam"
+	"github.com/hanzoai/cloud/clients/admin/invoices"
+	"github.com/hanzoai/cloud/clients/admin/metrics"
 	"github.com/hanzoai/cloud/clients/admin/revenue"
+	"github.com/hanzoai/cloud/clients/admin/subscriptions"
 	"github.com/hanzoai/cloud/clients/commerceinproc"
 	"github.com/hanzoai/cloud/clients/principal"
 	"github.com/zap-proto/zip"
@@ -87,42 +90,57 @@ func Mount(app *zip.App, deps cloud.Deps) error {
 // control plane behind core.Guard. Each carved-out domain (audit/customer/revenue/finance)
 // owns its own route registration.
 func routes(app *zip.App, s *cloud.Service[core.State]) {
+	g := app.Group("/v1/admin")
 	// Org-scoped panels — GuardScoped. Cross-tenant reads are impossible for a non-super
 	// caller.
-	app.Get("/v1/admin/me", core.GuardScoped(s, me))
-	app.Get("/v1/admin/overview", core.GuardScoped(s, overview))
-	app.Get("/v1/admin/orgs", core.GuardScoped(s, orgs))
-	app.Get("/v1/admin/users", core.GuardScoped(s, users))
-	app.Get("/v1/admin/usage", core.GuardScoped(s, usage))
+	g.Get("/me", core.GuardScoped(s, me))
+	g.Get("/overview", core.GuardScoped(s, overview))
+	g.Get("/orgs", core.GuardScoped(s, orgs))
+	g.Get("/users", core.GuardScoped(s, users))
+	g.Get("/usage", core.GuardScoped(s, usage))
 	// Platform reads — SuperAdmin only (cross-tenant by nature).
-	app.Get("/v1/admin/roles", core.Guard(s, roles))
-	app.Get("/v1/admin/applications", core.Guard(s, applications))
-	app.Get("/v1/admin/products", core.Guard(s, products))
-	app.Get("/v1/admin/compute", core.Guard(s, compute))
-	app.Get("/v1/admin/o11y", core.Guard(s, o11y))
-	app.Post("/v1/admin/sync", core.Guard(s, syncNow))
+	g.Get("/roles", core.Guard(s, roles))
+	g.Get("/applications", core.Guard(s, applications))
+	g.Get("/products", core.Guard(s, products))
+	g.Get("/compute", core.Guard(s, compute))
+	g.Get("/block-storage", core.Guard(s, blockStorage))
+	g.Get("/o11y", core.Guard(s, o11y))
+	g.Get("/aimetrics", core.Guard(s, aimetrics))
+	g.Post("/sync", core.Guard(s, syncNow))
+
+	// Credit grants — the ONE admin mint surface (SuperAdmin only). Thin, audited
+	// relay to commerce's mint-gated POST /v1/billing/credit-grants; commerce is the
+	// sole ledger. See creditgrant.go.
+	g.Post("/credit-grants", core.Guard(s, createCreditGrant))

 	// Product analytics — org-scoped (SuperAdmin: all-orgs; org admin: their own org).
-	app.Get("/v1/admin/analytics", core.GuardScoped(s, analytics))
+	g.Get("/analytics", core.GuardScoped(s, analytics))
 	// Bases — the tenant Base-instance panel, org-scoped (bases.go).
-	app.Get("/v1/admin/bases", core.GuardScoped(s, bases))
+	g.Get("/bases", core.GuardScoped(s, bases))

 	// ── Platform control plane — SuperAdmin ONLY (launch/release/flags + access). ──
-	app.Get("/v1/admin/flags", core.Guard(s, flagsBoard))
-	app.Put("/v1/admin/flags/:key", core.Guard(s, setFlag))
+	g.Get("/flags", core.Guard(s, flagsBoard))
+	g.Put("/flags/:key", core.Guard(s, setFlag))
 	// Launch-control services board — the waitlist-mode lens on the flag engine (twin
-	// of /v1/admin/flags), folded in from the former featuregate control plane.
-	app.Get("/v1/admin/services", core.Guard(s, services))
-	app.Post("/v1/admin/services", core.Guard(s, upsertService))
-	app.Post("/v1/admin/services/:service/mode", core.Guard(s, setServiceMode))
-	app.Get("/v1/admin/waitlist", core.Guard(s, waitlist))
-	app.Post("/v1/admin/waitlist/boost", core.Guard(s, waitlistBoost))
+	// of /v1/admin/flags), reading the registry + decide the admission gate owns.
+	g.Get("/services", core.Guard(s, services))
+	g.Post("/services", core.Guard(s, upsertService))
+	g.Post("/services/:service/mode", core.Guard(s, setServiceMode))
+	g.Get("/waitlist", core.Guard(s, waitlist))
+	g.Post("/waitlist/boost", core.Guard(s, waitlistBoost))

-	// ── Carved-out domains own their routes (audit/customer/revenue/finance). ──
+	// Usage-cap + promo control plane (promos platform-only; spend-caps org-scoped).
+	limitRoutes(app, s)
+
+	// ── Carved-out domains own their routes (audit/customer/revenue/finance +
+	// the billing fleet views metrics/invoices/subscriptions). ──
 	audit.Routes(app, s)
 	customer.Routes(app, s)
 	revenue.Routes(app, s)
 	finance.Routes(app, s)
+	metrics.Routes(app, s)
+	invoices.Routes(app, s)
+	subscriptions.Routes(app, s)
 }

 // ── /v1/admin/me — operator identity (AdminMe) ───────────────────────────────
@@ -24,16 +24,16 @@ import (
 // mount builds a zip app with admin mounted against the given upstream bases,
 // and returns a `do` helper that issues test requests through the whole app.
 func mount(t *testing.T, iamURL, commerceURL, healthURL string) func(method, path string, hdr map[string]string) (*http.Response, []byte) {
-	do, _, _ := mountSvc(t, iamURL, commerceURL, healthURL)
+	do, _, _ := mountService(t, iamURL, commerceURL, healthURL)
 	return do
 }

-// mountSvc is mount but also returns the underlying cloud.Service[state] (so finance tests can swap
+// mountService is mount but also returns the underlying cloud.Service[state] (so finance tests can swap
 // in a fake DigitalOcean client, and the cockpit tests can attach an audit store)
 // AND the raw fiber app (so tests that need a request BODY can drive it directly —
 // the returned `do` sends a nil body). The handlers read s.* live at request time,
 // so an override before issuing a request takes effect.
-func mountSvc(t *testing.T, iamURL, commerceURL, healthURL string) (func(method, path string, hdr map[string]string) (*http.Response, []byte), *cloud.Service[core.State], *fiber.App) {
+func mountService(t *testing.T, iamURL, commerceURL, healthURL string) (func(method, path string, hdr map[string]string) (*http.Response, []byte), *cloud.Service[core.State], *fiber.App) {
 	t.Helper()
 	app := zip.New(zip.Config{Logger: luxlog.New("test")})
 	s := &cloud.Service[core.State]{State: core.State{
@@ -0,0 +1,392 @@
+// Copyright 2023-2026 Hanzo AI Inc. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package admin
+
+// aimetrics — GET /v1/admin/aimetrics, the GLOBAL fleet-wide AI / training / eval
+// read that powers the operator's AI-metrics board on admin.hanzo.ai. It is the
+// AI-and-eval-focused companion to o11y (o11y.go): where o11y answers "how is the
+// FLEET behaving" (RED metrics, logs, usage), this answers "how are the MODELS and
+// EVALS doing" — LLM generations, per-model spend, and eval-run quality/progress —
+// over the SAME ONE datastore (Datastore), the SAME shared client
+// (aiobject.DatastoreQuery), no second connection.
+//
+// Signals, each from its canonical table in the one datastore:
+//   - LLM generations → langfuse.observations : generations, cost (USD), latency
+//                                                (fleet-wide; honest-empty until the
+//                                                Langfuse ingest lands rows)
+//   - Per-model usage → hanzo.cloud_usage      : requests, tokens, cost per model
+//                                                (the live usage ledger the ai gateway
+//                                                writes — populated today)
+//   - Eval runs       → hanzo.eval_traces      : traces, runs, datasets, models under
+//                                                test, per-trace latency
+//   - Eval progress   → hanzo.eval_scores      : score count, avg score, per-score-name
+//                                                distribution, recent-run averages, and
+//                                                the avg-score-over-time TREND — the
+//                                                training/eval progress signal
+//
+// The eval_traces / eval_scores tables are OWNED and written by the eval telemetry
+// store (clients/eval/telemetry.go) — the SAME warehouse, same db ("hanzo"), same
+// shared aiobject client. admin only READS them here. There is deliberately no
+// "training_progress" table: the router's per-request training events live in the ai
+// OLTP Postgres (object.RoutingEvent), NOT the OLAP warehouse, so the honest
+// warehouse-side progress signal is the eval-score trend, not a routing table.
+//
+// SUPERADMIN ONLY (the core.Guard wrap in admin.go), all-orgs, no org filter — the
+// one place a fleet operator crosses tenants for AI/eval metrics; a non-admin bearer
+// is refused 403 before a single row is read. Fail-closed.
+//
+// Honest by construction, exactly like o11y/compute: no datastore connected → the
+// real empty aggregate, never a fabricated fleet; and every signal degrades
+// INDEPENDENTLY — a table that is absent or a column that differs contributes its
+// zero-value (the enclosing `if err == nil`), never a failure, so the board always
+// renders what the datastore actually holds. admin READS only; it owns and creates
+// NO table. Money from cloud_usage is USD cents, from langfuse is USD; latency is
+// milliseconds; time bounds are POSITIONAL parameters (never interpolated), and the
+// bucket interval is a server-side constant — injection-safe.
+
+import (
+	"strconv"
+	"time"
+
+	aiobject "github.com/hanzoai/ai/object"
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/admin/core"
+	"github.com/zap-proto/zip"
+)
+
+// Fully-qualified datastore tables. admin only READS these — the ai gateway owns
+// hanzo.cloud_usage, Langfuse owns langfuse.observations, and the eval telemetry
+// store (clients/eval) owns hanzo.eval_traces / hanzo.eval_scores.
+const (
+	aimUsageTable  = "hanzo.cloud_usage"
+	aimLangfuseObs = "langfuse.observations"
+	aimEvalTraces  = "hanzo.eval_traces"
+	aimEvalScores  = "hanzo.eval_scores"
+	aimTopN        = 12
+)
+
+// aiMetrics is the whole AI-metrics board payload.
+type aiMetrics struct {
+	Range          string           `json:"range"`
+	Start          string           `json:"start"`
+	End            string           `json:"end"`
+	Langfuse       aimLangfuse      `json:"langfuse"`
+	Usage          aimUsage         `json:"usage"`
+	Evals          aimEvals         `json:"evals"`
+	TopModels      []aimModelStat   `json:"topModels"`      // cloud_usage per-model (populated today)
+	LangfuseModels []aimLfModelStat `json:"langfuseModels"` // langfuse per-model (honest-empty today)
+	ScoreNames     []aimScoreStat   `json:"scoreNames"`     // eval_scores per score-name
+	EvalRuns       []aimRunStat     `json:"evalRuns"`       // recent eval runs (progress)
+	ScoreSeries    []aimScorePoint  `json:"scoreSeries"`    // avg eval score over time (progress trend)
+}
+
+// aimLangfuse is the fleet-wide Langfuse generation rollup (honest-empty today).
+// Cost is USD (Langfuse's native unit); latency is milliseconds (end_time-start_time).
+type aimLangfuse struct {
+	Generations  int64   `json:"generations"`
+	CostUsd      float64 `json:"costUsd"`
+	LatencyMsAvg float64 `json:"latencyMsAvg"`
+	LatencyMsP95 float64 `json:"latencyMsP95"`
+}
+
+// aimUsage is the fleet LLM-usage KPI band from the live cloud_usage ledger.
+type aimUsage struct {
+	Requests         int64 `json:"requests"`
+	Tokens           int64 `json:"tokens"`
+	PromptTokens     int64 `json:"promptTokens"`
+	CompletionTokens int64 `json:"completionTokens"`
+	CostCents        int64 `json:"costCents"`
+	Models           int64 `json:"models"`
+}
+
+// aimEvals is the fleet eval KPI band: the trace half (eval_traces) and the score
+// half (eval_scores). LatencyMsAvg is the mean model-under-test call window.
+type aimEvals struct {
+	Runs         int64   `json:"runs"`
+	Traces       int64   `json:"traces"`
+	Datasets     int64   `json:"datasets"`
+	Models       int64   `json:"models"`
+	LatencyMsAvg float64 `json:"latencyMsAvg"`
+	Scores       int64   `json:"scores"`
+	ScoreNames   int64   `json:"scoreNames"`
+	AvgScore     float64 `json:"avgScore"`
+}
+
+// aimModelStat is one row of the per-model usage leaderboard (cloud_usage).
+type aimModelStat struct {
+	Model     string `json:"model"`
+	Requests  int64  `json:"requests"`
+	Tokens    int64  `json:"tokens"`
+	CostCents int64  `json:"costCents"`
+}
+
+// aimLfModelStat is one row of the per-model Langfuse leaderboard (honest-empty today).
+type aimLfModelStat struct {
+	Model       string  `json:"model"`
+	Generations int64   `json:"generations"`
+	CostUsd     float64 `json:"costUsd"`
+}
+
+// aimScoreStat is one row of the per-score-name eval leaderboard (eval_scores).
+type aimScoreStat struct {
+	Name     string  `json:"name"`
+	Count    int64   `json:"count"`
+	AvgValue float64 `json:"avgValue"`
+	MinValue float64 `json:"minValue"`
+	MaxValue float64 `json:"maxValue"`
+}
+
+// aimRunStat is one recent eval run: its dataset, how many scores it recorded, its
+// mean score, and when it last ran — the run-level eval-progress row.
+type aimRunStat struct {
+	RunName  string  `json:"runName"`
+	Dataset  string  `json:"dataset"`
+	Scores   int64   `json:"scores"`
+	AvgValue float64 `json:"avgValue"`
+	LastTs   string  `json:"lastTs"`
+}
+
+// aimScorePoint is one bucket of the avg-eval-score-over-time trend.
+type aimScorePoint struct {
+	Ts       string  `json:"ts"`
+	AvgValue float64 `json:"avgValue"`
+	Count    int64   `json:"count"`
+}
+
+// aimetrics answers GET /v1/admin/aimetrics. ?range=24h|7d|30d bounds the window
+// (default 30d). SUPERADMIN ONLY (core.Guard). Every signal degrades independently:
+// a table that is absent or errors contributes its zero-value, never a failure — the
+// board always renders what the datastore actually holds.
+func aimetrics(s *cloud.Service[core.State], c *zip.Ctx) error {
+	ctx := c.Context()
+	rangeLabel := o11yRange(c.Query("range"))
+	since := computeSince(rangeLabel)
+	payload := aiMetrics{
+		Range:          rangeLabel,
+		Start:          since.Format(time.RFC3339),
+		End:            time.Now().UTC().Format(time.RFC3339),
+		TopModels:      []aimModelStat{},
+		LangfuseModels: []aimLfModelStat{},
+		ScoreNames:     []aimScoreStat{},
+		EvalRuns:       []aimRunStat{},
+		ScoreSeries:    []aimScorePoint{},
+	}
+
+	// Honest-empty when the warehouse is not connected: the board renders its zero
+	// state, never a fabricated fleet.
+	if !aiobject.DatastoreEnabled() {
+		return core.OK(c, payload)
+	}
+
+	sinceTS := chTS(since) // DateTime literal — cloud_usage.timestamp, langfuse.start_time, eval_*.ts
+	interval := o11yBucket(rangeLabel)
+
+	// ── Langfuse generations (fleet) — honest-empty until ingest lands rows ──
+	if rows, err := aiobject.DatastoreQuery(ctx, aimLangfuseTotalsSQL(), sinceTS); err == nil {
+		r := firstRowOr(rows)
+		payload.Langfuse.Generations = chInt64(r["gens"])
+		payload.Langfuse.CostUsd = chFloat64(r["cost"])
+	}
+	// Langfuse latency (separate query so a Nullable end_time / column mismatch never
+	// zeroes the proven generations+cost number above).
+	if rows, err := aiobject.DatastoreQuery(ctx, aimLangfuseLatencySQL(), sinceTS); err == nil {
+		r := firstRowOr(rows)
+		payload.Langfuse.LatencyMsAvg = chFloat64(r["lat_avg"])
+		payload.Langfuse.LatencyMsP95 = chFloat64(r["lat_p95"])
+	}
+	// Langfuse per-model.
+	if rows, err := aiobject.DatastoreQuery(ctx, aimLangfuseModelsSQL(), sinceTS); err == nil {
+		payload.LangfuseModels = lfModelsFromRows(rows)
+	}
+
+	// ── Per-model usage (fleet) from the live cloud_usage ledger ──
+	if rows, err := aiobject.DatastoreQuery(ctx, aimUsageTotalsSQL(), sinceTS); err == nil {
+		fillAimUsage(&payload.Usage, firstRowOr(rows))
+	}
+	if rows, err := aiobject.DatastoreQuery(ctx, aimTopModelsSQL(), sinceTS); err == nil {
+		payload.TopModels = aimModelsFromRows(rows)
+	}
+
+	// ── Evals (fleet): traces + scores + progress ──
+	if rows, err := aiobject.DatastoreQuery(ctx, aimEvalTracesSQL(), sinceTS); err == nil {
+		fillAimEvalTraces(&payload.Evals, firstRowOr(rows))
+	}
+	if rows, err := aiobject.DatastoreQuery(ctx, aimEvalScoresSQL(), sinceTS); err == nil {
+		fillAimEvalScores(&payload.Evals, firstRowOr(rows))
+	}
+	if rows, err := aiobject.DatastoreQuery(ctx, aimScoreNamesSQL(), sinceTS); err == nil {
+		payload.ScoreNames = scoreNamesFromRows(rows)
+	}
+	if rows, err := aiobject.DatastoreQuery(ctx, aimEvalRunsSQL(), sinceTS); err == nil {
+		payload.EvalRuns = evalRunsFromRows(rows)
+	}
+	if rows, err := aiobject.DatastoreQuery(ctx, aimScoreSeriesSQL(interval), sinceTS); err == nil {
+		payload.ScoreSeries = scoreSeriesFromRows(rows)
+	}
+
+	return core.OK(c, payload)
+}
+
+// ── pure SQL builders (static SQL + one positional time bound; unit-tested) ──
+
+func aimLangfuseTotalsSQL() string {
+	return "SELECT count() AS gens, toFloat64(sum(total_cost)) AS cost FROM " + aimLangfuseObs +
+		" WHERE type = 'GENERATION' AND start_time >= ?"
+}
+
+func aimLangfuseLatencySQL() string {
+	lat := "(toUnixTimestamp64Milli(end_time) - toUnixTimestamp64Milli(start_time))"
+	return "SELECT round(avg(" + lat + "), 2) AS lat_avg, round(quantile(0.95)(" + lat + "), 2) AS lat_p95 " +
+		"FROM " + aimLangfuseObs + " WHERE type = 'GENERATION' AND start_time >= ? AND end_time > start_time"
+}
+
+func aimLangfuseModelsSQL() string {
+	return "SELECT provided_model_name AS model, count() AS gens, toFloat64(sum(total_cost)) AS cost " +
+		"FROM " + aimLangfuseObs + " WHERE type = 'GENERATION' AND start_time >= ? AND provided_model_name != '' " +
+		"GROUP BY model ORDER BY gens DESC LIMIT " + strconv.Itoa(aimTopN)
+}
+
+func aimUsageTotalsSQL() string {
+	return "SELECT count() AS requests, sum(total_tokens) AS tokens, " +
+		"sum(prompt_tokens) AS prompt_tokens, sum(completion_tokens) AS completion_tokens, " +
+		"sum(cost_cents) AS cost_cents, uniqExact(model) AS models " +
+		"FROM " + aimUsageTable + " WHERE timestamp >= ?"
+}
+
+func aimTopModelsSQL() string {
+	return "SELECT model, count() AS requests, sum(total_tokens) AS tokens, " +
+		"sum(cost_cents) AS cost_cents FROM " + aimUsageTable +
+		" WHERE timestamp >= ? AND model != '' GROUP BY model ORDER BY requests DESC LIMIT " + strconv.Itoa(aimTopN)
+}
+
+func aimEvalTracesSQL() string {
+	lat := "(toUnixTimestamp64Milli(end_time) - toUnixTimestamp64Milli(start_time))"
+	return "SELECT count() AS traces, uniqExact(run_name) AS runs, uniqExact(dataset) AS datasets, " +
+		"uniqExact(model) AS models, round(avgIf(" + lat + ", end_time > start_time), 2) AS lat_avg " +
+		"FROM " + aimEvalTraces + " WHERE ts >= ?"
+}
+
+func aimEvalScoresSQL() string {
+	return "SELECT count() AS scores, round(avg(value), 4) AS avg_value, uniqExact(name) AS score_names " +
+		"FROM " + aimEvalScores + " WHERE ts >= ?"
+}
+
+func aimScoreNamesSQL() string {
+	return "SELECT name, count() AS n, round(avg(value), 4) AS avg_value, " +
+		"round(min(value), 4) AS min_value, round(max(value), 4) AS max_value " +
+		"FROM " + aimEvalScores + " WHERE ts >= ? AND name != '' GROUP BY name ORDER BY n DESC LIMIT " + strconv.Itoa(aimTopN)
+}
+
+func aimEvalRunsSQL() string {
+	return "SELECT run_name, any(dataset) AS dataset, count() AS scores, round(avg(value), 4) AS avg_value, " +
+		"max(ts) AS last_ts FROM " + aimEvalScores + " WHERE ts >= ? AND run_name != '' " +
+		"GROUP BY run_name ORDER BY last_ts DESC LIMIT " + strconv.Itoa(aimTopN)
+}
+
+func aimScoreSeriesSQL(interval string) string {
+	return "SELECT toStartOfInterval(ts, INTERVAL " + interval + ") AS ts, " +
+		"round(avg(value), 4) AS avg_value, count() AS n FROM " + aimEvalScores +
+		" WHERE ts >= ? GROUP BY ts ORDER BY ts"
+}
+
+// ── pure row parsers (unit-tested) ──
+
+func fillAimUsage(u *aimUsage, r map[string]any) {
+	u.Requests = chInt64(r["requests"])
+	u.Tokens = chInt64(r["tokens"])
+	u.PromptTokens = chInt64(r["prompt_tokens"])
+	u.CompletionTokens = chInt64(r["completion_tokens"])
+	u.CostCents = chInt64(r["cost_cents"])
+	u.Models = chInt64(r["models"])
+}
+
+func fillAimEvalTraces(e *aimEvals, r map[string]any) {
+	e.Traces = chInt64(r["traces"])
+	e.Runs = chInt64(r["runs"])
+	e.Datasets = chInt64(r["datasets"])
+	e.Models = chInt64(r["models"])
+	e.LatencyMsAvg = chFloat64(r["lat_avg"])
+}
+
+func fillAimEvalScores(e *aimEvals, r map[string]any) {
+	e.Scores = chInt64(r["scores"])
+	e.AvgScore = chFloat64(r["avg_value"])
+	e.ScoreNames = chInt64(r["score_names"])
+}
+
+func aimModelsFromRows(rows []map[string]any) []aimModelStat {
+	out := make([]aimModelStat, 0, len(rows))
+	for _, r := range rows {
+		out = append(out, aimModelStat{
+			Model:     chStr(r["model"]),
+			Requests:  chInt64(r["requests"]),
+			Tokens:    chInt64(r["tokens"]),
+			CostCents: chInt64(r["cost_cents"]),
+		})
+	}
+	return out
+}
+
+func lfModelsFromRows(rows []map[string]any) []aimLfModelStat {
+	out := make([]aimLfModelStat, 0, len(rows))
+	for _, r := range rows {
+		out = append(out, aimLfModelStat{
+			Model:       chStr(r["model"]),
+			Generations: chInt64(r["gens"]),
+			CostUsd:     chFloat64(r["cost"]),
+		})
+	}
+	return out
+}
+
+func scoreNamesFromRows(rows []map[string]any) []aimScoreStat {
+	out := make([]aimScoreStat, 0, len(rows))
+	for _, r := range rows {
+		out = append(out, aimScoreStat{
+			Name:     chStr(r["name"]),
+			Count:    chInt64(r["n"]),
+			AvgValue: chFloat64(r["avg_value"]),
+			MinValue: chFloat64(r["min_value"]),
+			MaxValue: chFloat64(r["max_value"]),
+		})
+	}
+	return out
+}
+
+func evalRunsFromRows(rows []map[string]any) []aimRunStat {
+	out := make([]aimRunStat, 0, len(rows))
+	for _, r := range rows {
+		out = append(out, aimRunStat{
+			RunName:  chStr(r["run_name"]),
+			Dataset:  chStr(r["dataset"]),
+			Scores:   chInt64(r["scores"]),
+			AvgValue: chFloat64(r["avg_value"]),
+			LastTs:   chTime(r["last_ts"]),
+		})
+	}
+	return out
+}
+
+func scoreSeriesFromRows(rows []map[string]any) []aimScorePoint {
+	out := make([]aimScorePoint, 0, len(rows))
+	for _, r := range rows {
+		out = append(out, aimScorePoint{
+			Ts:       chTime(r["ts"]),
+			AvgValue: chFloat64(r["avg_value"]),
+			Count:    chInt64(r["n"]),
+		})
+	}
+	return out
+}
@@ -0,0 +1,171 @@
+// Copyright 2023-2026 Hanzo AI Inc. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package admin
+
+import (
+	"strings"
+	"testing"
+)
+
+// TestAimSQL_ReadsCanonicalTables proves every AI-metrics query reads the ONE
+// datastore's canonical table, binds the time bound as a POSITIONAL param (one
+// `?`), and never interpolates user input. The bucket interval is the only rendered
+// value in the series query and it is a server-side constant.
+func TestAimSQL_ReadsCanonicalTables(t *testing.T) {
+	cases := []struct {
+		name, sql, table string
+		wantQMarks       int
+	}{
+		{"langfuseTotals", aimLangfuseTotalsSQL(), "langfuse.observations", 1},
+		{"langfuseLatency", aimLangfuseLatencySQL(), "langfuse.observations", 1},
+		{"langfuseModels", aimLangfuseModelsSQL(), "langfuse.observations", 1},
+		{"usageTotals", aimUsageTotalsSQL(), "hanzo.cloud_usage", 1},
+		{"topModels", aimTopModelsSQL(), "hanzo.cloud_usage", 1},
+		{"evalTraces", aimEvalTracesSQL(), "hanzo.eval_traces", 1},
+		{"evalScores", aimEvalScoresSQL(), "hanzo.eval_scores", 1},
+		{"scoreNames", aimScoreNamesSQL(), "hanzo.eval_scores", 1},
+		{"evalRuns", aimEvalRunsSQL(), "hanzo.eval_scores", 1},
+		{"scoreSeries", aimScoreSeriesSQL("1 DAY"), "hanzo.eval_scores", 1},
+	}
+	for _, c := range cases {
+		if !strings.Contains(c.sql, "FROM "+c.table) {
+			t.Errorf("%s must read %s; got %q", c.name, c.table, c.sql)
+		}
+		if n := strings.Count(c.sql, "?"); n != c.wantQMarks {
+			t.Errorf("%s: %d bind params, want %d (time bound only) — no interpolation; got %q", c.name, n, c.wantQMarks, c.sql)
+		}
+	}
+}
+
+// TestAimLangfuseScopedToGeneration proves the Langfuse lens is scoped to
+// generations only (not spans/events), matching the o11y LLM lens.
+func TestAimLangfuseScopedToGeneration(t *testing.T) {
+	for _, sql := range []string{aimLangfuseTotalsSQL(), aimLangfuseLatencySQL(), aimLangfuseModelsSQL()} {
+		if !strings.Contains(sql, "type = 'GENERATION'") {
+			t.Errorf("langfuse lens must scope to GENERATION observations; got %q", sql)
+		}
+	}
+}
+
+// TestAimTop_LimitAndOrder proves the leaderboards bound + order the result.
+func TestAimTop_LimitAndOrder(t *testing.T) {
+	if !strings.Contains(aimTopModelsSQL(), "ORDER BY requests DESC LIMIT 12") {
+		t.Errorf("topModels must order by requests desc, limit %d", aimTopN)
+	}
+	if !strings.Contains(aimScoreNamesSQL(), "GROUP BY name ORDER BY n DESC LIMIT 12") {
+		t.Errorf("scoreNames must group+order+limit %d", aimTopN)
+	}
+	if !strings.Contains(aimEvalRunsSQL(), "ORDER BY last_ts DESC LIMIT 12") {
+		t.Errorf("evalRuns must order by last_ts desc, limit %d", aimTopN)
+	}
+}
+
+// TestAimScoreSeries_IntervalBound proves the (constant) bucket interval is
+// rendered into the score-trend series query and grouped/ordered by the bucket.
+func TestAimScoreSeries_IntervalBound(t *testing.T) {
+	for _, iv := range []string{"1 HOUR", "6 HOUR", "1 DAY"} {
+		s := aimScoreSeriesSQL(iv)
+		if !strings.Contains(s, "INTERVAL "+iv) || !strings.Contains(s, "GROUP BY ts ORDER BY ts") {
+			t.Errorf("score series must bucket by INTERVAL %s; got %q", iv, s)
+		}
+	}
+}
+
+// TestAimEvalLatencyGuarded proves the latency expressions guard end_time>start_time
+// so a zero/default end_time never contributes a garbage (negative) latency.
+func TestAimEvalLatencyGuarded(t *testing.T) {
+	if !strings.Contains(aimEvalTracesSQL(), "end_time > start_time") {
+		t.Errorf("eval traces latency must guard end_time>start_time; got %q", aimEvalTracesSQL())
+	}
+	if !strings.Contains(aimLangfuseLatencySQL(), "end_time > start_time") {
+		t.Errorf("langfuse latency must guard end_time>start_time; got %q", aimLangfuseLatencySQL())
+	}
+}
+
+// TestFillAimUsage reads a cloud_usage row into the KPI band across the numeric
+// variants the driver returns (uint64/int64/float64), honest zeros on an empty row.
+func TestFillAimUsage(t *testing.T) {
+	var empty aimUsage
+	fillAimUsage(&empty, map[string]any{})
+	if empty.Requests != 0 || empty.Tokens != 0 || empty.Models != 0 {
+		t.Fatalf("empty row must yield honest zeros; got %+v", empty)
+	}
+	var got aimUsage
+	fillAimUsage(&got, map[string]any{
+		"requests": uint64(274), "tokens": uint64(102597), "prompt_tokens": uint64(60000),
+		"completion_tokens": uint64(42597), "cost_cents": uint64(216), "models": uint64(42),
+	})
+	if got.Requests != 274 || got.Tokens != 102597 || got.CostCents != 216 || got.Models != 42 {
+		t.Fatalf("usage totals mis-parsed: %+v", got)
+	}
+}
+
+// TestFillAimEvals maps both eval halves (traces + scores) into the KPI band,
+// including the float latency/score columns (round()/avg() land as float64; a
+// Decimal-as-string is parsed).
+func TestFillAimEvals(t *testing.T) {
+	var e aimEvals
+	fillAimEvalTraces(&e, map[string]any{
+		"traces": uint64(1280), "runs": uint64(16), "datasets": uint64(4),
+		"models": uint64(6), "lat_avg": float64(842.5),
+	})
+	fillAimEvalScores(&e, map[string]any{
+		"scores": uint64(1280), "avg_value": "0.8125", "score_names": uint64(3),
+	})
+	if e.Traces != 1280 || e.Runs != 16 || e.Datasets != 4 || e.Models != 6 || e.LatencyMsAvg != 842.5 {
+		t.Fatalf("eval traces mis-parsed: %+v", e)
+	}
+	if e.Scores != 1280 || e.ScoreNames != 3 || e.AvgScore != 0.8125 { // string→float64 path
+		t.Fatalf("eval scores mis-parsed: %+v", e)
+	}
+}
+
+// TestAimParsers map datastore rows into the view-models and preserve order (the
+// SQL already ORDER BYs; a parser must not reorder or drop rows), with empty input
+// yielding an empty (non-nil) slice rather than a panic.
+func TestAimParsers(t *testing.T) {
+	models := aimModelsFromRows([]map[string]any{
+		{"model": "glm-5.2", "requests": uint64(154), "tokens": uint64(38966), "cost_cents": uint64(114)},
+		{"model": "deepseek-v4-flash", "requests": uint64(118), "tokens": uint64(61550), "cost_cents": uint64(101)},
+	})
+	if len(models) != 2 || models[0].Model != "glm-5.2" || models[1].Model != "deepseek-v4-flash" || models[0].Requests != 154 {
+		t.Fatalf("top models mis-parsed/reordered: %+v", models)
+	}
+	lf := lfModelsFromRows([]map[string]any{
+		{"model": "gpt-4o", "gens": uint64(42), "cost": float64(1.25)},
+	})
+	if len(lf) != 1 || lf[0].Model != "gpt-4o" || lf[0].Generations != 42 || lf[0].CostUsd != 1.25 {
+		t.Fatalf("langfuse models mis-parsed: %+v", lf)
+	}
+	names := scoreNamesFromRows([]map[string]any{
+		{"name": "accuracy", "n": uint64(320), "avg_value": float64(0.82), "min_value": float64(0), "max_value": float64(1)},
+	})
+	if len(names) != 1 || names[0].Name != "accuracy" || names[0].Count != 320 || names[0].AvgValue != 0.82 || names[0].MaxValue != 1 {
+		t.Fatalf("score names mis-parsed: %+v", names)
+	}
+	runs := evalRunsFromRows([]map[string]any{
+		{"run_name": "nightly-2026-07", "dataset": "gsm8k", "scores": uint64(200), "avg_value": float64(0.9), "last_ts": nil},
+	})
+	if len(runs) != 1 || runs[0].RunName != "nightly-2026-07" || runs[0].Dataset != "gsm8k" || runs[0].Scores != 200 || runs[0].AvgValue != 0.9 {
+		t.Fatalf("eval runs mis-parsed: %+v", runs)
+	}
+	// Empty input → empty (non-nil) slices, never a panic.
+	if got := scoreSeriesFromRows(nil); got == nil || len(got) != 0 {
+		t.Errorf("nil rows must yield empty slice, got %v", got)
+	}
+	if got := aimModelsFromRows(nil); got == nil || len(got) != 0 {
+		t.Errorf("nil rows must yield empty slice, got %v", got)
+	}
+}
@@ -26,8 +26,9 @@ import (

 // Routes registers the /v1/admin/audit* surface (SuperAdmin only).
 func Routes(app *zip.App, s *cloud.Service[core.State]) {
-	app.Get("/v1/admin/audit", core.Guard(s, Records))
-	app.Get("/v1/admin/audit/verify", core.Guard(s, Verify))
+	g := app.Group("/v1/admin")
+	g.Get("/audit", core.Guard(s, Records))
+	g.Get("/audit/verify", core.Guard(s, Verify))
 }

 // Records answers GET /v1/admin/audit from cloud's local tamper-evident store when
@@ -0,0 +1,197 @@
+// Copyright 2023-2026 Hanzo AI Inc. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package admin
+
+// blockStorage — GET /v1/admin/block-storage, the realtime DO block-storage fleet the
+// operator's Block Storage board (admin.hanzo.ai) watches to scale DO before it runs out.
+// (Named `block-storage`, not `storage`, so the operator's separate S3 object-buckets
+// view keeps /v1/admin/storage — two distinct storage concerns, two endpoints.)
+// Two REAL sources, honest by construction:
+//   - The FLEET inventory (count · total capacity · monthly cost · per-volume region +
+//     attachment) from the DigitalOcean API (the same DO_API_TOKEN client the finance
+//     dashboard already uses). DO exposes capacity + attachment but NOT fill %, so a
+//     volume's used/pct stay ABSENT (the console renders an honest "—", never a
+//     fabricated number).
+//   - The analytics DATASTORE's own fill from ClickHouse `system.disks` (the 200Gi PVC
+//     the datastore fork mounts) — total/free space over the SAME shared client
+//     (aiobject.DatastoreQuery) the analytics + compute lenses read, no second
+//     connection. This is THE number the operator scales on.
+//
+// SUPERADMIN ONLY (the s.guard wrap in admin.go): a cross-tenant infra read, all-orgs.
+// admin holds NO storage state — it only reads DO + the datastore. DO unconfigured →
+// empty fleet; datastore not connected → no datastore card. Never a fabricated fleet.
+
+import (
+	"context"
+
+	aiobject "github.com/hanzoai/ai/object"
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/admin/core"
+	"github.com/hanzoai/cloud/clients/admin/digitalocean"
+	"github.com/zap-proto/zip"
+)
+
+// doBlockUsdPerGiB is DO block storage's list price ($0.10/GiB/mo) — the fleet cost
+// line for the ops budget when DO doesn't itemize per-volume spend.
+const doBlockUsdPerGiB = 0.10
+
+// bytesPerGiB converts system.disks bytes (UInt64) → GiB.
+const bytesPerGiB = 1024 * 1024 * 1024
+
+// storageVolume mirrors the console StorageVolume. UsedGiB/Pct are POINTERS so an
+// absent fill serializes as JSON null (→ the console's honest "—"), distinct from a
+// real 0%.
+type storageVolume struct {
+	ID       string   `json:"id"`
+	Name     string   `json:"name"`
+	Region   string   `json:"region"`
+	SizeGiB  int      `json:"sizeGiB"`
+	UsedGiB  *float64 `json:"usedGiB"`
+	Pct      *float64 `json:"pct"`
+	Attached bool     `json:"attached"`
+	Service  string   `json:"service"`
+}
+
+// storageFleet is the roll-up: real count/capacity/cost; fleet fill absent (DO gives
+// no per-volume fill, so there is no honest fleet-wide used total to report).
+type storageFleet struct {
+	Count      int      `json:"count"`
+	TotalGiB   int      `json:"totalGiB"`
+	UsedGiB    *float64 `json:"usedGiB"`
+	Pct        *float64 `json:"pct"`
+	MonthlyUsd int      `json:"monthlyUsd"`
+}
+
+// datastoreVolume is the analytics backend's own volume, fill REAL from system.disks.
+type datastoreVolume struct {
+	Name    string  `json:"name"`
+	Mount   string  `json:"mount"`
+	SizeGiB int     `json:"sizeGiB"`
+	UsedGiB float64 `json:"usedGiB"`
+	Pct     float64 `json:"pct"`
+}
+
+// storageAlert flags a near-full volume (only the datastore carries a real fill today,
+// so alerts are datastore-derived until a per-volume filesystem source is wired).
+type storageAlert struct {
+	Volume string  `json:"volume"`
+	Pct    float64 `json:"pct"`
+	Level  string  `json:"level"`
+}
+
+// storageSnapshot is the whole board payload the console normalizes.
+type storageSnapshot struct {
+	Fleet     storageFleet     `json:"fleet"`
+	Datastore *datastoreVolume `json:"datastore"`
+	Volumes   []storageVolume  `json:"volumes"`
+	Alerts    []storageAlert   `json:"alerts"`
+}
+
+// blockStorage answers GET /v1/admin/block-storage. SuperAdmin only. Each source
+// degrades independently — a DO outage still returns the real datastore fill, and v.v.
+func blockStorage(s *cloud.Service[core.State], c *zip.Ctx) error {
+	ctx := c.Context()
+	vols, _ := s.State.DO.Volumes(ctx) // honest empty on not-configured / unreachable
+	fill := datastoreFill(ctx)         // nil unless system.disks answered
+	return core.OK(c, buildStorageSnapshot(vols, fill))
+}
+
+// buildStorageSnapshot assembles the board payload (PURE — unit-tested). It folds the
+// DO inventory into the fleet totals + per-volume rows (fill absent), attaches the real
+// datastore card, and derives a near-full alert from the datastore fill. No fabrication:
+// a volume's fill is left nil (DO gives none), and the datastore card is present only
+// when system.disks actually answered.
+func buildStorageSnapshot(vols []digitalocean.Volume, fill *datastoreVolume) storageSnapshot {
+	out := make([]storageVolume, 0, len(vols))
+	totalGiB := 0
+	for _, v := range vols {
+		out = append(out, storageVolume{
+			ID:       v.ID,
+			Name:     v.Name,
+			Region:   v.Region,
+			SizeGiB:  v.SizeGiB,
+			Attached: len(v.DropletIDs) > 0,
+		})
+		totalGiB += v.SizeGiB
+	}
+	alerts := make([]storageAlert, 0, 1)
+	if fill != nil {
+		if lvl := alertLevel(fill.Pct); lvl != "" {
+			alerts = append(alerts, storageAlert{Volume: fill.Name, Pct: fill.Pct, Level: lvl})
+		}
+	}
+	return storageSnapshot{
+		Fleet: storageFleet{
+			Count:      len(vols),
+			TotalGiB:   totalGiB,
+			MonthlyUsd: int(float64(totalGiB)*doBlockUsdPerGiB + 0.5),
+		},
+		Datastore: fill,
+		Volumes:   out,
+		Alerts:    alerts,
+	}
+}
+
+// alertLevel thresholds a fill %: critical ≥ 90, warn ≥ 80, else none (PURE, tested).
+func alertLevel(pct float64) string {
+	switch {
+	case pct >= 90:
+		return "critical"
+	case pct >= 80:
+		return "warn"
+	default:
+		return ""
+	}
+}
+
+// datastoreFill reads the analytics datastore's own volume usage from ClickHouse
+// `system.disks` (the largest disk by capacity is the data volume — the 200Gi PVC).
+// Returns nil when the datastore isn't connected or the query fails (honest — the
+// console shows no datastore card, never a fabricated fill).
+func datastoreFill(ctx context.Context) *datastoreVolume {
+	if !aiobject.DatastoreEnabled() {
+		return nil
+	}
+	rows, err := aiobject.DatastoreQuery(ctx,
+		"SELECT name, path, total_space, free_space FROM system.disks ORDER BY total_space DESC LIMIT 1")
+	if err != nil || len(rows) == 0 {
+		return nil
+	}
+	return datastoreFillFromRow(rows[0])
+}
+
+// datastoreFillFromRow maps a system.disks row → the datastore card (PURE, tested).
+// nil when the disk reports no capacity (an unusable read, not a fabricated 0%).
+func datastoreFillFromRow(r map[string]any) *datastoreVolume {
+	total := float64(chInt64(r["total_space"]))
+	if total <= 0 {
+		return nil
+	}
+	free := float64(chInt64(r["free_space"]))
+	used := total - free
+	if used < 0 {
+		used = 0
+	}
+	return &datastoreVolume{
+		Name:    chStr(r["name"]),
+		Mount:   chStr(r["path"]),
+		SizeGiB: int(total / bytesPerGiB),
+		UsedGiB: round1(used / bytesPerGiB),
+		Pct:     round1(used / total * 100),
+	}
+}
+
+// round1 rounds to one decimal (used/pct read cleanly; not a scientific quantity).
+func round1(x float64) float64 { return float64(int(x*10+0.5)) / 10 }
@@ -0,0 +1,130 @@
+// Copyright 2023-2026 Hanzo AI Inc. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package admin
+
+import (
+	"testing"
+
+	"github.com/hanzoai/cloud/clients/admin/digitalocean"
+)
+
+// The DO inventory folds into fleet totals + rows, and per-volume fill stays ABSENT
+// (DO exposes no fill) so the console renders an honest "—", never a fabricated 0%.
+func TestBuildStorageSnapshotFleet(t *testing.T) {
+	vols := []digitalocean.Volume{
+		{ID: "a", Name: "pvc-a", Region: "sfo3", SizeGiB: 200, DropletIDs: []int{1}},
+		{ID: "b", Name: "pvc-b", Region: "nyc1", SizeGiB: 100, DropletIDs: nil},
+		{ID: "c", Name: "pvc-c", Region: "sfo3", SizeGiB: 50, DropletIDs: []int{2, 3}},
+	}
+	snap := buildStorageSnapshot(vols, nil)
+
+	if snap.Fleet.Count != 3 {
+		t.Fatalf("count = %d, want 3", snap.Fleet.Count)
+	}
+	if snap.Fleet.TotalGiB != 350 {
+		t.Fatalf("totalGiB = %d, want 350", snap.Fleet.TotalGiB)
+	}
+	// 350 GiB * $0.10 = $35.
+	if snap.Fleet.MonthlyUsd != 35 {
+		t.Fatalf("monthlyUsd = %d, want 35", snap.Fleet.MonthlyUsd)
+	}
+	if snap.Fleet.UsedGiB != nil || snap.Fleet.Pct != nil {
+		t.Fatalf("fleet fill must be absent (DO gives none); got used=%v pct=%v", snap.Fleet.UsedGiB, snap.Fleet.Pct)
+	}
+	if len(snap.Volumes) != 3 {
+		t.Fatalf("volumes = %d, want 3", len(snap.Volumes))
+	}
+	// Attachment derives from droplet_ids; fill is absent per row.
+	if !snap.Volumes[0].Attached || snap.Volumes[1].Attached || !snap.Volumes[2].Attached {
+		t.Fatalf("attachment wrong: %+v", snap.Volumes)
+	}
+	for _, v := range snap.Volumes {
+		if v.UsedGiB != nil || v.Pct != nil {
+			t.Fatalf("volume %s fill must be absent, got used=%v pct=%v", v.ID, v.UsedGiB, v.Pct)
+		}
+	}
+	if snap.Datastore != nil {
+		t.Fatalf("datastore must be nil when no fill was read; got %+v", snap.Datastore)
+	}
+	if len(snap.Alerts) != 0 {
+		t.Fatalf("no alerts without a datastore fill; got %v", snap.Alerts)
+	}
+}
+
+// A near-full datastore raises exactly one alert; a healthy one raises none.
+func TestBuildStorageSnapshotDatastoreAlert(t *testing.T) {
+	full := &datastoreVolume{Name: "default", Mount: "/var/lib/hanzo-datastore", SizeGiB: 196, UsedGiB: 178, Pct: 91}
+	snap := buildStorageSnapshot(nil, full)
+	if snap.Datastore == nil || snap.Datastore.Pct != 91 {
+		t.Fatalf("datastore card missing/wrong: %+v", snap.Datastore)
+	}
+	if len(snap.Alerts) != 1 || snap.Alerts[0].Level != "critical" || snap.Alerts[0].Volume != "default" {
+		t.Fatalf("expected one critical alert, got %+v", snap.Alerts)
+	}
+
+	healthy := &datastoreVolume{Name: "default", SizeGiB: 196, UsedGiB: 13, Pct: 7}
+	if a := buildStorageSnapshot(nil, healthy).Alerts; len(a) != 0 {
+		t.Fatalf("a 7%%-full datastore must raise no alert, got %+v", a)
+	}
+}
+
+func TestAlertLevel(t *testing.T) {
+	cases := []struct {
+		pct  float64
+		want string
+	}{
+		{0, ""}, {7, ""}, {79.9, ""}, {80, "warn"}, {89.9, "warn"}, {90, "critical"}, {99, "critical"},
+	}
+	for _, c := range cases {
+		if got := alertLevel(c.pct); got != c.want {
+			t.Fatalf("alertLevel(%v) = %q, want %q", c.pct, got, c.want)
+		}
+	}
+}
+
+// system.disks bytes → GiB + pct, matching the live datastore (13.5G used of ~196G ≈ 7%).
+func TestDatastoreFillFromRow(t *testing.T) {
+	// total ≈ 196.6 GiB, free ≈ 183.1 GiB → used ≈ 13.5 GiB → ~6.9%.
+	gib := float64(bytesPerGiB) // a variable → runtime math (a float→int const conversion won't compile)
+	total := int64(196.6 * gib)
+	used := int64(13.5 * gib)
+	row := map[string]any{
+		"name":        "default",
+		"path":        "/var/lib/hanzo-datastore",
+		"total_space": uint64(total),
+		"free_space":  uint64(total - used),
+	}
+	d := datastoreFillFromRow(row)
+	if d == nil {
+		t.Fatal("expected a datastore fill, got nil")
+	}
+	if d.Name != "default" || d.Mount != "/var/lib/hanzo-datastore" {
+		t.Fatalf("name/mount wrong: %+v", d)
+	}
+	if d.SizeGiB != 196 {
+		t.Fatalf("sizeGiB = %d, want 196", d.SizeGiB)
+	}
+	if d.UsedGiB < 13.4 || d.UsedGiB > 13.6 {
+		t.Fatalf("usedGiB = %v, want ~13.5", d.UsedGiB)
+	}
+	if d.Pct < 6.5 || d.Pct > 7.5 {
+		t.Fatalf("pct = %v, want ~7", d.Pct)
+	}
+
+	// A disk that reports no capacity is an unusable read → nil (never a fake 0%).
+	if datastoreFillFromRow(map[string]any{"total_space": uint64(0)}) != nil {
+		t.Fatal("zero-capacity disk must yield nil, not a fabricated 0%")
+	}
+}
@@ -203,7 +203,7 @@ func newCockpitFakes(t *testing.T) *cockpitFakes {
 		}
 	}))

-	_, s, fa := mountSvc(t, f.iam.URL, f.commerce.URL, "")
+	_, s, fa := mountService(t, f.iam.URL, f.commerce.URL, "")
 	f.service = s
 	f.do = func(method, path string, hdr map[string]string, body string) (*http.Response, []byte) {
 		t.Helper()
@@ -33,6 +33,7 @@ import (
 	"time"

 	"github.com/hanzoai/cloud/clients/admin/money"
+	"github.com/hanzoai/cloud/clients/commerceinproc"
 )

 // errUnconfigured marks a write (Deposit) attempted against an unwired commerce.
@@ -45,12 +46,17 @@ type Client struct {
 	http  *http.Client
 }

-// New builds a commerce client for base + admin S2S token.
+// New builds a commerce client for base + admin S2S token. The HTTP client uses the
+// commerceinproc self-routing transport: when commerce is CO-RESIDENT (base is the
+// commerce.inproc placeholder) it dispatches in-process — a plain http.Client would
+// instead DNS-resolve "commerce.inproc" and fail "no such host", silently breaking the
+// admin cost/finance god-view. For a split-deploy (a real commerce URL) it falls
+// through to plain HTTP unchanged.
 func New(base, token string) *Client {
 	return &Client{
 		base:  strings.TrimRight(strings.TrimSpace(base), "/"),
 		token: strings.TrimSpace(token),
-		http:  &http.Client{Timeout: 15 * time.Second},
+		http:  commerceinproc.Client(15 * time.Second),
 	}
 }

@@ -295,6 +301,18 @@ func (c *Client) Deposit(ctx context.Context, subject string, amount money.Cents
 	return out, nil
 }

+// CreateCreditGrant forwards a credit-grant request verbatim to commerce's
+// mint-gated POST /v1/billing/credit-grants (CreateCreditGrant), authenticated
+// by the admin service token, with subject as the target-org namespace selector.
+// Commerce is the sole credit-grant ledger; this relays its contract untouched
+// (the raw response is returned to the caller) so the admin surface stays thin.
+func (c *Client) CreateCreditGrant(ctx context.Context, subject string, body []byte, idempotencyKey string) ([]byte, error) {
+	if !c.Ready() {
+		return nil, errUnconfigured
+	}
+	return c.post(ctx, "/v1/billing/credit-grants", subject, body, idempotencyKey)
+}
+
 // post performs one admin-authenticated commerce POST (JSON body) and returns the
 // raw response. The admin S2S service token is the bearer and X-Org-Id=<subject>
 // the per-org namespace selector commerce's EdgeAuth trusts only after verifying
@@ -332,6 +350,48 @@ func (c *Client) post(ctx context.Context, path, subject string, body []byte, id
 	return respBody, nil
 }

+// Forward proxies an admin-authenticated request to commerce VERBATIM and returns
+// the raw body + status. It is the ONE seam a SuperAdmin surface drives commerce's
+// own endpoints through — the platform plan-promo config (/v1/platform/promo) and a
+// per-org spend-alert override (/v1/billing/spend-alerts) — without a typed method
+// per shape. subject is the X-Org-Id namespace selector (the target org for a cap
+// override, or the admin org for platform config); body is nil for GET/DELETE. The
+// status is returned so the caller surfaces commerce's OWN verdict (400 validation,
+// 403, 404) instead of flattening every non-2xx into one code.
+func (c *Client) Forward(ctx context.Context, method, path, subject string, body []byte) ([]byte, int, error) {
+	if !c.Ready() {
+		return nil, 0, errUnconfigured
+	}
+	var rdr io.Reader
+	if body != nil {
+		rdr = bytes.NewReader(body)
+	}
+	req, err := http.NewRequestWithContext(ctx, method, c.base+path, rdr)
+	if err != nil {
+		return nil, 0, err
+	}
+	req.Header.Set("Accept", "application/json")
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	if c.token != "" {
+		req.Header.Set("Authorization", "Bearer "+c.token)
+	}
+	if subject != "" {
+		req.Header.Set("X-Org-Id", subject)
+	}
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return nil, 0, fmt.Errorf("commerce unreachable: %w", err)
+	}
+	defer resp.Body.Close()
+	raw, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return nil, resp.StatusCode, err
+	}
+	return raw, resp.StatusCode, nil
+}
+
 // get performs one admin-authenticated commerce GET and returns the raw body.
 func (c *Client) get(ctx context.Context, path string, q url.Values, subject string) ([]byte, error) {
 	u := c.base + path
@@ -0,0 +1,220 @@
+// Copyright 2023-2026 Hanzo AI Inc. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package core
+
+// warehouse — the ONE-copy datastore-read kernel the billing FLEET views
+// (metrics/invoices/subscriptions) compose. They read commerce.events — the
+// single warehouse table the commerce analytics collector lands every
+// customer-activity event in (subscription/invoice/usage lifecycle) — over the
+// SAME shared client (aiobject.DatastoreQuery) the o11y/compute/analytics lenses
+// already use, no second connection. This mirrors compute.go's row-coercers and
+// EXISTS-TABLE probe, hoisted here so the three sibling domains share ONE copy
+// instead of each re-deriving it (DRY; the admin-package o11y/compute keep their
+// own private copies as the read template).
+//
+// Every read is honest by construction: no datastore connected, or the events
+// table not provisioned (the emitter is still being wired) → the real empty
+// aggregate, NEVER a fabricated fleet. admin READS only; it owns and creates NO
+// table (the collector owns commerce.events). Time bounds are POSITIONAL
+// parameters (never interpolated) so the reads are injection-safe; money is USD
+// cents; timestamps are RFC3339.
+
+import (
+	"context"
+	"strconv"
+	"strings"
+	"time"
+
+	aiobject "github.com/hanzoai/ai/object"
+)
+
+// BillingEventsTable is the collector-owned warehouse table the commerce
+// customer-activity emitters land in (events/client.go → analytics-collector →
+// commerce.events). admin only READS it (never creates it — the collector owns
+// its writes), exactly as o11y reads hanzo.cloud_usage.
+const BillingEventsTable = "commerce.events"
+
+// Canonical customer-activity event names — the CONTRACT with the commerce
+// emitters (events/client.go). These are server-side constants (never user
+// input), so rendering them into an IN (...) list is injection-safe.
+const (
+	EvSubscriptionCreated     = "subscription_created"
+	EvSubscriptionRenewed     = "subscription_renewed"
+	EvSubscriptionPlanChanged = "subscription_plan_changed"
+	EvSubscriptionCanceled    = "subscription_canceled"
+	EvInvoiceFinalized        = "invoice_finalized"
+	EvInvoicePaid             = "invoice_paid"
+	EvInvoiceVoid             = "invoice_void"
+	EvAPIUsageDebit           = "api_usage_debit"
+)
+
+// SubscriptionEvents / InvoiceEvents are the lifecycle sets each fleet view
+// folds over (latest-event-wins per entity). Closed server-side constants.
+var (
+	SubscriptionEvents = []string{EvSubscriptionCreated, EvSubscriptionRenewed, EvSubscriptionPlanChanged, EvSubscriptionCanceled}
+	InvoiceEvents      = []string{EvInvoiceFinalized, EvInvoicePaid, EvInvoiceVoid}
+)
+
+// WarehouseReady reports whether the shared datastore ledger is connected, the
+// gate every fleet read checks first (honest-empty when false).
+func WarehouseReady() bool { return aiobject.DatastoreEnabled() }
+
+// BillingEventsReady reports whether the warehouse is connected AND the
+// collector's commerce.events table is provisioned — the two-part gate every
+// billing fleet view opens with, so an unwired collector degrades to an honest
+// empty aggregate rather than an error.
+func BillingEventsReady(ctx context.Context) bool {
+	return aiobject.DatastoreEnabled() && CHTableExists(ctx, BillingEventsTable)
+}
+
+// CHTableExists probes the datastore for a table's presence. The name is a
+// package constant (never user input), so EXISTS TABLE is safe. Any error →
+// false (honest "not available yet"), mirroring compute.computeTableExists.
+func CHTableExists(ctx context.Context, qualified string) bool {
+	rows, err := aiobject.DatastoreQuery(ctx, "EXISTS TABLE "+qualified)
+	if err != nil || len(rows) == 0 {
+		return false
+	}
+	for _, v := range rows[0] {
+		return CHInt64(v) == 1
+	}
+	return false
+}
+
+// SQLInList renders a set of server-side-constant strings as a datastore string
+// list ('a','b',…) for an IN (...) clause. ONLY for closed constant sets (the
+// event-name enums above) — never for user input; positional args carry all
+// caller-derived values.
+func SQLInList(vals []string) string {
+	quoted := make([]string, len(vals))
+	for i, v := range vals {
+		quoted[i] = "'" + v + "'"
+	}
+	return strings.Join(quoted, ",")
+}
+
+// WarehouseSince maps the ?range enum (24h|7d|30d, default 30d) to a lower time
+// bound, mirroring compute.computeSince so the fleet views share ONE window
+// grammar.
+func WarehouseSince(rangeLabel string) time.Time {
+	now := time.Now().UTC()
+	switch strings.TrimSpace(rangeLabel) {
+	case "24h":
+		return now.Add(-24 * time.Hour)
+	case "7d":
+		return now.Add(-7 * 24 * time.Hour)
+	default:
+		return now.Add(-30 * 24 * time.Hour)
+	}
+}
+
+// CHTimeLit formats a time as a datastore DateTime literal (UTC), bound as a
+// POSITIONAL string arg (never interpolated).
+func CHTimeLit(t time.Time) string { return t.UTC().Format("2006-01-02 15:04:05") }
+
+// CHFirstRow returns the first row or an empty map (never nil), so a parser
+// reads honest zeros from an empty result instead of panicking.
+func CHFirstRow(rows []map[string]any) map[string]any {
+	if len(rows) == 0 {
+		return map[string]any{}
+	}
+	return rows[0]
+}
+
+// ── map[string]any coercers (the DatastoreQuery row shape) ───────────────────
+//
+// The datastore driver decodes each column to its native Go type (uint64 for
+// count()/sum(UInt*), float64 for round()/JSON numerics, time.Time for DateTime,
+// string for String); these accept those natives so a driver/transport change
+// can't crash a read. Twins of the admin-package compute.go coercers.
+
+func CHInt64(v any) int64 {
+	switch n := v.(type) {
+	case int:
+		return int64(n)
+	case int64:
+		return n
+	case int32:
+		return int64(n)
+	case uint:
+		return int64(n)
+	case uint64:
+		return int64(n)
+	case uint32:
+		return int64(n)
+	case uint16:
+		return int64(n)
+	case uint8:
+		return int64(n)
+	case float64:
+		return int64(n)
+	case float32:
+		return int64(n)
+	case string:
+		f, err := strconv.ParseFloat(strings.TrimSpace(n), 64)
+		if err != nil {
+			return 0
+		}
+		return int64(f)
+	default:
+		return 0
+	}
+}
+
+func CHFloat64(v any) float64 {
+	switch n := v.(type) {
+	case float64:
+		return n
+	case float32:
+		return float64(n)
+	case int:
+		return float64(n)
+	case int64:
+		return float64(n)
+	case int32:
+		return float64(n)
+	case uint64:
+		return float64(n)
+	case uint32:
+		return float64(n)
+	case string:
+		f, err := strconv.ParseFloat(strings.TrimSpace(n), 64)
+		if err != nil {
+			return 0
+		}
+		return f
+	default:
+		return 0
+	}
+}
+
+func CHStr(v any) string {
+	if s, ok := v.(string); ok {
+		return s
+	}
+	return ""
+}
+
+// CHTime coerces a datastore DateTime (time.Time) to an RFC3339 UTC string.
+func CHTime(v any) string {
+	switch t := v.(type) {
+	case time.Time:
+		return t.UTC().Format(time.RFC3339)
+	case string:
+		return t
+	default:
+		return ""
+	}
+}
@@ -0,0 +1,62 @@
+package admin
+
+import (
+	"encoding/json"
+	"strings"
+
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/audit"
+	"github.com/hanzoai/cloud/clients/admin/core"
+	"github.com/zap-proto/zip"
+)
+
+// createCreditGrant is the admin mint surface: POST /v1/admin/credit-grants.
+//
+// SuperAdmin ONLY (wired through core.Guard). It does NOT mint in-process — it
+// forwards the request VERBATIM to commerce's already-mint-gated
+// POST /v1/billing/credit-grants (middleware.Mint → PlatformOnly), authenticated
+// by COMMERCE_SERVICE_TOKEN and scoped to the target org, and writes ONE
+// tamper-evident compliance record. Commerce stays the single credit-grant ledger;
+// this is a thin, audited relay so there is exactly one place credit is minted.
+//
+// The body is commerce's own CreateCreditGrant contract; the only field this layer
+// reads is the target org (`org`, or `user` as the org-pool alias) to select the
+// per-org namespace commerce's EdgeAuth trusts after verifying the service token.
+func createCreditGrant(s *cloud.Service[core.State], c *zip.Ctx) error {
+	if !s.State.Commerce.Ready() {
+		return core.Fail(c, "commerce is not configured on this deployment")
+	}
+
+	var req map[string]any
+	if err := c.Bind(&req); err != nil {
+		return core.Fail(c, "invalid request body")
+	}
+
+	org, _ := req["org"].(string)
+	if strings.TrimSpace(org) == "" {
+		org, _ = req["user"].(string)
+	}
+	org = strings.TrimSpace(org)
+	if org == "" {
+		return core.Fail(c, "org is required")
+	}
+	idempotencyKey, _ := req["idempotencyKey"].(string)
+
+	body, err := json.Marshal(req)
+	if err != nil {
+		return core.Fail(c, "invalid request body")
+	}
+
+	raw, err := s.State.Commerce.CreateCreditGrant(c.Context(), org, body, idempotencyKey)
+	if err != nil {
+		core.EmitAudit(s, c, "admin.customer.credit-grant", "credit-grant", org,
+			req, map[string]any{"error": err.Error()},
+			audit.Outcome{Result: "error", Status: 502, Reason: "credit-grant failed"})
+		return core.Fail(c, "credit-grant failed: "+err.Error())
+	}
+
+	core.EmitAudit(s, c, "admin.customer.credit-grant", "credit-grant", org,
+		nil, json.RawMessage(raw),
+		audit.Outcome{Result: "success", Status: 200})
+	return core.OK(c, json.RawMessage(raw))
+}
@@ -10,11 +10,12 @@ import (
 // precedes the :org param route; the write actions are POST (distinct method), so none
 // collide. The grants ledger + the org-in-body issue-grant share the ONE credit path.
 func Routes(app *zip.App, s *cloud.Service[core.State]) {
-	app.Get("/v1/admin/customers", core.Guard(s, Customers))
-	app.Get("/v1/admin/customers/:org", core.Guard(s, CustomerDetail))
-	app.Post("/v1/admin/customers/:org/credit", core.Guard(s, GrantCredit))
-	app.Get("/v1/admin/grants", core.Guard(s, Grants))
-	app.Post("/v1/admin/grants", core.Guard(s, IssueGrant))
-	app.Post("/v1/admin/customers/:org/suspend", core.Guard(s, SuspendCustomer))
-	app.Post("/v1/admin/customers/:org/reactivate", core.Guard(s, ReactivateCustomer))
+	g := app.Group("/v1/admin")
+	g.Get("/customers", core.Guard(s, Customers))
+	g.Get("/customers/:org", core.Guard(s, CustomerDetail))
+	g.Post("/customers/:org/credit", core.Guard(s, GrantCredit))
+	g.Get("/grants", core.Guard(s, Grants))
+	g.Post("/grants", core.Guard(s, IssueGrant))
+	g.Post("/customers/:org/suspend", core.Guard(s, SuspendCustomer))
+	g.Post("/customers/:org/reactivate", core.Guard(s, ReactivateCustomer))
 }
@@ -142,6 +142,69 @@ func (c *Client) History(ctx context.Context, perPage int) ([]Entry, error) {
 	return out, nil
 }

+// Volume is one DO block-storage volume: capacity + attachment + region. DO's API
+// gives capacity and which droplets a volume is attached to, but NOT fill % — the
+// caller enriches fill only where a filesystem source (the datastore's own
+// system.disks) reports it, and renders an honest "—" everywhere else.
+type Volume struct {
+	ID         string
+	Name       string
+	Region     string
+	SizeGiB    int
+	DropletIDs []int
+}
+
+// volumeWire is the raw DO /v2/volumes row.
+type volumeWire struct {
+	ID            string `json:"id"`
+	Name          string `json:"name"`
+	SizeGigabytes int    `json:"size_gigabytes"`
+	Region        struct {
+		Slug string `json:"slug"`
+	} `json:"region"`
+	DropletIDs []int `json:"droplet_ids"`
+}
+
+// Volumes lists ALL block-storage volumes across the account, following DO's
+// page-number pagination (200/page, a hard 25-page cap so a runaway can never loop).
+// The fleet inventory (count, capacity, monthly cost) is real; per-volume fill is NOT
+// exposed by DO and stays absent (honest) until a filesystem source reports it.
+func (c *Client) Volumes(ctx context.Context) ([]Volume, error) {
+	if !c.Ready() {
+		return nil, fmt.Errorf("DO_API_TOKEN not configured")
+	}
+	var out []Volume
+	for page := 1; page <= 25; page++ {
+		body, err := c.get(ctx, "/v2/volumes?per_page=200&page="+strconv.Itoa(page))
+		if err != nil {
+			return nil, err
+		}
+		var w struct {
+			Volumes []volumeWire `json:"volumes"`
+			Meta    struct {
+				Total int `json:"total"`
+			} `json:"meta"`
+		}
+		if err := json.Unmarshal(body, &w); err != nil {
+			return nil, fmt.Errorf("do volumes decode: %w", err)
+		}
+		for _, v := range w.Volumes {
+			out = append(out, Volume{
+				ID:         v.ID,
+				Name:       v.Name,
+				Region:     v.Region.Slug,
+				SizeGiB:    v.SizeGigabytes,
+				DropletIDs: v.DropletIDs,
+			})
+		}
+		// Stop on the last (short) page, or once we've collected the reported total.
+		if len(w.Volumes) < 200 || (w.Meta.Total > 0 && len(out) >= w.Meta.Total) {
+			break
+		}
+	}
+	return out, nil
+}
+
 // get performs one token-authenticated DO GET and returns the raw body.
 func (c *Client) get(ctx context.Context, path string) ([]byte, error) {
 	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.base+path, nil)
@@ -28,16 +28,17 @@ var errUnconfigured = errors.New("not configured")

 // Routes registers the finance dashboard (SuperAdmin only).
 func Routes(app *zip.App, s *cloud.Service[core.State]) {
-	app.Get("/v1/admin/finance", core.Guard(s, Finance))
+	g := app.Group("/v1/admin")
+	g.Get("/finance", core.Guard(s, Finance))
 	// One-time commerce→finance balance cutover (SuperAdmin only). Idempotent per org.
-	app.Post("/v1/admin/finance/backfill", core.Guard(s, Backfill))
+	g.Post("/finance/backfill", core.Guard(s, Backfill))
 	// Fund an ARBITRARY subject's native wallet — an org pool or a human ("hanzo/z").
 	// SuperAdmin only; additive (grants stack).
-	app.Post("/v1/admin/finance/deposit", core.Guard(s, Deposit))
+	g.Post("/finance/deposit", core.Guard(s, Deposit))
 	// Per-provider upstream credit ledger + usage funding split (multi-provider
 	// credit-management). Same SuperAdmin guard, same cloud_usage warehouse.
-	app.Get("/v1/admin/providers/credit", core.Guard(s, ProvidersCredit))
-	app.Get("/v1/admin/usage/funding", core.Guard(s, UsageFunding))
+	g.Get("/providers/credit", core.Guard(s, ProvidersCredit))
+	g.Get("/usage/funding", core.Guard(s, UsageFunding))
 }

 // FinanceData is the full /v1/admin/finance aggregate.
@@ -15,7 +15,7 @@ import (

 // The finance PURE-math derivation tests (ComputeFinance / AvgDailyBurnCents) live with
 // the handler in clients/admin/finance. These are the INTEGRATION tests that drive GET
-// /v1/admin/finance through the shared admin mount harness (mountSvc + fake IAM/commerce/DO).
+// /v1/admin/finance through the shared admin mount harness (mountService + fake IAM/commerce/DO).

 // newFakeDO serves the DO billing API with fixed decimal-dollar strings so the
 // finance aggregation is deterministic. account_balance is NEGATIVE (credit held).
@@ -49,7 +49,7 @@ func TestFinance_RealAggregation(t *testing.T) {
 	do := newFakeDO()
 	defer do.Close()

-	doReq, s, _ := mountSvc(t, iam.server.URL, commerce.URL, "")
+	doReq, s, _ := mountService(t, iam.server.URL, commerce.URL, "")
 	s.State.DO = digitalocean.NewWithBase(do.URL, "test-do-token") // configured DO client
 	admin := map[string]string{
 		"X-User-IsAdmin": "true", "X-Org-Id": "admin",
@@ -151,7 +151,7 @@ func TestFinance_HonestUnconfiguredDO(t *testing.T) {
 	commerce := newFakeCommerceFinance()
 	defer commerce.Close()

-	doReq, _, _ := mountSvc(t, iam.server.URL, commerce.URL, "") // s.do already has empty token → unconfigured
+	doReq, _, _ := mountService(t, iam.server.URL, commerce.URL, "") // s.do already has empty token → unconfigured
 	admin := map[string]string{"X-User-IsAdmin": "true", "X-Org-Id": "admin"}

 	resp, body := doReq("GET", "/v1/admin/finance", admin)
@@ -212,7 +212,7 @@ func TestFinance_RevenueSourceDown_NoFabrication(t *testing.T) {
 	defer commerce.Close()

 	// IAM points nowhere reachable → listOrgs errors; commerce /v1/costs still 200s.
-	doReq, _, _ := mountSvc(t, "http://127.0.0.1:0", commerce.URL, "")
+	doReq, _, _ := mountService(t, "http://127.0.0.1:0", commerce.URL, "")
 	admin := map[string]string{"X-User-IsAdmin": "true", "X-Org-Id": "admin"}

 	resp, body := doReq("GET", "/v1/admin/finance", admin)
@@ -0,0 +1,152 @@
+// Package invoices is the fleet INVOICE view (/v1/admin/invoices) — every issued
+// invoice across every tenant: number, org, amount, status, issue + due date, plus the
+// id a future detail view fetches /v1/billing/invoices/:id with. SuperAdmin only
+// (core.Guard).
+//
+// It reads the ONE shared warehouse (commerce.events) — the table the commerce
+// analytics collector lands every invoice-lifecycle event in — over the SAME client
+// (aiobject.DatastoreQuery) the o11y/compute lenses use, with ZERO per-org fan-out:
+// one GROUP BY resolves each invoice's LATEST lifecycle state (argMax by timestamp),
+// so the whole fleet is one query, not N per-org commerce reads. Honest by
+// construction: no datastore connected or the collector's table not provisioned yet →
+// the real empty list, never a fabricated row. Optional ?org= scopes to one tenant,
+// ?status= filters the LATEST status, ?limit= caps the list.
+package invoices
+
+import (
+	"sort"
+	"strconv"
+	"strings"
+
+	aiobject "github.com/hanzoai/ai/object"
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/admin/core"
+	"github.com/zap-proto/zip"
+)
+
+// defaultLimit caps the fleet invoice list when the caller sends none.
+const defaultLimit = 500
+
+// InvoiceRow is one row of GET /v1/admin/invoices — an issued invoice at a glance,
+// tagged with its owning org. Money is USD cents; timestamps are RFC3339 strings.
+type InvoiceRow struct {
+	ID          string `json:"id"`
+	Number      string `json:"number"`
+	Org         string `json:"org"`
+	Display     string `json:"display"`
+	Status      string `json:"status"`
+	AmountCents int64  `json:"amountCents"`
+	Currency    string `json:"currency"`
+	Issued      string `json:"issued"`
+	Due         string `json:"due"`
+}
+
+// Invoices answers GET /v1/admin/invoices.
+//
+//	GET /v1/admin/invoices?org=&status=&limit=
+func Invoices(s *cloud.Service[core.State], c *zip.Ctx) error {
+	ctx := c.Context()
+	status := strings.ToLower(strings.TrimSpace(c.Query("status")))
+	wantOrg := strings.TrimSpace(c.Query("org"))
+	limit := parseLimit(c.Query("limit"))
+
+	// Honest-empty when the warehouse is not connected or the collector's events
+	// table is not provisioned yet (the emitter is still being wired).
+	if !core.BillingEventsReady(ctx) {
+		return core.OKList(c, []InvoiceRow{}, 0)
+	}
+
+	rows, err := aiobject.DatastoreQuery(ctx, invoicesSQL())
+	if err != nil {
+		return core.Fail(c, "invoices query: "+err.Error())
+	}
+	all := invoiceRowsFromRows(rows)
+
+	// Filter (latest status / org) then newest issued first, cap to limit.
+	out := make([]InvoiceRow, 0, len(all))
+	for _, r := range all {
+		if wantOrg != "" && r.Org != wantOrg {
+			continue
+		}
+		if status != "" && strings.ToLower(r.Status) != status {
+			continue
+		}
+		out = append(out, r)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Issued > out[j].Issued })
+	total := len(out)
+	if len(out) > limit {
+		out = out[:limit]
+	}
+	return core.OKList(c, out, total)
+}
+
+// invoicesSQL resolves each invoice's LATEST lifecycle state from commerce.events
+// (argMax by timestamp). Static SQL over a closed event-name set (SQLInList of
+// server constants) — no user input is interpolated, so it is injection-safe.
+func invoicesSQL() string {
+	return "SELECT JSONExtractString(properties, 'invoice_id') AS id, " +
+		"argMax(JSONExtractString(properties, 'number'), timestamp) AS number, " +
+		"argMax(organization_id, timestamp) AS org, " +
+		"argMax(JSONExtractString(properties, 'status'), timestamp) AS status, " +
+		"argMax(JSONExtractInt(properties, 'amount_cents'), timestamp) AS amount_cents, " +
+		"argMax(JSONExtractString(properties, 'currency'), timestamp) AS currency, " +
+		"argMax(JSONExtractString(properties, 'issued'), timestamp) AS issued, " +
+		"argMax(JSONExtractString(properties, 'due'), timestamp) AS due, " +
+		"argMax(event, timestamp) AS last_event " +
+		"FROM " + core.BillingEventsTable + " " +
+		"WHERE event IN (" + core.SQLInList(core.InvoiceEvents) + ") " +
+		"AND JSONExtractString(properties, 'invoice_id') != '' " +
+		"GROUP BY id"
+}
+
+// invoiceRowsFromRows maps the datastore rows onto []InvoiceRow (pure). Display is
+// the org slug — the warehouse holds no friendly name and admin does no per-org IAM
+// fan-out here (honest, not fabricated). Status folds the lifecycle from the latest
+// event so a paid/voided invoice reads correctly regardless of the status snapshot.
+func invoiceRowsFromRows(rows []map[string]any) []InvoiceRow {
+	out := make([]InvoiceRow, 0, len(rows))
+	for _, r := range rows {
+		org := core.CHStr(r["org"])
+		out = append(out, InvoiceRow{
+			ID:          core.CHStr(r["id"]),
+			Number:      core.CHStr(r["number"]),
+			Org:         org,
+			Display:     org,
+			Status:      foldInvoiceStatus(core.CHStr(r["last_event"]), core.CHStr(r["status"])),
+			AmountCents: core.CHInt64(r["amount_cents"]),
+			Currency:    core.CHStr(r["currency"]),
+			Issued:      core.CHStr(r["issued"]),
+			Due:         core.CHStr(r["due"]),
+		})
+	}
+	return out
+}
+
+// foldInvoiceStatus resolves the effective status from the latest lifecycle event
+// (paid / void terminal), falling back to the last-emitted status snapshot (open
+// for a finalized invoice) when the event is a finalize.
+func foldInvoiceStatus(lastEvent, snapshot string) string {
+	switch lastEvent {
+	case core.EvInvoicePaid:
+		return "paid"
+	case core.EvInvoiceVoid:
+		return "void"
+	}
+	if s := strings.TrimSpace(snapshot); s != "" {
+		return s
+	}
+	return "open"
+}
+
+// parseLimit clamps the fleet-list cap to [1,5000], defaulting to defaultLimit.
+func parseLimit(s string) int {
+	n, err := strconv.Atoi(strings.TrimSpace(s))
+	if err != nil || n <= 0 {
+		return defaultLimit
+	}
+	if n > 5000 {
+		return 5000
+	}
+	return n
+}
@@ -0,0 +1,77 @@
+package invoices
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/hanzoai/cloud/clients/admin/core"
+)
+
+// TestInvoiceRowsFromRows proves the warehouse-row → InvoiceRow mapping (JSON-shape
+// contract): amount coerced from driver ints, status folded from the latest event,
+// display honestly the org slug (no fan-out).
+func TestInvoiceRowsFromRows(t *testing.T) {
+	rows := []map[string]any{
+		{
+			"id": "inv_1", "number": "INV-0042", "org": "acme",
+			"status": "open", "amount_cents": int64(4900), "currency": "usd",
+			"issued": "2026-07-01T00:00:00Z", "due": "2026-07-15T00:00:00Z",
+			"last_event": core.EvInvoicePaid,
+		},
+		{
+			"id": "inv_2", "number": "INV-0043", "org": "beta",
+			"status": "open", "amount_cents": uint64(1200), "currency": "usd",
+			"issued": "2026-07-02T00:00:00Z", "due": "",
+			"last_event": core.EvInvoiceVoid,
+		},
+	}
+	out := invoiceRowsFromRows(rows)
+	if len(out) != 2 {
+		t.Fatalf("got %d rows, want 2", len(out))
+	}
+	if out[0].ID != "inv_1" || out[0].Number != "INV-0042" || out[0].Org != "acme" || out[0].Display != "acme" {
+		t.Fatalf("row0 identity wrong: %+v", out[0])
+	}
+	if out[0].AmountCents != 4900 || out[0].Currency != "usd" {
+		t.Fatalf("row0 amount/currency wrong: %+v", out[0])
+	}
+	if out[0].Status != "paid" {
+		t.Fatalf("row0 status = %q, want paid (paid event folds)", out[0].Status)
+	}
+	if out[0].Issued != "2026-07-01T00:00:00Z" || out[0].Due != "2026-07-15T00:00:00Z" {
+		t.Fatalf("row0 dates wrong: %+v", out[0])
+	}
+	if out[1].Status != "void" {
+		t.Fatalf("row1 status = %q, want void", out[1].Status)
+	}
+}
+
+func TestFoldInvoiceStatus(t *testing.T) {
+	if got := foldInvoiceStatus(core.EvInvoicePaid, "open"); got != "paid" {
+		t.Fatalf("paid fold = %q", got)
+	}
+	if got := foldInvoiceStatus(core.EvInvoiceVoid, "open"); got != "void" {
+		t.Fatalf("void fold = %q", got)
+	}
+	if got := foldInvoiceStatus(core.EvInvoiceFinalized, "open"); got != "open" {
+		t.Fatalf("finalized snapshot = %q", got)
+	}
+	if got := foldInvoiceStatus(core.EvInvoiceFinalized, ""); got != "open" {
+		t.Fatalf("finalized default = %q", got)
+	}
+}
+
+func TestInvoicesSQLInjectionSafe(t *testing.T) {
+	sql := invoicesSQL()
+	if !strings.Contains(sql, core.BillingEventsTable) {
+		t.Fatalf("query must read %s: %q", core.BillingEventsTable, sql)
+	}
+	for _, ev := range core.InvoiceEvents {
+		if !strings.Contains(sql, "'"+ev+"'") {
+			t.Fatalf("query missing event %q", ev)
+		}
+	}
+	if strings.Contains(sql, "?") {
+		t.Fatalf("invoices state query takes no positional args: %q", sql)
+	}
+}
@@ -0,0 +1,13 @@
+package invoices
+
+import (
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/admin/core"
+	"github.com/zap-proto/zip"
+)
+
+// Routes registers the fleet invoice view (SuperAdmin only, cross-tenant).
+func Routes(app *zip.App, s *cloud.Service[core.State]) {
+	g := app.Group("/v1/admin")
+	g.Get("/invoices", core.Guard(s, Invoices))
+}
@@ -0,0 +1,144 @@
+package admin
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/url"
+	"strings"
+
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/admin/core"
+	"github.com/zap-proto/zip"
+)
+
+// The SuperAdmin usage-cap + promo control plane, twinning /v1/admin/flags. It owns
+// no store: it FORWARDS to commerce (the billing source of truth) over the ONE
+// service-token seam —
+//
+//	promos      → commerce /v1/platform/promo   (the admin-configured plan promo)
+//	spend-caps  → commerce /v1/billing/spend-alerts (a per-org usage cap override)
+//
+// so admin.hanzo.ai configures the 50%-off promo and oversees/overrides any org's
+// caps without a parallel model. Promo routes are platform-only (core.Guard); cap
+// routes are org-scoped (core.GuardScoped) so a SuperAdmin targets any org via ?org=
+// while a lesser admin is hard-pinned to their own.
+
+// limitRoutes registers the promo + cap control plane. Called from routes().
+func limitRoutes(app *zip.App, s *cloud.Service[core.State]) {
+	g := app.Group("/v1/admin")
+	// Platform plan promo — SuperAdmin only.
+	g.Get("/promos", core.Guard(s, getPromo))
+	g.Put("/promos", core.Guard(s, putPromo))
+
+	// Per-org usage-cap oversight/override — SuperAdmin (any org via ?org=) or an org
+	// admin (own org only). Reuses the customer's OWN self-service spend-alert CRUD,
+	// so a platform override and a customer edit are the same rows.
+	g.Get("/spend-caps", core.GuardScoped(s, listSpendCaps))
+	g.Post("/spend-caps", core.GuardScoped(s, createSpendCap))
+	g.Patch("/spend-caps/:id", core.GuardScoped(s, updateSpendCap))
+	g.Delete("/spend-caps/:id", core.GuardScoped(s, deleteSpendCap))
+}
+
+// getPromo returns the current platform plan promo. X-Org-Id is the admin org —
+// commerce stores the singleton in the reserved platform namespace regardless, and
+// the service token is what passes commerce's RequirePlatformAdmin.
+func getPromo(s *cloud.Service[core.State], c *zip.Ctx) error {
+	raw, status, err := s.State.Commerce.Forward(c.Context(), http.MethodGet, "/v1/platform/promo", s.State.AdminOrg, nil)
+	return relay(c, raw, status, err)
+}
+
+// putPromo upserts the platform plan promo from the SuperAdmin's {percentOff,start,
+// end,plans,active} body — the ONE place the 50%-off offer is configured.
+func putPromo(s *cloud.Service[core.State], c *zip.Ctx) error {
+	raw, status, err := s.State.Commerce.Forward(c.Context(), http.MethodPut, "/v1/platform/promo", s.State.AdminOrg, c.Body())
+	return relay(c, raw, status, err)
+}
+
+// listSpendCaps returns a target org's usage caps (spend-alerts + derived period
+// spend/over/warn/resetsAt). The org is the SuperAdmin's ?org= or, for a scoped
+// admin, their own — never a client-widened scope.
+func listSpendCaps(s *cloud.Service[core.State], c *zip.Ctx) error {
+	org, ok := targetOrg(s, c)
+	if !ok {
+		return core.Fail(c, "org required")
+	}
+	raw, status, err := s.State.Commerce.Forward(c.Context(), http.MethodGet, "/v1/billing/spend-alerts", org, nil)
+	return relay(c, raw, status, err)
+}
+
+// createSpendCap sets a cap on a target org (platform override of a customer budget).
+func createSpendCap(s *cloud.Service[core.State], c *zip.Ctx) error {
+	org, ok := targetOrg(s, c)
+	if !ok {
+		return core.Fail(c, "org required")
+	}
+	raw, status, err := s.State.Commerce.Forward(c.Context(), http.MethodPost, "/v1/billing/spend-alerts", org, c.Body())
+	return relay(c, raw, status, err)
+}
+
+// updateSpendCap edits a target org's cap by id (raise/lower the ceiling, flip enforce).
+func updateSpendCap(s *cloud.Service[core.State], c *zip.Ctx) error {
+	org, ok := targetOrg(s, c)
+	if !ok {
+		return core.Fail(c, "org required")
+	}
+	id := strings.TrimSpace(c.Param("id"))
+	if id == "" {
+		return core.Fail(c, "cap id required")
+	}
+	raw, status, err := s.State.Commerce.Forward(c.Context(), http.MethodPatch, "/v1/billing/spend-alerts/"+url.PathEscape(id), org, c.Body())
+	return relay(c, raw, status, err)
+}
+
+// deleteSpendCap removes a target org's cap by id.
+func deleteSpendCap(s *cloud.Service[core.State], c *zip.Ctx) error {
+	org, ok := targetOrg(s, c)
+	if !ok {
+		return core.Fail(c, "org required")
+	}
+	id := strings.TrimSpace(c.Param("id"))
+	if id == "" {
+		return core.Fail(c, "cap id required")
+	}
+	raw, status, err := s.State.Commerce.Forward(c.Context(), http.MethodDelete, "/v1/billing/spend-alerts/"+url.PathEscape(id), org, nil)
+	return relay(c, raw, status, err)
+}
+
+// targetOrg resolves which org a cap operation acts on: a SuperAdmin names it with
+// ?org=; a scoped admin is hard-pinned to their own subtree (?org= ignored). Empty
+// (false) when unresolvable, so the handler fails closed rather than acting on a
+// guessed tenant.
+func targetOrg(s *cloud.Service[core.State], c *zip.Ctx) (string, bool) {
+	sc := core.ResolveScope(s, c)
+	if sc.Super {
+		if org := strings.TrimSpace(c.Query("org")); org != "" {
+			return org, true
+		}
+		return "", false
+	}
+	if len(sc.Orgs) > 0 && strings.TrimSpace(sc.Orgs[0]) != "" {
+		return sc.Orgs[0], true
+	}
+	return "", false
+}
+
+// relay surfaces commerce's OWN verdict in the /v1 envelope: a 2xx passes the raw
+// JSON through as data (so the console decodes the exact SpendAlert/Promo shape), a
+// non-2xx becomes an honest failure carrying commerce's status + message rather than
+// masking a 400 validation as success.
+func relay(c *zip.Ctx, raw []byte, status int, err error) error {
+	if err != nil {
+		return core.Fail(c, err.Error())
+	}
+	if status < 200 || status >= 300 {
+		msg := strings.TrimSpace(string(raw))
+		if msg == "" {
+			msg = http.StatusText(status)
+		}
+		return core.Fail(c, msg)
+	}
+	if len(raw) == 0 {
+		return core.OK(c, map[string]any{"ok": true})
+	}
+	return core.OKRaw(c, json.RawMessage(raw), 0)
+}
@@ -0,0 +1,120 @@
+package admin
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+)
+
+// recCommerce records the X-Org-Id + method + path of the last forwarded request so a
+// test can prove the /v1/admin control plane targets the RIGHT tenant namespace, and
+// serves the promo + spend-alert shapes verbatim.
+type recCommerce struct {
+	server     *httptest.Server
+	mu         sync.Mutex
+	lastOrg    string
+	lastMethod string
+	lastPath   string
+}
+
+func newRecCommerce() *recCommerce {
+	f := &recCommerce{}
+	f.server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		f.mu.Lock()
+		f.lastOrg = r.Header.Get("X-Org-Id")
+		f.lastMethod = r.Method
+		f.lastPath = r.URL.Path
+		f.mu.Unlock()
+		w.Header().Set("Content-Type", "application/json")
+		switch {
+		case strings.HasSuffix(r.URL.Path, "/platform/promo"):
+			io.WriteString(w, `{"percentOff":50,"plans":["pro"],"active":true}`)
+		case strings.HasSuffix(r.URL.Path, "/spend-alerts"):
+			io.WriteString(w, `[{"id":"a1","threshold":10000,"enforce":true,"period":"2026-07","resetsAt":"2026-08-01T00:00:00Z"}]`)
+		default:
+			io.WriteString(w, `{}`)
+		}
+	}))
+	return f
+}
+
+func (f *recCommerce) seen() (string, string, string) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return f.lastMethod, f.lastPath, f.lastOrg
+}
+
+func envStatus(t *testing.T, body []byte) string {
+	t.Helper()
+	var e struct {
+		Status string `json:"status"`
+	}
+	_ = json.Unmarshal(body, &e)
+	return e.Status
+}
+
+// The promo control plane is SuperAdmin-only (core.Guard) and forwards to commerce's
+// platform-promo endpoint.
+func TestLimits_Promo_SuperOnly(t *testing.T) {
+	iam := newScopeIAM()
+	defer iam.server.Close()
+	com := newRecCommerce()
+	defer com.server.Close()
+	do := mount(t, iam.server.URL, com.server.URL, "")
+
+	// SuperAdmin GET → 200 ok, forwarded to /v1/platform/promo.
+	resp, body := do("GET", "/v1/admin/promos", superHdr)
+	if resp.StatusCode != http.StatusOK || envStatus(t, body) != "ok" {
+		t.Fatalf("super GET promos = %d %s", resp.StatusCode, body)
+	}
+	if m, p, _ := com.seen(); m != "GET" || !strings.HasSuffix(p, "/platform/promo") {
+		t.Fatalf("forwarded %s %s, want GET .../platform/promo", m, p)
+	}
+
+	// SuperAdmin PUT → forwarded as PUT.
+	if resp, _ := do("PUT", "/v1/admin/promos", superHdr); resp.StatusCode != http.StatusOK {
+		t.Fatalf("super PUT promos = %d", resp.StatusCode)
+	}
+	if m, _, _ := com.seen(); m != "PUT" {
+		t.Fatalf("promo PUT forwarded as %s, want PUT", m)
+	}
+
+	// A non-super org admin is REFUSED at the platform gate (403), never reaching commerce.
+	if resp, _ := do("GET", "/v1/admin/promos", orgAdminHdr); resp.StatusCode != http.StatusForbidden {
+		t.Fatalf("org-admin GET promos = %d, want 403 (platform-only)", resp.StatusCode)
+	}
+}
+
+// Cap oversight is org-scoped: a SuperAdmin targets any org via ?org=; a scoped admin
+// is hard-pinned to their OWN org (a client ?org= is ignored — the escalation line).
+func TestLimits_SpendCaps_OrgScoped(t *testing.T) {
+	iam := newScopeIAM()
+	defer iam.server.Close()
+	com := newRecCommerce()
+	defer com.server.Close()
+	do := mount(t, iam.server.URL, com.server.URL, "")
+
+	// SuperAdmin with ?org=maxpower → forwards X-Org-Id=maxpower.
+	resp, body := do("GET", "/v1/admin/spend-caps?org=maxpower", superHdr)
+	if resp.StatusCode != http.StatusOK || envStatus(t, body) != "ok" {
+		t.Fatalf("super spend-caps = %d %s", resp.StatusCode, body)
+	}
+	if _, p, org := com.seen(); org != "maxpower" || !strings.HasSuffix(p, "/spend-alerts") {
+		t.Fatalf("forwarded org=%q path=%q, want maxpower .../spend-alerts", org, p)
+	}
+
+	// SuperAdmin WITHOUT ?org → org required (honest error, no guessed tenant).
+	if _, body := do("GET", "/v1/admin/spend-caps", superHdr); envStatus(t, body) != "error" {
+		t.Fatalf("super spend-caps without org must be an error envelope, got %s", body)
+	}
+
+	// A scoped org admin naming a FOREIGN ?org=hanzo is hard-pinned to their OWN org.
+	do("GET", "/v1/admin/spend-caps?org=hanzo", orgAdminHdr)
+	if _, _, org := com.seen(); org != "maxpower" {
+		t.Fatalf("scoped admin forwarded org=%q, want maxpower (client ?org= must be ignored)", org)
+	}
+}
@@ -0,0 +1,488 @@
+// Package metrics is the fleet SaaS-operations god-view (/v1/admin/metrics) — the
+// operator's business dashboard: MRR/ARR, net-new vs churned MRR, the plan/category
+// mix, the top customers, and the recent subscription movements. SuperAdmin only
+// (core.Guard).
+//
+// It reads the ONE shared warehouse (commerce.events) — the table the commerce
+// analytics collector lands every subscription/invoice/usage-lifecycle event in —
+// over the SAME client (aiobject.DatastoreQuery) the o11y/compute lenses use, with
+// ZERO per-org fan-out. Each panel is ONE aggregate query that folds the whole fleet
+// (subscription state = latest-event-wins via argMax; new/churn/usage = windowed),
+// exactly the way o11y.go composes independent per-signal reads. An unconnected
+// warehouse — or the collector's events table not provisioned yet — degrades to an
+// honest empty snapshot (real zeros, `[]` not null) with a not-ok source, never a
+// fabricated number. Money is USD cents end to end; time bounds are POSITIONAL args.
+package metrics
+
+import (
+	"context"
+	"errors"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	aiobject "github.com/hanzoai/ai/object"
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/admin/core"
+	"github.com/hanzoai/cloud/clients/admin/money"
+	"github.com/zap-proto/zip"
+)
+
+// errUnconfigured marks the warehouse not connected on this deployment — core.SrcOf
+// reports it as a not-ok source so the console renders the honest not-configured state.
+var errUnconfigured = errors.New("billing warehouse not connected")
+
+// defaultLimit caps the top-customers list; recentLimit caps the movement feed.
+const (
+	defaultLimit = 20
+	recentLimit  = 20
+)
+
+// ── response shapes (byte-identical to the operator contract in api.ts) ──────
+// These were formerly modeled on the commerce S2S client; they now live here (the
+// one consumer) since the read is a direct warehouse aggregate. Money is money.Cents
+// (int64 underlying → plain-integer JSON, unchanged on the wire).
+
+// SaaSMetrics is the whole-business SaaS-operations aggregate.
+type SaaSMetrics struct {
+	AsOf      string         `json:"asOf"`
+	Currency  string         `json:"currency"`
+	Window    string         `json:"window"`
+	Revenue   SaaSRevenue    `json:"revenue"`
+	Subs      SaaSSubs       `json:"subscriptions"`
+	Usage     SaaSUsage      `json:"usage"`
+	Customers []SaaSCustomer `json:"customers"`
+	Orgs      int            `json:"orgs"`
+	Gaps      []string       `json:"gaps"`
+}
+
+// SaaSRevenue is the recurring-revenue headline (run-rate MRR/ARR + windowed movement).
+type SaaSRevenue struct {
+	MRRCents            money.Cents    `json:"mrrCents"`
+	ARRCents            money.Cents    `json:"arrCents"`
+	ActiveSubscriptions int            `json:"activeSubscriptions"`
+	PayingCustomers     int            `json:"payingCustomers"`
+	Trials              int            `json:"trials"`
+	NewMRRCents         money.Cents    `json:"newMrrCents"`
+	ChurnedMRRCents     money.Cents    `json:"churnedMrrCents"`
+	NetNewMRRCents      money.Cents    `json:"netNewMrrCents"`
+	ByCategory          []SaaSCategory `json:"byCategory"`
+}
+
+// SaaSCategory is one plan-category bucket of run-rate MRR (the plan mix).
+type SaaSCategory struct {
+	Category      string      `json:"category"`
+	MRRCents      money.Cents `json:"mrrCents"`
+	Subscriptions int         `json:"subscriptions"`
+}
+
+// SaaSSubs is the subscription-operations panel (per-plan mix, trials, new/canceled,
+// recent movements).
+type SaaSSubs struct {
+	ByPlan       []SaaSPlan  `json:"byPlan"`
+	TrialsActive int         `json:"trialsActive"`
+	New          int         `json:"new"`
+	Canceled     int         `json:"canceled"`
+	Recent       []SaaSEvent `json:"recent"`
+}
+
+// SaaSPlan is one plan's active/trialing counts, seats, and MRR contribution.
+type SaaSPlan struct {
+	Plan     string      `json:"plan"`
+	Name     string      `json:"name"`
+	Category string      `json:"category"`
+	Active   int         `json:"active"`
+	Trialing int         `json:"trialing"`
+	Seats    int         `json:"seats"`
+	MRRCents money.Cents `json:"mrrCents"`
+}
+
+// SaaSEvent is one recent subscription movement ("created" or "canceled").
+type SaaSEvent struct {
+	At            string      `json:"at"`
+	Org           string      `json:"org"`
+	Type          string      `json:"type"`
+	Plan          string      `json:"plan"`
+	Category      string      `json:"category"`
+	MRRDeltaCents money.Cents `json:"mrrDeltaCents"`
+}
+
+// SaaSUsage is the metered / pay-as-you-go revenue headline for the window.
+type SaaSUsage struct {
+	Instrumented     bool        `json:"instrumented"`
+	WindowUsageCents money.Cents `json:"windowUsageCents"`
+	Requests         int64       `json:"requests"`
+}
+
+// SaaSCustomer is one top customer by MRR + windowed usage.
+type SaaSCustomer struct {
+	Org        string      `json:"org"`
+	Plan       string      `json:"plan"`
+	Category   string      `json:"category"`
+	Status     string      `json:"status"`
+	MRRCents   money.Cents `json:"mrrCents"`
+	UsageCents money.Cents `json:"usageCents"`
+	Seats      int         `json:"seats"`
+	Since      string      `json:"since,omitempty"`
+}
+
+// MetricsData is the GET /v1/admin/metrics payload: the SaaS snapshot, flat, plus the
+// admin read time and the upstream freshness strip every god-view carries.
+type MetricsData struct {
+	SaaSMetrics
+	GeneratedAt string              `json:"generatedAt"`
+	Sources     []core.SourceStatus `json:"sources"`
+}
+
+// Metrics answers GET /v1/admin/metrics by aggregating commerce.events directly
+// (fleet-wide, no per-org fan-out). SuperAdmin only.
+//
+//	GET /v1/admin/metrics?window=30d&limit=20
+func Metrics(s *cloud.Service[core.State], c *zip.Ctx) error {
+	ctx := c.Context()
+	now := time.Now().UTC().Format(time.RFC3339)
+	window := normalizeWindow(c.Query("window"))
+	limit := parseLimit(c.Query("limit"))
+
+	// Honest not-configured snapshot when the warehouse/collector table is absent.
+	if !core.BillingEventsReady(ctx) {
+		return core.OK(c, empty(now, window, core.SrcOf("billing-warehouse", errUnconfigured, 0, now)))
+	}
+
+	sinceTS := core.CHTimeLit(core.WarehouseSince(window))
+	m := SaaSMetrics{AsOf: now, Currency: "usd", Window: window}
+
+	// Revenue headline + plan-mix (run-rate, latest-event-wins over active subs).
+	if rows, err := aiobject.DatastoreQuery(ctx, headlineSQL()); err == nil {
+		fillHeadline(&m.Revenue, core.CHFirstRow(rows))
+	}
+	if rows, err := aiobject.DatastoreQuery(ctx, byCategorySQL()); err == nil {
+		m.Revenue.ByCategory = byCategoryFromRows(rows)
+	}
+	if rows, err := aiobject.DatastoreQuery(ctx, byPlanSQL()); err == nil {
+		m.Subs.ByPlan = byPlanFromRows(rows)
+	}
+	m.Subs.TrialsActive = m.Revenue.Trials
+
+	// Windowed movement: new vs churned MRR + counts.
+	if rows, err := aiobject.DatastoreQuery(ctx, movementSQL(), sinceTS); err == nil {
+		r := core.CHFirstRow(rows)
+		m.Revenue.NewMRRCents = money.Cents(core.CHInt64(r["new_mrr"]))
+		m.Revenue.ChurnedMRRCents = money.Cents(core.CHInt64(r["churned_mrr"]))
+		m.Revenue.NetNewMRRCents = m.Revenue.NewMRRCents - m.Revenue.ChurnedMRRCents
+		m.Subs.New = int(core.CHInt64(r["new_count"]))
+		m.Subs.Canceled = int(core.CHInt64(r["canceled_count"]))
+	}
+	// Recent movements feed.
+	if rows, err := aiobject.DatastoreQuery(ctx, recentSQL(), sinceTS); err == nil {
+		m.Subs.Recent = recentFromRows(rows)
+	}
+	// Metered usage headline (window).
+	if rows, err := aiobject.DatastoreQuery(ctx, usageSQL(), sinceTS); err == nil {
+		r := core.CHFirstRow(rows)
+		m.Usage.Requests = core.CHInt64(r["requests"])
+		m.Usage.WindowUsageCents = money.Cents(core.CHInt64(r["usage_cents"]))
+		m.Usage.Instrumented = m.Usage.Requests > 0
+	}
+	// Fleet org count (any billing activity).
+	if rows, err := aiobject.DatastoreQuery(ctx, orgCountSQL()); err == nil {
+		m.Orgs = int(core.CHInt64(core.CHFirstRow(rows)["orgs"]))
+	}
+	// Top customers by MRR + windowed usage (two reads merged, no fan-out).
+	m.Customers = topCustomers(ctx, sinceTS, limit)
+
+	m.Gaps = gapsFor(m)
+	return core.OK(c, MetricsData{
+		SaaSMetrics: normalize(m),
+		GeneratedAt: now,
+		Sources:     []core.SourceStatus{core.SrcOf("billing-warehouse", nil, m.Orgs, now)},
+	})
+}
+
+// ── active-subscription state subquery (latest-event-wins, non-canceled) ─────
+
+// activeSubs is the fleet's current subscription state: one row per subscription,
+// its LATEST lifecycle values (argMax by timestamp), keeping only non-canceled
+// subs (HAVING on the latest event). Static SQL over a closed event-name set — no
+// user input interpolated. Reused by every run-rate panel so the definition of
+// "active" lives in ONE place.
+func activeSubs() string {
+	return "(SELECT " +
+		"argMax(organization_id, timestamp) AS org, " +
+		"argMax(JSONExtractString(properties, 'plan'), timestamp) AS plan, " +
+		"argMax(JSONExtractString(properties, 'plan_name'), timestamp) AS plan_name, " +
+		"argMax(JSONExtractString(properties, 'category'), timestamp) AS category, " +
+		"argMax(JSONExtractString(properties, 'status'), timestamp) AS status, " +
+		"argMax(JSONExtractInt(properties, 'mrr_cents'), timestamp) AS mrr_cents, " +
+		"argMax(JSONExtractInt(properties, 'seats'), timestamp) AS seats, " +
+		"min(timestamp) AS first_ts " +
+		"FROM " + core.BillingEventsTable + " " +
+		"WHERE event IN (" + core.SQLInList(core.SubscriptionEvents) + ") " +
+		"AND JSONExtractString(properties, 'subscription_id') != '' " +
+		"GROUP BY JSONExtractString(properties, 'subscription_id') " +
+		"HAVING argMax(event, timestamp) != '" + core.EvSubscriptionCanceled + "')"
+}
+
+// ── pure SQL builders (static SQL + at most one positional time bound) ────────
+
+// headlineSQL: run-rate MRR (paying, non-trial), active-sub count, paying-customer
+// count, and trial count — one pass over the active-subs state.
+func headlineSQL() string {
+	return "SELECT sumIf(mrr_cents, status != 'trialing') AS mrr, " +
+		"count() AS active_subs, " +
+		"uniqExactIf(org, status != 'trialing' AND mrr_cents > 0) AS paying, " +
+		"countIf(status = 'trialing') AS trials FROM " + activeSubs()
+}
+
+func byCategorySQL() string {
+	return "SELECT category, sumIf(mrr_cents, status != 'trialing') AS mrr, count() AS subs " +
+		"FROM " + activeSubs() + " GROUP BY category ORDER BY mrr DESC"
+}
+
+func byPlanSQL() string {
+	return "SELECT plan, any(plan_name) AS name, any(category) AS category, " +
+		"countIf(status = 'active') AS active, countIf(status = 'trialing') AS trialing, " +
+		"sum(seats) AS seats, sumIf(mrr_cents, status != 'trialing') AS mrr " +
+		"FROM " + activeSubs() + " GROUP BY plan ORDER BY mrr DESC"
+}
+
+// movementSQL: windowed new vs churned MRR + counts (one positional since bound).
+func movementSQL() string {
+	return "SELECT " +
+		"sumIf(JSONExtractInt(properties, 'mrr_cents'), event = '" + core.EvSubscriptionCreated + "') AS new_mrr, " +
+		"countIf(event = '" + core.EvSubscriptionCreated + "') AS new_count, " +
+		"sumIf(JSONExtractInt(properties, 'mrr_cents'), event = '" + core.EvSubscriptionCanceled + "') AS churned_mrr, " +
+		"countIf(event = '" + core.EvSubscriptionCanceled + "') AS canceled_count " +
+		"FROM " + core.BillingEventsTable + " " +
+		"WHERE event IN ('" + core.EvSubscriptionCreated + "','" + core.EvSubscriptionCanceled + "') AND timestamp >= ?"
+}
+
+func recentSQL() string {
+	return "SELECT timestamp AS at, organization_id AS org, event AS type, " +
+		"JSONExtractString(properties, 'plan_name') AS plan, " +
+		"JSONExtractString(properties, 'category') AS category, " +
+		"JSONExtractInt(properties, 'mrr_cents') AS mrr_delta " +
+		"FROM " + core.BillingEventsTable + " " +
+		"WHERE event IN ('" + core.EvSubscriptionCreated + "','" + core.EvSubscriptionCanceled + "') AND timestamp >= ? " +
+		"ORDER BY at DESC LIMIT " + strconv.Itoa(recentLimit)
+}
+
+func usageSQL() string {
+	return "SELECT count() AS requests, sum(JSONExtractInt(properties, 'amount_cents')) AS usage_cents " +
+		"FROM " + core.BillingEventsTable + " WHERE event = '" + core.EvAPIUsageDebit + "' AND timestamp >= ?"
+}
+
+func orgCountSQL() string {
+	return "SELECT uniqExact(organization_id) AS orgs FROM " + core.BillingEventsTable +
+		" WHERE event IN (" + core.SQLInList(allBillingEvents()) + ")"
+}
+
+func perOrgSubsSQL() string {
+	return "SELECT org, sumIf(mrr_cents, status != 'trialing') AS mrr, sum(seats) AS seats, " +
+		"argMax(plan_name, mrr_cents) AS plan, argMax(category, mrr_cents) AS category, " +
+		"argMax(status, mrr_cents) AS status, min(first_ts) AS since " +
+		"FROM " + activeSubs() + " GROUP BY org"
+}
+
+func perOrgUsageSQL() string {
+	return "SELECT organization_id AS org, sum(JSONExtractInt(properties, 'amount_cents')) AS usage_cents " +
+		"FROM " + core.BillingEventsTable + " WHERE event = '" + core.EvAPIUsageDebit + "' AND timestamp >= ? GROUP BY org"
+}
+
+// allBillingEvents is the union of every customer-activity event the fleet counts
+// an org as "active" on (subscription + invoice + usage).
+func allBillingEvents() []string {
+	out := append([]string{}, core.SubscriptionEvents...)
+	out = append(out, core.InvoiceEvents...)
+	return append(out, core.EvAPIUsageDebit)
+}
+
+// ── pure row parsers ─────────────────────────────────────────────────────────
+
+func fillHeadline(r *SaaSRevenue, row map[string]any) {
+	r.MRRCents = money.Cents(core.CHInt64(row["mrr"]))
+	r.ARRCents = r.MRRCents * 12
+	r.ActiveSubscriptions = int(core.CHInt64(row["active_subs"]))
+	r.PayingCustomers = int(core.CHInt64(row["paying"]))
+	r.Trials = int(core.CHInt64(row["trials"]))
+}
+
+func byCategoryFromRows(rows []map[string]any) []SaaSCategory {
+	out := make([]SaaSCategory, 0, len(rows))
+	for _, r := range rows {
+		out = append(out, SaaSCategory{
+			Category:      core.CHStr(r["category"]),
+			MRRCents:      money.Cents(core.CHInt64(r["mrr"])),
+			Subscriptions: int(core.CHInt64(r["subs"])),
+		})
+	}
+	return out
+}
+
+func byPlanFromRows(rows []map[string]any) []SaaSPlan {
+	out := make([]SaaSPlan, 0, len(rows))
+	for _, r := range rows {
+		out = append(out, SaaSPlan{
+			Plan:     core.CHStr(r["plan"]),
+			Name:     core.CHStr(r["name"]),
+			Category: core.CHStr(r["category"]),
+			Active:   int(core.CHInt64(r["active"])),
+			Trialing: int(core.CHInt64(r["trialing"])),
+			Seats:    int(core.CHInt64(r["seats"])),
+			MRRCents: money.Cents(core.CHInt64(r["mrr"])),
+		})
+	}
+	return out
+}
+
+func recentFromRows(rows []map[string]any) []SaaSEvent {
+	out := make([]SaaSEvent, 0, len(rows))
+	for _, r := range rows {
+		typ := "created"
+		delta := money.Cents(core.CHInt64(r["mrr_delta"]))
+		if core.CHStr(r["type"]) == core.EvSubscriptionCanceled {
+			typ = "canceled"
+			delta = -delta // churn reduces run-rate MRR
+		}
+		out = append(out, SaaSEvent{
+			At:            core.CHTime(r["at"]),
+			Org:           core.CHStr(r["org"]),
+			Type:          typ,
+			Plan:          core.CHStr(r["plan"]),
+			Category:      core.CHStr(r["category"]),
+			MRRDeltaCents: delta,
+		})
+	}
+	return out
+}
+
+// topCustomers folds per-org subscription state + per-org windowed usage into the
+// top-N customers by MRR (then usage). Two reads merged in Go by org — a union, so
+// a pay-as-you-go org with usage but no subscription still appears.
+func topCustomers(ctx context.Context, sinceTS string, limit int) []SaaSCustomer {
+	byOrg := map[string]*SaaSCustomer{}
+	if rows, err := aiobject.DatastoreQuery(ctx, perOrgSubsSQL()); err == nil {
+		for _, r := range rows {
+			org := core.CHStr(r["org"])
+			if org == "" {
+				continue
+			}
+			byOrg[org] = &SaaSCustomer{
+				Org:      org,
+				Plan:     core.CHStr(r["plan"]),
+				Category: core.CHStr(r["category"]),
+				Status:   core.CHStr(r["status"]),
+				MRRCents: money.Cents(core.CHInt64(r["mrr"])),
+				Seats:    int(core.CHInt64(r["seats"])),
+				Since:    core.CHTime(r["since"]),
+			}
+		}
+	}
+	if rows, err := aiobject.DatastoreQuery(ctx, perOrgUsageSQL(), sinceTS); err == nil {
+		for _, r := range rows {
+			org := core.CHStr(r["org"])
+			if org == "" {
+				continue
+			}
+			usage := money.Cents(core.CHInt64(r["usage_cents"]))
+			if cust, ok := byOrg[org]; ok {
+				cust.UsageCents = usage
+				continue
+			}
+			byOrg[org] = &SaaSCustomer{Org: org, Plan: "pay-as-you-go", Status: "active", UsageCents: usage}
+		}
+	}
+	out := make([]SaaSCustomer, 0, len(byOrg))
+	for _, c := range byOrg {
+		out = append(out, *c)
+	}
+	sortCustomers(out)
+	if len(out) > limit {
+		out = out[:limit]
+	}
+	return out
+}
+
+// ── small pure helpers ───────────────────────────────────────────────────────
+
+// sortCustomers ranks by MRR desc, ties broken by windowed usage desc.
+func sortCustomers(cs []SaaSCustomer) {
+	sort.SliceStable(cs, func(i, j int) bool { return lessCustomer(cs[i], cs[j]) })
+}
+
+func lessCustomer(a, b SaaSCustomer) bool {
+	if a.MRRCents != b.MRRCents {
+		return a.MRRCents > b.MRRCents
+	}
+	return a.UsageCents > b.UsageCents
+}
+
+// gapsFor lists honest not-yet-observed signals so the console can badge a partial
+// snapshot without fabricating data.
+func gapsFor(m SaaSMetrics) []string {
+	gaps := []string{}
+	if !m.Usage.Instrumented {
+		gaps = append(gaps, "api-usage debits not yet observed")
+	}
+	if m.Revenue.ActiveSubscriptions == 0 {
+		gaps = append(gaps, "no active subscriptions observed")
+	}
+	return gaps
+}
+
+// empty is the honest not-connected snapshot: real zeros + empty slices (never
+// null, never fabricated) plus the not-ok source.
+func empty(now, window string, src core.SourceStatus) MetricsData {
+	return MetricsData{
+		SaaSMetrics: normalize(SaaSMetrics{AsOf: now, Currency: "usd", Window: window}),
+		GeneratedAt: now,
+		Sources:     []core.SourceStatus{src},
+	}
+}
+
+// normalize replaces nil slices with empty ones so the JSON is honest arrays (`[]`,
+// not null) and the console never has to guard a missing collection.
+func normalize(m SaaSMetrics) SaaSMetrics {
+	if m.Revenue.ByCategory == nil {
+		m.Revenue.ByCategory = []SaaSCategory{}
+	}
+	if m.Subs.ByPlan == nil {
+		m.Subs.ByPlan = []SaaSPlan{}
+	}
+	if m.Subs.Recent == nil {
+		m.Subs.Recent = []SaaSEvent{}
+	}
+	if m.Customers == nil {
+		m.Customers = []SaaSCustomer{}
+	}
+	if m.Gaps == nil {
+		m.Gaps = []string{}
+	}
+	return m
+}
+
+// normalizeWindow clamps ?window to the supported set (default 30d) — mirrors the
+// warehouse window grammar (core.WarehouseSince).
+func normalizeWindow(v string) string {
+	switch strings.TrimSpace(v) {
+	case "24h":
+		return "24h"
+	case "7d":
+		return "7d"
+	default:
+		return "30d"
+	}
+}
+
+// parseLimit clamps the top-N cap to [1,200], defaulting to defaultLimit.
+func parseLimit(s string) int {
+	n, err := strconv.Atoi(strings.TrimSpace(s))
+	if err != nil || n <= 0 {
+		return defaultLimit
+	}
+	if n > 200 {
+		return 200
+	}
+	return n
+}
@@ -0,0 +1,121 @@
+package metrics
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/hanzoai/cloud/clients/admin/core"
+)
+
+// TestFillHeadline proves the run-rate headline coercion (driver ints) + the
+// ARR = 12×MRR derivation.
+func TestFillHeadline(t *testing.T) {
+	var rev SaaSRevenue
+	fillHeadline(&rev, map[string]any{
+		"mrr": int64(4900), "active_subs": uint64(3), "paying": uint64(2), "trials": uint64(1),
+	})
+	if rev.MRRCents != 4900 || rev.ARRCents != 4900*12 {
+		t.Fatalf("mrr/arr wrong: %+v", rev)
+	}
+	if rev.ActiveSubscriptions != 3 || rev.PayingCustomers != 2 || rev.Trials != 1 {
+		t.Fatalf("counts wrong: %+v", rev)
+	}
+}
+
+func TestByCategoryAndPlanFromRows(t *testing.T) {
+	cats := byCategoryFromRows([]map[string]any{
+		{"category": "cloud", "mrr": int64(9800), "subs": uint64(2)},
+	})
+	if len(cats) != 1 || cats[0].Category != "cloud" || cats[0].MRRCents != 9800 || cats[0].Subscriptions != 2 {
+		t.Fatalf("category row wrong: %+v", cats)
+	}
+	plans := byPlanFromRows([]map[string]any{
+		{"plan": "pro", "name": "Pro", "category": "cloud", "active": uint64(2), "trialing": uint64(1), "seats": uint64(5), "mrr": int64(9800)},
+	})
+	if len(plans) != 1 {
+		t.Fatalf("want 1 plan, got %d", len(plans))
+	}
+	p := plans[0]
+	if p.Plan != "pro" || p.Name != "Pro" || p.Category != "cloud" || p.Active != 2 || p.Trialing != 1 || p.Seats != 5 || p.MRRCents != 9800 {
+		t.Fatalf("plan row wrong: %+v", p)
+	}
+}
+
+// TestRecentFromRows proves the movement feed maps event→type and NEGATES churn MRR.
+func TestRecentFromRows(t *testing.T) {
+	rows := []map[string]any{
+		{"at": "2026-07-10T00:00:00Z", "org": "acme", "type": core.EvSubscriptionCreated, "plan": "Pro", "category": "cloud", "mrr_delta": int64(4900)},
+		{"at": "2026-07-09T00:00:00Z", "org": "beta", "type": core.EvSubscriptionCanceled, "plan": "Team", "category": "cloud", "mrr_delta": int64(3000)},
+	}
+	out := recentFromRows(rows)
+	if len(out) != 2 {
+		t.Fatalf("want 2, got %d", len(out))
+	}
+	if out[0].Type != "created" || out[0].MRRDeltaCents != 4900 {
+		t.Fatalf("created row wrong: %+v", out[0])
+	}
+	if out[1].Type != "canceled" || out[1].MRRDeltaCents != -3000 {
+		t.Fatalf("canceled row must negate mrr: %+v", out[1])
+	}
+}
+
+func TestSortCustomers(t *testing.T) {
+	cs := []SaaSCustomer{
+		{Org: "a", MRRCents: 100, UsageCents: 0},
+		{Org: "b", MRRCents: 500, UsageCents: 0},
+		{Org: "c", MRRCents: 500, UsageCents: 999}, // ties on MRR → usage breaks
+	}
+	sortCustomers(cs)
+	if cs[0].Org != "c" || cs[1].Org != "b" || cs[2].Org != "a" {
+		t.Fatalf("order wrong: %s,%s,%s", cs[0].Org, cs[1].Org, cs[2].Org)
+	}
+}
+
+// TestStateQueriesNoPositionalArgs: the run-rate (state) queries are fully static.
+func TestStateQueriesNoPositionalArgs(t *testing.T) {
+	for name, sql := range map[string]string{
+		"headline": headlineSQL(), "byCategory": byCategorySQL(), "byPlan": byPlanSQL(),
+		"orgCount": orgCountSQL(), "perOrgSubs": perOrgSubsSQL(),
+	} {
+		if !strings.Contains(sql, core.BillingEventsTable) {
+			t.Fatalf("%s must read %s", name, core.BillingEventsTable)
+		}
+		if strings.Contains(sql, "?") {
+			t.Fatalf("%s (run-rate) must take no positional args: %q", name, sql)
+		}
+	}
+}
+
+// TestWindowedQueriesOnePositionalArg: the windowed queries bind exactly ONE time
+// arg (injection-safe — the since bound is never interpolated).
+func TestWindowedQueriesOnePositionalArg(t *testing.T) {
+	for name, sql := range map[string]string{
+		"movement": movementSQL(), "recent": recentSQL(), "usage": usageSQL(), "perOrgUsage": perOrgUsageSQL(),
+	} {
+		if n := strings.Count(sql, "?"); n != 1 {
+			t.Fatalf("%s must bind exactly ONE positional time arg, got %d: %q", name, n, sql)
+		}
+		if !strings.Contains(sql, "timestamp >= ?") {
+			t.Fatalf("%s time bound must be positional: %q", name, sql)
+		}
+	}
+}
+
+func TestNormalizeAndEmpty(t *testing.T) {
+	m := normalize(SaaSMetrics{})
+	if m.Revenue.ByCategory == nil || m.Subs.ByPlan == nil || m.Subs.Recent == nil || m.Customers == nil || m.Gaps == nil {
+		t.Fatal("normalize must replace nil slices with empty (honest [] not null)")
+	}
+	e := empty("now", "30d", core.SrcOf("billing-warehouse", errUnconfigured, 0, "now"))
+	if e.Currency != "usd" || e.Window != "30d" || len(e.Sources) != 1 || e.Sources[0].OK {
+		t.Fatalf("empty snapshot wrong: %+v", e)
+	}
+}
+
+func TestNormalizeWindow(t *testing.T) {
+	for in, want := range map[string]string{"24h": "24h", "7d": "7d", "30d": "30d", "": "30d", "90d": "30d"} {
+		if got := normalizeWindow(in); got != want {
+			t.Fatalf("normalizeWindow(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
@@ -0,0 +1,14 @@
+package metrics
+
+import (
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/admin/core"
+	"github.com/zap-proto/zip"
+)
+
+// Routes registers the SaaS-metrics god-view (SuperAdmin only, cross-tenant business
+// aggregate).
+func Routes(app *zip.App, s *cloud.Service[core.State]) {
+	g := app.Group("/v1/admin")
+	g.Get("/metrics", core.Guard(s, Metrics))
+}
@@ -22,7 +22,8 @@ import (

 // Routes registers the fleet revenue board (SuperAdmin only, cross-tenant profitability).
 func Routes(app *zip.App, s *cloud.Service[core.State]) {
-	app.Get("/v1/admin/revenue", core.Guard(s, Revenue))
+	g := app.Group("/v1/admin")
+	g.Get("/revenue", core.Guard(s, Revenue))
 }

 // RevenueCustomer is one row of the per-customer revenue table.
@@ -1,16 +1,16 @@
 package admin

-// The /v1/admin/services board — the launch-control LENS on the ONE flag engine, twin
+// The /v1/admin/services board — the launch-control LENS over the waitlist gate, twin
 // of /v1/admin/flags. Every hosted service (studio/chat/console/app/api/team + runtime
-// onboards) with its LIVE waitlist mode — the switch waitlist.<svc> evaluated through
-// clients/flags. This is the "remove the waitlist one service at a time" toggle.
-// SuperAdmin only (core.Guard), like every platform /v1/admin/*.
+// onboards) with its LIVE waitlist mode — the switch waitlist.<svc>, evaluated through
+// clients/admission (which composes the flag engine one-way). This is the "remove the
+// waitlist one service at a time" toggle. SuperAdmin only (core.Guard), like every
+// platform /v1/admin/*.
 //
-// Formerly clients/featuregate owned its OWN SQLite mode store + this control plane;
-// both folded onto the flag engine so the platform has ONE decision plane. featuregate
-// now owns only the native Enforce middleware — a consumer of flags.WaitlistModeForHost.
-// Per-user approval (the second, orthogonal axis) stays IAM's, reached via the existing
-// admin IAM proxy — not re-served here.
+// The registry + mode decide + these admin control funcs live in clients/admission,
+// the complete launch-gate feature; flags is the pure engine underneath. Per-user
+// approval (the second, orthogonal axis) stays IAM's, reached via the existing admin IAM
+// proxy — not re-served here.

 import (
 	"errors"
@@ -19,13 +19,13 @@ import (

 	"github.com/hanzoai/cloud"
 	"github.com/hanzoai/cloud/clients/admin/core"
-	"github.com/hanzoai/cloud/clients/flags"
+	"github.com/hanzoai/cloud/clients/admission"
 	"github.com/zap-proto/zip"
 )

 // services answers GET /v1/admin/services — the launch board (every service + live mode).
 func services(s *cloud.Service[core.State], c *zip.Ctx) error {
-	rows, err := flags.ListWaitlistServices(c.Context())
+	rows, err := admission.ListWaitlistServices(c.Context())
 	if err != nil {
 		return zip.Errorf(http.StatusInternalServerError, "list services: %v", err)
 	}
@@ -35,14 +35,14 @@ func services(s *cloud.Service[core.State], c *zip.Ctx) error {
 // upsertService answers POST /v1/admin/services — onboard or edit a hosted service so a
 // new host is governed WITHOUT a redeploy. A re-register PRESERVES the live switch.
 func upsertService(s *cloud.Service[core.State], c *zip.Ctx) error {
-	var in flags.ServiceInput
+	var in admission.ServiceInput
 	if err := c.Bind(&in); err != nil {
 		return err
 	}
 	if strings.TrimSpace(in.Service) == "" {
 		return zip.ErrBadRequest("service slug is required")
 	}
-	view, err := flags.UpsertWaitlistService(c.Context(), in, c.UserEmail())
+	view, err := admission.UpsertWaitlistService(c.Context(), in, c.UserEmail())
 	if err != nil {
 		return zip.ErrBadRequest(err.Error())
 	}
@@ -62,9 +62,9 @@ func setServiceMode(s *cloud.Service[core.State], c *zip.Ctx) error {
 	if err := c.Bind(&body); err != nil {
 		return err
 	}
-	view, err := flags.SetWaitlistMode(c.Context(), service, body.WaitlistMode, c.UserEmail())
+	view, err := admission.SetWaitlistMode(c.Context(), service, body.WaitlistMode, c.UserEmail())
 	if err != nil {
-		if errors.Is(err, flags.ErrServiceNotFound) {
+		if errors.Is(err, admission.ErrServiceNotFound) {
 			return zip.ErrNotFound("service not found: " + service)
 		}
 		return zip.Errorf(http.StatusInternalServerError, "set mode: %v", err)
@@ -0,0 +1,13 @@
+package subscriptions
+
+import (
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/admin/core"
+	"github.com/zap-proto/zip"
+)
+
+// Routes registers the fleet subscription view (SuperAdmin only, cross-tenant).
+func Routes(app *zip.App, s *cloud.Service[core.State]) {
+	g := app.Group("/v1/admin")
+	g.Get("/subscriptions", core.Guard(s, Subscriptions))
+}
@@ -0,0 +1,156 @@
+// Package subscriptions is the fleet SUBSCRIPTION view (/v1/admin/subscriptions) —
+// every tenant's plan subscription: customer/org, plan, status, monthly-normalized
+// MRR, and the current-period start/renews. SuperAdmin only (core.Guard).
+//
+// It reads the ONE shared warehouse (commerce.events) — the table the commerce
+// analytics collector lands every subscription-lifecycle event in — over the SAME
+// client (aiobject.DatastoreQuery) the o11y/compute lenses use, with ZERO per-org
+// fan-out: one GROUP BY resolves each subscription's LATEST lifecycle state
+// (argMax by timestamp), so the whole fleet is one query, not N per-org commerce
+// reads. Honest by construction: no datastore connected or the collector's table
+// not provisioned yet → the real empty list, never a fabricated tenant. The MRR is
+// the monthly-normalized figure the emitter already computed (cents). Optional
+// ?org= scopes to one tenant, ?status= filters the LATEST status, ?limit= caps.
+package subscriptions
+
+import (
+	"sort"
+	"strconv"
+	"strings"
+
+	aiobject "github.com/hanzoai/ai/object"
+	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/admin/core"
+	"github.com/zap-proto/zip"
+)
+
+// defaultLimit caps the fleet subscription list when the caller sends none.
+const defaultLimit = 500
+
+// SubscriptionRow is one row of GET /v1/admin/subscriptions — a tenant's subscription at
+// a glance, tagged with its owning org. MRR is USD cents; timestamps are RFC3339 strings.
+type SubscriptionRow struct {
+	ID       string `json:"id"`
+	Org      string `json:"org"`
+	Display  string `json:"display"`
+	User     string `json:"user"`
+	Plan     string `json:"plan"`
+	Status   string `json:"status"`
+	MRRCents int64  `json:"mrrCents"`
+	Started  string `json:"started"`
+	Renews   string `json:"renews"`
+}
+
+// Subscriptions answers GET /v1/admin/subscriptions.
+//
+//	GET /v1/admin/subscriptions?org=&status=&limit=
+func Subscriptions(s *cloud.Service[core.State], c *zip.Ctx) error {
+	ctx := c.Context()
+	status := strings.ToLower(strings.TrimSpace(c.Query("status")))
+	wantOrg := strings.TrimSpace(c.Query("org"))
+	limit := parseLimit(c.Query("limit"))
+
+	// Honest-empty when the warehouse is not connected or the collector's events
+	// table is not provisioned yet (the emitter is still being wired).
+	if !core.BillingEventsReady(ctx) {
+		return core.OKList(c, []SubscriptionRow{}, 0)
+	}
+
+	rows, err := aiobject.DatastoreQuery(ctx, subscriptionsSQL())
+	if err != nil {
+		return core.Fail(c, "subscriptions query: "+err.Error())
+	}
+	all := subscriptionRowsFromRows(rows)
+
+	// Filter (latest status / org) then sort highest-MRR first, cap to limit.
+	out := make([]SubscriptionRow, 0, len(all))
+	for _, r := range all {
+		if wantOrg != "" && r.Org != wantOrg {
+			continue
+		}
+		if status != "" && strings.ToLower(r.Status) != status {
+			continue
+		}
+		out = append(out, r)
+	}
+	sort.Slice(out, func(i, j int) bool {
+		if out[i].MRRCents != out[j].MRRCents {
+			return out[i].MRRCents > out[j].MRRCents
+		}
+		return out[i].Started > out[j].Started
+	})
+	total := len(out)
+	if len(out) > limit {
+		out = out[:limit]
+	}
+	return core.OKList(c, out, total)
+}
+
+// subscriptionsSQL resolves each subscription's LATEST lifecycle state from
+// commerce.events (argMax by timestamp). Static SQL over a closed event-name set
+// (SQLInList of server constants) — no user input is interpolated, so it is
+// injection-safe. The emitted properties carry the plan/status/mrr/period fields.
+func subscriptionsSQL() string {
+	return "SELECT JSONExtractString(properties, 'subscription_id') AS id, " +
+		"argMax(organization_id, timestamp) AS org, " +
+		"argMax(distinct_id, timestamp) AS user, " +
+		"argMax(JSONExtractString(properties, 'plan_name'), timestamp) AS plan, " +
+		"argMax(JSONExtractString(properties, 'status'), timestamp) AS status, " +
+		"argMax(JSONExtractInt(properties, 'mrr_cents'), timestamp) AS mrr_cents, " +
+		"argMax(event, timestamp) AS last_event, " +
+		"min(timestamp) AS started, " +
+		"argMax(JSONExtractString(properties, 'period_end'), timestamp) AS renews " +
+		"FROM " + core.BillingEventsTable + " " +
+		"WHERE event IN (" + core.SQLInList(core.SubscriptionEvents) + ") " +
+		"AND JSONExtractString(properties, 'subscription_id') != '' " +
+		"GROUP BY id"
+}
+
+// subscriptionRowsFromRows maps the datastore rows onto []SubscriptionRow (pure).
+// Display is the org slug — the warehouse holds no friendly name and admin does
+// no per-org IAM fan-out here (honest, not fabricated). The final status folds
+// the lifecycle: a subscription whose LATEST event is a cancel reads "canceled"
+// regardless of the last-emitted status snapshot.
+func subscriptionRowsFromRows(rows []map[string]any) []SubscriptionRow {
+	out := make([]SubscriptionRow, 0, len(rows))
+	for _, r := range rows {
+		org := core.CHStr(r["org"])
+		out = append(out, SubscriptionRow{
+			ID:       core.CHStr(r["id"]),
+			Org:      org,
+			Display:  org,
+			User:     core.CHStr(r["user"]),
+			Plan:     core.CHStr(r["plan"]),
+			Status:   foldStatus(core.CHStr(r["last_event"]), core.CHStr(r["status"])),
+			MRRCents: core.CHInt64(r["mrr_cents"]),
+			Started:  core.CHTime(r["started"]),
+			Renews:   core.CHStr(r["renews"]),
+		})
+	}
+	return out
+}
+
+// foldStatus resolves the effective status: a subscription whose latest event is
+// a cancel is "canceled"; otherwise the last-emitted status snapshot (falling
+// back to "active" when the emitter sent none).
+func foldStatus(lastEvent, snapshot string) string {
+	if lastEvent == core.EvSubscriptionCanceled {
+		return "canceled"
+	}
+	if s := strings.TrimSpace(snapshot); s != "" {
+		return s
+	}
+	return "active"
+}
+
+// parseLimit clamps the fleet-list cap to [1,5000], defaulting to defaultLimit.
+func parseLimit(s string) int {
+	n, err := strconv.Atoi(strings.TrimSpace(s))
+	if err != nil || n <= 0 {
+		return defaultLimit
+	}
+	if n > 5000 {
+		return 5000
+	}
+	return n
+}
@@ -0,0 +1,91 @@
+package subscriptions
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/hanzoai/cloud/clients/admin/core"
+)
+
+// TestSubscriptionRowsFromRows proves the warehouse-row → SubscriptionRow mapping
+// (the JSON-shape contract) coerces the datastore driver's native types and folds
+// the lifecycle status; display honestly mirrors the org slug (no fan-out).
+func TestSubscriptionRowsFromRows(t *testing.T) {
+	started := time.Date(2026, 7, 1, 12, 0, 0, 0, time.UTC)
+	rows := []map[string]any{
+		{ // active (mrr as driver int64), latest event renewed
+			"id": "sub_1", "org": "acme", "user": "hanzo/alice",
+			"plan": "Pro", "status": "active", "mrr_cents": int64(4900),
+			"last_event": core.EvSubscriptionRenewed, "started": started,
+			"renews": "2026-08-01T00:00:00Z",
+		},
+		{ // canceled wins over a stale "active" snapshot
+			"id": "sub_2", "org": "beta", "user": "hanzo/bob",
+			"plan": "Team", "status": "active", "mrr_cents": uint64(0),
+			"last_event": core.EvSubscriptionCanceled, "started": started,
+			"renews": "",
+		},
+	}
+	out := subscriptionRowsFromRows(rows)
+	if len(out) != 2 {
+		t.Fatalf("got %d rows, want 2", len(out))
+	}
+	r0 := out[0]
+	if r0.ID != "sub_1" || r0.Org != "acme" || r0.Display != "acme" || r0.User != "hanzo/alice" {
+		t.Fatalf("row0 identity wrong: %+v", r0)
+	}
+	if r0.Plan != "Pro" || r0.Status != "active" || r0.MRRCents != 4900 {
+		t.Fatalf("row0 plan/status/mrr wrong: %+v", r0)
+	}
+	if r0.Started != "2026-07-01T12:00:00Z" {
+		t.Fatalf("row0 started = %q", r0.Started)
+	}
+	if r0.Renews != "2026-08-01T00:00:00Z" {
+		t.Fatalf("row0 renews = %q", r0.Renews)
+	}
+	if out[1].Status != "canceled" {
+		t.Fatalf("row1 status = %q, want canceled (latest-event folds)", out[1].Status)
+	}
+}
+
+func TestFoldStatus(t *testing.T) {
+	if got := foldStatus(core.EvSubscriptionCanceled, "active"); got != "canceled" {
+		t.Fatalf("cancel fold = %q", got)
+	}
+	if got := foldStatus(core.EvSubscriptionRenewed, "trialing"); got != "trialing" {
+		t.Fatalf("snapshot passthrough = %q", got)
+	}
+	if got := foldStatus(core.EvSubscriptionCreated, ""); got != "active" {
+		t.Fatalf("empty-snapshot default = %q", got)
+	}
+}
+
+// TestSubscriptionsSQLInjectionSafe asserts the query is fully static over the
+// closed event-name set — the warehouse table, no user-derived interpolation.
+func TestSubscriptionsSQLInjectionSafe(t *testing.T) {
+	sql := subscriptionsSQL()
+	if !strings.Contains(sql, core.BillingEventsTable) {
+		t.Fatalf("query must read %s: %q", core.BillingEventsTable, sql)
+	}
+	for _, ev := range core.SubscriptionEvents {
+		if !strings.Contains(sql, "'"+ev+"'") {
+			t.Fatalf("query missing event %q", ev)
+		}
+	}
+	if strings.Contains(sql, "?") {
+		t.Fatalf("subscriptions state query takes no positional args: %q", sql)
+	}
+}
+
+func TestParseLimitBounds(t *testing.T) {
+	if parseLimit("") != defaultLimit || parseLimit("0") != defaultLimit || parseLimit("x") != defaultLimit {
+		t.Fatal("bad/empty limit must default")
+	}
+	if parseLimit("10") != 10 {
+		t.Fatal("valid limit must pass through")
+	}
+	if parseLimit("999999") != 5000 {
+		t.Fatal("limit must clamp to 5000")
+	}
+}
@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.

-package featuregate
+package admission

 import (
 	"context"
@@ -31,7 +31,7 @@ import (
 // approval is FAIL-OPEN: a user is approved unless properties.approvalStatus is
 // EXACTLY "pending" (absent / "approved" / "rejected" all read approved via
 // IsApproved). Only "pending" holds a user on the waitlist. Keeping the literal
-// here (not importing IAM) keeps featuregate self-contained.
+// here (not importing IAM) keeps admission self-contained.
 const approvalStatusPending = "pending"

 // approvedHeader is the FORWARD-PERFECT path: once IAM carries approvalStatus in
@@ -1,7 +1,7 @@
 // Copyright 2023-2026 Hanzo AI Inc. All Rights Reserved.
 // Licensed under the Apache License, Version 2.0.

-package featuregate
+package admission

 import (
 	"context"
@@ -12,16 +12,24 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.

-// Package featuregate is the launch-control ENFORCEMENT for Hanzo's hosted services:
-// the native middleware (Enforce) + the per-user approval predicate (Approvals, reused
-// from IAM). It is a CONSUMER of the ONE policy engine — the per-service waitlist MODE
-// and the host→service registry live in clients/flags (a service's mode IS the
-// switch waitlist.<svc>, evaluated through the native engine); the admin board is the
-// /v1/admin/services lens and the guard's runtime mode read is /v1/featuregate/mode,
-// both served there. This package owns only enforcement, decomplected into two axes:
+// Package admission is the launch-control GATE for Hanzo's hosted services — the
+// COMPLETE waitlist feature, COMPOSING the ONE flag engine (clients/flags) one-way. It
+// owns:
 //
-//   - PER-SERVICE  waitlist mode on|off  — the flags switch waitlist.<svc>,
-//     resolved for a request host via flags.WaitlistModeForHost (the decide).
+//   - the host→service registry (registry.go) + the brand seed (waitlist.go),
+//   - the per-service MODE decide WaitlistModeForHost — a service's mode IS the switch
+//     waitlist.<svc>, evaluated through the flag engine (flags.Bool),
+//   - the admin control funcs (List/Set/Upsert) the /v1/admin/services board calls,
+//   - the guard's public mode read /v1/flags/waitlist, Mount,
+//   - the native enforcement middleware (Enforce, this file),
+//   - the per-user approval predicate (Approvals, reused from IAM — approval.go).
+//
+// flags NEVER imports admission; admission imports flags. The engine is the pure
+// (Principal, context) -> verdict primitive; this package is its first composed tenant.
+// Enforcement is decomplected into two orthogonal axes:
+//
+//   - PER-SERVICE  waitlist mode on|off  — the switch waitlist.<svc>, resolved for a
+//     request host via WaitlistModeForHost (the decide, waitlist.go).
 //   - PER-USER     approvalStatus pending|approved — owned by IAM (approval.go), REUSED.
 //
 // THE RULE, applied at ONE native enforcement point (Enforce):
@@ -29,14 +37,13 @@
 //	if waitlistMode[host] AND NOT user.approved → bounce to the waitlist
 //	if approved OR mode=off                     → allow
 //	unauthenticated                             → login first
-package featuregate
+package admission

 import (
 	"context"
 	"net/http"
 	"strings"

-	"github.com/hanzoai/cloud/clients/flags"
 	"github.com/zap-proto/zip"
 )

@@ -59,13 +66,13 @@ import (
 // INTEGRATION POINT — wire in serve.go RIGHT AFTER SanitizeIdentity:
 //
 //	app.Use(IdentityMiddleware(cfg))          // establishes the validated principal
-//	app.Use(featuregate.Enforce(featuregate.EnforceConfig{ WaitlistURL: … }))  // ← here
+//	app.Use(admission.Enforce(admission.EnforceConfig{ WaitlistURL: … }))  // ← here
 //
 // It reads the sanitized X-User-Id / X-User-IsAdmin / X-User-Approved that
 // IdentityMiddleware minted, so it MUST run after it and (like BillingGate) before
 // the subsystem handlers. It is deliberately NOT wired here — the unified-binary
 // agent owns serve.go's boot chain; this package exposes Enforce so the one-line
-// app.Use lands without a merge collision. The decide (flags.WaitlistModeForHost) is
+// app.Use lands without a merge collision. The decide (WaitlistModeForHost) is
 // resolved PER REQUEST and fail-opens until the flags engine has mounted, so Enforce
 // can be constructed before Mount runs.
 //
@@ -102,7 +109,7 @@ type EnforceConfig struct {
 	ExemptPrefixes []string

 	// Gate is THE decide: it resolves whether a request host is in waitlist mode,
-	// via the ONE policy engine. When nil it is flags.WaitlistModeForHost —
+	// via the ONE policy engine. When nil it is WaitlistModeForHost —
 	// host→service→waitlist.<svc>. Injected only in tests. Fail-open by contract:
 	// known=false (unmounted / registry error / un-governed host) → not gated.
 	Gate func(ctx context.Context, host string) (mode bool, service string, known bool)
@@ -112,9 +119,9 @@ type EnforceConfig struct {
 // health, the auth/OIDC handshake, and the waitlist join API itself (so a gated
 // user can still submit the waitlist form).
 var defaultExemptPrefixes = []string{
-	"/v1/featuregate/", // the mode read + the health route
-	"/v1/iam/",         // auth / OIDC / approval-status / get-account handshake
-	"/v1/waitlist",     // the waitlist join API (a gated user must reach it)
+	"/v1/flags/waitlist", // the guard's public mode read (flags engine)
+	"/v1/iam/",           // auth / OIDC / approval-status / get-account handshake
+	"/v1/waitlist",       // the waitlist join API (a gated user must reach it)
 	"/health",
 	"/healthz",
 	"/__guard/", // the @file guard's own callback surface (defense in depth)
@@ -131,7 +138,7 @@ func Enforce(cfg EnforceConfig) zip.Handler {
 	}
 	gate := cfg.Gate
 	if gate == nil {
-		gate = flags.WaitlistModeForHost // the ONE decide: host→service→waitlist.<svc>
+		gate = WaitlistModeForHost // the ONE decide: host→service→waitlist.<svc>
 	}
 	exempt := cfg.ExemptPrefixes
 	if len(exempt) == 0 {
@@ -199,7 +206,7 @@ func bounce(c *zip.Ctx, waitlistURL string) error {
 }

 // apiKeyPrefixes are the Hanzo API-key prefixes. This MIRRORS cloud
-// auth_identity.go isAPIKey (the ONE authority) — kept local so featuregate stays
+// auth_identity.go isAPIKey (the ONE authority) — kept local so admission stays
 // self-contained (no cloud-internal import) while agreeing on the exact contract:
 // a token with one of these prefixes is a possession-gated API key, not a session
 // principal. If cloud adds a prefix there, add it here.
@@ -1,7 +1,7 @@
 // Copyright 2023-2026 Hanzo AI Inc. All Rights Reserved.
 // Licensed under the Apache License, Version 2.0.

-package featuregate
+package admission

 import (
 	"context"
@@ -16,7 +16,7 @@ import (

 // testGate is the injected decide (the flags engine's WaitlistModeForHost seam):
 // hanzo.chat is gated, api.hanzo.ai is open, everything else is un-governed. This is
-// exactly what flags.WaitlistModeForHost returns for the equivalent registry, without
+// exactly what WaitlistModeForHost returns for the equivalent registry, without
 // standing up the native flag engine (cgo) in a middleware unit test.
 func testGate(_ context.Context, host string) (mode bool, service string, known bool) {
 	switch host {
@@ -186,7 +186,7 @@ func TestRule_UngovernedHost_PassesThrough(t *testing.T) {

 func TestRule_ExemptPaths_NeverGated(t *testing.T) {
 	app := gateApp(t, "pending")
-	for _, p := range []string{"/health", "/v1/iam/get-account", "/v1/waitlist/join", "/v1/featuregate/mode"} {
+	for _, p := range []string{"/health", "/v1/iam/get-account", "/v1/waitlist/join", "/v1/flags/waitlist"} {
 		code, _ := drive(t, app, greq{host: "hanzo.chat", path: p, user: "u", org: "acme", accept: html})
 		if code != 200 {
 			t.Fatalf("exempt path %q = %d, want 200 (never gated)", p, code)
@@ -205,7 +205,7 @@ func TestRule_ForwardHeaderApproved_ThroughWithoutLookup(t *testing.T) {
 	}
 }

-// The DEFAULT gate (nil Gate → flags.WaitlistModeForHost) fail-opens before the flags
+// The DEFAULT gate (nil Gate → WaitlistModeForHost) fail-opens before the flag
 // engine has mounted: with no engine, WaitlistModeForHost returns known=false for every
 // host, so Enforce never gates pre-boot.
 func TestEnforce_DefaultGate_FailsOpenPreBoot(t *testing.T) {
@@ -1,11 +1,11 @@
-package flags
+package admission

-// The waitlist REGISTRY — the host→service map + service metadata folded in from
-// the former clients/featuregate SQLite store. It is deliberately MODE-FREE: a
-// service's waitlist mode is NOT a column here, it is the platform switch
-// waitlist.<svc> evaluated through the ONE native engine (waitlist.go). This store
-// answers only "which service owns this host, and what is its display metadata" —
-// the config the decide needs, with the decision itself owned by the flag engine.
+// The launch-registry — the host→service map + service display metadata. It is
+// deliberately MODE-FREE: a service's waitlist mode is NOT a column here, it is the
+// platform switch waitlist.<svc> evaluated through the ONE flag engine (clients/flags,
+// composed one-way from waitlist.go). This store answers only "which service owns this
+// host, and what is its display metadata" — the config the decide needs, with the
+// decision itself owned by the flag engine.
 //
 // It rides the SAME per-(org,project) OrgDB machinery as the flag defs (opened via
 // cloud.OrgStore, encrypted at rest via cek); the registry is PLATFORM-global, so it
@@ -21,7 +21,7 @@ import (
 )

 // ErrServiceNotFound is returned when a service slug is not in the registry.
-var ErrServiceNotFound = errors.New("flags: waitlist service not found")
+var ErrServiceNotFound = errors.New("admission: waitlist service not found")

 // ServiceRow is one hosted service in the registry (host→service + metadata). The
 // waitlist MODE is intentionally absent — it is the platform switch waitlist.<svc>,
@@ -45,7 +45,7 @@ type waitlistStore struct {
 }

 // openWaitlistStore migrates the registry schema over an already-opened (pragma'd,
-// cek-wrapped) OrgDB handle — the same open contract as openStore for flag defs.
+// cek-wrapped) OrgDB handle — the same open contract as flags' openStore for flag defs.
 func openWaitlistStore(db *sql.DB) (*waitlistStore, error) {
 	const schema = `
 CREATE TABLE IF NOT EXISTS wl_services (
@@ -64,7 +64,7 @@ CREATE TABLE IF NOT EXISTS wl_hosts (
 CREATE INDEX IF NOT EXISTS ix_wl_hosts_service ON wl_hosts(service);
 `
 	if _, err := db.Exec(schema); err != nil {
-		return nil, fmt.Errorf("flags: waitlist migrate: %w", err)
+		return nil, fmt.Errorf("admission: waitlist migrate: %w", err)
 	}
 	return &waitlistStore{db: db}, nil
 }
@@ -210,7 +210,7 @@ func (s *waitlistStore) Get(ctx context.Context, service string) (ServiceRow, er
 func (s *waitlistStore) Upsert(ctx context.Context, in ServiceRow, by string, now int64) (ServiceRow, error) {
 	svc := strings.ToLower(strings.TrimSpace(in.Service))
 	if svc == "" {
-		return ServiceRow{}, fmt.Errorf("flags: waitlist service slug required")
+		return ServiceRow{}, fmt.Errorf("admission: waitlist service slug required")
 	}
 	tx, err := s.db.BeginTx(ctx, nil)
 	if err != nil {
@@ -1,9 +1,9 @@
-package flags
+package admission

-// Registry coverage for the folded host→service store. It drives the store over a raw
-// sqlite handle (the same driver OrgDB uses), so it exercises the fold WITHOUT the cek
+// Registry coverage for the host→service store. It drives the store over a raw sqlite
+// handle (the same driver OrgDB uses), so it exercises the registry WITHOUT the cek
 // at-rest layer — runnable under CGO=0. The MODE is out of scope here by design (it is
-// the waitlist.<svc> switch, evaluated by the native engine, covered separately).
+// the waitlist.<svc> switch, evaluated by the flag engine, covered separately).

 import (
 	"context"
@@ -1,19 +1,23 @@
-package flags
+package admission

-// The waitlist LENS on the ONE flag engine — the launch-control plane folded in from
-// the former clients/featuregate. Decomplected into the two orthogonal axes it always
-// was, now with a single decision plane:
+// The launch-control gate — the COMPLETE waitlist feature, COMPOSING the ONE flag
+// engine (clients/flags) one-way. Decomplected into the two orthogonal axes it always
+// was, with a single decision plane:
 //
 //   - MODE (per service):  waitlist.<svc> IS a platform switch, evaluated through the
-//     SAME native engine as every other platform flag. There is no second mode store.
-//   - HOST MAP + metadata:  the registry (waitlist_store.go) resolves a request host
-//     to the service whose switch governs it, and carries display metadata.
+//     flag engine (flags.Bool / flags.SetPlatformSwitch / flags.Register). There is no
+//     second mode store.
+//   - HOST MAP + metadata:  the registry (registry.go) resolves a request host to the
+//     service whose switch governs it, and carries display metadata.
 //
 // The decide is WaitlistModeForHost(host) → (mode, service, known): resolve host→svc,
-// then read waitlist.<svc>. featuregate.Enforce is now a CONSUMER of this decide, and
-// /v1/featuregate/mode + the /v1/admin/services board read it too. Per-user approval
-// (pending|approved) stays IAM's (featuregate/approval.go) — the second, orthogonal
-// axis, unchanged.
+// then read waitlist.<svc>. Enforce (middleware.go) consumes this decide; the admin
+// board (/v1/admin/services) and the guard's runtime mode read (/v1/flags/waitlist,
+// served here) read it too. Per-user approval (pending|approved) is the second,
+// orthogonal axis — IAM's, in approval.go.
+//
+// flags NEVER imports this package; this package imports flags. That one-way arrow is
+// the whole point of the decomplection: the engine is pure, the feature composes it.

 import (
 	"context"
@@ -25,10 +29,29 @@ import (
 	"time"

 	"github.com/hanzoai/cloud"
+	"github.com/hanzoai/cloud/clients/flags"
 	luxlog "github.com/luxfi/log"
 	"github.com/zap-proto/zip"
 )

+// The reserved platform tenant the launch registry rides in — the SAME reserved
+// (org, project) the flag engine uses for its platform switches, so the registry and
+// the waitlist.<svc> switches co-locate. One waitlist.db for the deployment.
+const (
+	platformOrg     = "platform"
+	platformProject = "platform"
+)
+
+// registryState is admission's process-wide launch state: the platform-tenant
+// host→service registry store + the deployment brand it was seeded for. Installed by
+// Mount, torn down by Shutdown.
+type registryState struct {
+	store *cloud.OrgStore[*waitlistStore]
+	brand string
+}
+
+var mounted *registryState
+
 // SeedService is one row of the launch registry (a hosted service + its hosts). Mode
 // is intentionally absent — the launch posture (gated) is waitlistDef's Default "true".
 type SeedService struct {
@@ -60,17 +83,17 @@ func waitlistKey(svc string) string { return "waitlist." + strings.ToLower(strin

 // waitlistDef is the platform switch for one service's mode. Default "true" = the
 // launch posture (gated until an admin opens it), so a deployment with no stored flag
-// behaves exactly as the old featuregate seed (waitlistMode ON).
-func waitlistDef(svc, display string) Def {
+// behaves exactly as the old admission seed (waitlistMode ON).
+func waitlistDef(svc, display string) flags.Def {
 	if strings.TrimSpace(display) == "" {
 		display = svc
 	}
-	return Def{
+	return flags.Def{
 		Key:      waitlistKey(svc),
 		Category: "Launch",
 		Label:    "Waitlist · " + display,
 		Desc:     "Waitlist mode for " + display + ": ON gates the service to APPROVED users; OFF opens it.",
-		Type:     TypeBool,
+		Type:     flags.TypeBool,
 		Default:  "true",
 	}
 }
@@ -78,9 +101,13 @@ func waitlistDef(svc, display string) Def {
 // ensureWaitlistDef registers a service's switch if it is not already registered
 // (Mount registers the seed set with nicer labels; this covers runtime onboards).
 func ensureWaitlistDef(svc, display string) {
-	if _, ok := lookupDef(waitlistKey(svc)); !ok {
-		Register(waitlistDef(svc, display))
+	key := waitlistKey(svc)
+	for _, d := range flags.Defs() {
+		if d.Key == key {
+			return
+		}
 	}
+	flags.Register(waitlistDef(svc, display))
 }

 // boolDef is the minimal PostHog flag definition for a boolean switch value.
@@ -92,26 +119,24 @@ func boolDef(on bool) json.RawMessage {
 }

 // requireRegistry resolves the platform-tenant registry store, or an error when the
-// engine is not mounted (writes need it; the decide fail-opens instead).
+// gate is not mounted (writes need it; the decide fail-opens instead).
 func requireRegistry() (*waitlistStore, error) {
-	c := mounted
-	if c == nil || c.registry == nil {
-		return nil, fmt.Errorf("flags: waitlist registry not mounted")
+	if mounted == nil || mounted.store == nil {
+		return nil, fmt.Errorf("admission: waitlist registry not mounted")
 	}
-	return c.registry.For(platformOrg, platformProject)
+	return mounted.store.For(platformOrg, platformProject)
 }

-// WaitlistModeForHost is THE decide the Enforce consumer, /v1/featuregate/mode, and
+// WaitlistModeForHost is THE decide the Enforce consumer, /v1/flags/waitlist, and
 // the admin board call: resolve host→service, then read the waitlist.<svc> switch
-// through the engine. FAIL-OPEN by construction — an unmounted registry, a store
+// through the flag engine. FAIL-OPEN by construction — an unmounted registry, a store
 // error, or an un-governed host all return known=false, so a request is NEVER gated
 // pre-boot or on a registry fault (availability over a hard gate, matching the guard).
 func WaitlistModeForHost(ctx context.Context, host string) (mode bool, service string, known bool) {
-	c := mounted
-	if c == nil || c.registry == nil {
+	if mounted == nil || mounted.store == nil {
 		return false, "", false
 	}
-	st, err := c.registry.For(platformOrg, platformProject)
+	st, err := mounted.store.For(platformOrg, platformProject)
 	if err != nil {
 		return false, "", false
 	}
@@ -119,7 +144,7 @@ func WaitlistModeForHost(ctx context.Context, host string) (mode bool, service s
 	if err != nil || !known {
 		return false, "", false
 	}
-	return Bool(waitlistKey(svc)), svc, true
+	return flags.Bool(waitlistKey(svc)), svc, true
 }

 // ListWaitlistServices returns the admin board: every registered service with its LIVE
@@ -135,19 +160,19 @@ func ListWaitlistServices(ctx context.Context) ([]ServiceView, error) {
 	}
 	out := make([]ServiceView, 0, len(rows))
 	for _, r := range rows {
-		out = append(out, ServiceView{ServiceRow: r, WaitlistMode: Bool(waitlistKey(r.Service))})
+		out = append(out, ServiceView{ServiceRow: r, WaitlistMode: flags.Bool(waitlistKey(r.Service))})
 	}
 	return out, nil
 }

 // SetWaitlistMode flips one service's waitlist switch — the launch lever — and returns
-// the updated view. It is the ONE write path (through SetPlatformSwitch, audited in the
-// flag activity log); the flip is hot (this pod applies immediately, peers converge
-// within the eval TTL). ErrServiceNotFound when the slug is unknown.
+// the updated view. It is the ONE write path (through flags.SetPlatformSwitch, audited
+// in the flag activity log); the flip is hot (this pod applies immediately, peers
+// converge within the eval TTL). ErrServiceNotFound when the slug is unknown.
 func SetWaitlistMode(ctx context.Context, service string, mode bool, actor string) (ServiceView, error) {
 	service = strings.ToLower(strings.TrimSpace(service))
 	if service == "" {
-		return ServiceView{}, fmt.Errorf("flags: service is required")
+		return ServiceView{}, fmt.Errorf("admission: service is required")
 	}
 	st, err := requireRegistry()
 	if err != nil {
@@ -158,10 +183,10 @@ func SetWaitlistMode(ctx context.Context, service string, mode bool, actor strin
 		return ServiceView{}, err
 	}
 	ensureWaitlistDef(service, row.DisplayName)
-	if err := SetPlatformSwitch(waitlistKey(service), boolDef(mode), actor); err != nil {
+	if err := flags.SetPlatformSwitch(waitlistKey(service), boolDef(mode), actor); err != nil {
 		return ServiceView{}, err
 	}
-	return ServiceView{ServiceRow: row, WaitlistMode: Bool(waitlistKey(service))}, nil
+	return ServiceView{ServiceRow: row, WaitlistMode: flags.Bool(waitlistKey(service))}, nil
 }

 // UpsertWaitlistService onboards or edits a hosted service so a new host is governed
@@ -170,7 +195,7 @@ func SetWaitlistMode(ctx context.Context, service string, mode bool, actor strin
 func UpsertWaitlistService(ctx context.Context, in ServiceInput, actor string) (ServiceView, error) {
 	svc := strings.ToLower(strings.TrimSpace(in.Service))
 	if svc == "" {
-		return ServiceView{}, fmt.Errorf("flags: service slug is required")
+		return ServiceView{}, fmt.Errorf("admission: service slug is required")
 	}
 	st, err := requireRegistry()
 	if err != nil {
@@ -192,43 +217,44 @@ func UpsertWaitlistService(ctx context.Context, in ServiceInput, actor string) (
 	}
 	ensureWaitlistDef(svc, row.DisplayName)
 	if isNew {
-		if err := SetPlatformSwitch(waitlistKey(svc), boolDef(in.WaitlistMode), actor); err != nil {
+		if err := flags.SetPlatformSwitch(waitlistKey(svc), boolDef(in.WaitlistMode), actor); err != nil {
 			return ServiceView{}, err
 		}
 	}
-	return ServiceView{ServiceRow: row, WaitlistMode: Bool(waitlistKey(svc))}, nil
+	return ServiceView{ServiceRow: row, WaitlistMode: flags.Bool(waitlistKey(svc))}, nil
 }

-// mountWaitlist seeds the registry and registers a waitlist.<svc> switch per known
-// service. Best-effort + fail-safe: a registry error (e.g. cek master key not yet
-// injected) degrades to the in-memory seed switches — the decide then fail-opens,
-// exactly the flag engine's own boot posture. Called from Mount.
-func mountWaitlist(c *Client, brand string, log luxlog.Logger) {
+// seedRegistry seeds the registry and registers a waitlist.<svc> switch per known
+// service, COMPOSING the flag engine (flags.Register). Best-effort + fail-safe: a
+// registry error (e.g. cek master key not yet injected) degrades to the in-memory seed
+// switches — the decide then fail-opens, exactly the flag engine's own boot posture.
+// Returns the number of seeded services (for the mount log). Called from Mount.
+func seedRegistry(brand string, log luxlog.Logger) int {
 	seed := seedWaitlist(brand)
 	for _, sv := range seed { // in-memory switches — always succeeds
-		Register(waitlistDef(sv.Service, sv.DisplayName))
+		flags.Register(waitlistDef(sv.Service, sv.DisplayName))
 	}
-	st, err := c.registry.For(platformOrg, platformProject)
+	st, err := mounted.store.For(platformOrg, platformProject)
 	if err != nil {
 		log.Warn("waitlist registry unavailable — modes degrade to seed defaults", "err", err)
-		return
+		return len(seed)
 	}
 	if _, err := st.Seed(context.Background(), seed, time.Now().Unix()); err != nil {
 		log.Warn("waitlist registry seed failed", "err", err)
-		return
+		return len(seed)
 	}
 	if rows, err := st.List(context.Background()); err == nil {
 		for _, r := range rows { // register any persisted onboard beyond the seed
 			ensureWaitlistDef(r.Service, r.DisplayName)
 		}
 	}
+	return len(seed)
 }

-// waitlistModeRoute answers GET /v1/featuregate/mode?host=<h> — the runtime lookup the
+// waitlistModeRoute answers GET /v1/flags/waitlist?host=<h> — the runtime lookup the
 // @file waitlist-guard caches. Public (in-cluster) read: it returns ONLY the boolean
-// mode for the ONE queried host, never an enumeration. Same wire shape as the former
-// featuregate route, so the interim guard ports 1:1.
-func waitlistModeRoute(_ *cloud.Service[state], c *zip.Ctx) error {
+// mode for the ONE queried host, never an enumeration.
+func waitlistModeRoute(c *zip.Ctx) error {
 	host := strings.TrimSpace(c.Query("host"))
 	if host == "" {
 		host = c.Fiber().Hostname()
@@ -242,7 +268,44 @@ func waitlistModeRoute(_ *cloud.Service[state], c *zip.Ctx) error {
 	})
 }

-// ── brand seed (moved verbatim from the former featuregate/seed.go) ──────────────
+// ── lifecycle ────────────────────────────────────────────────────────────────
+
+// Mount installs the launch-control gate: it opens the platform-tenant host→service
+// registry, seeds it for the deployment brand, registers a waitlist.<svc> switch per
+// service in the flag engine (flags.Register), and serves the guard's public mode read
+// at /v1/flags/waitlist. Fail-safe: a registry error (e.g. cek master key not yet
+// injected) degrades to the in-memory seed switches — WaitlistModeForHost then
+// fail-opens. Mounts AFTER flags so the engine's platform-switch plane is installed first.
+func Mount(app *zip.App, deps cloud.Deps) error {
+	if deps.Logger == nil {
+		return fmt.Errorf("admission.Mount: nil deps.Logger")
+	}
+	if deps.DataDir == "" {
+		return fmt.Errorf("admission.Mount: empty deps.DataDir")
+	}
+	log := deps.Logger.New("subsystem", "admission")
+	mounted = &registryState{
+		store: cloud.NewOrgStore[*waitlistStore](deps.DataDir, "waitlist", openWaitlistStore),
+		brand: deps.Brand,
+	}
+	n := seedRegistry(deps.Brand, log)
+	// The guard's public runtime mode read (host→service→waitlist.<svc>), one namespace
+	// under /v1/flags. Exempt from the Enforce gate (see defaultExemptPrefixes) so a
+	// gated user can still resolve mode.
+	app.Get("/v1/flags/waitlist", waitlistModeRoute)
+	log.Info("admission gate ready", "services", n)
+	return nil
+}
+
+// Shutdown closes the launch registry's per-org store handles.
+func Shutdown() error {
+	if mounted == nil || mounted.store == nil {
+		return nil
+	}
+	return mounted.store.CloseAll()
+}
+
+// ── brand seed (moved verbatim from the former flags/waitlist.go) ────────────────

 // seedWaitlist returns the launch registry for a brand. White-labeled so a Lux/Zoo/Pars
 // deployment governs its OWN hosts. New hosted services onboard at runtime via
@@ -32,6 +32,7 @@ package ads
 import (
 	"crypto/rand"
 	"encoding/hex"
+	"errors"
 	"fmt"
 	"net/http"
 	"os"
@@ -106,13 +107,15 @@ func Mount(app *zip.App, deps cloud.Deps) error {

 // routes registers the ads surface: the campaign CRUD + the summary roll-up.
 func routes(app *zip.App, s *cloud.Service[state]) {
-	app.Get("/v1/ads/summary", cloud.Handle(s, summary))
+	g := app.Group("/v1/ads")
+	g.Get("/summary", cloud.Handle(s, summary))

-	app.Get("/v1/ads/campaigns", cloud.Handle(s, listCampaigns))
-	app.Post("/v1/ads/campaigns", cloud.Handle(s, createCampaign))
-	app.Get("/v1/ads/campaigns/:id", cloud.Handle(s, getCampaign))
-	app.Put("/v1/ads/campaigns/:id", cloud.Handle(s, updateCampaign))
-	app.Delete("/v1/ads/campaigns/:id", cloud.Handle(s, deleteCampaign))
+	g.Get("/campaigns", cloud.Handle(s, listCampaigns))
+	g.Post("/campaigns", cloud.Handle(s, createCampaign))
+	g.Get("/campaigns/:id", cloud.Handle(s, getCampaign))
+	g.Put("/campaigns/:id", cloud.Handle(s, updateCampaign))
+	g.Delete("/campaigns/:id", cloud.Handle(s, deleteCampaign))
+	g.Post("/campaigns/:id/launch", cloud.Handle(s, launchCampaignHandler))
 }

 // ---- shared helpers (mirror clients/crm) ----
@@ -223,7 +226,7 @@ func createCampaign(s *cloud.Service[state], c *zip.Ctx) error {
 	}
 	now := time.Now().Unix()
 	camp := Campaign{
-		ID: id, Org: org, Name: name, Platform: platform, Status: status,
+		ID: id, Org: org, Name: name, Platform: platform, Account: clip(body.Account), Status: status,
 		Objective: clip(body.Objective), Budget: nonNeg(body.Budget), Spend: nonNeg(body.Spend),
 		CreatedAt: now, UpdatedAt: now,
 	}
@@ -281,7 +284,7 @@ func updateCampaign(s *cloud.Service[state], c *zip.Ctx) error {
 		return zip.ErrBadRequest("status must be one of draft, active, paused, completed")
 	}
 	camp := Campaign{
-		ID: idParam(c), Org: org, Name: name, Platform: platform, Status: status,
+		ID: idParam(c), Org: org, Name: name, Platform: platform, Account: clip(body.Account), Status: status,
 		Objective: clip(body.Objective), Budget: nonNeg(body.Budget), Spend: nonNeg(body.Spend),
 		UpdatedAt: time.Now().Unix(),
 	}
@@ -307,6 +310,63 @@ func deleteCampaign(s *cloud.Service[state], c *zip.Ctx) error {
 	return c.NoContent(http.StatusNoContent)
 }

+// ---- launch (consumes the connector plane) ----
+
+// launchCampaignHandler runs a stored ad campaign on its provider using the ORG'S
+// connected ad-account token. It is the standalone proof that /v1/ads consumes the
+// connector plane: no token is held here — LaunchPaid (provider.go) resolves it
+// from KMS through integrations.TokenFor and FAILS CLOSED when the org has not
+// connected the platform (424), so a launch can never spend on a connection the
+// org did not make. On success the provider campaign id is recorded (MarkLaunched)
+// and the campaign goes active. An optional body {account} sets/overrides the
+// target ad account when the stored campaign has none.
+func launchCampaignHandler(s *cloud.Service[state], c *zip.Ctx) error {
+	org, ok := tenant(c)
+	if !ok {
+		return zip.ErrForbidden("X-Org-Id required")
+	}
+	camp, err := s.State.store.GetCampaign(c.Context(), org, idParam(c))
+	if err != nil {
+		return mapErr(err, "campaign not found")
+	}
+	var body struct {
+		Account string `json:"account"`
+	}
+	_ = c.Bind(&body)
+	account := clip(body.Account)
+	if account == "" {
+		account = camp.Account
+	}
+	ref, lerr := LaunchPaid(c.Context(), org, PaidPlan{
+		Platform: camp.Platform, Account: account, Name: camp.Name,
+		Objective: camp.Objective, BudgetCents: camp.Budget,
+	})
+	if lerr != nil {
+		return mapProviderErr(lerr)
+	}
+	saved, err := s.State.store.MarkLaunched(c.Context(), org, camp.ID, ref.Account, ref.ExternalID, time.Now().Unix())
+	if err != nil {
+		return mapErr(err, "campaign not found")
+	}
+	return c.JSON(http.StatusOK, saved)
+}
+
+// mapProviderErr renders a provider-execution error as the honest HTTP status: a
+// missing/rejected connection is 424 (connect the account first), an unwired
+// platform is 501, a transient edge failure is 502.
+func mapProviderErr(err error) error {
+	switch {
+	case errors.Is(err, errNotConnected):
+		return zip.Errorf(http.StatusFailedDependency, "connect your ad account for this platform first")
+	case errors.Is(err, errUnsupportedPlatform):
+		return zip.Errorf(http.StatusNotImplemented, "%v", err)
+	case errors.Is(err, errUpstream):
+		return zip.Errorf(http.StatusBadGateway, "%v", err)
+	default:
+		return zip.Errorf(http.StatusBadRequest, "%v", err)
+	}
+}
+
 // ---- summary ----

 func summary(s *cloud.Service[state], c *zip.Ctx) error {
@@ -0,0 +1,115 @@
+package ads
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"testing"
+
+	"github.com/hanzoai/cloud/clients/campaign"
+)
+
+// campaign_paid_test.go is the END-TO-END proof of the paid GTM channel: the SAME
+// adapter apps/wire_seams.go registers (campaign.Plan → ads.PaidPlan → LaunchPaid)
+// driven through the campaign.Channel interface, so the whole chain
+// campaign → ads → integrations.TokenFor → provider is exercised against an
+// httptest Meta stub. It lives in package ads because only this package can point
+// the connector-custody seam (tokenFor) and the Meta base at test doubles;
+// importing clients/campaign here is acyclic (campaign never imports ads).
+
+// paidChannelForTest builds the exact paid-channel adapter the composition root
+// wires, so the test exercises the real seam shape, not a bespoke one.
+func paidChannelForTest() campaign.Channel {
+	return campaign.NewChannel(campaign.KindPaid,
+		func(ctx context.Context, org string, p campaign.Plan) (campaign.Ref, error) {
+			r, err := LaunchPaid(ctx, org, PaidPlan{
+				Platform: p.Platform, Account: p.Account, Name: p.Name,
+				Objective: p.Objective, BudgetCents: p.BudgetCents, ScheduleAt: p.ScheduleAt,
+			})
+			return campaign.Ref{Platform: r.Platform, Account: r.Account, ExternalID: r.ExternalID, Status: r.Status, Detail: r.Detail}, err
+		},
+		func(ctx context.Context, org string, ref campaign.Ref) (int64, error) {
+			return PaidSpend(ctx, org, PaidRef{Platform: ref.Platform, Account: ref.Account, ExternalID: ref.ExternalID})
+		},
+		func(ctx context.Context, org string, ref campaign.Ref) error {
+			return PausePaid(ctx, org, PaidRef{Platform: ref.Platform, Account: ref.Account, ExternalID: ref.ExternalID})
+		},
+	)
+}
+
+// TestCampaignPaidChannel_EndToEnd: a campaign's paid channel launches an ad
+// campaign on Meta using the ORG'S connected token, then reads spend — the full
+// capability→connector→provider chain.
+func TestCampaignPaidChannel_EndToEnd(t *testing.T) {
+	stubToken(t, func(_ context.Context, org, provider, _ string) ([]byte, error) {
+		if provider != "meta_ads" {
+			t.Fatalf("paid meta channel must consume meta_ads, got %q", provider)
+		}
+		return []byte("tok-" + org), nil
+	})
+	var gotAuth string
+	stubMeta(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/act_123/campaigns" {
+			gotAuth = r.Header.Get("Authorization")
+			_, _ = w.Write([]byte(`{"id":"120210000000009"}`))
+			return
+		}
+		if r.URL.Path == "/120210000000009/insights" {
+			_, _ = w.Write([]byte(`{"data":[{"spend":"7.50"}]}`))
+			return
+		}
+		http.NotFound(w, r)
+	})
+
+	paid := paidChannelForTest()
+	if paid.Kind() != campaign.KindPaid {
+		t.Fatalf("channel kind want paid, got %q", paid.Kind())
+	}
+
+	ref, err := paid.Launch(context.Background(), "acme", campaign.Plan{
+		CampaignID: "cmp_1", Platform: "meta", Account: "123", Name: "GTM Launch",
+	})
+	if err != nil {
+		t.Fatalf("paid Launch: %v", err)
+	}
+	if ref.ExternalID != "120210000000009" || ref.Status != "live" {
+		t.Fatalf("ref: %+v", ref)
+	}
+	if gotAuth != "Bearer tok-acme" {
+		t.Fatalf("Meta must be called with acme's connector token, got %q", gotAuth)
+	}
+
+	// Spend read composes the same token door → provider insights.
+	cents, err := paid.Spend(context.Background(), "acme", ref)
+	if err != nil {
+		t.Fatalf("paid Spend: %v", err)
+	}
+	if cents != 750 {
+		t.Fatalf("spend want 750 cents, got %d", cents)
+	}
+}
+
+// TestCampaignPaidChannel_ConnectorDisabledBlocksSend: a campaign whose org has
+// not connected the ad account cannot launch — the channel fails closed and the
+// provider is never called (no spend on an unmade connection).
+func TestCampaignPaidChannel_ConnectorDisabledBlocksSend(t *testing.T) {
+	stubToken(t, func(_ context.Context, _, _, _ string) ([]byte, error) {
+		return nil, errors.New("integrations: meta_ads not connected for org")
+	})
+	hit := false
+	stubMeta(t, func(w http.ResponseWriter, _ *http.Request) {
+		hit = true
+		_, _ = w.Write([]byte(`{"id":"nope"}`))
+	})
+
+	paid := paidChannelForTest()
+	_, err := paid.Launch(context.Background(), "acme", campaign.Plan{
+		CampaignID: "cmp_1", Platform: "meta", Account: "123", Name: "GTM",
+	})
+	if !errors.Is(err, errNotConnected) {
+		t.Fatalf("want errNotConnected, got %v", err)
+	}
+	if hit {
+		t.Fatalf("provider must NOT be called when the org's connector is disabled")
+	}
+}
@@ -0,0 +1,320 @@
+package ads
+
+// provider.go is the ad-network EXECUTION edge: the ONE place /v1/ads consumes the
+// connector plane. An ad campaign runs on a provider (Meta/Google/…) using the
+// ORG'S OWN connector token — resolved at call time from KMS through the
+// integrations.TokenFor custody seam, never held in this process, never in a
+// manifest. This closes the gap the ads store left open: a stored Campaign is now
+// LAUNCHABLE against the real provider, and it is what the /v1/campaign paid
+// channel fans out to (apps/wire_seams.go adapts LaunchPaid/PaidSpend/PausePaid
+// onto campaign.Channel).
+//
+// FAIL-CLOSED CUSTODY. Every operation resolves the org's token FIRST; any reason
+// it cannot be produced — the org never connected the ad account, the integrations
+// plane is unmounted, KMS is down — is errNotConnected, and NO provider call is
+// made. The token rides the Authorization header only (never the URL, never a log,
+// never argv), exactly the meta.go connector discipline.
+//
+// LEAST SURPRISE ON SPEND. A launch creates the campaign OBJECT on the provider;
+// delivery (and therefore spend) does not begin until the ad-set/ad legs are wired
+// (the documented ads follow-up), so a launch cannot silently burn budget. Spend is
+// READ back from the provider's insights (PaidSpend) — the connector's reported
+// number the /v1/campaign metrics plane joins with the analytics funnel.
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/hanzoai/cloud/clients/integrations"
+)
+
+const (
+	// accessTokenSecret is the KMS secret name every ad connector custodies its
+	// long-lived token under (meta.go/google_marketing.go: "access_token").
+	accessTokenSecret = "access_token"
+	// launchTimeout bounds a single provider call so a slow ad edge never wedges a
+	// launch or a metrics read.
+	launchTimeout = 20 * time.Second
+)
+
+// platformConnector maps an ads Platform to its integrations connector id. The
+// paid channel consumes the connector via TokenFor(org, <id>, "access_token").
+// A platform with no entry has no connector wired → errUnsupportedPlatform (the
+// token is never even sought), so the map is the ONE source of "which ad networks
+// this deployment can run".
+var platformConnector = map[string]string{
+	"meta":      "meta_ads",
+	"google":    "google_ads",
+	"tiktok":    "tiktok_ads",
+	"reddit":    "reddit_ads",
+	"linkedin":  "linkedin_ads",
+	"microsoft": "microsoft_ads",
+}
+
+var (
+	// errNotConnected — the org has no usable connection for the platform (no
+	// token, or the provider rejected it). Fail-closed: no spend, no fabrication.
+	errNotConnected = errors.New("ads: ad account not connected for org")
+	// errUnsupportedPlatform — a valid platform whose provider execution is not yet
+	// wired (the connector may be connected; only the create/read impl is missing).
+	errUnsupportedPlatform = errors.New("ads: paid execution not wired for platform")
+	// errUpstream — the ad platform edge failed transiently (network / non-auth non-2xx).
+	errUpstream = errors.New("ads: ad platform edge unavailable")
+)
+
+// tokenFor is the connector-custody seam. It defaults to integrations.TokenFor
+// (the ONE KMS-backed token door) and is a package var ONLY so a test can exercise
+// the provider path — the same reason meta.go's endpoints are package vars. It is
+// never reassigned in production.
+var tokenFor = integrations.TokenFor
+
+// metaAdsBase is the Meta Graph API base. A package var so a test points create /
+// insights / pause at an httptest server; never mutated in production.
+var metaAdsBase = "https://graph.facebook.com/v21.0"
+
+// adHTTP is the ONE bounded client for provider calls.
+var adHTTP = &http.Client{Timeout: launchTimeout}
+
+// PaidPlan is the standalone contract for launching one ad campaign — the campaign
+// paid channel adapts campaign.Plan onto it (apps/wire_seams.go). BudgetCents is
+// the org's own (connector-paid) budget; ScheduleAt an optional start time.
+type PaidPlan struct {
+	Platform    string
+	Account     string // provider ad-account ref (Meta: act_<id> or <id>)
+	Name        string
+	Objective   string // provider objective enum; defaulted per-provider when empty
+	BudgetCents int64
+	ScheduleAt  int64
+}
+
+// PaidRef is a launched ad campaign's durable handle: the provider-side id plus the
+// platform/account needed to read spend or pause it.
+type PaidRef struct {
+	Platform   string
+	Account    string
+	ExternalID string
+	Status     string
+	Detail     string
+}
+
+// adToken resolves (connectorID, token) for a platform, fail-closed. An unmapped
+// platform never reaches KMS. An empty/absent token is errNotConnected.
+func adToken(ctx context.Context, org, platform string) (string, string, error) {
+	connectorID, ok := platformConnector[strings.ToLower(strings.TrimSpace(platform))]
+	if !ok {
+		return "", "", fmt.Errorf("%w: %s", errUnsupportedPlatform, platform)
+	}
+	tok, err := tokenFor(ctx, org, connectorID, accessTokenSecret)
+	if err != nil || len(strings.TrimSpace(string(tok))) == 0 {
+		return connectorID, "", errNotConnected
+	}
+	return connectorID, strings.TrimSpace(string(tok)), nil
+}
+
+// LaunchPaid creates the ad campaign on its provider using the org's connector
+// token. Fail-closed: it resolves the token BEFORE any provider call. Meta is
+// executed for real; other connected platforms return errUnsupportedPlatform
+// (the connector is verified, only the provider impl is the remaining gap).
+func LaunchPaid(ctx context.Context, org string, p PaidPlan) (PaidRef, error) {
+	platform := strings.ToLower(strings.TrimSpace(p.Platform))
+	connectorID, token, err := adToken(ctx, org, platform)
+	if err != nil {
+		return PaidRef{}, err
+	}
+	switch platform {
+	case "meta":
+		return metaCreateCampaign(ctx, token, p)
+	default:
+		return PaidRef{}, fmt.Errorf("%w: %s (connector %s connected)", errUnsupportedPlatform, platform, connectorID)
+	}
+}
+
+// PaidSpend reads the provider-reported spend (minor units) for a launched ad
+// campaign. Fail-closed on the token; honest 0 when the platform is unsupported.
+func PaidSpend(ctx context.Context, org string, ref PaidRef) (int64, error) {
+	platform := strings.ToLower(strings.TrimSpace(ref.Platform))
+	_, token, err := adToken(ctx, org, platform)
+	if err != nil {
+		return 0, err
+	}
+	switch platform {
+	case "meta":
+		return metaCampaignSpend(ctx, token, ref.ExternalID)
+	default:
+		return 0, fmt.Errorf("%w: %s", errUnsupportedPlatform, platform)
+	}
+}
+
+// PausePaid pauses a launched ad campaign on its provider. Fail-closed on the token.
+func PausePaid(ctx context.Context, org string, ref PaidRef) error {
+	platform := strings.ToLower(strings.TrimSpace(ref.Platform))
+	_, token, err := adToken(ctx, org, platform)
+	if err != nil {
+		return err
+	}
+	switch platform {
+	case "meta":
+		return metaPauseCampaign(ctx, token, ref.ExternalID)
+	default:
+		return fmt.Errorf("%w: %s", errUnsupportedPlatform, platform)
+	}
+}
+
+// ── Meta (Facebook/Instagram) ad campaign execution ─────────────────────────
+
+// metaErr is Meta's Graph API error envelope.
+type metaErr struct {
+	Message string `json:"message"`
+	Type    string `json:"type"`
+	Code    int    `json:"code"`
+}
+
+// metaAcct normalizes a Meta ad-account ref to the act_<id> form the campaigns
+// edge expects. Empty stays empty (caller rejects).
+func metaAcct(account string) string {
+	a := strings.TrimSpace(account)
+	if a == "" {
+		return ""
+	}
+	if strings.HasPrefix(a, "act_") {
+		return a
+	}
+	return "act_" + a
+}
+
+// metaCreateCampaign POSTs a campaign to /act_<id>/campaigns. Objective defaults to
+// OUTCOME_TRAFFIC; special_ad_categories is the required empty set; the object is
+// created ACTIVE but does not deliver (no ad sets) so no spend starts on launch.
+func metaCreateCampaign(ctx context.Context, token string, p PaidPlan) (PaidRef, error) {
+	account := metaAcct(p.Account)
+	if account == "" {
+		return PaidRef{}, fmt.Errorf("meta: ad account (account) is required")
+	}
+	objective := strings.TrimSpace(p.Objective)
+	if objective == "" {
+		objective = "OUTCOME_TRAFFIC"
+	}
+	form := url.Values{
+		"name":                  {strings.TrimSpace(p.Name)},
+		"objective":             {objective},
+		"status":                {"ACTIVE"},
+		"special_ad_categories": {"[]"},
+	}
+	var out struct {
+		ID    string   `json:"id"`
+		Error *metaErr `json:"error"`
+	}
+	if err := metaPost(ctx, metaAdsBase+"/"+account+"/campaigns", token, form, &out); err != nil {
+		return PaidRef{}, err
+	}
+	if out.Error != nil {
+		return PaidRef{}, fmt.Errorf("meta create campaign: %s", out.Error.Message)
+	}
+	if strings.TrimSpace(out.ID) == "" {
+		return PaidRef{}, fmt.Errorf("meta create campaign returned no id")
+	}
+	return PaidRef{Platform: "meta", Account: account, ExternalID: out.ID, Status: "live"}, nil
+}
+
+// metaCampaignSpend reads spend from /{campaignID}/insights?fields=spend. Meta
+// reports spend in the account currency's major unit as a string; it is converted
+// to minor units (cents). No insights row (campaign hasn't spent) → 0.
+func metaCampaignSpend(ctx context.Context, token, campaignID string) (int64, error) {
+	if strings.TrimSpace(campaignID) == "" {
+		return 0, nil
+	}
+	var out struct {
+		Data []struct {
+			Spend string `json:"spend"`
+		} `json:"data"`
+		Error *metaErr `json:"error"`
+	}
+	if err := metaGet(ctx, metaAdsBase+"/"+campaignID+"/insights?fields=spend", token, &out); err != nil {
+		return 0, err
+	}
+	if out.Error != nil {
+		return 0, fmt.Errorf("meta insights: %s", out.Error.Message)
+	}
+	if len(out.Data) == 0 {
+		return 0, nil
+	}
+	dollars, err := strconv.ParseFloat(strings.TrimSpace(out.Data[0].Spend), 64)
+	if err != nil || dollars < 0 {
+		return 0, nil
+	}
+	return int64(dollars*100 + 0.5), nil
+}
+
+// metaPauseCampaign POSTs status=PAUSED to /{campaignID}.
+func metaPauseCampaign(ctx context.Context, token, campaignID string) error {
+	if strings.TrimSpace(campaignID) == "" {
+		return fmt.Errorf("meta: campaign id required")
+	}
+	var out struct {
+		Success bool     `json:"success"`
+		Error   *metaErr `json:"error"`
+	}
+	if err := metaPost(ctx, metaAdsBase+"/"+campaignID, token, url.Values{"status": {"PAUSED"}}, &out); err != nil {
+		return err
+	}
+	if out.Error != nil {
+		return fmt.Errorf("meta pause: %s", out.Error.Message)
+	}
+	return nil
+}
+
+// ── bounded HTTP (token on the Authorization header only) ────────────────────
+
+func metaPost(ctx context.Context, endpoint, token string, form url.Values, out any) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, strings.NewReader(form.Encode()))
+	if err != nil {
+		return fmt.Errorf("%w: %v", errUpstream, err)
+	}
+	req.Header.Set("Authorization", "Bearer "+token)
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	return adDo(req, out)
+}
+
+func metaGet(ctx context.Context, endpoint, token string, out any) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
+	if err != nil {
+		return fmt.Errorf("%w: %v", errUpstream, err)
+	}
+	req.Header.Set("Authorization", "Bearer "+token)
+	return adDo(req, out)
+}
+
+// adDo runs a bounded provider request and decodes the JSON body. A 401/403 is
+// fail-closed as errNotConnected (the org's token is invalid/revoked — the
+// connection is not usable); any other non-2xx or transport error is errUpstream.
+// The body is bounded so a hostile edge cannot amplify memory.
+func adDo(req *http.Request, out any) error {
+	resp, err := adHTTP.Do(req)
+	if err != nil {
+		return fmt.Errorf("%w: %v", errUpstream, err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	body, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+
+	if resp.StatusCode == http.StatusUnauthorized || resp.StatusCode == http.StatusForbidden {
+		return errNotConnected
+	}
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return fmt.Errorf("%w: %d", errUpstream, resp.StatusCode)
+	}
+	if out == nil {
+		return nil
+	}
+	if err := json.Unmarshal(body, out); err != nil {
+		return fmt.Errorf("%w: decode: %v", errUpstream, err)
+	}
+	return nil
+}
@@ -0,0 +1,210 @@
+package ads
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// stubToken overrides the connector-custody seam so the provider path is
+// exercised without standing up KMS + integrations. Restored on cleanup.
+func stubToken(t *testing.T, fn func(ctx context.Context, org, provider, name string) ([]byte, error)) {
+	t.Helper()
+	prev := tokenFor
+	tokenFor = fn
+	t.Cleanup(func() { tokenFor = prev })
+}
+
+// stubMeta points the Meta base at an httptest server (restored on cleanup) and
+// returns the server so the test can inspect what the provider received.
+func stubMeta(t *testing.T, h http.HandlerFunc) *httptest.Server {
+	t.Helper()
+	srv := httptest.NewServer(h)
+	prev := metaAdsBase
+	metaAdsBase = srv.URL
+	t.Cleanup(func() { metaAdsBase = prev; srv.Close() })
+	return srv
+}
+
+// TestLaunchPaid_MetaCreatesViaConnectorToken is the proof that /v1/ads consumes
+// the connector plane: LaunchPaid resolves the ORG'S token via the TokenFor seam
+// and creates the campaign on Meta with that token on the Authorization header.
+func TestLaunchPaid_MetaCreatesViaConnectorToken(t *testing.T) {
+	var (
+		gotAuth, gotPath, gotBody string
+		gotTokenOrg, gotProvider  string
+	)
+	stubToken(t, func(_ context.Context, org, provider, name string) ([]byte, error) {
+		gotTokenOrg, gotProvider = org, provider
+		if name != accessTokenSecret {
+			t.Fatalf("token secret name want %q, got %q", accessTokenSecret, name)
+		}
+		return []byte("T0K3N-acme"), nil
+	})
+	stubMeta(t, func(w http.ResponseWriter, r *http.Request) {
+		gotAuth = r.Header.Get("Authorization")
+		gotPath = r.URL.Path
+		_ = r.ParseForm()
+		gotBody = r.Form.Encode()
+		_, _ = w.Write([]byte(`{"id":"120210000000001"}`))
+	})
+
+	ref, err := LaunchPaid(context.Background(), "acme", PaidPlan{
+		Platform: "meta", Account: "123", Name: "Spring Launch", Objective: "OUTCOME_TRAFFIC",
+	})
+	if err != nil {
+		t.Fatalf("LaunchPaid: %v", err)
+	}
+	if ref.ExternalID != "120210000000001" || ref.Account != "act_123" || ref.Status != "live" {
+		t.Fatalf("ref: %+v", ref)
+	}
+	if gotTokenOrg != "acme" || gotProvider != "meta_ads" {
+		t.Fatalf("TokenFor called with (%q,%q), want (acme, meta_ads)", gotTokenOrg, gotProvider)
+	}
+	if gotAuth != "Bearer T0K3N-acme" {
+		t.Fatalf("Authorization header want the org token, got %q", gotAuth)
+	}
+	if gotPath != "/act_123/campaigns" {
+		t.Fatalf("create path want /act_123/campaigns, got %q", gotPath)
+	}
+	for _, want := range []string{"name=Spring", "objective=OUTCOME_TRAFFIC", "status=ACTIVE", "special_ad_categories="} {
+		if !strings.Contains(gotBody, want) {
+			t.Fatalf("create body missing %q: %q", want, gotBody)
+		}
+	}
+}
+
+// TestLaunchPaid_ConnectorDisabledNoProviderCall: when the org has not connected
+// the ad account (TokenFor fails), LaunchPaid fails closed and NEVER calls the
+// provider — no spend, no fabrication.
+func TestLaunchPaid_ConnectorDisabledNoProviderCall(t *testing.T) {
+	stubToken(t, func(_ context.Context, _, _, _ string) ([]byte, error) {
+		return nil, errors.New("integrations: meta_ads not connected for org")
+	})
+	hit := false
+	stubMeta(t, func(w http.ResponseWriter, r *http.Request) {
+		hit = true
+		_, _ = w.Write([]byte(`{"id":"should-not-happen"}`))
+	})
+
+	_, err := LaunchPaid(context.Background(), "acme", PaidPlan{Platform: "meta", Account: "123", Name: "X"})
+	if !errors.Is(err, errNotConnected) {
+		t.Fatalf("want errNotConnected, got %v", err)
+	}
+	if hit {
+		t.Fatalf("provider must NOT be called when the connector is disabled")
+	}
+}
+
+// TestLaunchPaid_TenantIsolationTokenPerOrg: each org's launch carries ITS OWN
+// org's token to the provider — org A can never spend on org B's connection.
+func TestLaunchPaid_TenantIsolationTokenPerOrg(t *testing.T) {
+	stubToken(t, func(_ context.Context, org, _, _ string) ([]byte, error) {
+		return []byte("tok-" + org), nil // each org has a distinct token
+	})
+	var seen []string
+	stubMeta(t, func(w http.ResponseWriter, r *http.Request) {
+		seen = append(seen, r.Header.Get("Authorization"))
+		_, _ = w.Write([]byte(`{"id":"1"}`))
+	})
+
+	if _, err := LaunchPaid(context.Background(), "acme", PaidPlan{Platform: "meta", Account: "1", Name: "A"}); err != nil {
+		t.Fatalf("acme launch: %v", err)
+	}
+	if _, err := LaunchPaid(context.Background(), "maxpower", PaidPlan{Platform: "meta", Account: "2", Name: "B"}); err != nil {
+		t.Fatalf("maxpower launch: %v", err)
+	}
+	if len(seen) != 2 || seen[0] != "Bearer tok-acme" || seen[1] != "Bearer tok-maxpower" {
+		t.Fatalf("each launch must carry its own org token, got %v", seen)
+	}
+}
+
+// TestLaunchPaid_AuthFailureIsNotConnected: a token the provider rejects (401) is
+// fail-closed as errNotConnected — the connection is not usable.
+func TestLaunchPaid_AuthFailureIsNotConnected(t *testing.T) {
+	stubToken(t, func(_ context.Context, _, _, _ string) ([]byte, error) { return []byte("stale"), nil })
+	stubMeta(t, func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusUnauthorized)
+		_, _ = w.Write([]byte(`{"error":{"message":"invalid token"}}`))
+	})
+	_, err := LaunchPaid(context.Background(), "acme", PaidPlan{Platform: "meta", Account: "1", Name: "X"})
+	if !errors.Is(err, errNotConnected) {
+		t.Fatalf("401 want errNotConnected, got %v", err)
+	}
+}
+
+// TestLaunchPaid_UnsupportedPlatformAfterToken: a mapped-but-unwired platform
+// resolves the connector token (proving consumption) then honestly reports the
+// execution gap — never a fabricated launch.
+func TestLaunchPaid_UnsupportedPlatformAfterToken(t *testing.T) {
+	tokenSought := false
+	stubToken(t, func(_ context.Context, _, provider, _ string) ([]byte, error) {
+		tokenSought = true
+		if provider != "google_ads" {
+			t.Fatalf("google platform must resolve google_ads, got %q", provider)
+		}
+		return []byte("g-token"), nil
+	})
+	_, err := LaunchPaid(context.Background(), "acme", PaidPlan{Platform: "google", Account: "1", Name: "X"})
+	if !errors.Is(err, errUnsupportedPlatform) {
+		t.Fatalf("want errUnsupportedPlatform, got %v", err)
+	}
+	if !tokenSought {
+		t.Fatalf("a mapped platform must resolve its connector token before reporting the gap")
+	}
+}
+
+// TestLaunchPaid_UnmappedPlatformNeverSeeksToken: a platform with no connector is
+// rejected BEFORE any KMS/token lookup.
+func TestLaunchPaid_UnmappedPlatformNeverSeeksToken(t *testing.T) {
+	stubToken(t, func(_ context.Context, _, _, _ string) ([]byte, error) {
+		t.Fatalf("token must not be sought for an unmapped platform")
+		return nil, nil
+	})
+	_, err := LaunchPaid(context.Background(), "acme", PaidPlan{Platform: "snapchat", Account: "1", Name: "X"})
+	if !errors.Is(err, errUnsupportedPlatform) {
+		t.Fatalf("want errUnsupportedPlatform, got %v", err)
+	}
+}
+
+// TestPaidSpend_MetaInsightsCents: spend is read from Meta insights and converted
+// to minor units (cents), through the org's connector token.
+func TestPaidSpend_MetaInsightsCents(t *testing.T) {
+	stubToken(t, func(_ context.Context, _, _, _ string) ([]byte, error) { return []byte("tok"), nil })
+	var gotPath string
+	stubMeta(t, func(w http.ResponseWriter, r *http.Request) {
+		gotPath = r.URL.Path
+		_, _ = w.Write([]byte(`{"data":[{"spend":"12.34"}]}`))
+	})
+	cents, err := PaidSpend(context.Background(), "acme", PaidRef{Platform: "meta", ExternalID: "120210000000001"})
+	if err != nil {
+		t.Fatalf("PaidSpend: %v", err)
+	}
+	if cents != 1234 {
+		t.Fatalf("spend want 1234 cents, got %d", cents)
+	}
+	if gotPath != "/120210000000001/insights" {
+		t.Fatalf("insights path want /120210000000001/insights, got %q", gotPath)
+	}
+}
+
+// TestPausePaid_MetaSetsPaused: pause posts status=PAUSED to the provider through
+// the org's connector token.
+func TestPausePaid_MetaSetsPaused(t *testing.T) {
+	stubToken(t, func(_ context.Context, _, _, _ string) ([]byte, error) { return []byte("tok"), nil })
+	var gotStatus string
+	stubMeta(t, func(w http.ResponseWriter, r *http.Request) {
+		_ = r.ParseForm()
+		gotStatus = r.Form.Get("status")
+		_, _ = w.Write([]byte(`{"success":true}`))
+	})
+	if err := PausePaid(context.Background(), "acme", PaidRef{Platform: "meta", ExternalID: "120210000000001"}); err != nil {
+		t.Fatalf("PausePaid: %v", err)
+	}
+	if gotStatus != "PAUSED" {
+		t.Fatalf("pause status want PAUSED, got %q", gotStatus)
+	}
+}
@@ -54,7 +54,9 @@ func openStore(path string) (*Store, error) {

 // migrate creates the campaigns table. Idempotent (IF NOT EXISTS). The table
 // leads its lookup indexes with `org` so tenant isolation is a physical
-// property, not just a WHERE clause.
+// property, not just a WHERE clause. account + external_id link a stored campaign
+// to its launched provider execution (provider.go); they are added idempotently
+// so a DB created before the connector-execution edge existed gains them cleanly.
 func (s *Store) migrate() error {
 	const ddl = `
 CREATE TABLE IF NOT EXISTS ads_campaigns (
@@ -62,6 +64,8 @@ CREATE TABLE IF NOT EXISTS ads_campaigns (
  org         TEXT NOT NULL,
  name        TEXT NOT NULL,
  platform    TEXT NOT NULL DEFAULT 'meta',
+  account     TEXT NOT NULL DEFAULT '',
+  external_id TEXT NOT NULL DEFAULT '',
  status      TEXT NOT NULL DEFAULT 'draft',
  objective   TEXT NOT NULL DEFAULT '',
  budget      INTEGER NOT NULL DEFAULT 0,
@@ -76,9 +80,48 @@ CREATE INDEX IF NOT EXISTS ix_ads_campaigns_org_platform ON ads_campaigns(org, p
 	if _, err := s.db.Exec(ddl); err != nil {
 		return fmt.Errorf("ads migrate: %w", err)
 	}
+	// Idempotent column adds for DBs created before account/external_id existed.
+	// The column names are package constants (never user input) → safe to inline.
+	for col, spec := range map[string]string{
+		"account":     "TEXT NOT NULL DEFAULT ''",
+		"external_id": "TEXT NOT NULL DEFAULT ''",
+	} {
+		if err := s.addColumnIfMissing("ads_campaigns", col, spec); err != nil {
+			return fmt.Errorf("ads migrate column %s: %w", col, err)
+		}
+	}
 	return nil
 }

+// addColumnIfMissing ALTERs table to add col (with spec) only when absent. table/
+// col/spec are package constants, so the interpolation is injection-safe. Makes
+// the schema migration forward-only and idempotent across process restarts.
+func (s *Store) addColumnIfMissing(table, col, spec string) error {
+	rows, err := s.db.Query(`PRAGMA table_info(` + table + `)`)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = rows.Close() }()
+	for rows.Next() {
+		var (
+			cid, notnull, pk int
+			name, ctype      string
+			dflt             sql.NullString
+		)
+		if err := rows.Scan(&cid, &name, &ctype, &notnull, &dflt, &pk); err != nil {
+			return err
+		}
+		if name == col {
+			return nil // already present
+		}
+	}
+	if err := rows.Err(); err != nil {
+		return err
+	}
+	_, err = s.db.Exec(`ALTER TABLE ` + table + ` ADD COLUMN ` + col + ` ` + spec)
+	return err
+}
+
 // Close closes the underlying database. Idempotent-safe via sql.DB.
 func (s *Store) Close() error { return s.db.Close() }

@@ -89,31 +132,33 @@ func (s *Store) Close() error { return s.db.Close() }
 // (draft/active/paused/completed) — both validated at the write layer against
 // the fixed vocabularies in ads.go.
 type Campaign struct {
-	ID        string `json:"id"`
-	Org       string `json:"-"`
-	Name      string `json:"name"`
-	Platform  string `json:"platform"`
-	Status    string `json:"status"`
-	Objective string `json:"objective"`
-	Budget    int64  `json:"budget"`
-	Spend     int64  `json:"spend"`
-	CreatedAt int64  `json:"createdAt"`
-	UpdatedAt int64  `json:"updatedAt"`
+	ID         string `json:"id"`
+	Org        string `json:"-"`
+	Name       string `json:"name"`
+	Platform   string `json:"platform"`
+	Account    string `json:"account,omitempty"`    // provider ad-account ref (Meta act_<id>)
+	ExternalID string `json:"externalId,omitempty"` // provider campaign id after a launch
+	Status     string `json:"status"`
+	Objective  string `json:"objective"`
+	Budget     int64  `json:"budget"`
+	Spend      int64  `json:"spend"`
+	CreatedAt  int64  `json:"createdAt"`
+	UpdatedAt  int64  `json:"updatedAt"`
 }

-const campaignCols = `id,org,name,platform,status,objective,budget,spend,created_at,updated_at`
+const campaignCols = `id,org,name,platform,account,external_id,status,objective,budget,spend,created_at,updated_at`

 func scanCampaign(sc interface{ Scan(...any) error }) (Campaign, error) {
 	var c Campaign
-	err := sc.Scan(&c.ID, &c.Org, &c.Name, &c.Platform, &c.Status, &c.Objective,
+	err := sc.Scan(&c.ID, &c.Org, &c.Name, &c.Platform, &c.Account, &c.ExternalID, &c.Status, &c.Objective,
 		&c.Budget, &c.Spend, &c.CreatedAt, &c.UpdatedAt)
 	return c, err
 }

 func (s *Store) CreateCampaign(ctx context.Context, c Campaign) (Campaign, error) {
 	if _, err := s.db.ExecContext(ctx,
-		`INSERT INTO ads_campaigns (`+campaignCols+`) VALUES (?,?,?,?,?,?,?,?,?,?)`,
-		c.ID, c.Org, c.Name, c.Platform, c.Status, c.Objective, c.Budget, c.Spend,
+		`INSERT INTO ads_campaigns (`+campaignCols+`) VALUES (?,?,?,?,?,?,?,?,?,?,?,?)`,
+		c.ID, c.Org, c.Name, c.Platform, c.Account, c.ExternalID, c.Status, c.Objective, c.Budget, c.Spend,
 		c.CreatedAt, c.UpdatedAt); err != nil {
 		return Campaign{}, fmt.Errorf("insert campaign: %w", err)
 	}
@@ -161,10 +206,13 @@ func (s *Store) ListCampaigns(ctx context.Context, org, status string, limit int
 	return out, rows.Err()
 }

+// UpdateCampaign edits the user-owned fields. external_id is deliberately NOT in
+// the SET list: it is launch-owned (MarkLaunched sets it), so editing a campaign
+// never clobbers the link to its live provider execution.
 func (s *Store) UpdateCampaign(ctx context.Context, c Campaign) (Campaign, error) {
 	res, err := s.db.ExecContext(ctx,
-		`UPDATE ads_campaigns SET name=?,platform=?,status=?,objective=?,budget=?,spend=?,updated_at=? WHERE org=? AND id=?`,
-		c.Name, c.Platform, c.Status, c.Objective, c.Budget, c.Spend, c.UpdatedAt, c.Org, c.ID)
+		`UPDATE ads_campaigns SET name=?,platform=?,account=?,status=?,objective=?,budget=?,spend=?,updated_at=? WHERE org=? AND id=?`,
+		c.Name, c.Platform, c.Account, c.Status, c.Objective, c.Budget, c.Spend, c.UpdatedAt, c.Org, c.ID)
 	if err != nil {
 		return Campaign{}, fmt.Errorf("update campaign: %w", err)
 	}
@@ -174,6 +222,23 @@ func (s *Store) UpdateCampaign(ctx context.Context, c Campaign) (Campaign, error
 	return s.GetCampaign(ctx, c.Org, c.ID)
 }

+// MarkLaunched records the provider execution on a stored campaign: its account +
+// external id, and status=active. Org-scoped — a cross-tenant id affects zero
+// rows (errNotFound), never a foreign mutation. This is the ONLY writer of
+// external_id, so the launch link is never clobbered by a user edit.
+func (s *Store) MarkLaunched(ctx context.Context, org, id, account, externalID string, updatedAt int64) (Campaign, error) {
+	res, err := s.db.ExecContext(ctx,
+		`UPDATE ads_campaigns SET account=?,external_id=?,status='active',updated_at=? WHERE org=? AND id=?`,
+		account, externalID, updatedAt, org, id)
+	if err != nil {
+		return Campaign{}, fmt.Errorf("mark launched: %w", err)
+	}
+	if n, _ := res.RowsAffected(); n == 0 {
+		return Campaign{}, errNotFound
+	}
+	return s.GetCampaign(ctx, org, id)
+}
+
 func (s *Store) DeleteCampaign(ctx context.Context, org, id string) (bool, error) {
 	res, err := s.db.ExecContext(ctx, `DELETE FROM ads_campaigns WHERE org=? AND id=?`, org, id)
 	if err != nil {
@@ -1,153 +1,44 @@
 package affiliates

 import (
-	"bytes"
 	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"io"
-	"net/http"
-	"net/url"
-	"strings"
-	"time"

-	"github.com/hanzoai/cloud/clients/commerceinproc"
+	"github.com/hanzoai/cloud/clients/payout"
 )

-// commerce is the narrow money seam the affiliate loop needs: read a referred
-// org's metered spend (the accrual base) and grant a promo credit to a wallet (a
-// payout made in credits). It is an INTERFACE so the store/handler logic is
-// testable with a fake ledger — the HTTP impl below is the ONE production binding.
+// commerce is the narrow money seam the affiliate loop needs: read a referred org's
+// metered spend (the commission accrual base) and grant a promo credit to a wallet
+// (a payout made in credits, ledger tag grant:affiliate). It is an INTERFACE so the
+// store/handler logic is testable with a fake ledger; the production binding is
+// clients/payout, reached through the thin adapter below.
 //
-// This mirrors clients/referrals/commerce.go EXACTLY (which itself mirrors
-// clients/admin/commerce.go): the same COMMERCE_SERVICE_TOKEN S2S path, the same
-// X-Org-Id=<org> namespace + bare org `user` subject that admin.grantCredit uses —
-// so an affiliate payout-in-credits lands in precisely the wallet the balance
-// panel reads, indistinguishable from an admin grant except by its ledger tag
-// (grant:affiliate vs grant:referral / grant:admin, all → the commerce Credit/trial
-// bucket per DepositKind's grant:* rule).
+// The S2S impl (COMMERCE_SERVICE_TOKEN path, X-Org-Id=<org> namespace, bare-org
+// `user` subject) was three byte-identical commerce.go copies; it now lives ONCE in
+// clients/payout. An affiliate payout-in-credits still lands in precisely the wallet
+// the balance panel reads, indistinguishable from an admin grant except by its
+// grant:affiliate tag.
 type commerce interface {
 	configured() bool
-	// deposit grants amountCents to org's wallet (Credit/trial bucket via the
-	// grant:affiliate tag) and returns the ledger transaction id.
 	deposit(ctx context.Context, org, user string, amountCents int64, currency, notes, tags string) (txnID string, err error)
-	// spendCents is a referred org's month-to-date metered consumption — the
-	// commission accrual base (spend × the affiliate's rate).
 	spendCents(ctx context.Context, org, user string) (int64, error)
 }

-// errUnconfigured is returned by a deposit against an unwired commerce so the
-// caller records an honest failure rather than reporting a phantom payout.
-var errUnconfigured = errors.New("affiliates: commerce endpoint not configured")
+// errUnconfigured is the shared sentinel a deposit against an unwired commerce
+// returns, so the caller records an honest failure rather than a phantom payout.
+var errUnconfigured = payout.ErrUnconfigured

-// httpCommerce is the production commerce binding (COMMERCE_SERVICE_TOKEN S2S).
-type httpCommerce struct {
-	base  string
-	token string
-	http  *http.Client
+// commerceSeam adapts the shared payout.Client onto this program's lowercase seam
+// (Go package-scoped interface methods cannot cross packages). Zero logic — pure
+// delegation; the money path lives in clients/payout.
+type commerceSeam struct{ c *payout.Client }
+
+func (s commerceSeam) configured() bool { return s.c.Configured() }
+func (s commerceSeam) deposit(ctx context.Context, org, user string, amountCents int64, currency, notes, tags string) (string, error) {
+	return s.c.Deposit(ctx, org, user, amountCents, currency, notes, tags)
+}
+func (s commerceSeam) spendCents(ctx context.Context, org, user string) (int64, error) {
+	return s.c.SpendCents(ctx, org, user)
 }

-func newCommerceClient(base, token string) *httpCommerce {
-	return &httpCommerce{
-		base:  strings.TrimRight(strings.TrimSpace(base), "/"),
-		token: strings.TrimSpace(token),
-		http:  commerceinproc.Client(15 * time.Second),
-	}
-}
-
-func (c *httpCommerce) configured() bool { return c != nil && c.base != "" && c.token != "" }
-
-// deposit posts POST /v1/billing/deposit — the ONE money-in primitive (identical
-// to admin.commerceClient.deposit). Commerce's EdgeAuth pins the body `user` to
-// the X-Org-Id subject, so a payout can never be mis-targeted to another wallet.
-func (c *httpCommerce) deposit(ctx context.Context, org, user string, amountCents int64, currency, notes, tags string) (string, error) {
-	if !c.configured() {
-		return "", errUnconfigured
-	}
-	if currency == "" {
-		currency = "usd"
-	}
-	body, err := json.Marshal(map[string]any{
-		"user":     user,
-		"currency": currency,
-		"amount":   amountCents,
-		"notes":    notes,
-		"tags":     tags,
-	})
-	if err != nil {
-		return "", err
-	}
-	raw, err := c.do(ctx, http.MethodPost, "/v1/billing/deposit", nil, org, body)
-	if err != nil {
-		return "", err
-	}
-	var out struct {
-		TransactionID string `json:"transactionId"`
-	}
-	if err := json.Unmarshal(raw, &out); err != nil {
-		return "", fmt.Errorf("commerce deposit decode: %w", err)
-	}
-	return out.TransactionID, nil
-}
-
-// spendCents reads GET /v1/billing/usage-rollup and returns consumedCents. Zero
-// (not an error) when commerce is unconfigured so a partial deploy degrades to
-// "no spend to accrue yet" rather than a 5xx.
-func (c *httpCommerce) spendCents(ctx context.Context, org, user string) (int64, error) {
-	if !c.configured() {
-		return 0, nil
-	}
-	q := url.Values{"user": {user}}
-	raw, err := c.do(ctx, http.MethodGet, "/v1/billing/usage-rollup", q, org, nil)
-	if err != nil {
-		return 0, err
-	}
-	var out struct {
-		ConsumedCents int64 `json:"consumedCents"`
-	}
-	if err := json.Unmarshal(raw, &out); err != nil {
-		return 0, fmt.Errorf("commerce rollup decode: %w", err)
-	}
-	return out.ConsumedCents, nil
-}
-
-// do performs one admin-S2S commerce request. X-Org-Id=<org> is the per-org
-// namespace selector commerce's EdgeAuth trusts only behind the service token.
-func (c *httpCommerce) do(ctx context.Context, method, path string, q url.Values, org string, body []byte) ([]byte, error) {
-	u := c.base + path
-	if enc := q.Encode(); enc != "" {
-		u += "?" + enc
-	}
-	var r io.Reader
-	if body != nil {
-		r = bytes.NewReader(body)
-	}
-	req, err := http.NewRequestWithContext(ctx, method, u, r)
-	if err != nil {
-		return nil, err
-	}
-	req.Header.Set("Accept", "application/json")
-	if body != nil {
-		req.Header.Set("Content-Type", "application/json")
-	}
-	if c.token != "" {
-		req.Header.Set("Authorization", "Bearer "+c.token)
-	}
-	if org != "" {
-		req.Header.Set("X-Org-Id", org)
-	}
-	resp, err := c.http.Do(req)
-	if err != nil {
-		return nil, fmt.Errorf("commerce unreachable: %w", err)
-	}
-	defer func() { _ = resp.Body.Close() }()
-	out, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
-	if err != nil {
-		return nil, err
-	}
-	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
-		return nil, fmt.Errorf("commerce status %d", resp.StatusCode)
-	}
-	return out, nil
-}
+// newCommerceClient builds the production binding, delegating to clients/payout.
+func newCommerceClient(base, token string) commerce { return commerceSeam{payout.NewClient(base, token)} }
@@ -22,7 +22,7 @@ import (
 	hz "github.com/hanzoai/agent"
 	"github.com/hanzoai/cloud"
 	"github.com/hanzoai/cloud/clients/tools"
-	openai "github.com/sashabaranov/go-openai"
+	openai "github.com/hanzoai/go-openai"
 	fiber "github.com/zap-proto/fiber/v3"
 	"github.com/zap-proto/zip"
 )
@@ -28,7 +28,9 @@ import (
 	"context"
 	"crypto/rand"
 	"encoding/hex"
+	"errors"
 	"fmt"
+	mrand "math/rand/v2"
 	"net/http"
 	"os"
 	"path/filepath"
@@ -107,6 +109,13 @@ type state struct {
 	// per subsystem. Empty only on a deployment that configured no default, in
 	// which case create still requires an explicit model.
 	defaultModel string
+	// failoverModel is the reliable model a run falls over to when the agent's own
+	// model stays throttled (429/overloaded) after bounded retries
+	// (deps.AIFallbackModel, default "best"). It makes an autonomous bot reply
+	// still land when the throttled default flash model is overloaded. Empty
+	// disables failover (retry-only). Only the run path reads it — interactive
+	// chat is untouched.
+	failoverModel string
 	// bill is the shared per-org gate+meter (reuses deps.Metering, the ONE
 	// commerce client — the same object ml/provisioning use). Nil/!Enabled()
 	// makes Gate allow and Meter a no-op, so an unconfigured deployment runs
@@ -262,11 +271,12 @@ func Mount(app *zip.App, deps cloud.Deps) error {
 	s := &cloud.Service[state]{
 		Base: cloud.NewBase(deps, "agents"),
 		State: state{
-			store:        store,
-			ai:           deps.AI,
-			defaultModel: strings.TrimSpace(deps.AIDefaultModel),
-			bill:         cloud.NewResourceMeter(deps, meterKind),
-			bus:          newBus(),
+			store:         store,
+			ai:            deps.AI,
+			defaultModel:  strings.TrimSpace(deps.AIDefaultModel),
+			failoverModel: strings.TrimSpace(deps.AIFallbackModel),
+			bill:          cloud.NewResourceMeter(deps, meterKind),
+			bus:           newBus(),
 			// TASKS PLUG-IN POINT: durable execution rides hanzoai/tasks, not a
 			// bespoke engine. Default is record-only; wiring client.Dial(TASKS_URL)
 			// from github.com/hanzoai/tasks/pkg/sdk/client here makes control forward
@@ -276,6 +286,7 @@ func Mount(app *zip.App, deps cloud.Deps) error {
 	}
 	mounted = s

+	g := app.Group("/v1/agents")
 	app.Get("/v1/agents", cloud.Handle(s, list))
 	app.Post("/v1/agents", cloud.Handle(s, create))
 	// The static org-wide surfaces are listed before the :ref wildcard for reading
@@ -284,18 +295,18 @@ func Mount(app *zip.App, deps cloud.Deps) error {
 	// a ref). Registration order decides nothing here — it only decides which
 	// handler silently wins when two patterns are byte-identical, which is a
 	// collision, not a precedence.
-	app.Get("/v1/agents/metrics", cloud.Handle(s, metrics))
-	app.Get("/v1/agents/activity", cloud.Handle(s, activity))
+	g.Get("/metrics", cloud.Handle(s, metrics))
+	g.Get("/activity", cloud.Handle(s, activity))
 	// Live agent-session control plane: /v1/agents/sessions[/...].
 	mountSessions(s, app)
 	// Agent targets: /v1/agents/targets[/...] — the #48 dispatch destinations a
 	// session runs on.
 	mountTargets(s, app)
-	app.Get("/v1/agents/:ref", cloud.Handle(s, get))
-	app.Patch("/v1/agents/:ref", cloud.Handle(s, update))
-	app.Delete("/v1/agents/:ref", cloud.Handle(s, del))
-	app.Post("/v1/agents/:ref/run", cloud.Handle(s, run))
-	app.Get("/v1/agents/:ref/runs", cloud.Handle(s, runs))
+	g.Get("/:ref", cloud.Handle(s, get))
+	g.Patch("/:ref", cloud.Handle(s, update))
+	g.Delete("/:ref", cloud.Handle(s, del))
+	g.Post("/:ref/run", cloud.Handle(s, run))
+	g.Get("/:ref/runs", cloud.Handle(s, runs))

 	// Long-running scheduler: invokes each long-running agent's run on its cron
 	// cadence through the SAME runAgent path as the HTTP handler (one run path,
@@ -665,11 +676,12 @@ func runAgent(s *cloud.Service[state], ctx context.Context, a Agent, input, acto
 		return Run{}, err
 	}

-	r := executeRun(ctx, s.State.ai, a.Org, a, input)
+	r := executeRun(ctx, s.State.ai, a.Org, a, input, s.State.failoverModel)
 	span.SetAttributes(
 		attribute.String("hanzo.agent.run_id", r.ID),
 		attribute.String("hanzo.agent.run_status", r.Status),
 		attribute.Int64("hanzo.agent.duration_ms", r.DurationMs),
+		attribute.String("gen_ai.response.model", r.Model),
 	)
 	if r.Status == "error" {
 		span.SetStatus(codes.Error, r.Error)
@@ -685,12 +697,14 @@ func runAgent(s *cloud.Service[state], ctx context.Context, a Agent, input, acto
 	openRunSession(s, ctx, a, r, actor)

 	// Bill only a successful run (mirrors the edge gate: failed work is not
-	// charged). Rich attribution: product=agent (Provider), the agent's model,
-	// and the actor for the audit trail. Fire-and-forget on a background context.
+	// charged). Rich attribution: product=agent (Provider), the model ACTUALLY
+	// used (r.Model — a failover run bills the reliable model it fell over to, not
+	// the throttled one it started on), and the actor for the audit trail.
+	// Fire-and-forget on a background context.
 	if r.Status == "ok" {
 		s.State.bill.MeterUsage(a.Org, meterKind, metering.Usage{
 			AmountCents: fee,
-			Model:       a.Model,
+			Model:       r.Model,
 			Actor:       actor,
 			RequestID:   requestID,
 			ClientIP:    clientIP,
@@ -699,11 +713,31 @@ func runAgent(s *cloud.Service[state], ctx context.Context, a Agent, input, acto
 	return r, nil
 }

-// executeRun composes the agent's instructions with the caller input, runs one
-// real chat completion through the AI client, and returns the resulting Run —
-// status "ok" with output, or "error" with the upstream failure. Pure of HTTP
-// and persistence so it is directly testable; the caller records + responds.
-func executeRun(ctx context.Context, ai types.AIClient, org string, a Agent, input string) Run {
+// maxAttempts bounds retries of a SINGLE model's completion on a transient
+// upstream failure (429 / 5xx / empty-choices / "Platform overloaded"). Retrying
+// a completion is side-effect-free — nothing bills until it succeeds — so a
+// bounded retry with jittered backoff turns an intermittent gateway 429 into a
+// delivered reply instead of a dropped one.
+const maxAttempts = 3
+
+// retryBaseDelay / retryMaxDelay bound the exponential, equal-jittered backoff
+// between attempts. Small by design: a gateway overload clears in well under a
+// second, and a run must not stall a bot conversation.
+const (
+	retryBaseDelay = 150 * time.Millisecond
+	retryMaxDelay  = 2 * time.Second
+)
+
+// executeRun composes the agent's instructions with the caller input and runs
+// one chat completion through the AI client — with a bounded retry on transient
+// upstream overload and, if the agent's own model stays throttled, ONE failover
+// to the deployment's reliable model (fallback) so an autonomous bot reply still
+// lands. It returns the resulting Run — status "ok" with output and Model set to
+// the model that ACTUALLY answered (so metering bills that model), or "error"
+// with the final upstream failure. Pure of HTTP and persistence so it is directly
+// testable; the caller records + responds. This reliability policy is the agent
+// runner's ALONE — the interactive user-facing chat path is untouched.
+func executeRun(ctx context.Context, ai types.AIClient, org string, a Agent, input, fallback string) Run {
 	// Child step span; the AI client opens its own GenAI span nested under this.
 	ctx, span := agentTracer.Start(ctx, "agent.step", trace.WithSpanKind(trace.SpanKindInternal))
 	defer span.End()
@@ -717,11 +751,11 @@ func executeRun(ctx context.Context, ai types.AIClient, org string, a Agent, inp
 		prompt += in
 	}
 	start := time.Now()
-	resp, aiErr := ai.ChatCompletion(ctx, &types.ChatRequest{Model: a.Model, Prompt: prompt, Org: org})
+	resp, used, aiErr := completeWithFailover(ctx, ai, org, prompt, a.Model, fallback)
 	dur := time.Since(start).Milliseconds()
 	id, _ := genID("run")
 	r := Run{
-		ID: id, Org: org, AgentName: a.Name, Model: a.Model, Input: input,
+		ID: id, Org: org, AgentName: a.Name, Model: used, Input: input,
 		DurationMs: dur, CreatedAt: time.Now().Unix(),
 	}
 	if aiErr != nil {
@@ -738,6 +772,77 @@ func executeRun(ctx context.Context, ai types.AIClient, org string, a Agent, inp
 	return r
 }

+// completeWithFailover runs the completion on the agent's model with a bounded
+// retry (completeWithRetry), then — only if that model is STILL throttled after
+// its retries — fails over ONCE to fallback, a reliable model. It returns the
+// response, the model that actually produced it (for honest metering), and the
+// final error. A non-transient failure on either model returns immediately (the
+// next model would fail identically). ONE ordered mechanism, no config sprawl.
+func completeWithFailover(ctx context.Context, ai types.AIClient, org, prompt, model, fallback string) (*types.ChatResponse, string, error) {
+	models := []string{model}
+	if f := strings.TrimSpace(fallback); f != "" && f != model {
+		models = append(models, f)
+	}
+	var lastErr error
+	for _, m := range models {
+		resp, err := completeWithRetry(ctx, ai, org, prompt, m)
+		if err == nil {
+			return resp, m, nil
+		}
+		lastErr = err
+		// Escalate to the next model ONLY on a transient overload; a hard error
+		// (bad request, auth, unserved model) fails fast — failover cannot help.
+		if !errors.Is(err, types.ErrUpstreamBusy) {
+			return nil, m, err
+		}
+	}
+	return nil, models[len(models)-1], lastErr
+}
+
+// completeWithRetry calls the completion up to maxAttempts times, retrying ONLY a
+// transient upstream overload (types.ErrUpstreamBusy) with jittered backoff and
+// respecting context cancellation. A non-transient error returns immediately.
+func completeWithRetry(ctx context.Context, ai types.AIClient, org, prompt, model string) (*types.ChatResponse, error) {
+	var lastErr error
+	for attempt := 0; attempt < maxAttempts; attempt++ {
+		resp, err := ai.ChatCompletion(ctx, &types.ChatRequest{Model: model, Prompt: prompt, Org: org})
+		if err == nil {
+			return resp, nil
+		}
+		lastErr = err
+		if !errors.Is(err, types.ErrUpstreamBusy) {
+			return nil, err // permanent — do not burn retries repeating it
+		}
+		if attempt == maxAttempts-1 {
+			break
+		}
+		if err := sleepBackoff(ctx, attempt); err != nil {
+			return nil, err // context cancelled/expired mid-backoff
+		}
+	}
+	return nil, lastErr
+}
+
+// sleepBackoff waits an exponential, equal-jittered delay before the next
+// attempt, or returns the context error if the caller's deadline fires first.
+func sleepBackoff(ctx context.Context, attempt int) error {
+	d := retryBaseDelay << attempt
+	if d > retryMaxDelay {
+		d = retryMaxDelay
+	}
+	// Equal jitter: half fixed, half random in [0, d/2) — spreads retries without
+	// ever collapsing the delay to ~0 (guarantees forward progress under load).
+	wait := d/2 + time.Duration(mrand.Int64N(int64(d/2)+1))
+	t := time.NewTimer(wait)
+	defer t.Stop()
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-t.C:
+		return nil
+	}
+}
+
 func runs(s *cloud.Service[state], c *zip.Ctx) error {
 	org, ok := tenant(c)
 	if !ok {
@@ -157,7 +157,7 @@ func TestExecuteRunOK(t *testing.T) {
 	ai := &fakeAI{content: "hi there"}
 	a := mk("maxpower", "greeter")
 	a.Instructions = "You are a greeter."
-	r := executeRun(context.Background(), ai, "maxpower", a, "say hi")
+	r := executeRun(context.Background(), ai, "maxpower", a, "say hi", "")

 	if r.Status != "ok" {
 		t.Fatalf("want ok, got %q err=%q", r.Status, r.Error)
@@ -178,7 +178,7 @@ func TestExecuteRunOK(t *testing.T) {

 func TestExecuteRunRecordsError(t *testing.T) {
 	ai := &fakeAI{err: errors.New("model unavailable")}
-	r := executeRun(context.Background(), ai, "maxpower", mk("maxpower", "x"), "in")
+	r := executeRun(context.Background(), ai, "maxpower", mk("maxpower", "x"), "in", "")
 	if r.Status != "error" {
 		t.Fatalf("want error status, got %q", r.Status)
 	}
@@ -13,8 +13,8 @@ import (
 	"time"

 	"github.com/hanzoai/cloud"
-	"github.com/hanzoai/cloud/types"
 	"github.com/hanzoai/cloud/clients/metering"
+	"github.com/hanzoai/cloud/types"
 	luxlog "github.com/luxfi/log"
 	"github.com/zap-proto/zip"
 )
@@ -88,7 +88,10 @@ func mountBilled(t *testing.T, commerceURL string, ai types.AIClient) *zip.App {
 		t.Fatalf("metering.New: %v", err)
 	}
 	app := zip.New(zip.Config{Logger: luxlog.New("test")})
-	deps := cloud.Deps{Logger: luxlog.New("test"), DataDir: t.TempDir(), AI: ai, Metering: m}
+	// AIFallbackModel="best" arms the agent runner's failover so the retry/failover
+	// tests exercise the real escalation path; it never fires for a run whose model
+	// answers (or fails non-transiently), so the other billed tests are unaffected.
+	deps := cloud.Deps{Logger: luxlog.New("test"), DataDir: t.TempDir(), AI: ai, Metering: m, AIFallbackModel: "best"}
 	if err := Mount(app, deps); err != nil {
 		t.Fatalf("Mount: %v", err)
 	}
@@ -71,6 +71,44 @@ func OpenSession(ctx context.Context, org, actor, agent, title string) (string,
 	return id, nil
 }

+// OpenSessionOn is OpenSession with the run's dispatch TARGET recorded, so
+// mission-control shows a routed run on the machine it was sent to (session.target
+// == the target id) exactly as a locally-linked run shows its host. The target is
+// re-resolved org-scoped and MUST belong to this org — a session can never claim
+// to run on another tenant's machine (the same fail-closed rule sessionContext
+// enforces on the HTTP register path). An empty target falls back to OpenSession.
+func OpenSessionOn(ctx context.Context, org, actor, agent, title, target string) (string, error) {
+	target = strings.TrimSpace(target)
+	if target == "" {
+		return OpenSession(ctx, org, actor, agent, title)
+	}
+	if mounted == nil {
+		return "", fmt.Errorf("agents: not mounted")
+	}
+	org = strings.TrimSpace(org)
+	if org == "" {
+		return "", fmt.Errorf("agents: org required")
+	}
+	if _, err := mounted.State.store.GetTarget(ctx, org, target); err != nil {
+		if err == errTargetNotFound {
+			return "", fmt.Errorf("agents: target not found in this org")
+		}
+		return "", fmt.Errorf("agents: resolve target: %w", err)
+	}
+	id, err := OpenSession(ctx, org, actor, agent, title)
+	if err != nil {
+		return "", err
+	}
+	// Stamp the target onto the freshly-opened row (org-scoped update); a failure
+	// here is non-fatal — the session is live, it simply lacks its machine tag.
+	if x, gerr := mounted.State.store.GetSession(ctx, org, id); gerr == nil {
+		x.Target = target
+		x.UpdatedAt = time.Now().Unix()
+		_ = mounted.State.store.UpdateSession(ctx, x)
+	}
+	return id, nil
+}
+
 // LogSessionEvent appends one ordered event (message|tool-call|spawn|log|status|
 // control) to an org's session and fans it out live. The (org, id) pair is
 // re-resolved so a caller can only write to a session THIS org owns; kind is
@@ -114,3 +114,50 @@ func TestInproc_NotMounted_FailsClosed(t *testing.T) {
 		t.Fatal("unmounted OpenSession must fail closed")
 	}
 }
+
+// ResolveTarget turns a human's reference (id or friendly label) into the org's
+// target, org-scoped and fail-closed: an id wins, else an exact case-folded label,
+// and a reference matching neither — or another org's machine — is not found.
+func TestResolveTarget_IdThenLabel_OrgScoped(t *testing.T) {
+	mountInproc(t)
+	ctx := context.Background()
+	now := int64(1000)
+	acme := Target{ID: "tgt_acme1", Org: "acme", Label: "evo", Kind: TargetGPU, Status: TargetOnline, Host: "evo", CreatedAt: now, UpdatedAt: now}
+	evil := Target{ID: "tgt_evil1", Org: "evil", Label: "evo", Kind: TargetGPU, Status: TargetOnline, Host: "evo", CreatedAt: now, UpdatedAt: now}
+	if err := mounted.State.store.CreateTarget(ctx, acme); err != nil {
+		t.Fatal(err)
+	}
+	if err := mounted.State.store.CreateTarget(ctx, evil); err != nil {
+		t.Fatal(err)
+	}
+
+	// By id.
+	if got, err := ResolveTarget(ctx, "acme", "tgt_acme1"); err != nil || got.ID != "tgt_acme1" {
+		t.Fatalf("resolve by id: %+v %v", got, err)
+	}
+	// By label (case-folded), scoped to the caller's org — never evil's same-labelled box.
+	if got, err := ResolveTarget(ctx, "acme", "EVO"); err != nil || got.ID != "tgt_acme1" {
+		t.Fatalf("resolve by label must find acme's own, got %+v %v", got, err)
+	}
+	// Another org's id is not found (no cross-tenant leak).
+	if _, err := ResolveTarget(ctx, "acme", "tgt_evil1"); err != errTargetNotFound {
+		t.Fatalf("cross-org id must be not-found, got %v", err)
+	}
+	// An unknown reference is not found — the caller renders an honest error.
+	if _, err := ResolveTarget(ctx, "acme", "nope"); err != errTargetNotFound {
+		t.Fatalf("unknown ref must be not-found, got %v", err)
+	}
+	// Empty ref is not found (never resolves to "some" machine).
+	if _, err := ResolveTarget(ctx, "acme", ""); err != errTargetNotFound {
+		t.Fatalf("empty ref must be not-found, got %v", err)
+	}
+}
+
+func TestResolveTarget_NotMounted_FailsClosed(t *testing.T) {
+	prev := mounted
+	mounted = nil
+	t.Cleanup(func() { mounted = prev })
+	if _, err := ResolveTarget(context.Background(), "acme", "evo"); err == nil {
+		t.Fatal("unmounted ResolveTarget must fail closed")
+	}
+}
@@ -0,0 +1,316 @@
+package agents
+
+import (
+	"context"
+	"os"
+	"strconv"
+	"strings"
+	"sync"
+
+	luxlog "github.com/luxfi/log"
+)
+
+// mailbox.go is the LIVE hand-off between a routed run's durable owner (the
+// coding RoutedRunWorkflow, running on the embedded tasks engine) and the
+// external machine that claims and executes it over HTTP. It is the rendezvous
+// ONLY — never the durable queue. The tasks engine is the queue of record: it
+// survives a cloud restart, times a never-claimed run out, and retries. On every
+// (re)start of the delivery activity the run is (re-)Offered here, so a machine
+// that long-polls Claim always finds work the engine still owns; a cloud restart
+// simply re-populates the mailbox from durable history.
+//
+// ISOLATION IS STRUCTURAL. Every offer is filed under the key (org, target), and
+// Claim/Report only ever touch that one key's slot. A run offered for (orgB,
+// targetY) is unreachable from a Claim or Report for (orgA, targetX) — the tenant
+// + machine boundary is a property of the map key, not a check a caller can skip.
+
+// RoutedRun is the NON-SECRET spec of one coding run dispatched to a target. It
+// carries no credential by design: the executing machine authenticates git +
+// model routing with its OWN already-held credentials (the same ones `hanzo code`
+// uses), so no secret ever enters the durable store or crosses to the machine in
+// the claim response. Everything here is safe to persist in the tasks engine.
+type RoutedRun struct {
+	Org            string `json:"org"`
+	TargetID       string `json:"targetId"`
+	SessionID      string `json:"sessionId"` // the live session opened at dispatch; the machine streams into it
+	Repo           string `json:"repo"`
+	Project        string `json:"project,omitempty"`
+	Base           string `json:"base,omitempty"`
+	Branch         string `json:"branch"`
+	Prompt         string `json:"prompt"`
+	CloneURL       string `json:"cloneUrl"`
+	TimeoutSeconds int    `json:"timeoutSeconds,omitempty"`
+	// Actor + AgentRef are CLOUD-SIDE attribution for the completion path (session
+	// close + PR assignee). They are NOT part of routedRunView, so they never cross
+	// to the executing machine — the machine needs neither.
+	Actor    string `json:"actor,omitempty"`
+	AgentRef string `json:"agentRef,omitempty"`
+}
+
+// RoutedResult is a routed run's terminal outcome, reported by the machine and
+// returned to the durable activity so the workflow completes.
+type RoutedResult struct {
+	OK        bool   `json:"ok"`
+	Changed   bool   `json:"changed"`
+	Branch    string `json:"branch,omitempty"`
+	CommitSha string `json:"commitSha,omitempty"`
+	Diffstat  string `json:"diffstat,omitempty"`
+	Error     string `json:"error,omitempty"`
+}
+
+// offer is one run waiting to be claimed, plus the channel its durable owner
+// blocks on for the terminal result. result is buffered(1) so Report never blocks
+// even if the owner is between selects; closed fires when the offer is finished
+// (reported OR abandoned) so a waiter always unblocks.
+type offer struct {
+	mb     *mailbox
+	key    string // (org,target)
+	rk     string // (org,target,sessionID)
+	run    RoutedRun
+	result chan RoutedResult
+	closed chan struct{}
+	once   sync.Once
+}
+
+// Await blocks until the machine reports this run's result, the offer is
+// abandoned, or ctx (the activity's StartToClose budget) fires. It is the
+// durable owner's half of the rendezvous.
+func (o *offer) Await(ctx context.Context) (RoutedResult, bool) {
+	select {
+	case res := <-o.result:
+		return res, true
+	case <-o.closed:
+		// Abandoned or reported-then-closed: drain a delivered result if one raced in.
+		select {
+		case res := <-o.result:
+			return res, true
+		default:
+			return RoutedResult{}, false
+		}
+	case <-ctx.Done():
+		return RoutedResult{}, false
+	}
+}
+
+// Close removes the offer from the mailbox (if still present) and unblocks any
+// waiter. Idempotent — the durable owner defers it so a timed-out or crashed
+// delivery never leaks a queued or claimed offer.
+func (o *offer) Close() { o.mb.discard(o) }
+
+// mailbox is the process-wide rendezvous. queues holds each key's FIFO of
+// unclaimed offers; byRun indexes every live offer by (org,target,sessionID) for
+// Report + re-offer dedupe; signal is a per-key broadcast channel (closed and
+// recreated on Offer) that Claim waits on.
+type mailbox struct {
+	mu     sync.Mutex
+	queues map[string][]*offer
+	byRun  map[string]*offer
+	signal map[string]chan struct{}
+	// inflight is the per-org set of live routed sessions (offered, not yet finished),
+	// the gauge the per-org admission cap reads. A SET keyed by session id (not a bare
+	// counter) so a re-offer after a restart re-adds idempotently and a superseded
+	// offer never double-counts or wrongly decrements the still-live session.
+	inflight map[string]map[string]struct{}
+}
+
+func newMailbox() *mailbox {
+	return &mailbox{
+		queues:   map[string][]*offer{},
+		byRun:    map[string]*offer{},
+		signal:   map[string]chan struct{}{},
+		inflight: map[string]map[string]struct{}{},
+	}
+}
+
+func (m *mailbox) inflightAddLocked(org, sess string) {
+	s := m.inflight[org]
+	if s == nil {
+		s = map[string]struct{}{}
+		m.inflight[org] = s
+	}
+	s[sess] = struct{}{}
+}
+
+func (m *mailbox) inflightRemoveLocked(org, sess string) {
+	if s := m.inflight[org]; s != nil {
+		delete(s, sess)
+		if len(s) == 0 {
+			delete(m.inflight, org)
+		}
+	}
+}
+
+// InFlight returns how many routed runs an org has live (offered, not yet finished).
+func (m *mailbox) InFlight(org string) int {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return len(m.inflight[org])
+}
+
+// routedMailbox is the ONE process-wide rendezvous, shared by the coding
+// delivery activity (Offer/Await) and the machine-facing HTTP surface
+// (Claim/Report). One mailbox, one way.
+//
+// SINGLE-REPLICA DEPENDENCY (accepted, inherited). This rendezvous is IN-PROCESS: the
+// durable delivery activity (Offer/Await, on whichever replica's tasks worker polls
+// the agent-routed queue) and the external machine's POST /claim (ingress load-
+// balanced to any replica) must land on the SAME process, because the mailbox is a
+// package global, not a shared broker. cloud already runs HARD single-replica —
+// Recreate, replicas:1 — because the embedded Badger KMS holds an exclusive file lock
+// and the audit sequence is an in-memory counter (infra/k8s/operator/crs/cloud.yaml),
+// so route-work INHERITS that guarantee for free and needs no broker. assertSingleReplica
+// logs the assumption at mount and warns loudly if a multi-replica signal is present.
+//
+// IF cloud is ever made multi-replica (the KMS lock lifted): this rendezvous MUST
+// become replica-aware — either a sticky route that pins a target's /claim to the
+// replica whose worker owns its delivery, or a shared broker (the embedded NATS/
+// JetStream already in-process, keyed by (org,target)) so Offer and Claim meet
+// regardless of which replica each hits. Until then, single-replica is the contract.
+var routedMailbox = newMailbox()
+
+// assertSingleReplica records the single-replica assumption the process-global
+// rendezvous depends on, and warns LOUDLY if a multi-replica signal is detectable
+// (CLOUD_REPLICAS > 1). It does not fail mount — cloud's replicas:1 is enforced by the
+// deployment (the KMS lock), so this is a defensive breadcrumb for the day that
+// changes, not a runtime gate. Called once from mountRouting.
+func assertSingleReplica(log luxlog.Logger) {
+	if log == nil {
+		return
+	}
+	replicas := 1
+	if v := strings.TrimSpace(os.Getenv("CLOUD_REPLICAS")); v != "" {
+		if n, err := strconv.Atoi(v); err == nil {
+			replicas = n
+		}
+	}
+	if replicas > 1 {
+		log.Warn("route-work: the routed-run rendezvous is process-global and REQUIRES cloud to run single-replica, but CLOUD_REPLICAS>1 — routed /claim will silently fail on a replica that does not own the delivery. Make the rendezvous replica-aware (sticky target route or shared broker) before scaling out.",
+			"replicas", replicas)
+		return
+	}
+	log.Info("route-work: routed-run rendezvous is in-process; assumes cloud single-replica (inherited from the KMS exclusive lock)")
+}
+
+func mbKey(org, target string) string        { return org + "\x00" + target }
+func runKey(org, target, sess string) string { return org + "\x00" + target + "\x00" + sess }
+
+// Offer files run for its (org,target) and returns the handle its durable owner
+// awaits. A re-offer of the same (org,target,sessionID) — the workflow retrying
+// or replaying after a restart — supersedes the stale prior offer (removing it
+// from the queue and unblocking its dead waiter) so a machine never claims a run
+// whose owner has already moved on.
+func (m *mailbox) Offer(run RoutedRun) *offer {
+	key := mbKey(run.Org, run.TargetID)
+	rk := runKey(run.Org, run.TargetID, run.SessionID)
+	o := &offer{mb: m, key: key, rk: rk, run: run, result: make(chan RoutedResult, 1), closed: make(chan struct{})}
+	m.mu.Lock()
+	if prev := m.byRun[rk]; prev != nil {
+		m.removeFromQueueLocked(key, prev)
+		prev.finish()
+	}
+	m.byRun[rk] = o
+	m.queues[key] = append(m.queues[key], o)
+	m.broadcastLocked(key)
+	m.mu.Unlock()
+	return o
+}
+
+// Claim blocks until an unclaimed run exists for (org,target) or ctx fires,
+// returning the oldest. The claimed offer leaves the queue but stays in byRun,
+// awaiting Report. Only this key's queue is ever read, so a claim can never
+// surface another tenant's or another machine's run.
+func (m *mailbox) Claim(ctx context.Context, org, target string) (RoutedRun, bool) {
+	key := mbKey(org, target)
+	for {
+		m.mu.Lock()
+		if q := m.queues[key]; len(q) > 0 {
+			o := q[0]
+			m.queues[key] = q[1:]
+			m.mu.Unlock()
+			return o.run, true
+		}
+		sig := m.signalLocked(key)
+		m.mu.Unlock()
+		select {
+		case <-sig:
+			// a new offer (or a superseding one) arrived — re-check
+		case <-ctx.Done():
+			return RoutedRun{}, false
+		}
+	}
+}
+
+// Report delivers a terminal result to the run's durable owner. Scoped to
+// (org,target,sessionID): a report can only ever complete a run that exact key
+// owns, so one machine can never report on behalf of another. Returns false when
+// no live offer matches (already reported, abandoned, or never existed).
+func (m *mailbox) Report(org, target, sess string, res RoutedResult) bool {
+	rk := runKey(org, target, sess)
+	m.mu.Lock()
+	o := m.byRun[rk]
+	if o == nil {
+		m.mu.Unlock()
+		return false
+	}
+	delete(m.byRun, rk)
+	m.removeFromQueueLocked(mbKey(org, target), o)
+	m.mu.Unlock()
+	o.deliver(res)
+	return true
+}
+
+// discard drops an offer the owner is done with (ctx timeout / crash / normal
+// close) so neither the queue nor byRun retains it.
+func (m *mailbox) discard(o *offer) {
+	m.mu.Lock()
+	if m.byRun[o.rk] == o {
+		delete(m.byRun, o.rk)
+	}
+	m.removeFromQueueLocked(o.key, o)
+	m.mu.Unlock()
+	o.finish()
+}
+
+func (m *mailbox) removeFromQueueLocked(key string, o *offer) {
+	q := m.queues[key]
+	for i, e := range q {
+		if e == o {
+			m.queues[key] = append(q[:i:i], q[i+1:]...)
+			return
+		}
+	}
+}
+
+// broadcastLocked wakes every Claim waiting on key by closing its signal channel;
+// a fresh channel replaces it for the next wait.
+func (m *mailbox) broadcastLocked(key string) {
+	if ch, ok := m.signal[key]; ok {
+		close(ch)
+		delete(m.signal, key)
+	}
+}
+
+func (m *mailbox) signalLocked(key string) chan struct{} {
+	ch, ok := m.signal[key]
+	if !ok {
+		ch = make(chan struct{})
+		m.signal[key] = ch
+	}
+	return ch
+}
+
+func (o *offer) deliver(res RoutedResult) {
+	o.once.Do(func() {
+		o.result <- res // buffered(1) — never blocks
+		close(o.closed)
+	})
+}
+
+func (o *offer) finish() {
+	o.once.Do(func() { close(o.closed) })
+}
+
+// OfferRoutedRun is the exported seam the coding delivery activity uses to place
+// a run into the live rendezvous. Kept here (agents owns targets + sessions) so
+// the machine-facing HTTP surface and the durable activity share ONE mailbox.
+func OfferRoutedRun(run RoutedRun) *offer { return routedMailbox.Offer(run) }
@@ -0,0 +1,166 @@
+package agents
+
+import (
+	"context"
+	"sync"
+	"testing"
+	"time"
+)
+
+func mkRun(org, target, sess string) RoutedRun {
+	return RoutedRun{Org: org, TargetID: target, SessionID: sess, Repo: "api", Branch: "agent/" + sess}
+}
+
+// A claimed run comes back to exactly one claimer, then its report reaches the
+// offerer that is awaiting it.
+func TestMailbox_OfferClaimReport(t *testing.T) {
+	m := newMailbox()
+	off := m.Offer(mkRun("acme", "tgt_1", "sess_1"))
+
+	got, ok := m.Claim(context.Background(), "acme", "tgt_1")
+	if !ok || got.SessionID != "sess_1" {
+		t.Fatalf("claim wrong: ok=%v run=%+v", ok, got)
+	}
+
+	done := make(chan RoutedResult, 1)
+	go func() {
+		res, _ := off.Await(context.Background())
+		done <- res
+	}()
+	if !m.Report("acme", "tgt_1", "sess_1", RoutedResult{OK: true, CommitSha: "abc"}) {
+		t.Fatal("report should deliver to the awaiting offer")
+	}
+	select {
+	case res := <-done:
+		if !res.OK || res.CommitSha != "abc" {
+			t.Fatalf("await got wrong result: %+v", res)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("await never received the reported result")
+	}
+}
+
+// THE tenant + machine boundary: a claim for (org,target) can NEVER surface a run
+// offered for a different org OR a different target — it is a property of the key.
+func TestMailbox_CrossTenantAndCrossMachineIsolation(t *testing.T) {
+	m := newMailbox()
+	m.Offer(mkRun("orgB", "tgt_Y", "sess_foreign_org"))
+	m.Offer(mkRun("acme", "tgt_Y", "sess_foreign_machine"))
+	m.Offer(mkRun("acme", "tgt_X", "sess_mine"))
+
+	// A claim for (acme, tgt_X) gets ONLY acme/tgt_X's run.
+	got, ok := m.Claim(context.Background(), "acme", "tgt_X")
+	if !ok || got.SessionID != "sess_mine" {
+		t.Fatalf("claim leaked across a boundary: ok=%v run=%+v", ok, got)
+	}
+	// And that queue is now empty — no foreign run fell through.
+	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+	defer cancel()
+	if _, ok := m.Claim(ctx, "acme", "tgt_X"); ok {
+		t.Fatal("a foreign run must never be claimable as acme/tgt_X")
+	}
+
+	// A Report can only complete a run under its exact key: reporting the foreign
+	// machine's session under tgt_X does nothing.
+	if m.Report("acme", "tgt_X", "sess_foreign_machine", RoutedResult{OK: true}) {
+		t.Fatal("report crossed the machine boundary")
+	}
+	if m.Report("acme", "tgt_Y", "sess_foreign_org", RoutedResult{OK: true}) {
+		t.Fatal("report crossed the org boundary")
+	}
+}
+
+// Two racing claimers, one run: exactly one wins.
+func TestMailbox_NoDoubleClaim(t *testing.T) {
+	m := newMailbox()
+	m.Offer(mkRun("acme", "tgt_1", "sess_1"))
+
+	var wins int
+	var mu sync.Mutex
+	var wg sync.WaitGroup
+	for i := 0; i < 8; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
+			defer cancel()
+			if _, ok := m.Claim(ctx, "acme", "tgt_1"); ok {
+				mu.Lock()
+				wins++
+				mu.Unlock()
+			}
+		}()
+	}
+	wg.Wait()
+	if wins != 1 {
+		t.Fatalf("exactly one claimer must win, got %d", wins)
+	}
+}
+
+// A claim with no work times out on ctx and reports no run — fail closed, never hang.
+func TestMailbox_ClaimTimesOut(t *testing.T) {
+	m := newMailbox()
+	ctx, cancel := context.WithTimeout(context.Background(), 80*time.Millisecond)
+	defer cancel()
+	if _, ok := m.Claim(ctx, "acme", "tgt_empty"); ok {
+		t.Fatal("an empty mailbox must not yield a run")
+	}
+}
+
+// The durable owner's Await unblocks (fail-closed) when its budget ctx fires with
+// no report — the machine never claimed, or claimed and died.
+func TestMailbox_AwaitFailsClosedOnDeadline(t *testing.T) {
+	m := newMailbox()
+	off := m.Offer(mkRun("acme", "tgt_1", "sess_1"))
+	ctx, cancel := context.WithTimeout(context.Background(), 80*time.Millisecond)
+	defer cancel()
+	if _, ok := off.Await(ctx); ok {
+		t.Fatal("await must fail closed when the deadline fires without a report")
+	}
+}
+
+// A re-offer of the same run (workflow retry / cloud restart) supersedes the stale
+// offer: the old waiter unblocks abandoned, and the fresh run is claimable.
+func TestMailbox_ReOfferSupersedes(t *testing.T) {
+	m := newMailbox()
+	old := m.Offer(mkRun("acme", "tgt_1", "sess_1"))
+
+	// re-offer BEFORE anyone claims the first
+	fresh := m.Offer(mkRun("acme", "tgt_1", "sess_1"))
+
+	// old is abandoned
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+	if _, ok := old.Await(ctx); ok {
+		t.Fatal("the superseded offer must not complete")
+	}
+
+	// exactly one claimable run remains, and reporting reaches the fresh offer
+	got, ok := m.Claim(context.Background(), "acme", "tgt_1")
+	if !ok || got.SessionID != "sess_1" {
+		t.Fatalf("fresh run not claimable: %+v", got)
+	}
+	if _, ok := m.Claim(ctxShort(), "acme", "tgt_1"); ok {
+		t.Fatal("the stale offer must not have left a duplicate in the queue")
+	}
+	done := make(chan struct{})
+	go func() { fresh.Await(context.Background()); close(done) }()
+	if !m.Report("acme", "tgt_1", "sess_1", RoutedResult{OK: true}) {
+		t.Fatal("report must reach the fresh offer")
+	}
+	<-done
+}
+
+// Report for an unknown/already-finished run is a clean false.
+func TestMailbox_ReportUnknownIsNoOp(t *testing.T) {
+	m := newMailbox()
+	if m.Report("acme", "tgt_1", "nope", RoutedResult{OK: true}) {
+		t.Fatal("report for an unknown run must be a no-op")
+	}
+}
+
+func ctxShort() context.Context {
+	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Millisecond)
+	_ = cancel
+	return ctx
+}
@@ -0,0 +1,119 @@
+// personalities.go seeds an org's BUILT-IN agents — the named personas a human
+// @-mentions in Hanzo Team (@dev to build, @des to design, @vi for vision). They
+// are ordinary rows in the ONE agent registry (this package's store): nothing
+// about them is special-cased downstream — they list, project into Team as bot
+// members (bots.go), and answer through the SAME agents.RunOnBehalf path every
+// other agent uses. The only thing this file adds is a one-time, idempotent
+// create so a fresh org has its crew without anyone POSTing them by hand.
+//
+// One and only one seed: keyed by the registry's UNIQUE(org,name), a re-seed is a
+// no-op (errConflict is swallowed). The Name is the @-handle (dev/des/vi), so the
+// Team mention resolves to the persona; Description is the human-facing title.
+
+package agents
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+)
+
+// persona is one built-in agent definition. Name is the lowercase @-handle;
+// Description is the display title; Instructions is the system prompt that gives
+// the persona its voice and remit.
+type persona struct {
+	Name         string
+	Description  string
+	Instructions string
+}
+
+// personalities is the canonical built-in crew. Adding one here is the ONE way a
+// new default persona ships — no per-org config, no duplicate definition. The old
+// hanzo.ai site's voices, brought into Team.
+var personalities = []persona{
+	{
+		Name:        "dev",
+		Description: "Dev — the builder",
+		Instructions: "You are Dev, Hanzo's builder. You ship. When a human @-mentions you " +
+			"you write the code, wire the change, and report what you did in plain terms — " +
+			"file paths, commands, results. You prize the smallest correct change, one and " +
+			"only one way to do a thing, and no ceremony. You never hand-wave: if you built " +
+			"it you say so with proof; if you're blocked you name the blocker. Terse, exact, " +
+			"and always moving toward a finished, working solution.",
+	},
+	{
+		Name:        "des",
+		Description: "Des — the designer",
+		Instructions: "You are Des, Hanzo's designer. You own how it looks and feels — layout, " +
+			"type, color, motion, the whole experience. When a human @-mentions you, you " +
+			"think in systems, not one-off screens: a token, a component, a consistent rule " +
+			"that reads as one product in light and dark. You give concrete, buildable design " +
+			"direction (spacing, hierarchy, states), not vague taste. Elegant, accessible, and " +
+			"opinionated — you make the obvious thing beautiful.",
+	},
+	{
+		Name:        "vi",
+		Description: "Vi — the visionary",
+		Instructions: "You are Vi, Hanzo's visionary lead. You hold the big picture and the long " +
+			"arc — where the product is going, why it matters, and what to do next to get there. " +
+			"When a human @-mentions you, you connect the dots across the org, cut through noise " +
+			"to the one thing that matters, and rally the crew around it. You think in bets and " +
+			"outcomes, name the strategy plainly, and turn a sprawling ask into a sharp, " +
+			"sequenced plan. Inspiring, decisive, and grounded in what actually ships.",
+	},
+}
+
+// SeedPersonalities ensures the built-in crew exists for org. Idempotent: an
+// already-present persona (UNIQUE org+name) is left untouched, so it is safe to
+// call on every org first-touch (a new Team workspace, say). Returns the number
+// newly created.
+//
+// It needs a model to attach — the deployment's configured default. With no
+// default model, seeding is a NO-OP (0, nil): an org gets its crew the moment the
+// binary has a model to run them on, never a half-created persona that can't run.
+// A subsystem that is not mounted also no-ops rather than erroring, so a caller on
+// the login path can call it best-effort without ever blocking a human.
+func SeedPersonalities(ctx context.Context, org string) (int, error) {
+	if mounted == nil || mounted.State.store == nil {
+		return 0, nil
+	}
+	org = strings.TrimSpace(org)
+	if org == "" {
+		return 0, nil
+	}
+	model := strings.TrimSpace(mounted.State.defaultModel)
+	if model == "" {
+		return 0, nil
+	}
+
+	created := 0
+	now := time.Now().Unix()
+	for _, p := range personalities {
+		id, err := genID("agent")
+		if err != nil {
+			return created, err
+		}
+		a := Agent{
+			ID:           id,
+			Org:          org,
+			Name:         p.Name,
+			Model:        model,
+			Instructions: p.Instructions,
+			Description:  p.Description,
+			Status:       "ready",
+			CreatedAt:    now,
+			UpdatedAt:    now,
+		}
+		err = mounted.State.store.Create(ctx, a)
+		switch {
+		case err == nil:
+			created++
+		case errors.Is(err, errConflict):
+			// Already seeded — the one-way idempotent no-op.
+		default:
+			return created, err
+		}
+	}
+	return created, nil
+}
--- a/Show More
+++ b/Show More