@m-kopa/launchpad-cli 0.23.0

package/dist/update-notifier.d.ts

@@ -0,0 +1,69 @@
+import type { CliIo, Command } from "./dispatcher.js";
+import { resolveLatestVersion, type InstallChannel } from "./commands/update.js";
+/** Internal verb the detached refresh process runs. Hidden from help. */
+export declare const INTERNAL_REFRESH_VERB = "__refresh-update-cache";
+/** Re-check the registry at most once per this window (24h). */
+export declare const CHECK_INTERVAL_MS: number;
+/** Persisted shape of {@link CACHE_FILE}. */
+export interface CacheState {
+    /** `Date.now()` at the last completed refresh (success OR failure). */
+    readonly checkedAt: number;
+    /** Latest version last seen, or null if never successfully fetched. */
+    readonly latest: string | null;
+}
+/** Read + parse the cache file; null on any error (missing/corrupt). */
+export declare function readCache(): CacheState | null;
+/** Write the cache file (0600), creating ~/.launchpad if needed. Best-effort. */
+export declare function writeCache(state: CacheState): void;
+/** Context derived from the running process, passed in for testability. */
+export interface NotifyContext {
+    readonly argv: readonly string[];
+    readonly env: NodeJS.ProcessEnv;
+    readonly stderrIsTTY: boolean;
+}
+/** Injectable surface so the core is testable without fs/clock/spawn. */
+export interface NotifierDeps {
+    readonly cliVersion: string;
+    readonly channel: () => InstallChannel;
+    readonly readCache: () => CacheState | null;
+    readonly now: () => number;
+    /** Kick off the detached background refresh (no-op in tests). */
+    readonly spawnRefresh: () => void;
+}
+/**
+ * Should the notifier stay silent entirely (no notice, no refresh)?
+ * Keeps the CLI quiet in every non-interactive / machine context.
+ */
+export declare function isSuppressed(ctx: NotifyContext): boolean;
+/** The one-line, channel-appropriate notice. */
+export declare function noticeLine(current: string, latest: string, channel: InstallChannel): string;
+/**
+ * Core notifier: print a cached notice if a newer version is known, and
+ * trigger a background refresh when the cache is stale. Synchronous and
+ * allocation-light on the hot path; the only async work (the network)
+ * happens in the detached process `spawnRefresh` launches.
+ */
+export declare function maybeNotify(io: CliIo, ctx: NotifyContext, deps: NotifierDeps): void;
+/**
+ * Entry point for the bin wrapper, invoked AFTER the command resolves.
+ * Builds the real deps from `process.*` and runs the core, fully
+ * guarded so a notifier fault can never affect the command's result.
+ */
+export declare function notifyAfterCommand(io: CliIo, argv: readonly string[], cliPath?: string | undefined): void;
+/** Injectable surface for {@link refreshUpdateCache}. */
+export interface RefreshDeps {
+    readonly resolveLatestVersion: typeof resolveLatestVersion;
+    readonly readCache: () => CacheState | null;
+    readonly writeCache: (s: CacheState) => void;
+    readonly now: () => number;
+}
+/**
+ * Refresh the cached latest-version marker. Always bumps `checkedAt`
+ * (success OR failure) so a flaky/offline registry backs off for the
+ * full interval rather than re-spawning on every command; preserves the
+ * previously-seen `latest` on failure.
+ */
+export declare function refreshUpdateCache(deps?: RefreshDeps): Promise<void>;
+/** Hidden command: the detached background refresh. Not shown in help. */
+export declare const refreshUpdateCacheCommand: Command;
+//# sourceMappingURL=update-notifier.d.ts.map

package/dist/update-notifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-notifier.d.ts","sourceRoot":"","sources":["../src/update-notifier.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAIL,oBAAoB,EACpB,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAE9B,yEAAyE;AACzE,eAAO,MAAM,qBAAqB,2BAA2B,CAAC;AAE9D,gEAAgE;AAChE,eAAO,MAAM,iBAAiB,QAAsB,CAAC;AAQrD,6CAA6C;AAC7C,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,wEAAwE;AACxE,wBAAgB,SAAS,IAAI,UAAU,GAAG,IAAI,CAkB7C;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAOlD;AAID,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAED,yEAAyE;AACzE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,cAAc,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,UAAU,GAAG,IAAI,CAAC;IAC5C,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,YAAY,EAAE,MAAM,IAAI,CAAC;CACnC;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAQxD;AAED,gDAAgD;AAChD,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,cAAc,GACtB,MAAM,CAMR;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,KAAK,EACT,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,YAAY,GACjB,IAAI,CAcN;AAwBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,KAAK,EACT,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,GAAE,MAAM,GAAG,SAA2B,GAC5C,IAAI,CAoBN;AAID,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,oBAAoB,EAAE,OAAO,oBAAoB,CAAC;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,UAAU,GAAG,IAAI,CAAC;IAC5C,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;IAC7C,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;CAC5B;AASD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,GAAE,WAA6B,GAClC,OAAO,CAAC,IAAI,CAAC,CASf;AAED,0EAA0E;AAC1E,eAAO,MAAM,yBAAyB,EAAE,OAQvC,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const CLI_VERSION = "0.23.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,WAAW,WAAW,CAAC"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@m-kopa/launchpad-cli",
+  "version": "0.23.0",
+  "description": "Launchpad CLI — clone / deploy / review / merge against Launchpad-managed apps. Talks to the portal-bot endpoints (SCOPE-M-760 / T4).",
+  "type": "module",
+  "bin": {
+    "launchpad": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/M-KOPA/launchpad-platform.git",
+    "directory": "packages/launchpad-cli"
+  },
+  "homepage": "https://github.com/M-KOPA/launchpad-platform/tree/main/packages/launchpad-cli#readme",
+  "license": "UNLICENSED",
+  "dependencies": {
+    "esbuild": "0.27.3",
+    "yaml": "2.9.0",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "22.18.10",
+    "@typescript-eslint/eslint-plugin": "8.46.4",
+    "@typescript-eslint/parser": "8.46.4",
+    "@vitest/coverage-istanbul": "4.1.5",
+    "eslint": "9.39.4",
+    "typescript": "5.9.3",
+    "vitest": "4.1.5",
+    "@m-kopa/launchpad-engine": "workspace:*"
+  },
+  "scripts": {
+    "build": "rm -rf dist && bun build src/cli.ts src/postinstall.ts --target=node --outdir=dist --external yaml --external zod --external esbuild --external '@m-kopa/platform-auth' && chmod +x dist/cli.js && tsc -p tsconfig.build.json --emitDeclarationOnly --declarationDir dist",
+    "postinstall": "node dist/postinstall.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src tests",
+    "typecheck": "tsc --noEmit",
+    "check:version-sync": "bash scripts/check-version-sync.sh",
+    "check:installer-syntax": "bash scripts/check-installer-syntax.sh",
+    "check:skill-contract": "bash scripts/sync-skill-contract.sh --check",
+    "check:skill-bash-dialect": "bash scripts/check-skill-bash-dialect.sh",
+    "check:skill-bash-parse": "bash scripts/check-skill-bash-parse.sh",
+    "check:skills": "bun run check:skill-contract && bun run check:skill-bash-dialect && bun run check:skill-bash-parse",
+    "sync:skill-contract": "bash scripts/sync-skill-contract.sh write",
+    "version:patch": "npm version patch --no-git-tag-version",
+    "version:minor": "npm version minor --no-git-tag-version"
+  }
+}

package/skills/README.md

@@ -0,0 +1,100 @@
+# Launchpad Claude Code skill bundle
+
+This directory ships the Claude Code slash-commands that
+`launchpad skills install` copies into `~/.claude/skills/`.
+
+```text
+skills/
+├── _partials/
+│   └── shell-contract.md         # single source of truth for the
+│                                  #  Shell Contract block at the top
+│                                  #  of every launchpad-* SKILL.md
+├── launchpad-onboard/SKILL.md
+├── launchpad-deploy/SKILL.md
+├── launchpad-deploy-status/SKILL.md
+├── launchpad-content-pr/SKILL.md
+├── launchpad-status/SKILL.md
+├── launchpad-destroy/SKILL.md
+└── marquee-share/                # vendored from M-KOPA/marquee, do
+                                  #  not hand-edit — managed by
+                                  #  scripts/sync-marquee-share-skill.sh
+```
+
+## Cross-platform shell contract
+
+Claude Code's `Bash` tool **always** runs `bash`, on every OS — on
+Windows it resolves to Git for Windows / MSYS bash. Skills that
+contain bash blocks must be unambiguously bash, because models will
+otherwise sometimes transliterate to PowerShell on Windows and the
+bash tool will then fail with `/usr/bin/bash: syntax error`.
+
+To make this explicit, each `launchpad-*` SKILL.md starts with a
+**Shell contract** preamble that tells the agent not to translate:
+
+```markdown
+<!-- BEGIN shell-contract (managed by …) -->
+## Shell contract — read this first
+
+Every fenced `bash` block below MUST be sent to the `Bash` tool
+verbatim. Do not rewrite into PowerShell, cmd, …
+<!-- END shell-contract -->
+```
+
+The canonical body lives at `_partials/shell-contract.md`. **Do not
+edit the copies in the four launchpad-* SKILL.md files directly** —
+edit the partial, then run:
+
+```bash
+bun run sync:skill-contract
+```
+
+CI (`bun run check:skills`) fails if any SKILL.md drifts from the
+partial, contains a PowerShell token inside a bash fence, or fails
+`bash -n` parse.
+
+## Versioning
+
+The `version:` frontmatter line in each `launchpad-*/SKILL.md` is
+**stamped** from `package.json` by `scripts/sync-skill-contract.sh`.
+Do not hand-bump it.
+
+Workflow:
+
+1. Bump `package.json` (`bun run version:patch` / `:minor`) and
+   `src/version.ts`'s `CLI_VERSION`.
+2. Run `bun run sync:skill-contract` — this rewrites each SKILL.md's
+   `version:` line and re-stamps the Shell Contract block.
+3. Commit the result.
+
+CI gate `bun run check:skills` will reject the PR if step 2 was
+skipped (the rendered SKILL.md disagrees with the partial or the
+package.json version).
+
+## Authoring guidance
+
+When you write or edit a `launchpad-*` SKILL.md, follow these rules.
+They keep the bash blocks portable to Git Bash on Windows without
+forking the skill into per-OS versions.
+
+| Do | Don't |
+|---|---|
+| `"$HOME/.launchpad/session.json"` | `~/.launchpad/session.json` (parses fine, but visually nudges the agent toward `$env:USERPROFILE`) |
+| `"$TOKEN"`, `"$BOT"` (quoted) | bare `$TOKEN`, `$BOT` |
+| `${TMPDIR:-/tmp}/foo` | `/tmp/foo` (Git Bash needs `$TMPDIR`) |
+| `case "$(uname -s)" in …` | per-OS prose ("on macOS … on Linux …") |
+| `[ -n "$VAR" ] \|\| { echo …; exit 1; }` for nullable inputs | unchecked `$(jq -r .field file)` pipes |
+| `gh auth status --hostname github.com` | `gh auth status` (lenient about which host) |
+
+Forbidden tokens (CI grep blocks these inside ```bash``` fences):
+`Test-Path`, `Get-Content`, `Get-ChildItem`, `Where-Object`,
+`Write-Output`, `Write-Host`, `$env:`, `Set-Location`, `New-Item`,
+`Remove-Item`. Update the list in `scripts/check-skill-bash-dialect.sh`
+and `tests/skill-contract.test.ts` together if you need to extend it.
+
+## Why not ship a PowerShell version of each skill?
+
+The audience is Claude Code users, and Claude Code's `Bash` tool runs
+bash. There is no audience for a PowerShell version of these skills.
+Per-OS forks would also double the maintenance burden and risk drift
+between variants. One skill, one shell, OS-branched inside bash with
+`case "$(uname -s)"` where it actually matters.

package/skills/_partials/shell-contract.md

@@ -0,0 +1,42 @@
+<!--
+shell-contract.md — single source of truth for the "Shell contract"
+preamble that every launchpad-* skill must carry verbatim.
+
+Why this exists: Claude Code's `Bash` tool always invokes `bash`,
+even on Windows (where it resolves to Git for Windows / MSYS bash).
+Without an explicit contract, models will sometimes transliterate
+the fenced bash blocks into PowerShell on Windows ("$env:USERPROFILE",
+Test-Path, Get-Content, etc.), which then fails with a confusing
+`/usr/bin/bash: syntax error` because the bash tool is still what
+runs the command.
+
+The block below is short and imperative on purpose — models follow
+brief rules far better than verbose ones. Edit cautiously; CI
+asserts that the rendered block in each SKILL.md is byte-identical
+to this file (scripts/check-skill-contract.sh).
+
+Do NOT edit the launchpad-*/SKILL.md copies of this block directly.
+Edit this file, then run `bun run sync:skill-contract` to re-stamp
+the four launchpad-* skills.
+-->
+## 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
+```

package/skills/launchpad-content-pr/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: launchpad-content-pr
+description: Push a content change to a Launchpad app via `launchpad deploy` and verify it shipped via `launchpad status`. Covers the post-first-deploy iteration loop (edit → deploy → verify) and the stack-fit pre-flight that the bot enforces server-side. Use when someone says "push a content change", "ship an update", "/launchpad-content-pr", "verify my deploy", or after `/launchpad-deploy` reports `done` and they want to follow up with an edit.
+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-content-pr
+
+Push a content change to an already-provisioned Launchpad app, then
+verify it shipped.
+
+Under Model A the first deploy and the first content are the same
+event — `launchpad init` + `launchpad deploy` from the user's CWD
+opens a PR that contains their working tree, the bot waits for the
+Cloudflare Pages deployment to come up green (`deployment_verified`
+lifecycle gate), and the lifecycle flips to `live`. There is no
+separate "now push content" step.
+
+This skill is therefore the **iteration** companion to
+`/launchpad-deploy`: once an app is live, how do you ship the next
+change? It is also the canonical place to find the stack-fit
+pre-flight (the rules the bot enforces server-side on every bundle).
+
+## Pre-flight
+
+```bash
+launchpad whoami
+```
+
+If that fails, run `/launchpad-onboard` first. You also need to be
+an owner or editor on the slug — `launchpad apps` lists every app
+the caller can see along with the role per app.
+
+## Confirm the app is live
+
+```bash
+launchpad apps
+```
+
+Look for the slug in the `live` lifecycle bucket. If it's in
+`provisioning` / `failed` / `destroying` / `destroyed`, the
+iteration loop is not the right tool — route to
+`/launchpad-deploy-status` (in-flight) or `/launchpad-destroy`
+(teardown) instead.
+
+## Edit and ship
+
+The iteration loop is two verbs:
+
+```bash
+# 1. Edit your working tree.
+
+# 2. Ship it.
+launchpad deploy --message "<one-line description>"
+```
+
+The CLI bundles the CWD (using `git ls-files -co --exclude-standard`
+where available; falling back to a pure-FS walker honouring
+`.gitignore` and a default-ignore set), gzips it, uploads to the
+bot, and the bot opens a content PR on `launchpad-app-<slug>`.
+Cloudflare Pages auto-deploys on merge to `main`; the bot waits for
+the deploy to come up green via the `deployment_verified` lifecycle
+gate before reporting `done`.
+
+Common flags:
+
+- **`--slug <slug>`** — explicit override. Defaults to the slug from
+  `./launchpad.yaml`, or the cwd-name parse if you're in a
+  `launchpad-app-<slug>/` clone.
+- **`--message <text>`** — threaded as the PR description. Useful
+  for change logs and audit trails.
+- **`--file <path>`** — point at a non-default manifest path.
+
+Exit codes:
+
+- **0** — content PR opened + Cloudflare Pages deployment verified.
+- **non-zero** — see `/launchpad-deploy-status <slug>` for the
+  failure reason.
+
+## Stack-fit — what the bot enforces server-side
+
+The bot rejects bundles that contain shapes the Cloudflare Pages +
+Workers runtime cannot host. The validation runs on every
+`launchpad deploy`; you do not need to pre-flight it locally, but
+**knowing what's enforced saves the round-trip when a bundle is
+going to fail**.
+
+The accepted Launchpad stack is the single source of truth in:
+
+- `launchpad-platform/ARCHITECTURE.md § Tech Stack`
+- `launchpad-platform/PATTERNS.md § Approved Libraries`
+- `launchpad-platform/ANTI-PATTERNS.md`
+
+### Forbidden runtime dependencies
+
+The bot rejects bundles whose `package.json` declares any of these
+runtime dependencies — they do not work in the Workers runtime
+without a non-trivial port:
+
+| Forbidden | Replacement on Launchpad |
+|---|---|
+| `fastify` / `express` / `koa` / `hapi` / `@nestjs/*` | `hono` mounted at `functions/api/[[path]].ts` — the only server framework (PATTERNS.md). |
+| `better-sqlite3` / native `sqlite3` | Cloudflare D1 binding (`wrangler.toml [[d1_databases]]`). |
+| `pg` / `mysql2` / `mongodb` / `mongoose` / `redis` / `ioredis` | Neon (Postgres over HTTP) or another HTTP-driver backend. Native TCP drivers do not work in the Workers runtime. |
+| `dotenv` | `c.env.*` bindings; `wrangler secret put` (or `launchpad envvars` / `launchpad secrets push`) for secrets. |
+| `pm2` / `forever` / `nodemon` | Cloudflare Cron Triggers (`wrangler.toml [triggers] crons`). |
+
+### Forbidden top-level files
+
+The bot rejects bundles whose root contains any of these (on non-
+container app-types):
+
+```
+Dockerfile · docker-compose.yml · docker-compose.yaml · nginx.conf
+pm2.config.js · ecosystem.config.js · Procfile
+```
+
+Their presence is the smoking gun that the app was copied from a
+long-running-server stack without removing the legacy infra.
+
+### Forbidden source patterns
+
+The bot's secret-scan + build-command policy rejects bundles where
+the source tree contains:
+
+- `process.env.X` / `process.env['X']` reads — switch to `c.env.*`
+  bindings.
+- `setInterval` / `setTimeout` daemons — Workers do not run between
+  requests; use Cron Triggers for periodic work.
+- High-signal secret patterns (AWS access keys, GitHub PATs / OAuth
+  / app tokens, Slack tokens, SSH/RSA/EC/PGP keys, generic
+  `api_key` shapes). These never belong in a bundle — push them
+  through `launchpad secrets push` instead.
+
+### `react+api` requires `nodejs_compat`
+
+The bot checks that `wrangler.toml` declares
+`compatibility_flags = ["nodejs_compat"]` for any `react+api` app
+(ADR-0011 carve-out).
+
+### Verifying locally before you ship
+
+The CLI ships an offline validator that catches the schema-level
+issues without uploading anything:
+
+```bash
+launchpad validate
+launchpad plan
+```
+
+Neither verb talks to the bot. Catch what you can locally; the bot
+catches the rest server-side.
+
+## Verify after merge
+
+```bash
+launchpad status <slug>
+```
+
+Three possible states (see `/launchpad-status` for the canonical
+reference):
+
+- **`in sync`** — local matches deployed; the deploy landed and
+  `deployment_verified` is green. You're done.
+- **`drift: <fields>`** — your local manifest diverges from what was
+  deployed. Either re-run `launchpad deploy` to ship the local, or
+  `launchpad pull <slug> --out launchpad.yaml` to bring the local
+  into line with deployed.
+- **`no deployed manifest yet`** — the deploy is still in flight or
+  failed. Re-check in a minute, or run `/launchpad-deploy-status
+  <slug>`.
+
+You can also point a browser at `https://<slug>.launchpad.m-kopa.us`
+once status reports `in sync`. An SSO gate sits in front of the app:
+for a gateway-fronted app (the default, `auth: gateway`) expect a
+redirect to the Entra-OIDC gateway (Microsoft sign-in) on the first
+request; for an `auth: access` app expect a redirect to
+`*.cloudflareaccess.com`. Either way you land on your app after sign-in.
+
+If the URL serves the wrong thing:
+
+- **`200 OK` with no SSO redirect** → the edge gate is missing or
+  open. Check the app's auth (gateway KV entry, or the Access policy
+  via the portal admin UI); the
+  access-lockout runbook lives in
+  `launchpad-platform/docs/runbooks/access-lockout.md`.
+- **`404`** → Pages deploy hasn't finished, or build failed. Run
+  `launchpad status <slug> --json` to see the most recent error.
+- **`5xx` from Cloudflare** → wait + retry; cert issuance can lag a
+  few minutes on a brand-new hostname.
+
+## Ongoing-deploy verbs
+
+Once you've shipped first content, the daily-use verbs are:
+
+- **`launchpad status`** (`/launchpad-status`) — is my local
+  `launchpad.yaml` in sync with what's deployed?
+- **`launchpad pull <slug>`** (`/launchpad-status`) — read the
+  currently-deployed `launchpad.yaml`.
+- **`launchpad deploy`** — package the working tree + open an
+  update PR via the bot.
+- **`launchpad envvars`** — list / set / remove non-secret
+  production env vars.
+- **`launchpad secrets push`** — push secrets (never via git).
+- **`launchpad logs <slug>`** — recent Cloudflare Pages deployment
+  history.
+- **`launchpad rollback`** — revert manifest to a prior git SHA +
+  re-apply.
+
+## Don'ts
+
+- Do **not** shell out to `gh`, `jq`, `curl`, or `git` from this
+  skill. Every step is a `launchpad` verb. External users without
+  M-KOPA GitHub access need this skill to work end-to-end on the
+  CLI alone.
+- Do **not** open content PRs by hand against the app repo — the
+  bot's bootstrap ruleset gates auto-merge, and a hand-rolled PR
+  bypasses the bundle scan, secret-scan, and build-command policy.
+  Use `launchpad deploy`.
+- Do **not** treat the stack-fit pre-flight as something the user
+  re-implements locally. The bot enforces it server-side on every
+  bundle; the playbook describes what's enforced, not how to
+  re-implement it.
+- Do **not** force-merge if the bot's PR checks are red. The
+  bundle-policy / secret-scan / build-command checks are detecting
+  real things; surface the failure verbatim and let the user fix
+  the bundle.
+- Do **not** edit `launchpad.yaml`'s `production_env:` block to
+  contain secret values. That block is non-secret by contract;
+  `launchpad status` warns when a value looks like a secret. Use
+  `launchpad secrets push` for the real secret path.