@m-kopa/launchpad-cli 0.23.0

package/skills/launchpad-deploy/SKILL.md

@@ -0,0 +1,415 @@
+---
+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.23.0
+---
+
+<!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
+## Shell contract — read this first
+
+Every fenced `bash` block below MUST be sent to the `Bash` tool **verbatim**.
+Do not rewrite into PowerShell, cmd, zsh-isms, or "equivalent" forms.
+
+- macOS / Linux: the `Bash` tool runs system bash.
+- Windows: the `Bash` tool runs Git for Windows (MSYS) bash. `$HOME`,
+  forward slashes, `test -f`, `command -v`, heredocs, and `[[ … ]]` all
+  work. There is no reason to translate to `Test-Path`, `$env:USERPROFILE`,
+  `Get-Content`, `Where-Object`, `Get-ChildItem`, or backslash paths —
+  doing so will fail with `/usr/bin/bash: syntax error`.
+
+If a step genuinely needs OS branching, branch *inside* bash:
+
+```bash
+case "$(uname -s)" in
+  Darwin)               : ;;
+  Linux)                : ;;
+  MINGW*|MSYS*|CYGWIN*) : ;;
+esac
+```
+<!-- END shell-contract -->
+
+# /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
+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.
+
+## Constants (single source of truth)
+
+These values are referenced by `/launchpad-deploy-status`,
+`/launchpad-content-pr`, and `/launchpad-status`; if the bot's
+contract changes, update them **here only** and the other skills
+inherit the change.
+
+### Bot URL
+
+```
+https://launchpad-portal-bot.mkopa-launchpad.workers.dev
+```
+
+Override with `$LAUNCHPAD_BOT_URL` for staging. The CLI reads this
+itself; the playbook never speaks to the bot directly.
+
+### App types
+
+```
+static · react · react+api · container
+```
+
+## Pre-flight
+
+```bash
+launchpad whoami
+```
+
+- **Exit 0** → identity + session expiry + role per app printed.
+  Proceed.
+- **Any failure** → tell the user to run `/launchpad-onboard` first
+  (it covers the install + login dance) and exit.
+
+If you need to remind a returning user what they already have:
+
+```bash
+launchpad apps
+```
+
+This lists every app the caller can see (own + editor + break-glass).
+
+## Action selector
+
+Use `AskUserQuestion` to pick the path. Two options, single-select:
+
+| Label | What it does |
+|---|---|
+| Deploy from this directory (Model A) | The recommended path. Runs `launchpad init` then `launchpad deploy` against the CWD. Works for external users. |
+| Recover a legacy in-flight deploy | Resume or abandon a slug stuck in the pre-Model-A zero-touch flow. M-KOPA-internal only. |
+
+> Note: `AskUserQuestion` is a deferred tool. Before the first call,
+> run `ToolSearch` with query `select:AskUserQuestion` to load its
+> schema.
+
+## Model A — deploy from this directory
+
+This is the primary flow. The user's local working directory is the
+source of truth; the CLI bundles it and ships it.
+
+### A.1 Confirm the working directory
+
+Ask: "Is the app you want to deploy in your current directory? If
+not, `cd` there first and re-invoke the skill."
+
+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.
+
+### A.2 Scaffold `launchpad.yaml`
+
+```bash
+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.
+
+Non-interactive form for scripting:
+
+```bash
+launchpad init --non-interactive \
+  --slug <slug> \
+  --display-name "<display name>" \
+  --app-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).
+
+`launchpad init` writes `./launchpad.yaml` and exits 0. Re-running
+against an existing file is rejected unless `--force` is passed —
+the manifest is the user's authored artefact, the CLI does not
+silently overwrite it.
+
+**Stack constraints by app-type** (single source of truth:
+`launchpad-platform/ARCHITECTURE.md § Tech Stack` and `PATTERNS.md §
+Approved Libraries`). Surface this table to the user **before** they
+commit to a slug:
+
+| `appType`   | Server framework      | Data layer                              | Background work        | Notes                                                  |
+|-------------|-----------------------|-----------------------------------------|------------------------|--------------------------------------------------------|
+| `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.
+
+### A.3 Allowed Entra group
+
+The CLI resolves Entra groups via the bot's `/groups` endpoint
+(Entra-canonical, per M-940). The playbook never speaks to that
+endpoint directly. Two helpers:
+
+```bash
+launchpad groups list                # every group the caller can see
+launchpad groups search <query>      # fuzzy match by name / nickname / id
+launchpad groups show <name>         # UUID + displayName + mailNickname
+```
+
+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.
+
+If `launchpad groups list` fails with:
+
+- `503 graph_not_configured` → the bot's Graph credentials aren't
+  wired; route the user to platform-team. `ENTRA_GRAPH_TENANT_ID`
+  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.
+
+Use `launchpad groups whoami` to remind the user which groups
+**they** are currently a member of — handy when an app is gated and
+they want to confirm they'll still be able to reach it.
+
+### A.4 (Optional) Validate before shipping
+
+```bash
+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.
+
+```bash
+launchpad plan
+```
+
+Same, but also summarises what the manifest would deploy: hostnames,
+build command, destination directory, allowed group. Still offline.
+
+### A.5 Deploy
+
+```bash
+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.
+
+**First deploy vs subsequent deploys** (M-1234). Under Model A there
+is no separate "create the app" step — `launchpad deploy` against a
+fresh slug auto-provisions:
+
+- **First deploy** (slug never seen): the bot reads the manifest,
+  claims the slug in its registry, and kicks the provisioning
+  workflow (TF apply, cert issuance, edge auth, app-repo scaffold).
+  New apps default to the platform **Entra-OIDC gateway**
+  (`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`.
+- **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>`.
+
+Concurrent first-deploys against the same slug: the first request
+wins (gets the `provisioning_started` response); the second gets HTTP
+409 `slug_in_flight`. The CLI surfaces this as "slug is already
+provisioning" — wait for the existing workflow to land before
+re-trying.
+
+The CLI exits as soon as the bot acknowledges the upload (202). For
+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:
+
+- **`--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.
+
+### A.6 Terminal handling
+
+- **`done`** → "🎉 demo-X is live at `https://<slug>.launchpad.m-kopa.us`.
+  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
+  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`.
+- **Anything else terminal** → run `/launchpad-deploy-status <slug>`
+  and surface the diagnostic.
+
+## Two-tier apps (Pages + sibling cron Worker)
+
+A `react+api` app that needs **scheduled background work** (e.g. an hourly
+ingest) is **two-tier**: the Pages `react+api` dashboard **plus a sibling cron
+Worker**. Pages Functions have **no `scheduled` handler** — a cron trigger
+lives only on a Worker (ADR 0022). The operator stays **CLI-only**: `launchpad
+deploy` bundles the Worker locally (esbuild) and ships it; the bot does every
+Cloudflare write. **No `wrangler`.**
+
+Declare the Worker in the manifest's `targets[]`. The `schedule` is what makes
+it a **deploy** surface (a worker target *without* a schedule is a secrets-only
+target, not deployed):
+
+```yaml
+targets:
+  - kind: worker
+    script: <slug>-ingest-cron     # MUST equal `name` in the worker's cron/wrangler.toml
+    schedule:
+      - "0 * * * *"                # one or more cron expressions
+    d1_binding: DB                 # shared D1 binding name (optional; omit for a pure-fetch cron)
+```
+
+On `launchpad deploy` (a *subsequent* deploy, after the slug is `live`) the bot:
+ensures the shared D1 (named after the slug — **create-or-adopt, never
+deleted**), uploads the CLI-built Worker module, sets its cron trigger, and
+binds the **same** D1 on **both** tiers. The Worker's `cron/wrangler.toml`
+supplies `main` + `compatibility_date` + `compatibility_flags`; its
+`[[d1_databases]]` block is **ignored** on the launchpad path (the bot owns the
+binding + id).
+
+**Secrets to both tiers.** A secret with `targets: all` in the manifest fans to
+the Pages tier **and** the cron Worker via `launchpad secrets push` — the bot
+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`.
+
+## Gateway auth — the failure classes (assert these; do not relearn them)
+
+New apps default to `auth: gateway` (the platform Entra-OIDC gateway). For a
+`react+api` (verifier-bearing) app the per-app Terraform emits the verifier
+wiring automatically — **do not hand-edit or fight it**:
+
+- **`confine_origin = false` is intentional, keep it.** CF Access service-token
+  confinement **strips the gateway's user JWT** from `Cf-Access-Jwt-Assertion`
+  → the app sees only the service token and returns **401** for every user. The
+  per-app TF sets `confine_origin = false` for gateway react+api apps so the
+  user JWT reaches the origin. Re-enabling confinement re-breaks auth.
+- **Canonical JWKS, not the CF Access certs path.** The verifier must fetch keys
+  from the gateway's `JWKS_URL`
+  (`https://auth.launchpad.m-kopa.us/.well-known/jwks.json`), **not**
+  `${team}/cdn-cgi/access/certs`. App code prefers `env.JWKS_URL` when set.
+- **Auth env MUST be `secret_text`, never `plain_text`.** `CF_ACCESS_TEAM_DOMAIN`
+  (= the gateway issuer), `CF_ACCESS_AUD` (= the app host), and `JWKS_URL` are
+  emitted as `secret_text` by the per-app TF. **`plain_text` env vars are wiped
+  on every `launchpad deploy`; `secret_text` survives.** A verifier env var as
+  `plain_text` ⇒ the app is one deploy away from 401-ing.
+- **`aud`/`iss` are exact-matched.** The gateway mints `iss` = the gateway
+  issuer and `aud` = the app's own host; a wrong or duplicate `CF_ACCESS_AUD`
+  ⇒ `AUD_MISMATCH`. One audience, the app's host.
+- **`wrangler kv` defaults to LOCAL.** If you ever inspect gateway KV manually,
+  `wrangler kv ... --remote` is required — without `--remote` you read/write a
+  local sandbox namespace and see phantom/empty results.
+
+## Legacy — recover an in-flight provisioning
+
+These modes are for **M-KOPA-internal apps stuck in the pre-Model-A
+zero-touch flow** (M-892). They require M-KOPA GH access and assume
+the bot already opened a `launchpad-platform` TF PR for the slug.
+External users will never need this branch.
+
+### Resume
+
+```bash
+launchpad deploy --resume <slug>
+```
+
+Re-fires the bot's resume endpoint against an existing failed slug.
+Terminal handling is the same as §A.6.
+
+### Abandon
+
+Confirm via `AskUserQuestion`:
+
+| Label | What it does |
+|---|---|
+| Yes, abandon `<slug>` (Recommended) | Frees the slug. Any in-flight provisioning is marked terminal. **Does NOT delete the GitHub repo or any Cloudflare resources** — those need separate cleanup. |
+| No, keep | Aborts the abandon. |
+
+```bash
+launchpad deploy --abandon <slug>
+```
+
+For destructive teardown of a fully-provisioned app, the right verb
+is `launchpad destroy <slug>` (covered in `/launchpad-destroy`) —
+that one cleans up Cloudflare + the platform-repo TF entries +
+archive-renames the app repo. `--abandon` only frees the slug for
+the in-flight case.
+
+## Don'ts
+
+- Do **not** hardcode app-type or group choices — `launchpad init`'s
+  auto-detect and `launchpad groups list` are the source of truth.
+- Do **not** assume a `git clone` or local platform-repo checkout is
+  needed. The CLI bundles the CWD directly and the bot owns every
+  downstream side-effect.
+- Do **not** shell out to `gh`, `jq`, `curl`, or `git` from this
+  skill — the CLI verbs cover every step. A regression that
+  re-introduces a system dependency surfaces in the
+  `launchpad-cli-e2e` zero-deps matrix.
+- Do **not** run `--abandon` without explicit `AskUserQuestion`
+  confirmation.
+- Do **not** mix `--new` / `--resume` / `--abandon` with the Model A
+  flow. The legacy modes target the M-892 zero-touch path; Model A's
+  primary flow (`launchpad init` + `launchpad deploy` from CWD) is
+  what new users want.
+- Do **not** add a cron trigger to a Pages `react+api` app directly —
+  Pages has no `scheduled` handler. Scheduled work needs a sibling cron
+  **Worker** declared in `targets[]` (see "Two-tier apps").
+- Do **not** set verifier env (`CF_ACCESS_TEAM_DOMAIN`, `CF_ACCESS_AUD`,
+  `JWKS_URL`) as `plain_text` — it is wiped on the next deploy. The per-app
+  TF emits them as `secret_text`; trust it.
+- Do **not** re-enable `confine_origin` on a gateway `react+api` app — it
+  strips the user JWT and 401s every user (see "Gateway auth").
+- Do **not** `wrangler secret put` for a two-tier app — `launchpad secrets
+  push` with `targets: all` seeds both tiers via the bot.

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

@@ -0,0 +1,231 @@
+---
+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.23.0
+---
+
+<!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
+## Shell contract — read this first
+
+Every fenced `bash` block below MUST be sent to the `Bash` tool **verbatim**.
+Do not rewrite into PowerShell, cmd, zsh-isms, or "equivalent" forms.
+
+- macOS / Linux: the `Bash` tool runs system bash.
+- Windows: the `Bash` tool runs Git for Windows (MSYS) bash. `$HOME`,
+  forward slashes, `test -f`, `command -v`, heredocs, and `[[ … ]]` all
+  work. There is no reason to translate to `Test-Path`, `$env:USERPROFILE`,
+  `Get-Content`, `Where-Object`, `Get-ChildItem`, or backslash paths —
+  doing so will fail with `/usr/bin/bash: syntax error`.
+
+If a step genuinely needs OS branching, branch *inside* bash:
+
+```bash
+case "$(uname -s)" in
+  Darwin)               : ;;
+  Linux)                : ;;
+  MINGW*|MSYS*|CYGWIN*) : ;;
+esac
+```
+<!-- END shell-contract -->
+
+# /launchpad-deploy-status
+
+Read-only status check for a Launchpad app. Routes the user to the
+right CLI verb depending on whether the app is being deployed under
+Model A (the normal path) or stuck in a legacy M-892 provisioning
+flow.
+
+## Pre-flight
+
+```bash
+launchpad whoami
+```
+
+If that fails, run `/launchpad-onboard` first.
+
+## Input
+
+Accept a **slug** (e.g. `demo-9`) as a positional argument. If the
+user invokes the skill without one, ask for it. If the user is
+sitting inside a `launchpad-app-<slug>/` clone, the slug can be
+inferred from cwd by every verb below.
+
+## Quick triage — which verb do you want?
+
+| Question | Verb |
+|---|---|
+| Is my local manifest in sync with what's deployed? | `launchpad status <slug>` |
+| What lifecycle bucket is the app in? | `launchpad apps` |
+| 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 |
+
+The Model A default is `launchpad status <slug>`. The other verbs
+are specialisations.
+
+## Standard (Model A) status
+
+```bash
+launchpad status <slug>
+```
+
+Output is one of three states (see `/launchpad-status` for the
+canonical reference):
+
+- **`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`,
+  `metadata.owner`, `metadata.description`, `deployment.type`,
+  `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.
+
+Add `--json` for structured output:
+
+```bash
+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.
+
+## Lifecycle bucket
+
+```bash
+launchpad apps
+```
+
+Renders every app the caller can see, sorted by the bot:
+`provisioning` → `failed` → `live`, newest `lifecycleAt` first
+within each bucket. The `Lifecycle` column is the load-bearing
+field. Common values:
+
+- **`live`** — app is operational. Use `launchpad status <slug>` for
+  drift + the `deployment_verified` outcome of the most recent
+  deploy.
+- **`provisioning`** — first-deploy is still in flight. Wait, then
+  re-check. If it stays in `provisioning` for more than ~20 minutes,
+  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.
+- **`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.
+
+## Render
+
+Pretty-print the result as a single block:
+
+```
+App:        demo-9
+Lifecycle:  live
+State:      in sync
+Live at:    https://demo-9.launchpad.m-kopa.us
+```
+
+Drift case:
+
+```
+App:        demo-9
+Lifecycle:  live
+State:      drift (metadata.owner, production_env.API_BASE)
+
+Next steps:
+  Edit ./launchpad.yaml to resolve the differences, then run
+  `launchpad deploy` to roll it out.
+
+  Or run `launchpad pull demo-9 --out deployed.yaml` to bring your
+  local manifest into line with what's deployed.
+```
+
+In-flight first deploy:
+
+```
+App:        demo-9
+Lifecycle:  provisioning
+State:      no deployed manifest yet
+
+Next steps:
+  Wait for the first deploy to complete. Re-run this skill in a few
+  minutes, or watch `launchpad apps` for the lifecycle to flip to
+  `live`.
+```
+
+Failed deploy:
+
+```
+App:        demo-7
+Lifecycle:  failed
+State:      no deployed manifest yet — bundle_rejected (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.
+```
+
+## 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:
+
+```
+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
+```
+
+Terminal failure stages: `failed`, `bot_pr_ci_failed`, `abandoned`,
+`cf-pages-poll-unrecoverable`.
+
+The CLI surfaces this through `launchpad apps` (lifecycle bucket)
+and `launchpad status <slug> --json` (the most recent transition).
+You no longer parse the bot's `/apps/<sub>/status` shape by hand
+from the playbook — every status surface goes through the CLI.
+
+If a legacy app is genuinely stuck mid-pipeline (e.g. a bot PR
+failed CI), the recovery paths are:
+
+- **Resume:** `launchpad deploy --resume <slug>` — re-fires the bot
+  endpoint and walks the stages again from where they failed.
+- **Abandon:** `launchpad deploy --abandon <slug>` — frees the slug
+  but does NOT clean up Cloudflare resources or the GitHub repo.
+  Follow up with `launchpad destroy <slug>` for a full teardown.
+
+Both flows live in `/launchpad-deploy` § Legacy.
+
+## Linking open PRs
+
+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.
+
+## Don'ts
+
+- Do **not** mutate anything from this skill. Status 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
+  taxonomy block — consistency with `/launchpad-deploy` is what
+  makes the renames-ripple property work.
+- Do **not** retry indefinitely on transient 5xx. The CLI verbs do
+  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.