@lifeaitools/rdc-skills 0.35.18 → 0.35.21

package/skills/deploy/SKILL.md

@@ -1,566 +1,115 @@
 ---
 name: deploy
-description: rdc:deploy (slug, [action]) - [--fix, --hotfix] — ship to PM2 dev; promote to Coolify production
+description: rdc:deploy (slug, [action]) — run one command; exit 0 means shipped
 ---
 
 > **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
-> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
-> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
+> One command, then one line: the URL on exit 0, or the `DEPLOY-FAILED` block on
+> non-zero. No tool-call narration, no raw JSON dumps, no progress commentary.
 
+# rdc:deploy — run the program, read the exit code
 
-# rdc:deploy — Bearer Deployment Control Plane
+**This skill is not a procedure. It is one command.**
 
-**READ FIRST:** `guides/output-contract.md`. Checklist-only output. No narration.
-No raw MCP dumps. No UUIDs unless asked.
-
-> **Sandbox contract:** This skill honors `RDC_TEST=1` per `guides/agent-bootstrap.md` § RDC_TEST Sandbox Contract. Destructive external calls short-circuit under the flag.
->
-> *Under `$RDC_TEST=1`:* Modes 1 (PM2 dev deploy), 2 (new), and 5 (Coolify promote) are **entirely skipped** — echo `[RDC_TEST] skipping PM2 deploy/create/Coolify promote` and mark every `[ ]` line in those checklists as `[~]`. Modes 3 (diagnose) and 4 (audit without `--fix`) are **read-only and run normally**. Mode 4 with `--fix` skips all remediation — echo `[RDC_TEST] skipping audit --fix remediation` and report findings only. Registry SELECTs, Coolify status reads, HTTP gate probes, TLS checks, and DNS lookups are NOT destructive and run normally. Anything that writes (create app, set watch_paths, deploy trigger, **PR/admin-merge to main**, env var write, DNS write, CF cache purge, registry UPDATE/INSERT) is gated.
-
-## When to Use
-- Project lead says "deploy", "ship it", "push to production", "update the server"
-- Project lead says "promote", "patch prod", "hotfix production", "push this fix live" — use `rdc:deploy <slug> promote`
-- Dev is a Next.js app but prod is still a static site for the same slug ("dev is XJS, prod is static", "make prod Next") — use `rdc:deploy <slug> convert` (Mode 6)
-- A new app needs to be registered and deployed for the first time (`rdc:deploy new`)
-- A deployed app is behaving unexpectedly and needs diagnosis (`rdc:deploy diagnose`)
-- Running a compliance/health audit of all deployed apps (`rdc:deploy audit`)
-- A platform service needs to run only on the Coolify network, with no public domain or host port (`rdc:deploy maintenance <service>`)
-
-## Arguments
-
-- `rdc:deploy <slug>` — submit the registered `develop` deployment to the PM2 dev target
-- `rdc:deploy <slug> <ref>` — submit one registered manifest ref (never arbitrary shell or repository input)
-- `rdc:deploy <slug> promote` — promote the verified `develop` change for this app to production (Mode 5)
-- `rdc:deploy <slug> promote --hotfix <sha>` — promote a specific commit (cherry-pick just that sha to `main`)
-- `rdc:deploy <slug> convert` — convert a prod app's runtime in place from static→Next (Mode 6); use when dev is Next but prod is still a static Coolify build
-- `rdc:deploy new <slug>` — create a new Coolify app from registry
-- `rdc:deploy diagnose <slug>` — debug why an app is broken
-- `rdc:deploy audit` — fleet-wide scan for missed failures
-- `rdc:deploy audit --fix` — fleet scan + auto-remediate safe issues
-- `rdc:deploy maintenance <service>` — create, update, or verify one allowlisted private infrastructure service (Mode 7)
-- `rdc:deploy dev <slug>` — explicit alias for the first form above. Plain
-  `rdc:deploy <slug>` already targets PM2 dev, so this only makes the intent
-  unmissable when a reader expects Coolify.
-- `rdc:deploy` (no args) — print mode menu, ask which
-
-> `<ref>` is what `commands/deploy.md` called `<build-id>` before that file was
-> removed (2026-08-29). Same thing — a registered manifest ref, a commit, or a
-> tag. With no ref, the deployment is the latest commit on the app's WATCHED
-> branch, not on whatever branch happens to be checked out locally.
-
-## Modes
-
-### Mode 1 — deploy <slug> [ref]
-
-```
-rdc:deploy: <slug> → PM2 dev target
-[ ] Registry lookup (slug, uuid, branch, type, env_vars_needed)
-[ ] Runtime-source guard: if the source being deployed is static (`sites/<name>`, nixpacks/static) but the registry `runtime` for <slug> is `next`, BLOCK — never deploy a flat/static source over a Next app. A static prototype deploys only under its OWN slug (never an existing Next app's slug), dev only. Changing a slug's runtime is architectural. (`.claude/rules/production-stack-nextjs.md`)
-[ ] Git state verified (registered ref is pushed to origin)
-[ ] Dev deployment manifest resolved (application, repo path, fixed build argv, PM2 name, allowed ref, health URL)
-[ ] Local clauth retrieves `vultr-ops-api-token` internally; bearer is never printed or passed by an agent
-[ ] Mandatory pre-deploy code-review (pr-review-toolkit:code-reviewer on `git diff <last-deployed-sha>..HEAD` for this app's paths). Block deploy on `critical`/`high` findings; record `medium`/`low` and proceed.
-[ ] PUBLISH.md read from app root (warn if absent; fail if present but invalid)
-[ ] watch_paths derived from PUBLISH.md surfaces (union of all surface watch_paths arrays) and updated in app_deployments
-[ ] `clauth ops deploy --endpoint <control-plane> --application <slug> --ref <registered-ref>` accepted (202)
-[ ] Job polled at `GET /v1/ops/jobs/<id>` to terminal state; receipt proves checkout SHA, build, PM2 reload, and health probe
-[ ] Gate: HTTP 200
-[ ] Gate: TLS valid (no SSL cipher mismatch)
-[ ] Gate: cache headers correct on HTML
-[ ] Gate: named PM2 process is online at its declared port
-[ ] Gate: metadata audit (see § Metadata Audit below) — warn on gaps, do not block deploy
-[ ] Cloudflare cache purged (if proxied)
-[ ] artifact_registry INSERT per PUBLISH.md surface (if PUBLISH.md present)
-[ ] deployment_registry updated (last_deploy_at, status)
-✅ rdc:deploy: <slug> deployed in Nm Ns
-```
-
-#### Static PM2 dev sites — bearer job + served-content gate
-
-For a **static** PM2 dev site, a successful `git push` is not deployment proof:
-the formerly unreliable webhook could leave the host working tree and committed
-`dist/` stale while HTTP still returned 200. The agent MUST submit the same
-manifest-scoped `clauth ops deploy` job used by every other dev runtime, then
-record its checkout SHA, declared build, PM2 reload, and health receipt.
-
-Agents MUST NOT retrieve `vultr-dev-ssh`, stage private keys, run raw SSH, reset
-the host checkout, or invoke PM2 directly. If a served-asset hash or content
-marker does not match the declared build after the job reaches `succeeded`, mark
-the deployment verification failed and use `rdc:deploy <slug> diagnose`; only
-the server-operations recovery procedure may perform host-level repair.
-
-### Mode 2 — new <slug>
-
-**MANDATORY:** All new apps are created from `docs/runbooks/coolify-app-templates.json`. Read that file first — pick the right template, substitute the required vars, POST the exact payload. No manual field configuration. No improvisation. The template encodes all learned lessons (base_directory, build_pack, watch_paths, health_check, ports). Deviating from it breaks things.
-
-Template selection:
-- `nextjs-app` — for `apps/<name>/` (Dockerfile, turbo filter, port 3000)
-- `static-site` — for `sites/<name>/` (nixpacks, publish_directory=out, no packages)
-- `mcp-server` — for `mcp-servers/<name>/` (Dockerfile, health check enabled, custom port)
-
-```
-rdc:deploy new: <slug>
-[ ] .dockerignore present at project root (`ls {PROJECT_ROOT}/.dockerignore` — STOP if missing)
-[ ] Template loaded from docs/runbooks/coolify-app-templates.json (pick nextjs-app / static-site / mcp-server)
-[ ] Required vars substituted: NAME, APP_PATH, DOMAIN, BRANCH, PROJECT_UUID, ENVIRONMENT_UUID [+ TURBO_FILTER / PORT]
-[ ] DNS path chosen (A: staging wildcard  B: apex  C: other zone)
-[ ] DNS record verified or wildcard confirmed
-[ ] Cloudflare proxy setting correct for DNS path
-[ ] Application created via POST /applications/private-github-app (template payload)
-[ ] UUID recorded from response
-[ ] watch_paths verified via GET /api/v1/applications/<uuid> — must match template
-[ ] Env vars set in Coolify (from deployment_registry.env_vars_needed)
-[ ] First deploy triggered
-[ ] Deployment reached "finished" state
-[ ] Gate: HTTP 200 on <domain>
-[ ] Gate: TLS valid
-[ ] deployment_registry row inserted
-✅ rdc:deploy new: <slug> live at <domain>
-```
-
-### Mode 3 — diagnose <slug>
-
-```
-rdc:deploy diagnose: <slug>
-[ ] App located (uuid, domain, last deploy)
-[ ] Container state (running / restarting / stopped)
-[ ] Last 100 log lines scanned for known error patterns
-[ ] Port mismatch check (declared vs actual)
-[ ] Env var drift check (registry vs Coolify)
-[ ] watch_paths sanity check
-[ ] HTTP / TLS reachability
-[ ] Cloudflare proxy state check
-[ ] Disk space on server
-[ ] Branch mismatch check (Coolify git_branch vs expected)
-⚠️ rdc:deploy diagnose: <root cause in one sentence> — fix: <one command>
-```
-
-#### `next start` crash-loop — check `.next/BUILD_ID` FIRST
-
-When a PM2 `next start` app is crash-looping (`pm2 jlist` shows high `restart_time`
-/ "waiting restart"), check **`.next/BUILD_ID`** before chasing env/port theories —
-it is the single gate `next start` enforces (`Could not find a production build in
-the '.next' directory` repeats for every restart when it is missing). A `.next`
-tree can exist as a PARTIAL build (manifests + server artifacts but no `BUILD_ID`)
-— the signature of a `next build` that started but was interrupted/OOM-killed; the
-crash loop then churns CPU and can re-trigger the OOM (lesson
-2026-06-13-deploy-nextstart-missing-buildid: ~7300 restarts, all `BUILD_ID`-missing,
-while the documented prior lead was the NEXT_PUBLIC env issue — which was NOT the
-cause here). Fix sequence:
-```bash
-pm2 stop <app>                              # halt the loop so it stops competing for resources
-rm -rf apps/<name>/.next                    # clear the partial tree
-pnpm --filter @regen/<name> build           # ONE clean scoped build (LOCAL BUILD SAFETY)
-pm2 restart <app> --update-env
-```
-Guard: assert `apps/<name>/.next/BUILD_ID` exists before (re)starting any
-`next start` process.
-
-#### ⛔ On the 2nd IDENTICAL failed probe, STOP polling and diagnose full-state
-
-A repeated identical failure (same 404, same 502, same non-200) is a STRUCTURAL
-signal, not eventual-consistency — polling it will never clear it and reads to the
-user as stalling/throttling (lesson 2026-06-10-deploy-stop-polling-diagnose: a
-12×-404 poll loop on a remote-managed tunnel that was structurally ignoring the
-local config — it could never clear). On the **2nd identical failed check**, stop
-polling and pull GROUND TRUTH instead: list ALL processes / the whole effective
-remote config / the full event log (`debugging-protocol.md` Rule 6 — full-state, not
-a narrow filter). Poll ONLY when something is genuinely in-progress with a known
-finish (a deploy build, a DNS first-create) — never to hope a structural error
-resolves itself.
-
-### Mode 4 — audit
-
-```
-rdc:deploy audit: fleet scan
-[ ] Inventory join: Coolify apps ⋈ deployment_registry
-[ ] Orphans (in one but not the other)
-[ ] Monorepo apps missing watch_paths
-[ ] Stale deploys (>14 days since last success)
-[ ] Registry rows with status='broken'
-[ ] Failed deployments in last 7 days
-[ ] HTTP gate sweep (non-200 per domain)
-[ ] TLS cert expiry <30 days
-[ ] Port mismatches (ports_exposes vs actual container port)
-[ ] Env var drift (registry.env_vars_needed vs Coolify env)
-[ ] Branch mismatches (Coolify git_branch ≠ expected)
-[ ] Disk space on 64.237.54.189
-[ ] DNS/proxy misconfigs on configured staging wildcard
-[ ] Duplicate apps (same repo, multiple UUIDs)
-
-Findings:
-| Severity | App | Issue | Fix |
-|----------|-----|-------|-----|
-| HIGH     | ... | ...   | ... |
-⚠️ rdc:deploy audit: N HIGH · M MED · K LOW — run `rdc:deploy audit --fix` to auto-remediate safe issues
-```
-
-Severity rules:
-- **HIGH** — user-facing down (HTTP non-200, TLS invalid, container not running)
-- **MED** — degraded or drifting (watch_paths missing, env var drift, stale deploy, branch mismatch)
-- **LOW** — cleanup (orphans, duplicates, registry status stale)
-
-`--fix` auto-remediates only: missing watch_paths, registry row updates, CF cache purges. Never touches env vars, DNS, or container config without explicit confirmation.
-
-### Mode 5 — promote <slug> [--hotfix <sha>]
-
-Promote a **verified `develop` change** for one app to production. This is the sanctioned production-patch fast path — one command instead of fighting branch protection, the main-push hook, and a flaky Coolify webhook by hand.
-
-**Authorization:** production promote requires explicit user go-ahead, in either form:
-- **Per-promote:** a direct go word for THIS call ("promote", "patch prod", "push live", "go").
-- **Standing opt-in:** the user names one slug and grants it for the current session only ("auto-promote <slug> whenever dev is green", "standing go-ahead for <slug> this session"). Scope rules:
-  - One named slug per opt-in — never blanket ("auto-promote everything").
-  - Expires with the session. A new session/conversation needs a fresh opt-in; never infer one from a prior session's transcript or memory.
-  - Does not skip any other gate below — metadata-audit block, content-level verify, mandatory code review block on critical/high, scope guard, and back-merge all still run in full. The opt-in only removes the "stop and ask" step.
-  - Before EACH promote under a standing opt-in, re-verify dev is green with a **fresh** check (the content-level check further down this checklist) — "dev is green" means checked now for this call, not remembered from earlier in the session.
-
-A dev deploy requires neither form. If the user has not given either form of go-ahead for THIS promote, stop and ask first.
-
-Approved: option-2 — standing per-slug/session opt-in. Interview: 2026-07-31 (Dave), regen-root session.
-
-```
-rdc:deploy promote: <slug> → <prod-domain>
-[ ] Registry lookup: PROD row (uuid, prod branch=main, watch_paths, url)
-[ ] PUBLISH.md status gate: status=active AND prod in environments (block if not)
-[ ] Runtime-source guard: BLOCK promoting a static source to a prod row whose intended `runtime` is `next` — production apps are Next.js (DB-backed). (`.claude/rules/production-stack-nextjs.md`)
-[ ] Scope resolved: --hotfix <sha> → that commit; else the app-path commits on develop not on main
-[ ] Scope guard: promote ONLY this app's paths. NEVER merge develop→main wholesale (drags unrelated WIP to prod)
-[ ] Clean worktree off origin/main (never switch the dirty working tree)
-[ ] Export Supabase creds in the worktree BEFORE commit (the pre-commit `sync:docs` hook needs them, and a fresh worktree does NOT inherit the main checkout's `.env*`/shell env — without the key sync:docs silently regenerates a GUTTED `app-deployments.md` ("Registry: unavailable") and `git add`s it into the surgical promote; `--no-verify` is forbidden):
-      `export NEXT_PUBLIC_SUPABASE_URL=https://uvojezuorjgqzmhhgluu.supabase.co`
-      `export NEXT_PUBLIC_SUPABASE_ANON_KEY=$(curl -s http://127.0.0.1:52437/v/supabase-anon)`
-      Then ALWAYS `git show --stat HEAD` before pushing and confirm the file set is scoped — never ship the no-key gutted app-deployments.md. (lesson 2026-06-13-deploy-worktree-syncdocs-guts-app-deployments)
-[ ] Apply change: cherry-pick <sha> (or `git checkout <develop-sha> -- <app-paths>`); confirm diff = expected files only
-[ ] Mandatory pre-promote code-review (pr-review-toolkit:code-reviewer on the promote diff). Block on critical/high.
-[ ] Commit on promote branch; push branch (NOT main directly — the main-push hook blocks raw main pushes)
-[ ] Open PR base=main; merge with admin override (`gh pr merge --squash --admin --delete-branch`) — branch protection needs --admin
-[ ] EXPLICITLY trigger Coolify deploy — NEVER rely on the GitHub→Coolify webhook (it silently no-ops on some merges even with auto-deploy ON)
-[ ] Deployment reached "finished" state (poll coolify_events / deployment status)
-[ ] Gate: HTTP 200 on prod domain
-[ ] Gate: content-level check — assert the actual changed string is live (200 alone is NOT proof; origin may serve stale)
-[ ] Gate: TLS valid
-[ ] Gate: metadata audit (see § Metadata Audit below) — BLOCK promote on any missing required item
-[ ] Cloudflare cache purged (if proxied)
-[ ] deployment_registry updated (last_deploy_at, last_deploy_commit, status)
-✅ rdc:deploy promote: <slug> live in prod — <changed-string> verified
-```
-
-**The explicit Coolify trigger (the whole point — do not skip):** submit
-`clauth ops promote --endpoint <control-plane> --application <registered-coolify-uuid>`.
-The local client retrieves `vultr-ops-api-token` internally; the server-side
-allowlist owns the Coolify UUID and keeps `coolify-api` out of agent inputs and
-transcripts. Poll the returned job or subscribe to
-`GET /v1/ops/jobs/<id>/events` until the redacted receipt reaches a terminal
-state.
-
-**Why each guard exists (lessons from 2026-06-05 EF Hooper promote):**
-- `main` branch protection rejects PR merge without `--admin`; a raw `git push …:main` is blocked by the main-push hook → must go branch → PR → admin-merge.
-- Coolify auto-deploy was **ON** for the app yet the merge did **not** auto-deploy — a webhook-delivery flake. A promote must ALWAYS trigger the deploy explicitly and verify; never hope the webhook fired.
-- `develop` was 87 commits ahead of `main` (unrelated apps' WIP). Promoting must be surgical (this app's paths / one sha), never a develop→main merge.
-- HTTP 200 was returned by the stale origin the whole time — only a content-level assertion (`curl … | grep '<new string>'`) proves the promote landed.
-
-### Mode 6 — convert <slug> (prod runtime static→Next, in place)
-
-One-time conversion of an existing **production** Coolify app from a static/nixpacks build to the Next.js (dockerfile) runtime, **in place** — same UUID, same fqdn, same DNS. After this, the slug is a normal Next app and every future ship is just `rdc:deploy <slug> promote`. This is the mode for "dev is Next, prod is still static" (the `vlas.earth` / `life.ai` class). `promote` alone CANNOT do this — it re-triggers the prod app's existing (static) build; only `convert` changes the build config.
-
-**Authorization:** this changes a production app's runtime — **architectural** per `.claude/rules/production-stack-nextjs.md` + `.claude/rules/architectural-change-approval.md`. Requires explicit user go-ahead for THIS slug. Stop and ask if not given.
-
-**Why in-place PATCH, not recreate:** keeps the application UUID, fqdn (apex + `www`), DNS binding, and project — zero DNS cutover, zero window where the domain is unbound. PATCH switches the build pack; the next deploy builds the Next app on the same application object.
-
-```
-rdc:deploy convert: <slug> → <prod-domain>  (static→Next, in place)
-[ ] Go-ahead confirmed for THIS slug (production runtime change — architectural)
-[ ] Registry lookup: PROD coolify_uuid, fqdn, project/env, current build_pack
-[ ] Confirm it IS a convert: dev runtime=next AND prod build_pack ∈ {static, nixpacks}. If prod build_pack already `dockerfile` → already converted, fall through to Mode 5 promote.
-[ ] Source Next-prod-readiness preflight (BLOCK on any miss):
-      - apps/<name>/Dockerfile present (prod build) — BLOCK "source not Next-prod-ready: add Dockerfile" if missing
-      - start/listen port reconciled with intended ports_exposes (no dev-only port like :3214 leaking to prod)
-      - PUBLISH.md present, build_type=nextjs, status=active, prod in environments
-[ ] Mandatory pre-convert code-review (pr-review-toolkit:code-reviewer on the apps/<name> diff being promoted). Block on critical/high.
-[ ] Promote app code to main (Mode 5 path): clean worktree off origin/main → checkout apps/<name> paths (or cherry-pick) → confirm diff = expected files only → branch → PR base=main → `gh pr merge --squash --admin --delete-branch`
-[ ] LOCKFILE IMPORTER (mandatory for an app NEW to main): if `git show origin/main:pnpm-lock.yaml | grep -c "apps/<name>:"` is 0, the Docker `pnpm install --frozen-lockfile` WILL fail. In the clean main worktree run `pnpm install --lockfile-only` (adds only the apps/<name> importer; verify the diff is minimal — do NOT promote develop's whole lockfile, it carries unrelated drift) and include `pnpm-lock.yaml` in the SAME promote PR.
-[ ] In-place PATCH prod Coolify app <uuid> to nextjs-app template fields:
-      build_pack=dockerfile · dockerfile_location=/apps/<name>/Dockerfile · base_directory=/ ·
-      build_command="pnpm turbo run build --filter=<pkg>" · start_command="pnpm --filter=<pkg> start" ·
-      install_command="pnpm install --frozen-lockfile" · ports_exposes=<port> ·
-      watch_paths="apps/<name>/**\npackages/**"
-      (clear publish_directory; static-only field)
-[ ] PROXY LABELS (mandatory — the static-app `custom_labels` are read-only and do NOT auto-update on a build_pack PATCH): fetch `custom_labels`, base64-decode, rewrite `loadbalancer.server.port=80`→`=<port>` (all routers) AND `upstreams 80}}`→`upstreams <port>}}`, and STRIP the static `caddy_*.try_files=…/index.html /index.php` lines (wrong for a Next app), re-base64, PATCH `custom_labels`. Skipping this = container serves on :<port> but the proxy still routes :80 → **502** even though the build "finished" and the app logs "Ready". (Note: the API rejects `is_container_label_readonly_enabled` and a non-base64 `custom_labels` — you must hand-rewrite the base64.)
-[ ] Env vars present in Coolify (compare registry.env_vars_needed); set any missing
-[ ] EXPLICITLY trigger deploy: GET /api/v1/deploy?uuid=<PROD_UUID>&force=true — never rely on the webhook
-[ ] Deployment reached "finished" state (poll coolify_events)
-[ ] Gate: SSR proof — prod HTML now contains `/_next/static` (it is the Next app, not the old static build)
-[ ] Gate: HTTP 200 + content-level assertion of a known string from the Next render
-[ ] Gate: TLS valid; cache headers correct on HTML
-[ ] Gate: metadata audit (see § Metadata Audit) — BLOCK on any required gap
-[ ] Cloudflare cache purged (apex + www)
-[ ] app_deployments updated: runtime intent → next, notes (converted static→Next <date>), last_deploy_at, last_deploy_commit, status=active
-[ ] `apps` row runtime=next confirmed
-✅ rdc:deploy convert: <slug> now Next.js in prod — SSR verified at <prod-domain>
-```
-
-**Rollback:** PATCH the app back to static (`build_pack=static`, `base_directory=/sites/<name>`, `publish_directory=/sites/<name>`, `ports_exposes=80`, `watch_paths=sites/<name>/**`) and redeploy. `sites/<name>` stays in the repo precisely so this rollback is always available.
-
-### Mode 7 — maintenance <service> (private Coolify infrastructure)
-
-Use this mode for a **private service**, not a website: its consumers run on the
-same Coolify Docker network and reach it by internal service alias.  It is the
-only sanctioned path for creating or changing private infrastructure such as
-the Coolify clauth runtime.
-
-**Authorization and scope:** maintenance may create, deploy, or update only a
-service declared in the `private-service` template. It must never add a public
-domain, host-port publication, DNS record, Cloudflare route, or public probe.
-Destructive retirement remains separately approval-gated and is not part of
-this command. Secrets are checked by **key name only**; their values must never
-be retrieved, logged, or copied into source control.
-
-```
-rdc:deploy maintenance: <service>
-[ ] Service allowlisted by the `private-service` template; source repository, branch, Dockerfile, port, and health path resolved
-[ ] Private-only contract checked: domains empty, no host port mapping, and service alias declared for the Coolify network
-[ ] Required secret keys present by name only; values neither read nor emitted
-[ ] Dockerfile preflight: service binds its container interface and exposes only its declared internal port
-[ ] Create or update performed through the private-service template; no manual Coolify field configuration
-[ ] Deploy explicitly triggered and reaches finished state
-[ ] Container health gate passes at the declared health path
-[ ] In-network probe from an existing Coolify workload reaches the declared service alias and health path
-[ ] Public exposure gate passes: no domain, DNS, TLS, or host-port endpoint exists for the service
-[ ] Service record and maintenance receipt updated without secret values
-✅ rdc:deploy maintenance: <service> private service healthy on the Coolify network
-```
-
-**Current allowlisted service — `clauth`:** source `LIFEAI/clauth` on `main`;
-Dockerfile `/Dockerfile`; internal port `52437`; health path `/ping`; required
-secret key names `CLAUTH_MACHINE_ID` and `CLAUTH_MASTER_PASSWORD`. Its Docker
-runtime must bind `0.0.0.0` *inside the container only*. Consumers use the
-resolved Coolify network alias, never `localhost` and never a published URL.
-
-**Verification boundary:** a host-side request to this service is not evidence
-of correctness. Verify it from a running workload on the same Coolify network;
-the expected result is a successful internal health response while public
-domain, TLS, and host-port checks remain absent.
-
-**PATCH command (in-place build-pack switch):**
-```bash
-_COOLIFY=$(curl -s http://127.0.0.1:52437/v/coolify-api)
-curl -s -X PATCH -H "Authorization: Bearer $_COOLIFY" -H "Content-Type: application/json" \
-  -d '{"build_pack":"dockerfile","dockerfile_location":"/apps/<name>/Dockerfile","base_directory":"/","build_command":"pnpm turbo run build --filter=<pkg>","start_command":"pnpm --filter=<pkg> start","install_command":"pnpm install --frozen-lockfile","ports_exposes":"<port>","watch_paths":"apps/<name>/**\npackages/**"}' \
-  "$DEPLOY_API_BASE/api/v1/applications/<PROD_UUID>"
 ```
-
-## Metadata Audit
-
-After a successful deploy or promote, audit the live site's `<head>` metadata. Run this against the deployed URL (not a local file).
-
-**Check list** (curl the deployed URL, parse the HTML `<head>`):
-
-| # | Item | How to check | Required | Severity |
-|---|------|-------------|----------|----------|
-| 1 | `<title>` | grep `<title>` — non-empty, not default/placeholder | yes | block |
-| 2 | `<meta name="description">` | content attr ≥ 50 chars, ≤ 160 chars | yes | block on promote; warn on deploy |
-| 3 | `<link rel="canonical">` | href present, starts with `https://`, matches the deployed domain | yes | block on promote; warn on deploy |
-| 4 | `og:title` | `<meta property="og:title">` present | yes | block on promote; warn on deploy |
-| 5 | `og:description` | `<meta property="og:description">` present, ≥ 50 chars | yes | block on promote; warn on deploy |
-| 6 | `og:image` | `<meta property="og:image">` present, URL returns HTTP 200 | yes | block on promote; warn on deploy |
-| 7 | `og:url` | present, matches canonical | recommended | warn |
-| 8 | `twitter:card` | `summary_large_image` or `summary` | recommended | warn |
-| 9 | `twitter:image` | present, URL returns HTTP 200 | recommended | warn |
-| 10 | Favicon | `<link rel="icon">` present, href returns HTTP 200 | yes | block on promote; warn on deploy |
-| 11 | `sitemap.xml` | `<domain>/sitemap.xml` returns HTTP 200 | recommended | warn |
-| 12 | `robots.txt` | `<domain>/robots.txt` returns HTTP 200 | recommended | warn |
-| 13 | Version | `<meta name="version">` or visible version string in page | yes (project rule) | warn |
-
-**Behavior by mode:**
-- **Mode 1 (deploy):** run the audit after HTTP/TLS gates. Print a table of results. **Warn** on gaps but do NOT block the deploy — dev deploys are iterative.
-- **Mode 5 (promote):** run the audit after content-level check. **Block the promote** if any item marked "block on promote" is missing. Print the table and require the metadata to be fixed before re-attempting.
-- **Mode 4 (audit):** include the metadata sweep in the fleet scan (one row per app per missing item in the findings table).
-
-**Implementation — one-liner per check:**
-```bash
-URL="https://<domain>"
-HEAD=$(curl -s "$URL" | sed -n '/<head/,/<\/head>/p')
-echo "$HEAD" | grep -ioE '<title>[^<]+</title>'
-echo "$HEAD" | grep -ioE 'name="description"[^>]*content="[^"]*"'
-echo "$HEAD" | grep -ioE 'rel="canonical"[^>]*href="[^"]*"'
-echo "$HEAD" | grep -ioE 'property="og:title"[^>]*content="[^"]*"'
-echo "$HEAD" | grep -ioE 'property="og:image"[^>]*content="[^"]*"'
-echo "$HEAD" | grep -ioE 'name="twitter:card"[^>]*content="[^"]*"'
-echo "$HEAD" | grep -ioE 'rel="icon"[^>]*href="[^"]*"'
-echo "$HEAD" | grep -ioE 'name="version"[^>]*content="[^"]*"'
-curl -s -o /dev/null -w "%{http_code}" "$URL/sitemap.xml"
-curl -s -o /dev/null -w "%{http_code}" "$URL/robots.txt"
-OG_IMG=$(echo "$HEAD" | grep -ioE 'property="og:image"[^>]*content="([^"]*)"' | grep -ioE 'https://[^"]*')
-[ -n "$OG_IMG" ] && curl -s -o /dev/null -w "%{http_code}" "$OG_IMG"
+rdc:deploy <slug>            →  node scripts/deploy/deploy.mjs <slug>
+rdc:deploy <slug> promote    →  node scripts/deploy/deploy.mjs <slug> promote
 ```
 
-**Why this exists (2026-06-05):** life.ai deployed to production with zero social/SEO metadata — no description, no OG, no favicon, no sitemap. HTTP 200 + TLS + content passed; metadata was invisible to the existing gates. This audit catches that class of defect.
+Run it from the regen-root checkout you are working in. That is the whole
+instruction. There is no checklist to follow, no mode to pick, and no decision
+for you to make on the success path.
 
-## Hotlink referer allowlist — new media.place.fund consumer domains
+## Exit 0 — you are done
 
-When onboarding a NEW brand domain that loads assets from `media.place.fund`, add
-that domain to the hotlink-protection Worker's referer allowlist **before
-go-live** (lesson 2026-06-14-deploy-issholiving-referer-hotlink-403: a new brand
-domain served its own HTML fine but every `media.place.fund` image returned 403
-because the hotlink Worker rejected the unknown `Referer`). The image 403 is
-invisible to the HTTP-200 / TLS / metadata gates — they probe the HTML document,
-not the cross-origin asset.
+Print the URL the program reports, and stop.
 
-- Add the new origin (apex + `www`, dev + prod) to the Worker's referer allowlist
-  and redeploy the Worker before the brand domain goes live.
-- Verify with an explicit `Referer` probe (NOT a bare curl — a missing Referer can
-  pass while the real browser Referer fails):
-  ```bash
-  curl -s -o /dev/null -w "%{http_code}" -e "https://<new-brand-domain>/" \
-    "https://media.place.fund/<a-known-asset-path>"   # expect 200, not 403
-  ```
+Do not verify it again, do not audit anything, do not "while I'm here". The
+program already resolved the slug from the registry, submitted the build and the
+ship, polled the job to a terminal phase, health-probed the deployed URL and
+wrote a receipt under `.rdc/evidence/deploys/`. If any of those had failed, the
+exit code would not have been 0.
 
-## PUBLISH.md Integration
+## Exit non-zero — and ONLY then, diagnose
 
-Every deploy reads `PUBLISH.md` from the app's source root to derive `watch_paths` and to register surfaces in Studio `artifact_registry`.
+Every non-zero exit prints a `DEPLOY-FAILED` block naming four things — **which
+step, which command, which exit code, and what the tool actually said** —
+followed by the same record as one line of JSON.
 
-### Step 6 — Read PUBLISH.md from the app root
+| exit | meaning | first move |
+|---|---|---|
+| 2 | usage — bad or missing arguments | read the usage line; this program takes a slug and optionally `promote` |
+| 3 | deploy manager unreachable | `pm2 restart regen-deploy-mgr` (it is a local PM2 process), then re-run |
+| 4 | slug not resolvable or not routable | the block names what is missing — a registry row, or an allowlist entry |
+| 5 | a submitted job failed or was rejected | the block carries the manager's own step, command, exit code and stderr tail |
+| 6 | the job succeeded but the health probe did not | bytes shipped, app did not come up — read the job the block names |
+| 7 | polling exceeded the deadline | the job is NOT cancelled; the block gives the URL to read it |
 
-```bash
-MONOREPO_PATH=$(get_app_deployments_monorepo_path "$SLUG")
-PUBLISH_MD="$MONOREPO_PATH/PUBLISH.md"
+**Fix the script, never the symptom.** When the deploy is wrong, the repair
+belongs in `scripts/deploy/deploy.mjs` or in the deploy manager it calls. A
+one-off workaround leaves the next agent to rediscover the same failure, which
+is the exact history this command replaced.
 
-if [ ! -f "$PUBLISH_MD" ]; then
-  echo "WARN: PUBLISH.md missing for $SLUG — using app_deployments.watch_paths only"
-  # Deploy continues; watch_paths derivation and artifact_registry INSERT are skipped
-fi
-```
-
-PUBLISH.md format: see `C:/Dev/rdc-skills/guides/publish-md-spec.md` (authoritative).
+## Hand-rolling a deploy is guard-blocked
 
-Required frontmatter fields: `schema_version`, `entity_slug`, `artifact_type`, `environments`, `status`.
-One or more `<!-- SURFACE:<id> -->` … `<!-- /SURFACE:<id> -->` blocks per surface (each with `path`, `source_dir`, `build_type`, `visibility`, `cache`, `watch_paths`).
+Over a remote shell, these are refused at the tool layer by the
+`hand-rolled-deploy` rule (both engines):
 
-If PUBLISH.md is **present but invalid** (missing required field, bad enum, no surface blocks): abort deploy with `BLOCKED: PUBLISH.md parse error for <slug> — <reason>`.
+- `pm2 restart|reload|start|stop|delete` aimed at an application
+- an application build (`next build`, `pnpm build`, `turbo run build`, …)
+- `git pull` on a deploy target
 
-### Step 7 — Derive watch_paths from PUBLISH.md surfaces
+Direct Coolify deploy triggers are refused by `coolify-direct`.
 
-Union all `watch_paths` arrays across every surface section in PUBLISH.md. Update `app_deployments.watch_paths` for the app slug to this derived union before triggering the Coolify deploy.
+Not blocked, because they are how you diagnose the failure above: remote `pm2
+list` / `pm2 logs` / `pm2 describe`, `docker ps`, anything local, and PM2
+lifecycle operations on infrastructure daemons (codeflow-mcp, fs-mcp, rtp,
+regen-deploy-mgr, pollers).
 
-```sql
-UPDATE app_deployments
-SET watch_paths = '<union-of-surface-watch_paths>'
-WHERE app_slug = '<slug>';
-```
+Genuine host-level recovery goes through `flow=sv-override`. Reaching for it to
+avoid a failing deploy is not recovery.
 
-Also PATCH the Coolify application's `watch_paths` field:
-
-```bash
-_COOLIFY=$(curl -s http://127.0.0.1:52437/v/coolify-api)
-WATCH_PATHS_JSON=$(derive_watch_paths_union "$PUBLISH_MD")
-curl -s -X PATCH -H "Authorization: Bearer $_COOLIFY" \
-  -H "Content-Type: application/json" \
-  -d "{\"watch_paths\":\"$WATCH_PATHS_JSON\"}" \
-  "$DEPLOY_API_BASE/api/v1/applications/<uuid>"
-```
-
-### Step 15 — storeArtifact per surface (after successful deploy)
-
-After the deployment reaches "finished" state, INSERT one row into Studio `artifact_registry` for each surface declared in PUBLISH.md:
-
-| Column | Value |
-|--------|-------|
-| `entity_slug` | from PUBLISH.md frontmatter `entity_slug` |
-| `artifact_type` | from PUBLISH.md frontmatter `artifact_type` |
-| `canonical_url` | `https://<app_deployments.url><surface.path>` |
-| `surface_id` | surface name from `<!-- SURFACE:<id> -->` marker |
-| `commit_sha` | HEAD SHA of the deploy |
-| `published_at` | `now()` |
-
-Use the Supabase MCP (`mcp__claude_ai_Supabase__execute_sql`) from the supervisor session:
-
-```sql
-INSERT INTO artifact_registry (entity_slug, artifact_type, canonical_url, surface_id, commit_sha, published_at)
-VALUES ('<entity_slug>', '<artifact_type>', 'https://<url><path>', '<surface_id>', '<commit_sha>', now())
-ON CONFLICT (entity_slug, surface_id) DO UPDATE SET
-  canonical_url = EXCLUDED.canonical_url,
-  commit_sha = EXCLUDED.commit_sha,
-  published_at = EXCLUDED.published_at;
-```
-
-If the INSERT fails, surface the failure in the deploy output but **do NOT roll back the deploy**. The artifact registry is a post-deploy record, not a deploy gate.
-
-## Control-plane Access — clauth bearer jobs
-
-There is no Coolify MCP server. Agent-facing deploy and promotion operations use
-the clauth control plane, not raw PM2, SSH, or the Coolify deploy-trigger API.
-The local fixed client obtains `vultr-ops-api-token` from local clauth and sends
-it as `Authorization: Bearer`; it never prints the token.
-
-```bash
-clauth ops catalog --endpoint <control-plane>
-clauth ops list --endpoint <control-plane>
-clauth ops describe --endpoint <control-plane> --target <pm2-name>
-clauth ops deploy --endpoint <control-plane> --application <slug> --ref <registered-ref>
-clauth ops promote --endpoint <control-plane> --application <registered-coolify-uuid>
-clauth ops job --endpoint <control-plane> --job <job-id>
-```
-
-Returns are accepted jobs (`202`) and the server persists redacted `queued`,
-`running`, `building`, `waiting`, and terminal events. Generic PM2 catalog
-operations are policy-disabled unless the server owner explicitly allowlists the
-operation and target.
-
-**Domain change / namespace migration** (lesson 2026-06-13-deploy-media-manager-namespace-migration):
-PATCH `applications/<uuid>` with `{"domains":"https://<host>"}` — never `fqdn`.
-For an app NEW to main (first prod deploy) also bring the app + a lockfile importer
-to main (clean worktree off origin/main, `pnpm install --lockfile-only`, verify the
-diff = additions for `apps/<name>:` only); resolve the lockfile-guard vs scope-guard
-collision by committing the app+lockfile as a SINGLE `chore(infra):`-subject commit
-(the scope-guard's documented escape hatch) so both pre-commit guards pass.
-
-**Never print `$_COOLIFY` to stdout.** Inline from clauth only — do not assign raw strings.
-
-If clauth daemon is not responding (`curl -s http://127.0.0.1:52437/ping` fails):
-```
-BLOCKED: credential provider is not responding.
-Fix: start the project's credential provider or configure deployment credentials through env vars, then retry.
-I cannot proceed until this is resolved.
-```
-
-## Deployment Event Log — `coolify_events`
-
-Every Coolify deploy emits a webhook → `coolify_events` row. Use this for last-N-deploys queries, debugging failed deploys, and reconciling local state with Coolify state.
-
-Query the last 5 events for an app:
-```sql
-SELECT created_at, event_type, status, branch, commit_hash, duration_seconds
-FROM coolify_events
-WHERE app_uuid = '<uuid>' OR app_name = '<slug>'
-ORDER BY created_at DESC LIMIT 5;
-```
+## What this command deliberately does NOT do
 
-Fields:
-- `app_uuid` — Coolify application UUID (matches `app_deployments.coolify_uuid`)
-- `event_type` — `started | succeeded | failed | cancelled` (canonical values; consult webhook receiver for full enum)
-- `status` — overall deploy status
-- `branch`, `commit_hash`, `commit_message` — git context
-- `duration_seconds` — total deploy time
-- `payload` — full webhook payload (jsonb) for forensic debugging
+`deploy` and `promote` are the only two actions. The program refuses anything
+else by name rather than guessing.
 
-When diagnosing a broken deploy in Mode 3: query `coolify_events` FIRST before re-running the deploy — the most recent event row tells you whether the previous deploy actually triggered, whether it failed, and how long it ran. Faster than checking the Coolify UI.
+The previous version of this file carried seven modes — `new`, `diagnose`,
+`audit`, `convert`, `maintenance` alongside deploy and promote — across 566
+lines of checklists and prose. Every one of them was an instruction an agent had
+to read and interpret, and interpretation is why deployments broke differently
+each time. **Those modes are not implemented here and are not silently available
+elsewhere** — that is a real reduction in what this skill offers, recorded rather
+than glossed:
 
-## Capture lessons (exit step)
+| dropped mode | where the capability stands now |
+|---|---|
+| `new <slug>` | not automated — register the app in `app_deployments` first; this program ships registered apps, it does not create them |
+| `diagnose <slug>` | the failure block plus the manager's job record (`GET :52438/v1/local/jobs/<id>`) and its two-box dashboard |
+| `audit` | the manager's dashboard (`GET :52438/v1/local/dashboard?box=local\|vultr`) — PM2 state joined against the registry, with URL health |
+| `convert` | an architectural change; goes through `.claude/rules/architectural-change-approval.md` |
+| `maintenance <service>` | private Coolify infrastructure; unchanged and not part of this command |
 
-Before the final verdict line, follow `.rdc/guides/lessons-learned-spec.md` § Capture procedure. If this run taught something non-obvious — a first root-cause theory that turned out wrong, the documented/standard path not working, a missing gate or check that cost a round, or a surprising tool/infra behavior — write one `.rdc/lessons/<YYYY-MM-DD>-deploy-<short-slug>.md` per lesson using the schema in that spec. Set `scope` (`simple` | `architectural`) and `status` (`open`, or `applied` if you shipped the fix in this same run, with the commit linked). Commit the lesson file(s) on `develop` alongside the run's other commits, and note "N lessons captured" in your verdict/summary. A run that taught nothing writes nothing — absence is the default.
+The removed prose also carried real, hard-won operational knowledge — the
+`next start` `BUILD_ID` crash-loop, the `media.place.fund` hotlink referer
+allowlist, the `<head>` metadata audit, the lockfile-importer trap on a first
+promote to `main`. That knowledge is in git history for this file and in the
+named `.rdc/lessons/` entries it cited. **It was removed from here because prose
+that duplicates behaviour drifts from it** — not because it stopped being true.
+Where such a check belongs in the pipeline, it belongs in the program or in the
+manager, where it runs, rather than in a document that hopes to be read.
 
-## References
+## Authorization
 
-- Type-specific checklists + DNS tree + gate commands: `docs/runbooks/coolify-deploy-checklist.md`
-- Rules / registry RPCs / hard limits: `.claude/context/coolify-deployment.md`
-- Infrastructure constants:
-  ```
-  Server UUID:     ih386anenvvvn6fy1umtyow0
-  Server IP:       64.237.54.189
-  Dashboard:       <deployment-dashboard-url>
-  GitHub App UUID: xdmcy60putp5h9j7k4kwg9c3
-  ```
+A dev deploy needs no approval. `promote` puts bytes on production and needs
+explicit go-ahead for that call. The program itself refuses to promote anything
+that is not an image-model app, because promote retags the digest dev already
+runs — **a promote never builds**, and one that fell back to building would ship
+bytes production has never seen under a name claiming it had.
 
-## Supersedes
+## Verification
 
-`coolify-deploy` standalone skill (kept for back-compat; new work uses `rdc:deploy`).
+`node scripts/deploy/__tests__/deploy.test.mjs` (node --test) covers the exit
+contract; `scripts/deploy/atf.ladder.mjs` holds golden-capture records of every
+enumerated failure; `scripts/deploy/atf.probe.mjs` is the live probe against the
+running manager. Full climb: `node C:/Dev/atf/bin/ladder-run.mjs scripts/deploy`.