@mutmutco/claude-plugin 4.5.161 → 4.5.162

package/skills/release/verification.md

@@ -0,0 +1,7 @@
+For the independent run recheck, scope the read to the release window, so a busy repo's unrelated runs cannot fill the cap: note the UTC instant you started `--apply` (`date -u +%Y-%m-%dT%H:%M:%SZ`), then run `gh run list --repo {owner}/{repo} --created ">=<apply-start-utc>" --limit 100 --json databaseId,headSha,workflowName,status,conclusion,url > .jerv/tmp/release-runs.json`, then filter locally by the exact SHA from the saved receipt with `node -e 'const rows = require("./.jerv/tmp/release-runs.json"); const sha = process.argv[1]; const matches = rows.filter((run) => run.headSha === sha); if (rows.length >= 100 || !matches.length) throw new Error("release run set is incomplete or absent"); console.log(JSON.stringify(matches, null, 2));' "<release-sha>"`.
+
+Do not use the raw `releases/latest` API route, a `--jq` formatter, or `gh run list --commit`; if the bounded list reaches 100 rows or has no SHA match, the run set is unverified and must not be called green.
+
+- A `private` npm surface (`surfaces.json`): the doctor's `npm-token-rejected` finding comes first. A 401 from `npm whoami` through the `_org` `npm/NPM_TOKEN` vault hop means the token is rejected, and every authenticated `npm view` then 404s exactly like an absent package — rotate the token; only after a login is a restricted 404 "unverifiable from here", never "not published" (`publish-private-package`). On a repo whose workflows publish through Trusted Publishing and name no registry token, that row is `info`, not a warning: no lane consumes the org token, so it constrains your manual read only.
+
+- `served-channel(<product>)` row — the release's proof that new installs get it: the public `/release/version` pointer of the releasing repo's OWN channel (the Hub's `mmi`, or the product its registry `installer` declaration names; no declaration → no row), read after deploy and publish are green. `success` names the version read. `failure` is either a channel still on the previous version or a stale served process (the route answers 401/404): the note names what moves that channel and the exact remedy; run it, then re-read the pointer. `pending` means not probed (legs not green) or unreadable, never proof. The row is receipt evidence only, never a ledger leg, so it never blocks the next train.

package/skills/secrets/SKILL.md

@@ -23,12 +23,7 @@ SecureString + KMS, and **a value is never echoed to chat or logs**):
   A project-admin reaches one of these only via a master **grant**; the master is unrestricted (master ⊇
   project-admin).
 
-**Grant scope (#3652).** A grant is `rw` by default — it opens both keyless `use` and `set`/`rm` on that
-key. `mmi-cli vault secrets grant <repo> <login> <key> --read` grants **consume-only** reach: keyless `use`
-works, rotate and remove still refuse. Only a `--read` grant may name a **wildcard** key — `*` for the
-whole namespace, `<provider>/*` for one provider group — so "may read every crown jewel" is one grant
-instead of forty. A wildcard never confers write; asking for one as `rw` is refused, not narrowed.
-`mmi-cli oracle org access capabilities` prints `grant (read)` or `grant (rw)` next to each name.
+For org-infra grants (including read-only wildcards), read [reference.md](reference.md) before granting access.
 
 A bare `<KEY>` is the **stageless canonical** at the slug root — one value every stage shares (#2244)
 and the path deploys resolve (#2523). A staged `dev/<KEY>` is a **per-stage override** and WINS for that
@@ -86,65 +81,9 @@ mmi-cli vault secrets rm SCRAPER_API_KEY
 **Never** pass a value as an argument (`secrets set KEY thevalue` is wrong — there is no value arg). The
 confirmation prints the **name and tier only**, never the value.
 
-**Windows: a multiline wrapped command must be file-backed (#6048).** `cmd.exe` truncates at the first
-newline, so an inline `node -e "<multiline script>"` after `--` reaches the child truncated and fails
-before your code runs. Write the script to a **project-local ignored file** (e.g. `tmp/fetch-models.mjs`
-— git-ignored, never tracked) and wrap the file instead; the key is still injected into the child's env:
+On Windows, read [reference.md](reference.md) before wrapping a multiline command.
 
-```bash
-mmi-cli vault secrets use GEMINI_API_KEY -- node tmp/fetch-models.mjs
-```
-
-## Rotation checklist
-
-Before rotating, enumerate every copy of the key so no tier stays stale:
-
-```bash
-mmi-cli vault secrets list --repo owner/Repo
-```
-
-Check the bare canonical plus any `dev/`, `rc/`, `main/` overrides the list shows. Rotate the provider-side
-key first, then write every declared coordinate that still needs that key. For keys with a provider probe
-(`RECALL_API_KEY` today), `secrets set` validates the new value before printing success; `secrets verify
-<KEY>` repeats the same probe later without printing the value. If the verifier fails, treat the rotation as
-incomplete even if the vault write itself succeeded.
-
-## Step 2 — org-infra elevation (master-only)
-
-Your own repo's full tree (dev/rc/main) is already self-serve (#2032). The **org-infra** namespaces
-(`shared`/`cloudflare`/`docs`/`mmi-hub`, every tier) stay master-only. A project-admin who needs one of
-those keys asks the master, who grants a **scoped, auditable** standing access to that one key (or revokes
-it). These verbs are **master-only** — the backend 403s anyone else.
-
-```bash
-# MASTER: let @oguz-mut consume one _org provider key from their MM-Chat project
-mmi-cli vault secrets grant mutmutco/MM-Chat oguz-mut google/SOME_SHARED_KEY
-# MASTER: withdraw it
-mmi-cli vault secrets revoke mutmutco/MM-Chat oguz-mut google/SOME_SHARED_KEY
-```
-
-The master can also operate the org-infra key directly while guiding (master ⊇ project-admin). Org-infra
-access by a project-admin **always originates from the master** — own-project access does not.
-
-## Coordinate — where does a new project secret belong?
-
-- Shared across stages → bare `<KEY>` at the project slug root (the usual canonical value).
-- Genuinely stage-distinct → `<stage>/<KEY>` override for `dev`, `rc`, or `main`.
-- The project-admin owns both shapes across their own project. A path under `_org`/shared infrastructure is
-  not a project coordinate and stays master-managed.
-
-## Tier-to-tier copy (provider keys, #1433)
-
-**Encryption / stage-distinct keys** (`*_ENC_KEY`, `SECRET_KEY_BASE`, etc.) must be **generated per stage** —
-never copied. **Provider sandbox keys** (e.g. Recall/Gemini for Katip dev/rc) **may** be shared across dev/rc
-when they point at the same sandbox project; prod should stay distinct when the provider contract requires it.
-
-Sanctioned copy within the own-project vault (org-infra/cross-project sources remain master-gated):
-```bash
-mmi-cli vault secrets copy --from rc --to dev --keys RECALL_API_KEY,GEMINI_API_KEY
-mmi-cli vault secrets copy --from rc --to dev --keys RECALL_API_KEY --dry-run   # plan only
-```
-Prefer this over manual copy piping — audit-logged, blocklist enforced.
+For rotation, org-infra elevation, new-key coordinates, or tier-to-tier copies, read [reference.md](reference.md) before the operation.
 
 ## Notes
 

package/skills/secrets/reference.md

@@ -0,0 +1,67 @@
+**Grant scope (#3652).** A grant is `rw` by default — it opens both keyless `use` and `set`/`rm` on that
+key. `mmi-cli vault secrets grant <repo> <login> <key> --read` grants **consume-only** reach: keyless `use`
+works, rotate and remove still refuse. Only a `--read` grant may name a **wildcard** key — `*` for the
+whole namespace, `<provider>/*` for one provider group — so "may read every crown jewel" is one grant
+instead of forty. A wildcard never confers write; asking for one as `rw` is refused, not narrowed.
+`mmi-cli oracle org access capabilities` prints `grant (read)` or `grant (rw)` next to each name.
+
+**Windows: a multiline wrapped command must be file-backed (#6048).** `cmd.exe` truncates at the first
+newline, so an inline `node -e "<multiline script>"` after `--` reaches the child truncated and fails
+before your code runs. Write the script to a **project-local ignored file** (e.g. `tmp/fetch-models.mjs`
+— git-ignored, never tracked) and wrap the file instead; the key is still injected into the child's env:
+
+```bash
+mmi-cli vault secrets use GEMINI_API_KEY -- node tmp/fetch-models.mjs
+```
+
+## Rotation checklist
+
+Before rotating, enumerate every copy of the key so no tier stays stale:
+
+```bash
+mmi-cli vault secrets list --repo owner/Repo
+```
+
+Check the bare canonical plus any `dev/`, `rc/`, `main/` overrides the list shows. Rotate the provider-side
+key first, then write every declared coordinate that still needs that key. For keys with a provider probe
+(`RECALL_API_KEY` today), `secrets set` validates the new value before printing success; `secrets verify
+<KEY>` repeats the same probe later without printing the value. If the verifier fails, treat the rotation as
+incomplete even if the vault write itself succeeded.
+
+## Step 2 — org-infra elevation (master-only)
+
+Your own repo's full tree (dev/rc/main) is already self-serve (#2032). The **org-infra** namespaces
+(`shared`/`cloudflare`/`docs`/`mmi-hub`, every tier) stay master-only. A project-admin who needs one of
+those keys asks the master, who grants a **scoped, auditable** standing access to that one key (or revokes
+it). These verbs are **master-only** — the backend 403s anyone else.
+
+```bash
+# MASTER: let @oguz-mut consume one _org provider key from their MM-Chat project
+mmi-cli vault secrets grant mutmutco/MM-Chat oguz-mut google/SOME_SHARED_KEY
+# MASTER: withdraw it
+mmi-cli vault secrets revoke mutmutco/MM-Chat oguz-mut google/SOME_SHARED_KEY
+```
+
+The master can also operate the org-infra key directly while guiding (master ⊇ project-admin). Org-infra
+access by a project-admin **always originates from the master** — own-project access does not.
+
+## Coordinate — where does a new project secret belong?
+
+- Shared across stages → bare `<KEY>` at the project slug root (the usual canonical value).
+- Genuinely stage-distinct → `<stage>/<KEY>` override for `dev`, `rc`, or `main`.
+- The project-admin owns both shapes across their own project. A path under `_org`/shared infrastructure is
+  not a project coordinate and stays master-managed.
+
+## Tier-to-tier copy (provider keys, #1433)
+
+**Encryption / stage-distinct keys** (`*_ENC_KEY`, `SECRET_KEY_BASE`, etc.) must be **generated per stage** —
+never copied. **Provider sandbox keys** (e.g. Recall/Gemini for Katip dev/rc) **may** be shared across dev/rc
+when they point at the same sandbox project; prod should stay distinct when the provider contract requires it.
+
+Sanctioned copy within the own-project vault (org-infra/cross-project sources remain master-gated):
+```bash
+mmi-cli vault secrets copy --from rc --to dev --keys RECALL_API_KEY,GEMINI_API_KEY
+mmi-cli vault secrets copy --from rc --to dev --keys RECALL_API_KEY --dry-run   # plan only
+```
+Prefer this over manual copy piping — audit-logged, blocklist enforced.
+

package/skills/stage/SKILL.md

@@ -26,33 +26,7 @@ up -d`, choose a free port from the registry range, and report the local URL (e.
 The commands are shell-aware and `--apply` runs them cross-shell. Board, deploy, secret, and project registry
 facts all live in the Hub registry — no repo-local control-plane file.
 
-**Secrets are vault-native — no `.env` on disk (#2655).** The org forbids *using* `.env` files, not just
-committing them. A repo **without** `.env.example` stages vault-native: `mmi-cli stage --apply` resolves the
-declared dev runtime secrets (registry `requiredRuntimeSecrets[dev]`) from the vault and injects them straight
-into the compose **process environment**, which Compose interpolates the file with — no secret ever touches
-disk. A repo that still ships `.env.example` keeps the legacy `.env` bootstrap for back-compat until its
-compose migrates to passthrough; new repos should ship **no** `.env.example`.
-
-**Runtime env reaches the container through the generated passthrough (#6345).** Interpolation is not
-delivery: a container receives only what its own `environment:` declares. So `/stage` mirrors the box deploy —
-it generates `tmp/stage/runtime-env.override.yml` (gitignored, **key names only**, values stay in the process
-env) passing every runtime key through to each service the compose marks `labels: {"mmi.runtime-env": "true"}`,
-and loads it beside `docker-compose.yml` for the whole stage. Mark the app service with that label; a repo
-that hand-declares its variables needs nothing. Unmarked sidecars (db, cache) keep getting only what they
-interpolate themselves. Never wrap an individual `docker compose` call in `mmi-cli vault secrets use` to work
-around a missing value (#6344) — that value is scoped to the one child process it wraps, so the next `docker
-compose logs`/`down` fails the same `required variable … is missing a value`. Declare the key in registry
-`requiredRuntimeSecrets[dev]` and let `/stage` carry it across the whole lifecycle.
-
-**Build-time secrets (#5381).** When META declares `requiredBuildSecrets` (e.g. Katip's
-`NODE_AUTH_TOKEN=@github-packages-token` for `@mutmutco/example-ui` on GitHub Packages), `/stage` injects those
-BuildKit ids into the **`docker compose build`** process env only — not into the running container. Central
-deploy mints the packages sentinel from Actions `GITHUB_TOKEN`; a laptop cannot. Resolution order: existing
-process env → stageless project vault secret under the BuildKit id → existing GitHub sign-in
-(`GH_TOKEN`, `GITHUB_TOKEN`, or `gh auth token`). Package read access is still required and is enforced
-by GitHub Packages during the build. Cloud containers whose GH_TOKEN is a proxy placeholder set MMI_GH_PAT to a fine-grained PAT (resource owner mutmutco, Organization → Members: read); mmi-cli prefers it. If every source is missing, `/stage` fails before the build.
-Setup: [`docs/Guides/tenant-runtime.md`](../../docs/Guides/tenant-runtime.md) § Local `/stage`. Never commit
-or print the PAT.
+For vault/env passthrough or build-time secret setup, read [reference.md](reference.md) before running the stage.
 
 ## Step 0 — inspect the plan
 
@@ -101,22 +75,7 @@ their own stage on separate ports — you do not need to stop one before startin
 keys on branch; use a distinct North Star slug per parallel grind or feature. Stage JSON/state records
 the starting `cwd` plus git branch/commit when available.
 
-### Step 1a — post-smoke panel (when criteria exist)
-
-When grinding or the user supplied **acceptance criteria** (from the issue body at Gate 1 — not
-ad-hoc chat text), run a **Budget-routing panel** on observable stage signals before teardown:
-
-1. **Panel** (parallel):
-   - **requirements-match** (budget tier) — does the staged URL/behavior meet the criteria?
-   - **runtime-health** (budget tier) — console errors, failed `healthUrl`, broken UI signals
-     *(smoke observability — not the grind `correctness` hard lens)*
-   - **tests-actually-test** (budget tier) — if Playwright ran, did it exercise the changed path?
-2. **Confirm** — get an independent second model to verify the staged URL or behavior meets the acceptance criteria.
-3. Feed the result back to the active loop or report to the human. A blocker
-   means the stage failed smoke — do not claim the grind criterion met.
-   This panel is **not** a security clearance — grind Phase 2 still runs the `security` hard lens.
-
-Skip when `/stage` is ad-hoc preview with no criteria.
+When grinding or issue acceptance criteria exist, read [smoke.md](smoke.md) and run its post-smoke panel before teardown.
 
 ## Step 2 — stop when done
 
@@ -132,64 +91,13 @@ from the original stage working directory. Stop re-fetches the declared dev runt
 can interpolate the same file (`${POSTGRES_PASSWORD:?}`, `${PORT:?}`) — secrets never come from the state
 file (#6351). A vault-native repo with no `.env` gets `PORT` defaulted to the bound stage port.
 
-## /stage --live — personal cloud dev stage
-
-Project admins can deploy the **current branch** to their project's dev runtime without an IP
-restriction. The CLI dispatches legacy gate cleanup, then the dev deploy through the Hub backend.
-Cleanup removes only that project's old stage rules and creates no Cloudflare rules, so rule-slot
-quotas do not block staging. It still reads Cloudflare to detect old gates; cleanup failures stay visible.
-The stage is accessible from any IP after both workflows succeed. The app's own sign-in still applies.
-No SSH from your machine; project authorization remains enforced by the Hub.
-
-**Deploy-model preflight (#5466 / #5467).** `/stage --live` is **not** generally available. Read
-`deployModel` first (`mmi-cli oracle org project get {owner}/{repo}` → `deployModel`, or the dry
-`mmi-cli stage --live --json` refusal). It applies only to **`tenant-container`** repos (the same
-model the Hub tenant-deploy + tenant-control gates require). **`registry-publish` is not applicable**
-for live stages — nor are hub-serverless, solo-container, static-cdn, vercel (its preview URL is on the
-plain `/stage` receipt), content, or none. For an
-unsupported model the dry plan refuses **before** offering `--apply` / `--down`; do not invent a
-tenant deploy.
-
-```bash
-mmi-cli stage --live           # dry-run plan (refuses when deployModel is not tenant-container)
-mmi-cli stage --live --apply   # clear legacy gates + deploy without an IP restriction
-```
-
-Tear it down when done — **only when `--apply` actually created a runtime**. This stops the runtime
-without Cloudflare work:
-
-```bash
-mmi-cli stage --live --down --apply
-```
-
-If apply never landed (unsupported model, failed dispatch, or you never ran `--apply`), `--down` is a
-**safe no-op** — do not promise teardown of a stage that was never created. Personal dev stages only —
-rc/live environments still move exclusively through the promotion train.
+For a personal cloud dev stage (`--live`), read [live.md](live.md) before offering, applying, or tearing it down.
 
 ## Step 3 — report
 
 The stage URL, what's running (server + tools), the workspace path (`tmp/stage/`), and the teardown command.
 
-## Notes
-
-- `/stage` is local — no AWS, no deploy, no board or version effect. The one cloud exception is
-  `--live`: an on-demand **dev** stage of your branch for **`tenant-container`** repos only, without
-  a stage IP restriction (above). Preflight `deployModel` before offering it; `registry-publish`
-  and other models have no live stage.
-- Remote rc/live environments move only through `/rcand`, `/release`, and `/hotfix`.
-- Everything is gitignored; `/stage` never produces a tracked change.
-- **Playwright MCP output goes to `tmp/`**, never the repo root: if you drive the Playwright MCP server,
-  pass `--output-dir tmp/playwright-mcp` (or point its output there). `.playwright-mcp/` is kept gitignored
-  by the org `.gitignore` managed block (`mmi-cli doctor`) as a safety net, so a stray default capture is
-  never tracked.
-- `tools[]` is declarative for now; stage hardening starts/stops the main configured process. Repos with
-  extra local services should encode them behind `stage.up` until a tool runner is added.
-- **Stale Docker bundle:** the registry-derived Docker Compose default builds with `docker compose build
-  --no-cache` before `up`. If the browser still serves an old bundle, run `mmi-cli stage stop --apply`, rerun
-  `/stage`, then inspect `tmp/stage/state.json` identity, container image labels, and compose build inputs.
-- **Stale `.env`:** when `.env` already exists from a prior `/stage` run, `stage run` does **not** refresh it
-  from an updated `.env.example` — it warns on stderr and keeps the stale file. Delete `.env` (or merge in the
-  new keys by hand) when `.env.example` changes, then re-run `/stage`.
+For Playwright output placement, extra services, or stale Docker/env troubleshooting, read [reference.md](reference.md) Notes.
 
 ## Retro — one check before you finish
 Before your final report, answer one question honestly: did **this skill's own instructions** misfire

package/skills/stage/live.md

@@ -0,0 +1,34 @@
+## /stage --live — personal cloud dev stage
+
+Project admins can deploy the **current branch** to their project's dev runtime without an IP
+restriction. The CLI dispatches legacy gate cleanup, then the dev deploy through the Hub backend.
+Cleanup removes only that project's old stage rules and creates no Cloudflare rules, so rule-slot
+quotas do not block staging. It still reads Cloudflare to detect old gates; cleanup failures stay visible.
+The stage is accessible from any IP after both workflows succeed. The app's own sign-in still applies.
+No SSH from your machine; project authorization remains enforced by the Hub.
+
+**Deploy-model preflight (#5466 / #5467).** `/stage --live` is **not** generally available. Read
+`deployModel` first (`mmi-cli oracle org project get {owner}/{repo}` → `deployModel`, or the dry
+`mmi-cli stage --live --json` refusal). It applies only to **`tenant-container`** repos (the same
+model the Hub tenant-deploy + tenant-control gates require). **`registry-publish` is not applicable**
+for live stages — nor are hub-serverless, solo-container, static-cdn, vercel (its preview URL is on the
+plain `/stage` receipt), content, or none. For an
+unsupported model the dry plan refuses **before** offering `--apply` / `--down`; do not invent a
+tenant deploy.
+
+```bash
+mmi-cli stage --live           # dry-run plan (refuses when deployModel is not tenant-container)
+mmi-cli stage --live --apply   # clear legacy gates + deploy without an IP restriction
+```
+
+Tear it down when done — **only when `--apply` actually created a runtime**. This stops the runtime
+without Cloudflare work:
+
+```bash
+mmi-cli stage --live --down --apply
+```
+
+If apply never landed (unsupported model, failed dispatch, or you never ran `--apply`), `--down` is a
+**safe no-op** — do not promise teardown of a stage that was never created. Personal dev stages only —
+rc/live environments still move exclusively through the promotion train.
+

package/skills/stage/reference.md

@@ -0,0 +1,49 @@
+**Secrets are vault-native — no `.env` on disk (#2655).** The org forbids *using* `.env` files, not just
+committing them. A repo **without** `.env.example` stages vault-native: `mmi-cli stage --apply` resolves the
+declared dev runtime secrets (registry `requiredRuntimeSecrets[dev]`) from the vault and injects them straight
+into the compose **process environment**, which Compose interpolates the file with — no secret ever touches
+disk. A repo that still ships `.env.example` keeps the legacy `.env` bootstrap for back-compat until its
+compose migrates to passthrough; new repos should ship **no** `.env.example`.
+
+**Runtime env reaches the container through the generated passthrough (#6345).** Interpolation is not
+delivery: a container receives only what its own `environment:` declares. So `/stage` mirrors the box deploy —
+it generates `tmp/stage/runtime-env.override.yml` (gitignored, **key names only**, values stay in the process
+env) passing every runtime key through to each service the compose marks `labels: {"mmi.runtime-env": "true"}`,
+and loads it beside `docker-compose.yml` for the whole stage. Mark the app service with that label; a repo
+that hand-declares its variables needs nothing. Unmarked sidecars (db, cache) keep getting only what they
+interpolate themselves. Never wrap an individual `docker compose` call in `mmi-cli vault secrets use` to work
+around a missing value (#6344) — that value is scoped to the one child process it wraps, so the next `docker
+compose logs`/`down` fails the same `required variable … is missing a value`. Declare the key in registry
+`requiredRuntimeSecrets[dev]` and let `/stage` carry it across the whole lifecycle.
+
+**Build-time secrets (#5381).** When META declares `requiredBuildSecrets` (e.g. Katip's
+`NODE_AUTH_TOKEN=@github-packages-token` for `@mutmutco/example-ui` on GitHub Packages), `/stage` injects those
+BuildKit ids into the **`docker compose build`** process env only — not into the running container. Central
+deploy mints the packages sentinel from Actions `GITHUB_TOKEN`; a laptop cannot. Resolution order: existing
+process env → stageless project vault secret under the BuildKit id → existing GitHub sign-in
+(`GH_TOKEN`, `GITHUB_TOKEN`, or `gh auth token`). Package read access is still required and is enforced
+by GitHub Packages during the build. Cloud containers whose GH_TOKEN is a proxy placeholder set MMI_GH_PAT to a fine-grained PAT (resource owner mutmutco, Organization → Members: read); mmi-cli prefers it. If every source is missing, `/stage` fails before the build.
+Setup: [`docs/Guides/tenant-runtime.md`](../../docs/Guides/tenant-runtime.md) § Local `/stage`. Never commit
+or print the PAT.
+
+## Notes
+
+- `/stage` is local — no AWS, no deploy, no board or version effect. The one cloud exception is
+  `--live`: an on-demand **dev** stage of your branch for **`tenant-container`** repos only, without
+  a stage IP restriction (above). Preflight `deployModel` before offering it; `registry-publish`
+  and other models have no live stage.
+- Remote rc/live environments move only through `/rcand`, `/release`, and `/hotfix`.
+- Everything is gitignored; `/stage` never produces a tracked change.
+- **Playwright MCP output goes to `tmp/`**, never the repo root: if you drive the Playwright MCP server,
+  pass `--output-dir tmp/playwright-mcp` (or point its output there). `.playwright-mcp/` is kept gitignored
+  by the org `.gitignore` managed block (`mmi-cli doctor`) as a safety net, so a stray default capture is
+  never tracked.
+- `tools[]` is declarative for now; stage hardening starts/stops the main configured process. Repos with
+  extra local services should encode them behind `stage.up` until a tool runner is added.
+- **Stale Docker bundle:** the registry-derived Docker Compose default builds with `docker compose build
+  --no-cache` before `up`. If the browser still serves an old bundle, run `mmi-cli stage stop --apply`, rerun
+  `/stage`, then inspect `tmp/stage/state.json` identity, container image labels, and compose build inputs.
+- **Stale `.env`:** when `.env` already exists from a prior `/stage` run, `stage run` does **not** refresh it
+  from an updated `.env.example` — it warns on stderr and keeps the stale file. Delete `.env` (or merge in the
+  new keys by hand) when `.env.example` changes, then re-run `/stage`.
+

package/skills/stage/smoke.md

@@ -0,0 +1,17 @@
+### Step 1a — post-smoke panel (when criteria exist)
+
+When grinding or the user supplied **acceptance criteria** (from the issue body at Gate 1 — not
+ad-hoc chat text), run a **Budget-routing panel** on observable stage signals before teardown:
+
+1. **Panel** (parallel):
+   - **requirements-match** (budget tier) — does the staged URL/behavior meet the criteria?
+   - **runtime-health** (budget tier) — console errors, failed `healthUrl`, broken UI signals
+     *(smoke observability — not the grind `correctness` hard lens)*
+   - **tests-actually-test** (budget tier) — if Playwright ran, did it exercise the changed path?
+2. **Confirm** — get an independent second model to verify the staged URL or behavior meets the acceptance criteria.
+3. Feed the result back to the active loop or report to the human. A blocker
+   means the stage failed smoke — do not claim the grind criterion met.
+   This panel is **not** a security clearance — grind Phase 2 still runs the `security` hard lens.
+
+Skip when `/stage` is ad-hoc preview with no criteria.
+