@m-kopa/launchpad-cli 0.26.1 → 0.27.1

package/skills/launchpad-deploy/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: launchpad-deploy
-description: Walk a Launchpad user through deploying an app from their local working directory (Model A — `launchpad init` + `launchpad deploy`). Wraps the CLI verbs end-to-end: detects the app shape, scaffolds `launchpad.yaml`, resolves the allowed Entra group via `launchpad groups`, bundles the CWD via `launchpad deploy`, and tails the resulting content PR. Use when someone says "deploy a new app", "ship my app to Launchpad", "/launchpad-deploy", "I have an app locally — get it on Launchpad", or any variant. Resume/abandon for legacy in-flight provisioning is at the bottom.
-version: 0.26.1
+description: Walk a Launchpad user through deploying an app from their local working directory (Model A — `launchpad init` + `launchpad deploy`). Wraps the CLI verbs end-to-end: detects the app shape, scaffolds `launchpad.yaml`, resolves the allowed Entra group via `launchpad groups`, bundles the CWD via `launchpad deploy`, and watches the rollout via `launchpad status`. Use when someone says "deploy a new app", "ship my app to Launchpad", "/launchpad-deploy", "I have an app locally — get it on Launchpad", or any variant. Resume/abandon for legacy in-flight provisioning is at the bottom.
+version: 0.27.1
 ---
 
 <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -31,12 +31,13 @@ esac
 # /launchpad-deploy
 
 Model A deploy flow: the user already has an app in their working
-directory (Vite/React, static, or container-shape), and wants it
+directory (Vite/React or static), and wants it
 running on Launchpad. The CLI handles everything end-to-end —
 detection, scaffolding, group resolution, bundling, upload, and the
-content PR the bot opens on their behalf. **No `gh`, `jq`, or `curl`
-required; no M-KOPA GitHub access required.** External users with a
-Cf Access account are first-class.
+commit the bot lands on the app repo. **No `gh`, `jq`, or `curl`
+required; no M-KOPA GitHub access required.** External users without
+M-KOPA GitHub access are first-class — a Launchpad sign-in
+(`launchpad login`, M-KOPA Microsoft account) is all they need.
 
 ## Constants (single source of truth)
 
@@ -106,7 +107,10 @@ If the user is unsure, `launchpad init` itself runs an auto-detector
 (M-1216 T2): it looks for `package.json`, `vite.config.{ts,js}`, a
 lockfile, a `functions/` subdirectory, etc., and infers app-type +
 package manager + build command + dest dir. Surface what it
-discovered before committing to a slug.
+discovered before committing to a slug. Genuine ambiguity (multiple
+lockfiles, missing vite config, monorepo-shape root) aborts loudly —
+resolve it by passing `--type` explicitly or skipping detection with
+`--no-detect`.
 
 ### A.2 Scaffold `launchpad.yaml`
 
@@ -116,31 +120,34 @@ launchpad init
 
 This is interactive by default. It will ask for:
 
-- **slug** — `lowercase-with-hyphens`, 3–30 chars, must not start or
-  end with a hyphen. Reuse-rejection is server-side; you don't need
-  to pre-check.
-- **display name** — free text, shown in the portal catalogue.
-- **app type** — `static`, `react`, `react+api`, or `container`. The
-  detector pre-selects the right one for Vite/React layouts; the
-  user overrides if needed.
-- **team / owner** — for the registry.
-- **allowed Entra group** — see §A.3.
+- **name (slug)** — lowercase letters, digits, and hyphens; 2–63
+  chars; must start and end alphanumeric. Reuse-rejection is
+  server-side; you don't need to pre-check.
+- **team** — for the registry.
+- **owner email** — must be a valid email address.
+- **deployment type** — `static`, `react`, `react+api`, or
+  `container`. The detector pre-selects the right one for Vite/React
+  layouts; the user overrides if needed.
+- **allowed_entra_groups** — one or more, comma-separated; see §A.3.
 
 Non-interactive form for scripting:
 
 ```bash
 launchpad init --non-interactive \
-  --slug <slug> \
-  --display-name "<display name>" \
-  --app-type <apptype> \
+  --name <slug> \
+  --type <apptype> \
   --team <team> \
   --owner <owner-email> \
   --group <group>
 ```
 
-`--app-type` must be one of `static`, `react`, `react+api`, or
-`container`. `--group` accepts the Entra group's display name or
-UUID (the bot canonicalises to the UUID).
+`--type` must be one of `static`, `react`, `react+api`, or
+`container`. `--group` (preferred long form `--allowed-group`,
+repeatable for multiple groups) accepts the Entra group's display
+name or UUID (the bot canonicalises to the UUID). Other flags:
+`--description <text>`, `--auth <mode>` (see §A.5),
+`--session-duration <d>`, `--hostname <host>` (repeatable),
+`--out <path>`, `--force`, `--no-gitignore`, `--no-detect`.
 
 `launchpad init` writes `./launchpad.yaml` and exits 0. Re-running
 against an existing file is rejected unless `--force` is passed —
@@ -157,20 +164,19 @@ commit to a slug:
 | `static`    | n/a                   | n/a                                     | n/a                    | No bundler, no TS, no React.                           |
 | `react`     | n/a                   | client-side or remote-fetch only        | n/a                    | SPA only — no server-side anything.                    |
 | `react+api` | `hono` (exclusive)    | Cloudflare D1 / Neon (HTTP) / KV / R2   | **Sibling cron Worker** (Pages has no `scheduled` handler — see "Two-tier apps" below) | Requires `compatibility_flags = ["nodejs_compat"]` in `wrangler.toml` (ADR-0011 carve-out). |
-| `container` | any HTTP server       | any (container-local or HTTP backend)   | container-local        | Single HTTP port; deployed via Cloudflare Containers.  |
-
-**Will not run on Launchpad** (representative — not exhaustive):
-`fastify` / `@fastify/*` / `express` / `koa` / `@koa/*` /
-`@nestjs/*` / `hapi` / `@hapi/*`, `better-sqlite3` / native
-`sqlite3`, native TCP drivers (`pg`, `mysql`, `mysql2`, `mongodb`,
-`mongoose`, `redis`, `ioredis`), `dotenv`, `setInterval` /
-`setTimeout` daemons, top-level `Dockerfile` / `docker-compose.yml`
-on non-container app-types, `nginx.conf`, `Procfile`, `pm2`,
-`pm2.config.js`, `ecosystem.config.js`, `forever`, `nodemon`. The
-**canonical validation list** is `/launchpad-content-pr` § Stack-fit
-pre-flight — that skill enforces the gate at deploy time. If the
-existing app uses any of these, plan the swap **before** picking a
-slug — do not deploy first and port later.
+| `container` | any HTTP server       | any (container-local or HTTP backend)   | container-local        | Single HTTP port. Schema-valid, but the guided flow in this skill covers `static`/`react`/`react+api` — container guidance ships separately. |
+
+**Will not run on the Workers runtime** (advisory — representative,
+not exhaustive): `fastify` / `@fastify/*` / `express` / `koa` /
+`@koa/*` / `@nestjs/*` / `hapi` / `@hapi/*`, `better-sqlite3` /
+native `sqlite3`, native TCP drivers (`pg`, `mysql`, `mysql2`,
+`mongodb`, `mongoose`, `redis`, `ioredis`), `dotenv`, `setInterval` /
+`setTimeout` daemons, `pm2` / `forever` / `nodemon`. The bot does
+**not** reject these — there is no dependency or source-pattern gate —
+they simply fail at build or runtime on Cloudflare Pages/Workers. If
+the existing app uses any of these, plan the swap **before** picking
+a slug — do not deploy first and port later. What the bot *does*
+enforce at deploy time is the gate set in §A.5.
 
 ### A.3 Allowed Entra group
 
@@ -179,11 +185,17 @@ The CLI resolves Entra groups via the bot's `/groups` endpoint
 endpoint directly. Two helpers:
 
 ```bash
-launchpad groups list                # every group the caller can see
+launchpad groups list                # every group assigned to the Launchpad app in Entra
 launchpad groups search <query>      # fuzzy match by name / nickname / id
 launchpad groups show <name>         # UUID + displayName + mailNickname
+launchpad groups resolve <name>      # just the Entra Object-ID UUID (script-friendly)
 ```
 
+`groups list` is **not** the whole tenant and not caller-scoped: it
+lists the groups **assigned to the Launchpad enterprise application**
+in Entra — the only groups that can actually grant sign-in to a
+deployed app.
+
 When the user picks a group, pass either the **displayName** or the
 **UUID** to `launchpad init --group <…>` — the CLI accepts both and
 the bot canonicalises to the UUID.
@@ -195,12 +207,14 @@ If `launchpad groups list` fails with:
   and `ENTRA_GRAPH_CLIENT_ID` are non-secret identifiers (live in
   `wrangler.toml` `[vars]`); only `ENTRA_GRAPH_CLIENT_SECRET`
   requires `wrangler secret put`.
-- `502 graph_auth_failed` / `graph_fetch_failed` → the Entra app's
-  Graph permission grant (`Group.Read.All` or
-  `GroupMember.Read.All`) is missing admin consent, or Graph is
-  unreachable. Surface the error body.
-- empty list → no groups visible to the bot; check the Graph
-  permission scope.
+- `502 graph_auth_failed` / `graph_fetch_failed` → the bot's Graph
+  credential can't read the Launchpad service principal's
+  `appRoleAssignedTo` assignment list (missing admin consent on the
+  Graph application permission), or Graph is unreachable. Surface
+  the error body.
+- empty list → no groups are assigned to the Launchpad enterprise
+  app in Entra. A group must be **assigned to the app** before it
+  can gate anything — membership alone is not enough.
 
 Use `launchpad groups whoami` to remind the user which groups
 **they** are currently a member of — handy when an app is gated and
@@ -213,8 +227,14 @@ launchpad validate
 ```
 
 Parses `launchpad.yaml` against the v1alpha1 schema and reports
-problems. Doesn't talk to the bot. Useful when the user wants a
-second look before paying for an upload + PR round-trip.
+problems. Doesn't talk to the bot by default. Useful when the user
+wants a second look before paying for an upload round-trip.
+
+Add `--strict-groups` to *additionally* resolve the manifest's
+allowed Entra group online against the bot's group list — it catches
+typo'd or renamed group names before deploy time. This mode needs a
+session and the network (exit 1 = group not found / ambiguous,
+2 = network error, 3 = no valid session).
 
 ```bash
 launchpad plan
@@ -229,10 +249,13 @@ build command, destination directory, allowed group. Still offline.
 launchpad deploy
 ```
 
-Bundles the working tree (using `git ls-files -co --exclude-standard`
-where available; falls back to a pure-FS walker honouring
-`.gitignore` and a default-ignore set), gzips it, and POSTs to the
-bot's `/apps/<slug>/deploy/bundle` endpoint.
+Bundles the working tree with a pure-FS walker honouring `.gitignore`
+plus a built-in default-ignore set — it never shells out to
+`git ls-files`, so users with no `git` installed can still deploy —
+gzips it, and POSTs to the bot's `/apps/<slug>/deploy/bundle`
+endpoint. Files outside the manifest's app boundary (`app.root` /
+`app.include`) and never-shippable files (private keys, `.env`
+material) are stripped with a warning before upload.
 
 **First deploy vs subsequent deploys** (M-1234). Under Model A there
 is no separate "create the app" step — `launchpad deploy` against a
@@ -245,14 +268,43 @@ fresh slug auto-provisions:
   (`auth: gateway`); pass `--auth access` to `launchpad init` to use a
   per-app Cloudflare Access app instead. The CLI prints `✓ First-time deploy — provisioning
   workflow started` and exits 0. Provisioning typically takes
-  5–10 minutes. Watch it with `launchpad status <slug>` and re-run
-  `launchpad deploy` once lifecycle hits `live`.
+  5–10 minutes. **Your bundle ships with the provisioning run** — when
+  lifecycle reaches `live`, this deploy's content is what's serving.
+  **No second deploy needed**; re-deploying is only for the rare case
+  where the app comes up live *without* your content. Watch with
+  `launchpad status <slug>`.
 - **Subsequent deploys** (slug already live): the bot extracts the
-  tarball, runs the ingest gates (forbidden file types, oversized
-  binaries, secret patterns, build-command allowlist), commits the
-  bundle into `launchpad-app-<slug>` via the GitHub App, and CF Pages
-  auto-deploys on the push. The CLI prints `✓ Bundle accepted —
-  committed as <sha>`.
+  tarball, runs the ingest gates (see below), commits the bundle
+  straight onto `main` of `launchpad-app-<slug>` via the GitHub App
+  (no PR, no merge step), and CF Pages auto-builds on the push. The
+  CLI prints `✓ Bundle accepted — committed as <sha>`. A successful
+  deploy is **not** a live app yet — the Pages build runs
+  asynchronously and can fail after the commit lands; confirm with
+  `launchpad status <slug>`.
+
+**What the bot enforces at deploy time** (the real gate set — there
+is no dependency/stack-fit gate, see §A.2):
+
+- **Bundle policy** — hard caps (5000 files, 50 MB bundle, 10 MB per
+  file); symlinks; path traversal / absolute paths; `.github/workflows`;
+  `CODEOWNERS`; `.npmrc`/`.yarnrc` carrying auth tokens; `.git/`
+  directories. All violations are returned in one pass, verbatim, so
+  the user can fix everything at once.
+- **Secret scan** — high-signal patterns (AWS keys, GitHub tokens,
+  Slack tokens, SSH/RSA/EC private keys, generic api-key shapes).
+  Rejections name `{path, rule}` only — never the matched bytes.
+- **Build-command allowlist** — the manifest's `spec.build.command`
+  is checked against a safety policy.
+
+These gates are **delta-judged** (ADR 0025): the bot evaluates what
+your deploy *changes* against what is already on `main`, not the
+whole workspace. Pre-existing violations in files you didn't touch
+become non-blocking **standing exceptions** — the CLI prints them
+after the deploy and `launchpad status <slug>` lists the full
+inventory. If the delta can't be computed, the bot falls back to
+judging the whole bundle (fail-closed — never a skipped gate). The
+bot may also strip never-shippable files server-side; the CLI
+surfaces those as a `boundary_stripped` warning.
 
 Concurrent first-deploys against the same slug: the first request
 wins (gets the `provisioning_started` response); the second gets HTTP
@@ -265,13 +317,16 @@ subsequent deploys it prints the commit short-SHA + repo; for first
 deploys it prints provisioning guidance. Use `launchpad status
 <slug>` to watch lifecycle progress to its terminal state.
 
-Common flags:
+Flags — there is nothing useful to pass on the Model A path:
 
-- **`--slug <slug>`** — explicit override. Defaults to the slug from
-  `./launchpad.yaml`.
-- **`--message <text>`** — threaded as the PR description. Useful
-  for change logs.
-- **`--file <path>`** — point at a non-default manifest path.
+- The slug always comes from `./launchpad.yaml` — a `--slug` flag
+  does **not** override it (it only applies to the legacy clone flow
+  and `--new`).
+- `--message` is sent as a request header on the legacy path only,
+  and the bot currently **ignores** it — don't offer it as a
+  change-log mechanism.
+- `--file <path>` is valid only with the `--dry-run` / `--apply`
+  manifest modes, not with a bundle deploy.
 
 ### A.6 Terminal handling
 
@@ -279,12 +334,19 @@ Common flags:
   Run `/launchpad-status` to confirm; `/launchpad-content-pr` is no
   longer needed under Model A (the first deploy already shipped your
   content)."
-- **`failed` / `bundle_rejected` / `cf-pages-poll-unrecoverable`** →
-  run `/launchpad-deploy-status <slug>` and surface the failure
-  reason. The bundle policy errors (oversized files, forbidden
+- **Terminal failure stages** — `validator_rejected`,
+  `tf_apply_failed`, `bot_pr_ci_failed`, `abandoned`, `failed` → run
+  `/launchpad-deploy-status <slug>` and surface the failure reason
+  (a string like `cf-pages-poll-unrecoverable` is a failure *reason*,
+  not a stage). Bundle-policy errors (oversized files, forbidden
   symlinks, secret-pattern hits, build-command violations) are
-  self-describing in the CLI's stderr; surface them verbatim and let
-  the user fix and re-`launchpad deploy`.
+  rejected at upload and self-describing in the CLI's stderr; surface
+  them verbatim and let the user fix and re-`launchpad deploy`.
+- **Terminal-failed but the app is actually serving** → `launchpad
+  recover <slug>`. The bot re-derives reality from live Cloudflare
+  state and repairs the record to `live` only when the app is
+  verifiably serving; if it isn't, it refuses with exactly what was
+  checked — it never fabricates a live state.
 - **Anything else terminal** → run `/launchpad-deploy-status <slug>`
   and surface the diagnostic.
 
@@ -324,6 +386,30 @@ pushes both with its broker token. Verify with `launchpad secrets status
 <slug>` (PRESENT on both surfaces). **Never `wrangler secret put`** — the
 operator has no `wrangler`.
 
+## Pages-tier D1 (`d1_binding` on a `pages` target)
+
+A pure `react+api` app (no cron Worker) that needs a database declares the
+binding on a `pages` target (sp-pgd1b7):
+
+```yaml
+targets:
+  - kind: pages
+    d1_binding: DB        # env binding name your /api code reads
+```
+
+On `launchpad deploy` the bot auto-provisions the shared D1 named after the
+slug (**create-or-adopt by slug, never deleted** — a re-provision adopts the
+existing database) and binds it to the Pages app, so `env.DB` works with no
+manual `wrangler d1 create`. The bot also pins the matching
+`[[d1_databases]]` block into the **committed** `wrangler.toml` — Pages
+git-source builds read bindings from that file, and a build without the
+block silently resets the binding to empty.
+
+**Empty-DB gotcha:** the platform provisions an **empty** database — schema
+and migrations are the app's job. The usual pattern is idempotent
+`CREATE TABLE IF NOT EXISTS …` at runtime (startup / first request); there
+is no platform-side migration step.
+
 ## Gateway auth — the failure classes (assert these; do not relearn them)
 
 New apps default to `auth: gateway` (the platform Entra-OIDC gateway). For a

package/skills/launchpad-deploy-status/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: launchpad-deploy-status
-description: Show the current provisioning stage + failure reason for a Launchpad app via `launchpad status` (Model A drift + deployment_verified) and `launchpad apps` (lifecycle bucket). Renders the M-892 stage trace for legacy in-flight provisioning. Use when someone says "what's the status of demo-X", "/launchpad-deploy-status", "is my deploy stuck", or after `/launchpad-deploy` reports a non-`done` terminal stage.
-version: 0.26.1
+description: Show the current provisioning stage + failure reason for a Launchpad app via `launchpad status` (Model A drift + deployment_verified) and `launchpad apps` (lifecycle bucket). Renders the M-892 stage trace for in-flight provisioning, and is the canonical home for `launchpad recover` (repair a terminal-failed app record that is actually live). Use when someone says "what's the status of demo-X", "/launchpad-deploy-status", "is my deploy stuck", "my app says failed but it's serving", or after `/launchpad-deploy` reports a non-`done` terminal stage.
+version: 0.27.1
 ---
 
 <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -61,6 +61,7 @@ inference source resolves.
 | What was actually deployed? | `launchpad pull <slug>` |
 | Is the app stuck in the legacy M-892 zero-touch flow? | See § Legacy below |
 | What broke the most recent deploy? | `launchpad status <slug> --json` + the bot's PR check trail |
+| It says `failed` but the app is live in a browser | `launchpad recover <slug>` — see § Recover below |
 
 The Model A default is `launchpad status <slug>`. The other verbs
 are specialisations.
@@ -71,10 +72,20 @@ are specialisations.
 launchpad status <slug>
 ```
 
-Output is one of three states (see `/launchpad-status` for the
-canonical reference):
+Output is one of a closed set of states (see `/launchpad-status` for
+the canonical reference). Lifecycle-shaped states:
 
-- **`in sync`** — local `./launchpad.yaml` matches what's deployed.
+- **`provisioning`** — first deploy still in flight. The live
+  workflow stage is shown inline (`stage: …`); see § Stage taxonomy.
+- **`provisioning_failed`** — provisioning failed; the failing stage
+  and reason are shown inline. If the app is actually live, see
+  § Recover.
+- **`destroying` / `destroyed` / `destroy_failed`** — teardown
+  states. Route to `/launchpad-destroy`.
+
+Live-app states:
+
+- **`in_sync`** — local `./launchpad.yaml` matches what's deployed.
   Nothing pending. App is live and the most-recent deploy verified.
 - **`drift: <field list>`** — local and deployed differ on at least
   one v1 closed-set field (`metadata.name`, `metadata.team`,
@@ -82,10 +93,17 @@ canonical reference):
   `access.allowed_entra_group`, `hostnames[0]`, `build.command`,
   `build.destination_dir`, `build.root_dir`, `production_env.*`).
   Run `launchpad deploy` to roll the local manifest out.
-- **`no deployed manifest yet`** — the bot reports no
-  `output "<slug>_manifest_sha"`. Either the first deploy is still
-  in flight, or it failed. Check `launchpad apps` for the lifecycle
-  bucket.
+- **`live_no_content`** — provisioned, but no content deployed yet.
+  Run `launchpad deploy`.
+- **`live_content_untracked`** — live Cloudflare Pages content
+  exists but there is no platform-tracked manifest: the app deploys
+  via git integration / outside `launchpad deploy`.
+- **`live_drift_unknown`** — live and tracked, but no local
+  `launchpad.yaml` to compare against; status degrades to the
+  live-truth-only view.
+- **`no_deployed_manifest`** — nothing deployed through the platform
+  yet. Either the first deploy is still in flight, or it failed.
+  Check `launchpad apps` for the lifecycle bucket.
 
 Add `--json` for structured output:
 
@@ -93,10 +111,13 @@ Add `--json` for structured output:
 launchpad status <slug> --json
 ```
 
-The JSON envelope includes `deployedSha`, `headSha`, `hasOpenPr`,
-`openPrNumber`, `driftFields`, and per-field `driftDetails`. This
-is the shape downstream tooling should parse — never grep the prose
-output.
+The JSON envelope is discriminated by `state` (the union above) and
+includes `deployedSha`, `headSha`, `hasOpenPr`, `openPrNumber`,
+`driftFields`, and per-field `driftDetails`. Provisioning/failed
+states carry `stage` + `failedReason`; live states carry a
+`deployment` block (last CF Pages deployment, trigger, build outcome
++ failure-log excerpt). This is the shape downstream tooling should
+parse — never grep the prose output.
 
 ## Lifecycle bucket
 
@@ -117,12 +138,15 @@ field. Common values:
   the apply may have failed silently — surface to platform-team.
 - **`failed`** — provisioning failed. See `launchpad status <slug>
   --json` for the most recent error, and the bot's open PR on
-  `launchpad-platform` for the apply trace.
+  `launchpad-platform` for the apply trace. If the app is actually
+  live and serving, repair the record with `launchpad recover
+  <slug>` (§ Recover).
 - **`destroying` / `destroyed` / `destroy_failed`** — teardown
   states. Route to `/launchpad-destroy`.
 
-Restrict to a single slug with `grep` (or `--json` parsing) if the
-list is long. `launchpad apps` is read-only and cheap.
+Restrict to a single slug with `grep` if the list is long —
+`launchpad apps` has no `--json` flag, so the table is the only
+surface. `launchpad apps` is read-only and cheap.
 
 ## Render
 
@@ -155,7 +179,7 @@ In-flight first deploy:
 ```
 App:        demo-9
 Lifecycle:  provisioning
-State:      no deployed manifest yet
+State:      provisioning (stage: tf_applied)
 
 Next steps:
   Wait for the first deploy to complete. Re-run this skill in a few
@@ -168,28 +192,99 @@ Failed deploy:
 ```
 App:        demo-7
 Lifecycle:  failed
-State:      no deployed manifest yet — bundle_rejected (3 oversized files)
+State:      provisioning_failed (stage: content_seeded — 3 oversized files)
 
 Next steps:
-  /launchpad-deploy "Recover a legacy in-flight deploy" → resume,
-  OR fix the bundle (per the reasons above) and run `launchpad deploy`
-  again. The bot is idempotent on retries against a failed slug.
+  If the app is actually live in a browser, run `launchpad recover
+  demo-7` to reconcile the record against live state.
+  Otherwise fix the bundle (per the reasons above) and run
+  `launchpad deploy` again — the bot is idempotent on retries
+  against a failed slug. For a stuck legacy in-flight deploy,
+  /launchpad-deploy "Recover a legacy in-flight deploy" → resume.
+```
+
+## Recover — terminal-failed but actually live
+
+The observed class (live fixture: `ai-audit`): provisioning hit a
+since-fixed platform bug *after* the app's content was already
+serving, so the registry record is stuck at `lifecycle: failed`
+while the app itself is live. `launchpad status` short-circuits on
+the failed lifecycle, and no other CLI verb can mutate the record.
+The shipped repair verb:
+
+```bash
+launchpad recover <slug>
+# or, structured:
+launchpad recover <slug> --json
 ```
 
+Slug inference matches `launchpad status` (manifest slug first, then
+`launchpad-app-<slug>` dirname), so a bare `launchpad recover` works
+from inside the app directory.
+
+What it does (bot `POST /apps/<slug>/recover`):
+
+- **Re-derives reality from the live Cloudflare Pages API** — never
+  TF state, never the stale record. The record is repaired (flipped
+  to `live`) only when the Pages project exists and a successful
+  production deployment is serving. The repair touches ONLY the
+  lifecycle/failure fields; owners, editors, targets, and auth
+  config are preserved verbatim.
+- **Never fabricates a live state.** A not-live app is refused
+  (exit 1) with exactly what was checked (project existence, latest
+  production deployment + build status) and the next steps.
+- **Fail-closed.** Cloudflare unreachable → refusal, nothing
+  changed; retry shortly.
+- **Idempotent.** Recovering an already-healthy app is a no-op
+  success.
+- **Scoped to terminal `failed` records.** `provisioning` apps are
+  refused (let the workflow finish); destroy-side states are owned
+  by `launchpad destroy`; container apps are unsupported.
+
+Exit codes: `0` repaired or no-op (already healthy); `1` refusal,
+fail-closed, or auth/transport error; `64` usage. Owner or editor
+role required; every decision is audited server-side.
+
+Recover is the one **mutating** verb this skill may reach for, and
+its only mutation is the registry lifecycle record — repaired
+strictly after live verification. It never touches Cloudflare
+resources, the app repo, or TF. After a repair, re-run `launchpad
+status <slug>` — it then reports the live deployment truth.
+
 ## Legacy — M-892 stage taxonomy
 
-For apps that are stuck in the pre-Model-A zero-touch provisioning
-flow (`launchpad deploy --new` / `--resume` / `--abandon`), the bot
-still emits the original stage trace. The taxonomy is:
+The provisioning workflow (Model A first deploys and the legacy
+zero-touch flow `launchpad deploy --new` / `--resume` / `--abandon`
+alike) emits a stage trace; `launchpad status` shows the live stage
+inline while `provisioning`. The happy-path order is:
 
 ```
 pending → repo_created → bootstrap_pr_opened → bootstrap_pr_merged →
-tf_pr_opened → tf_pr_merged → tf_applied → cert_active →
-policy_attached → ready_for_content → deployment_verified → done
+content_seeded → tf_pr_opened → tf_pr_merged → tf_applied →
+cert_active → policy_attached → tf_env_pr_opened → tf_env_pr_merged →
+tf_env_applied → ready_for_content → deployment_verified → done
 ```
 
-Terminal failure stages: `failed`, `bot_pr_ci_failed`, `abandoned`,
-`cf-pages-poll-unrecoverable`.
+Notes on the non-obvious stages:
+
+- **`content_seeded`** (M-1235) — commits the bundle staged at
+  deploy time onto the app repo's `main` *before* the Pages project
+  exists, so the first Pages build has real content. No-op when no
+  bundle was staged (wizard path).
+- **`tf_env_pr_opened` → `tf_env_pr_merged` → `tf_env_applied`**
+  (5c.2) — per-app-workspace audience stages. Legacy slugs set the
+  audience inline within `policy_attached` and skip straight to
+  `ready_for_content`.
+- **`deployment_verified`** (M-1217) — polls the CF Pages
+  production-deployment API; the `lifecycle: live` flip is gated
+  behind a terminal build state.
+- **`scheduled_tier`** appears only as an error-prefix pseudo-stage
+  for a two-tier app's cron-Worker writes — never in the happy path.
+
+Terminal failure stages: `validator_rejected`, `tf_apply_failed`,
+`bot_pr_ci_failed`, `abandoned`, `failed`. Note that
+`cf-pages-poll-unrecoverable` is a failure *reason* string (the
+`deployment_verified` poll giving up), not a stage.
 
 The CLI surfaces this through `launchpad apps` (lifecycle bucket)
 and `launchpad status <slug> --json` (the most recent transition).
@@ -211,16 +306,19 @@ Both flows live in `/launchpad-deploy` § Legacy.
 
 If the user wants to see open bot PRs for the app, route through
 `launchpad status <slug> --json` — the `hasOpenPr` / `openPrNumber`
-pair points at the platform-repo TF PR for in-flight changes. For
-the app repo, `launchpad apps` includes the deploy PR URL on the
-most-recent transition row when relevant. The playbook does not
-shell out to `gh pr list` — the bot owns GH credentials, not the
-CLI, and external users without M-KOPA GH access will not be able
-to follow such a link anyway.
+pair points at the platform-repo TF PR for in-flight changes.
+(`launchpad apps` renders only SLUG / NAME / ROLE / LIFECYCLE /
+UPDATED — it carries no PR URLs.) The playbook does not shell out
+to `gh pr list` — the bot owns GH credentials, not the CLI, and
+external users without M-KOPA GH access will not be able to follow
+such a link anyway.
 
 ## Don'ts
 
-- Do **not** mutate anything from this skill. Status is read-only.
+- Do **not** mutate anything from this skill — with one sanctioned
+  exception: `launchpad recover` (§ Recover), whose only mutation is
+  the registry lifecycle record, repaired strictly after live
+  verification. Every other verb here is read-only.
 - Do **not** shell out to `gh`, `jq`, `curl`, or `git`. The CLI
   verbs cover every surface this skill needs.
 - Do **not** invent stage names or skip stages from the legacy
@@ -230,4 +328,6 @@ to follow such a link anyway.
   their own bounded retries; one playbook call, one error message,
   suggest the user re-run.
 - Do **not** parse the prose output of `launchpad status` /
-  `launchpad apps`. Use `--json` for any downstream automation.
+  `launchpad apps`. Use `launchpad status <slug> --json` for any
+  downstream automation (`launchpad apps` has no `--json`; for
+  per-app automation go through `status --json` instead).