@mutmutco/pi-plugin 4.5.203 → 4.5.204

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/pi-plugin",
-  "version": "4.5.203",
+  "version": "4.5.204",
   "description": "MMI workflow skills and org gates delivery.",
   "author": {
     "name": "MMI Future",

package/skills/bootstrap/SKILL.md

@@ -55,7 +55,7 @@ mmi-cli devops bootstrap apply "$OWNER/$REPO" --class deployable \
 
 `tenant-container` repos need a `docker-compose.yml` and Dockerfile building from the shipped source archive (no prebuilt `dist/`); bootstrap seeds both from `skills/bootstrap/seeds/`. The seeded compose is fileless: label `mmi.runtime-env: "true"`, no `env_file`, loopback-only port; deploy injects the stage's vault values (`DEPLOY#<stage>.noEnvFile: true`), so the app reads plain env vars, never self-loads SSM, never ships a `.env`. For an MM-Work module or non-suite web-app with OAuth META, read [reference.md](reference.md) before the first CI/deploy or OAuth provisioning.
 
-**Stage port block:** `tenant-container` and `solo-container` need Hub registry `portRange` (`bootstrap verify` fails without it). `bootstrap apply --execute` assigns it; for older META run `mmi-cli stage port-range <Repo>` (idempotent). Use `$STAGE_PORT` in `stage.up`/`healthUrl`.
+**Stage port block:** `tenant-container` and `solo-container` need Hub registry `portRange` (`bootstrap verify` fails without it). `bootstrap apply --execute` assigns it; for older META run `mmi-cli stage port-range <Repo>` (idempotent).
 
 ## Step 7 — org-managed .gitignore block
 

package/skills/bootstrap/reference.md

@@ -457,16 +457,12 @@ the bootstrap seed Dockerfile and compose templates). The seeded compose is file
 `labels: { mmi.runtime-env: "true" }`, no `env_file`, and a loopback-only port; the deploy injects the stage's
 vault values at runtime (`DEPLOY#<stage>.noEnvFile: true`) and the app reads plain env vars — it must **not** self-load SSM and must **not** ship a committed `.env`.
 
-Local `/stage` is optional product-owned configuration. A repo that wants `/stage` may carry a local
-`stage` block, but that file must not contain board, deploy, or secret registry facts.
-
 **Stage port block (required for central-container):** run `mmi-cli stage port-range <Repo>` to assign
 (idempotently) the repo's local port block from the central registry. `tenant-container` and
 `solo-container` **must** have Hub registry `portRange` — `mmi-cli devops bootstrap verify` fails without
 it (#5539), and `mmi-cli stage` cannot derive a local preview until the block exists. `bootstrap apply
 --execute` assigns the block automatically after DDB register for those models; for older META holes,
-run `stage port-range` explicitly. Use `$STAGE_PORT` in `stage.up` / `healthUrl`; `/stage` then picks a
-free port inside the block so a dev can run several projects/versions locally without collisions.
+run `stage port-range` explicitly. The block keeps local ports collision-free across projects and versions.
 
 Repo, default branch, ruleset applied, train branches locked (push allowlist), repository Environments
 provisioned per track (plan-gated protections named in apply output), project attached/created

package/skills/bootstrap/seeds/README.template.md

@@ -26,7 +26,7 @@ Read this section at the start of agent work in this repo.
   **routing** index only (`mmi-cli oracle docs index --check`), not product truth.
 - **GitHub wikis are retired org-wide** — this repo does not publish to a `.wiki.git`; do not create one.
 - **Stack:** (languages, frameworks, major services)
-- **Run locally:** (install, dev server, `/stage` if non-obvious)
+- **Run locally:** (install and dev server command)
 - **Verify before done:** (exact commands — test, lint, typecheck, repo gate script)
 - **Architecture:** deep build/deploy shape → `architecture.md`
 - **Gotchas:** (ports, env from vault not files, Windows/shell quirks specific to this repo)

package/skills/bootstrap/seeds/google-login.template.md

@@ -1,6 +1,6 @@
 # Google login — {{REPO_NAME}}
 
-This repo has a Google OAuth client provisioned by the org — one client spanning local/`/stage`, dev, rc, and
+This repo has a Google OAuth client provisioned by the org — one client spanning local, dev, rc, and
 prod. Adding Google login here is **self-serve**: you do not need master-admin help.
 
 ## Reach the creds (from SSM — never in git, never printed)
@@ -14,7 +14,7 @@ mmi-cli vault secrets use GOOGLE_CLIENT_SECRET -- <cmd>
 The canonical keys are the stageless `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET` pair at the project vault
 root. The project-admin can manage them for their own repo; runtime and CI read them keylessly. Never bake a secret into an
 image or commit it. The remote fileless deploy writes no release `.env`; **do not commit or hand-edit a `.env`**.
-The only `.env` you may create is the gitignored one `/stage` makes from `.env.example` for local dev.
+Never commit or hand-edit a `.env` file; local dev reads declared secrets keylessly via `mmi-cli vault secrets use`.
 
 ## The one rule that makes every environment work
 Build the OAuth `redirect_uri` from the **incoming request** — never a hardcoded base URL:

package/skills/bootstrap/seeds/suite-guide.template.md

@@ -17,11 +17,81 @@ The server exposes `/health` and `/module.js`. Register the module's bundle URL,
 3. **Impeccable knows Atomic Design at boot:** `impeccable context` loads `PRODUCT.md`, `DESIGN.md` and the `design.json` sidecar in `.impeccable`, which carry the Atomic Design contract 1.1.0: `Atoms -> Molecules -> Organisms -> Templates -> Pages`, upward-only composition enforced by `npx mmwork-check-ui --rules=all`. Pages arrange exported `@mutmutco/mmwork-ds` pieces around one template and never paint custom controls, raw `<button>`/`<input>`, `mw-*` classes, inline visual styles or raw hex/px values.
 4. **Automatic propagation:** on every kit release the Hub kit-adopt workflow opens an adoption PR here that bumps `@mutmutco/mmwork-ds`, runs `mmwork-sync-impeccable`, and writes `DESIGN.md`, the `.impeccable` design manifest and `.impeccable/config.json` (`hook.enabled: true`) at the repository root, and deletes any stale copies under `module/`. These files are kit-owned: do not hand-edit them, and keep them committed even if `.impeccable/` is ignored (the adoption PR force-stages them).
 5. **Root only:** `PRODUCT.md`, `DESIGN.md`, the `.impeccable` design manifest and `.impeccable/config.json` live only at this repository's root, never duplicated under `module/`; a copy there makes Impeccable treat `module/` as a separate root without `PRODUCT.md` and the config. Run `impeccable context` from the root. Any suite-wide propagation of these files needs an explicit intercom ACK handshake with the MM-Work Design Lead naming the files written and removed, `impeccable context` + `impeccable doctor --json` verification, and the issue/PR reference.
+6. **Front-loaded harmony (owner, 2026-10-25; Hub#8837 / MM-Work#7668):** design work runs one workflow — Front-Loaded Impeccable v4.7.0 + MM Artifacts + Live Docs (`Canlı belgeler`, `3a5c79df-5274-40ad-a1b5-a75e67a74dac`) + Atomic Design Kit (`@mutmutco/mmwork-ds`). The former local stage skill is retired; preview and verify through these tools only.
+
+## The MM Open Design System Bible (owner, 2026-10-25; Hub#8837 / Hub#8839)
+
+The bible for the MM open design system; every agent doing UI, design or MM Artifact work in this module treats it as second nature. Part 1 is how the system is built and used; Part 2 is how agents improve it when it fails them; Part 3 governs A/B choosing architecture and viewer behavior.
+
+### Part 1 — The five pillars (owner, 2026-10-25; Hub#8837)
+
+| Pillar | What it is | Claude / industry analogy | Where it lives |
+|---|---|---|---|
+| **1. MM Artifacts (`mm-artifact`)** | The HTML artifact file format (`type: 'document' \| 'canvas' \| 'design-system'`). By default a single self-contained HTML artifact; a multi-board Canvas only when comparing A/B options or viewport sizes side by side. | Claude Artifacts (the HTML artifact itself) | Local `.html` / `artifact.json` during agent dev (opened straight in the browser); stored in Live Docs when shared or created by Junior. |
+| **2. Design System Artifacts (`type: 'design-system'`)** | MM Artifacts stored in Live Docs that define a complete visual system (tokens, CSS, components, `DESIGN.md`). Every MM Artifact binds to one (`kit: { id, version }`). Includes (a) the MM-Work Atomic Design System (`3a5c79df`, MM-Work app and modules), (b) the Document/Editorial Design System (reports, checklists, decks, client documents), and future brand/client systems. | Claude Design Systems / theme packs an artifact pulls from on creation | Hosted in Live Docs (`Canlı belgeler`). Only the MM-Work app design system is also exported to npm (`@mutmutco/mmwork-ds`). |
+| **3. Live Docs (`Canlı belgeler`)** | The viewer, library, commenter and A/B picker inside the MM-Work app (`/documents/:id`), where people, Junior and agents view, comment on, version and share MM Artifacts. | Claude's Artifact viewer / workspace panel | Built into MM-Work (`web/src/documents/`, `src/documents.ts`). |
+| **4. Open Design Kit (`@mutmutco/mmwork-ds`)** | The npm package generated from `packages/mmwork-ds/source/` (the source of the MM-Work Atomic Design System), so MM-Work, the 10 suite modules and local app-UI MM Artifacts render real Atoms, Molecules, Organisms, Templates and Pages. | Published React/CSS component kit | `packages/mmwork-ds/source/` → `@mutmutco/mmwork-ds`, synced to Live Docs (`3a5c79df`) and all 10 module roots. |
+| **5. Impeccable (`v4.7.0`)** | The front-loaded design craft and quality engine (`impeccable context`, `craft-floor`, 15 playbooks such as `distill`, `typeset`, `layout`, `colorize`, `clarify`, `polish`, plus `impeccable detect --json` and `DESIGN.md`). Runs in front of every UI or MM Artifact creation so output is readable, well typeset, purposefully coloured and never AI slop. | Design director + mechanical UI linter | `.agents/skills/impeccable` + root `DESIGN.md` and the `design.json` sidecar in `.impeccable`. |
+
+Four owner decisions (2026-10-25T15:35:52Z):
+
+1. **Doc vs. app kit — add a Document Design System too.** Keep the MM-Work Atomic Design System (`3a5c79df-5274-40ad-a1b5-a75e67a74dac`) for MM-Work and module app UI (and as the fallback for now), and add a dedicated Document/Editorial Design System Artifact in Live Docs for reports, checklists, decks and client documents made by Junior or agents.
+2. **Where to save — local HTML for dev, Live Docs for shared.** Coding agents build and open local `.html` MM Artifacts (`node artifacts/review/review.mjs <folder> --standalone [<out.html>] [--open]`) for fast iteration, and publish to Live Docs only for a shared deliverable, an A/B decision canvas or a Design System. Junior inside MM-Work saves directly to Live Docs.
+3. **Artifact shape — single HTML by default, Canvas for A/B.** A single self-contained HTML view for documents, checklists and single-screen work; a multi-board spatial Canvas only for A/B choices or `1440`/`1024`/`390` side-by-side comparisons.
+4. **Kit binding — Live Docs hosts kits; npm only for MM-Work.** Every Design System Artifact in Live Docs stores its tokens/CSS/components and `DESIGN.md` so any HTML artifact can bind to it (`kit: { id, version }`); only the MM-Work app design system is also exported as `@mutmutco/mmwork-ds`, because the MM-Work app and the 10 suite modules compile against it.
+
+Craft essentials (owner, 2026-10-25; Hub#8839):
+
+- **Rich module colour and frosted glass — never graywashed.** Use purposeful module tones (`blue`, `coral`, `teal`, `purple`, `terracotta`, `green`, `pink`, `lime`, `cyan`, `magenta`, `fuchsia`) through kit props on `Card` (`tone`, `icon`/`mark`, `edge="bite"`), `Badge`, `Mark` and `Checkbox` (`lead`), backed by the kit's `--card-tint-dark: 34%`, `--card-tint-light: 22%` and `--card-blur`. Never override these tokens locally.
+- **Surface modes.** After `impeccable context --target <path>`, `DESIGN.md` and `reference/craft-floor.md`, choose the surface mode (`Operate`, `Read`, `Persuade` or `Experience`) and load the matching playbooks (`shape`, `distill`, `typeset`, `layout`, `colorize`, `clarify`, `polish`, `harden`, `adapt`) before writing markup.
+- **Restraint and hierarchy.** Group related items into section `Card`s (`heading: 2` under the page `<h1>`), keep main-column rows concise (`Cluster` with `fill` = `Checkbox` plus one trailing action), and put multi-line inspector detail in the right-hand `HelperCard` as `Stack` + `Text` — never `DataList`, which clips multi-line prose.
+- **Verify SSR pre-rendered HTML.** `impeccable detect --json` is blind on an unrendered `<div id="root"></div>` file; verify the output of `review.mjs <folder> --standalone --open`, which pre-renders into `#root`. An empty `#root`, missing fonts or an unrendered detector run is a failure, not a pass.
+
+### Part 2 — The System-First Autolearn Doctrine (never work around a broken tool in `tmp/`)
+
+Owner ruling 2026-10-25T15:41:41.360Z (Hub#8839): learn from the work, mistakes and discoveries and improve the system, instead of only fixing the current situation. Never patch the moment in `tmp/` and leave the shared system broken. If creating, bundling, rendering, checking or opening an MM Artifact or kit change needs a custom `tmp/` script, a bundler-regex patch, manually inlined fonts or locally overridden tokens, that is a **system defect, not a local task**. Run the three-step reflex at once:
+
+1. **Step A — fix the shared system at its source:** file or claim an issue, or message the owning suite seat (Design Lead, MM-Work, Jerv-JervCode, MMI-Hub, Jerv-Hub), so the shipped CLI, bundler, token, component or skill is fixed and no agent needs the workaround again. Any temporary workaround is named as such and linked to that issue.
+2. **Step B — record an autolearn note** (`jerv_learning_note`, or `mmi-cli learning skill-lesson`) with the exact friction and root cause.
+3. **Step C — record it in Hindsight memory** (`hindsight_ingest_document`): the root cause and the permanent fix.
+
+Autolearn watches for ad-hoc build/render/verify scripts under `tmp/`, empty `#root` renders, missing fonts, unrendered `impeccable detect` runs, geometry regressions, graywashed or untinted surfaces, walls of text, and skipped `impeccable context` or playbook passes, and escalates each into a shared toolchain, kit or skill improvement.
+
+### Part 3 — A/B Choosing Architecture & Viewer Rules (owner ruling 2026-10-25T15:57:26.199Z, #8841)
+
+Settled owner ruling: present clear, distinct choices in the existing MM Artifact viewer, not a
+"shell over a shell". These are authoring and viewer requirements, not proof of installed capabilities.
+
+1. **No "shell over a shell" — designer agents build only the alternatives, never their own A/B switcher.**
+   The outer MM Artifact viewer (the local review shell and `CanvasStage` / `CompareView` in Live Docs)
+   already IS the A/B selector shell: it renders the question prompt, Option A / Option B / Neither
+   buttons, notes and board switcher. A `designer` subagent must **NEVER** draw an A/B picker,
+   question header, option cards or a gallery of tiny `ThemePreview` thumbnails inside a board.
+   **One A/B decision = one page with two full-resolution live HTML boards:**
+   - `board-a`: the actual full-size (`1440x900`) live MM-Work screen rendered in **Option A**
+     (for example, Linear Dark).
+   - `board-b`: the exact same full-size (`1440x900`) live MM-Work screen rendered in **Option B**
+     (for example, Apple Black).
+   Never pack multiple themes or multiple options onto a single board.
+2. **Compare the live HTML artifacts directly — never screenshots or low-res thumbnails.**
+   Both options are live, vector-sharp HTML/CSS/React artifacts rendered from `@mutmutco/mmwork-ds`,
+   never raster PNG screenshots or shrunken preview cards. The A/B viewer must let the owner inspect
+   Option A and Option B side-by-side or toggle 1:1 at full crisp resolution, so subtle palette,
+   contrast and typography differences (such as Linear Dark vs. Apple Black) are immediately clear.
+3. **Content-only zoom — zoom the artifact content, never the outer A/B shell.**
+   In the local review viewer and Live Docs (`CanvasStage` / `BoardBridge`), `wheel` events
+   (including `ctrlKey` / `metaKey` pinch-zoom) and keyboard zoom (`Ctrl/Cmd + +/-/0`) on both the
+   outer review shell and inside board iframes (forwarded via `postMessage`) must call
+   `preventDefault()` and zoom **only the artifact canvas/board viewport**. `Ctrl + Mousewheel` and
+   viewer zoom controls must keep the outer A/B selector shell, question bar and controls at a fixed
+   1:1 UI size.
 
 ## Mandatory Impeccable workflow (owner, 2026-10-25; Hub#8814 / MM-Work#7629)
 
 UI and design verification uses `@mutmutco/mmwork-ds` (`mmwork-check-ui`) plus Impeccable on every design task: inspect the toolkit for applicable capabilities, work directly on the live app, and use our own MM Artifacts A/B canvas only when an owner A/B choice is needed. Functional journeys, where separately permitted, stay opt-in `workflow_dispatch`-only and never act as design checks.
 
+Front-load Impeccable before any UI or MM Artifact authoring: `impeccable context --target <path>`, `DESIGN.md` + the `design.json` sidecar in `.impeccable`, `.impeccable/config.json` (`hook.enabled: true`), `reference/craft-floor.md` + `reference/operate.md`, and `impeccable detect --json <target>`. Local/canvas MM Artifacts (`mm-artifact` v3 format) are checked and opened with one command: `node artifacts/review/review.mjs <folder> --standalone [<out.html>] [--open]`, which runs `check.mjs`, `check-ui.mjs` and `geometry.mjs`, pre-renders the board in `node:vm` (`ReactDOMServer.renderToStaticMarkup` into `#root`), runs `impeccable detect --json` on that rendered HTML, and opens it in the browser with `--open`.
+
 Impeccable v4.7.0 (engine v0.1.16) workflow; CLI verbs and agent playbooks are distinct:
 
 1. Boot once with `impeccable context --target <path>`. Use the `init` playbook for durable PRODUCT.md context, `document` for DESIGN.md + `.impeccable/design.json`, `impeccable doctor --json` to report drift, and `extract` to identify reuse. Read `reference/craft-floor.md` immediately before UI edits and `reference/operate.md` for task-oriented app UI. Extract through the existing kit; only the Design Lead can authorize kit changes.

package/skills/mmi-help/SKILL.md

@@ -18,8 +18,10 @@ Print a friendly, human-readable **MMI help** card of at most 180 words:
 2. Show the npm install command, `mmi-hub install`, and the read-only `mmi-hub status` check.
 3. Summarize the essentials: automatic updates, vault/keyless secrets, no repository environment
    files or personal agent instructions, and approved MMI release workflows.
-4. Name the org-guide skill for details, board, secrets, stage, and release for common tasks, and
-   brand when a company document, report, deck, or artifact needs the house identity.
+4. Name the org-guide skill for details, board, secrets, and release for common tasks, and
+   brand when a company document, report, deck, or artifact needs the house identity. Note that
+   org-guide also carries the MM Open Design System Bible: MM Artifacts, Live Docs (`Canlı belgeler`),
+   `@mutmutco/mmwork-ds`, front-loaded Impeccable v4.7.0, and system-first autolearn.
    Render invocation syntax for the current host only, using the forms above with the skill name
    substituted. If the host is unknown, use plain skill names rather than guessing.
 

package/skills/org-guide/SKILL.md

@@ -11,19 +11,21 @@ the [MMI help skill](../mmi-help/SKILL.md).
 ## Essential rules
 
 - Install `@mutmutco/hub` through npm, run `mmi-hub install`, and keep automatic updates enabled.
-  Check actual health with `mmi-hub status`; installation alone is not proof of a working updater.
+  Check health with `mmi-hub status`; installation alone does not prove updates work.
 - Use the scoped two-tier vault and keyless workflows. Never put secret values in chat, logs,
   command arguments, or repository environment files.
-- Personal agent instructions and host settings stay local and gitignored in product repositories.
-  Do not commit AGENTS.md, CLAUDE.md, or copied plugin instructions.
+- Personal agent instructions and host settings stay local and gitignored; never commit AGENTS.md,
+  CLAUDE.md, or copied plugin instructions.
 - Update affected `docs/Guides/operator.md` instructions with code. Commit, then run existing fast preflight before pushes/PRs.
 - Claim approved work through the board, use the repository's checks, and land through MMI.
-  A request for help or a plan does not authorize a change or a production release.
-- When an MMI tooling bug affects a developer other than `jervaise`, ask before filing a Hub report.
-  Respect a decline. Follow [Work and releases](references/work-and-releases.md#report-mmi-tooling-bugs)
-  for consent, duplicate handling, and optional released-fix Slack notifications.
-- Read the registry for release tracks, domains, and OAuth configuration. Use MMI provisioning
-  and release workflows rather than inventing parallel deployment or credential paths.
+  A help or plan request does not authorize changes or releases.
+- When an MMI tooling bug affects a developer other than `jervaise`, ask before filing a Hub report
+  and respect a decline; see [tooling bug reports](references/work-and-releases.md#report-mmi-tooling-bugs).
+- Read the registry for release tracks, domains, and OAuth. Use MMI provisioning and release
+  workflows, never parallel deployment or credential paths.
+- Design work follows the [MM Open Design System Bible](references/work-and-releases.md#the-mm-open-design-system-bible-8837-8839):
+  never patch broken shared tools with one-off `tmp/` scripts; fix them at source, record a learning
+  note, and update memory.
 
 ## Read one topic
 
@@ -31,13 +33,12 @@ the [MMI help skill](../mmi-help/SKILL.md).
 | --- | --- |
 | Install, update, reload, or diagnose tooling | [Getting started](references/getting-started.md) |
 | Report an MMI tooling bug with developer consent | [Tooling bug reports](references/work-and-releases.md#report-mmi-tooling-bugs) |
-| Work an issue, test, merge, or release | [Work and releases](references/work-and-releases.md) |
+| Work an issue, test, merge, release, or design | [Work and releases](references/work-and-releases.md) |
 | Consume, declare, rotate, or request a secret | [Vault and keyless access](references/vault.md) |
 | Register domains or configure Google OAuth | [Domains and OAuth](references/domains-and-oauth.md) |
 | Decide what belongs in a product repository | [Repository rules](references/repository-rules.md) |
 | Build an MM-Work module | not bundled — [MM-Work module guide](https://github.com/mutmutco/MM-Work/blob/development/packages/mmwork-ds/GUIDE.md) in `@mutmutco/mmwork-ds` |
 | Produce company-facing documents in the MM brand | not bundled — the MM-Strategy MCP serves the brand kit (`mm_brand_guide`); strategists install `@mutmutco/strategy` |
 
-This is MMI organization guidance, not Jerv or JervCode operating instructions.
-The plugin carries these files locally at its installed release version. Resolve current values
-and exact command flags through the live CLI; a bundled guide is not a live status report.
+This is MMI organization guidance, not Jerv or JervCode instructions. These bundled files match the
+installed plugin release; resolve current values and flags through the live CLI, not this guide.

package/skills/org-guide/references/domains-and-oauth.md

@@ -13,8 +13,8 @@ The Hub creates each registered host's proxied record during bootstrap and never
 one; check or re-run it with `mmi-cli devops runtime edge dns status|ensure <owner/repo> <stage>`.
 A dev or rc host also needs its advanced edge certificate: `mmi-cli devops runtime edge cert status|ensure <owner/repo> <stage>`.
 A dev stage is private only after its independent edge-block check succeeds. A configured record
-or successful deployment alone does not prove access control. Use [stage](../../stage/SKILL.md)
-for the supported private live workflow.
+or successful deployment alone does not prove access control. Use `mmi-cli devops runtime edge`
+and `mmi-cli devops runtime tenant status <owner/repo> dev` to verify the private dev edge.
 
 Inbound mail on `mutmut.work` is Hub-owned: Cloudflare Email Routing sends every address to MM-Work's
 inbound mail Worker, which delivers to the owning module. A product never adds MX records or routing

package/skills/org-guide/references/work-and-releases.md

@@ -34,7 +34,50 @@ capabilities for every design task. Work on the live app; use our own MM Artifac
 for owner choices, with live kit pieces and recorded choice ID / owner-decision reference.
 Functional browser journeys remain opt-in `workflow_dispatch`-only, never design checks or gates.
 
-Impeccable **v4.7.0 / engine v0.1.16** workflow:
+## The MM Open Design System Bible (#8837, #8839)
+
+This is the bible for the MM open design system: every agent doing UI, design, document or MM
+Artifact work reads it first and treats it as second nature. Part 1 says how the system is built and
+used; Part 2 says how agents improve it when it fails them; Part 3 governs A/B choosing architecture
+and viewer behavior.
+
+### Part 1 — The five pillars of the MM Open Design System
+
+Owner ruling 2026-10-25 (#8837, MM-Work#7668): the stage skill is retired completely. UI and
+design work follows one harmonized **Front-Loaded Impeccable v4.7.0 + MM Artifacts + Live Docs
+(`Canlı belgeler`) + Atomic Design Kit (`@mutmutco/mmwork-ds`)** workflow:
+
+- **Front-load Impeccable** before any UI or MM Artifact authoring: `impeccable context --target <path>`,
+  `DESIGN.md` plus its `design.json` sidecar in `.impeccable`, shared `.impeccable/config.json`
+  (`hook.enabled: true`), `reference/craft-floor.md` + `reference/operate.md`, and
+  `impeccable detect --json <target>`.
+- **MM Artifacts** (local/canvas packs in the `mm-artifact` v3 format) use one command:
+  `node artifacts/review/review.mjs <folder> --standalone [<out.html>] [--open]`. It runs `check.mjs`,
+  `check-ui.mjs` and `geometry.mjs`, pre-renders the board in `node:vm` via
+  `ReactDOMServer.renderToStaticMarkup` into `#root`, runs `impeccable detect --json` on that
+  SSR-rendered HTML, and opens the result in the browser with `--open`.
+- **Live Docs** (`Canlı belgeler` viewer) carry the living references, including the live
+  design-system artifact `3a5c79df-5274-40ad-a1b5-a75e67a74dac`.
+- **Atomic Design Kit** (`@mutmutco/mmwork-ds`): kit pieces and tokens only, checked with `mmwork-check-ui`.
+
+How the five pillars fit together (owner, 2026-10-25):
+
+| Pillar | What it is | Claude / industry analogy | Where it lives |
+|---|---|---|---|
+| **1. MM Artifacts (`mm-artifact`)** | The HTML artifact file format (`type: 'document' \| 'canvas' \| 'design-system'`). By default a single self-contained HTML artifact; a multi-board Canvas only when comparing A/B options or viewport sizes side by side. | Claude Artifacts (the HTML artifact itself) | Local `.html` / `artifact.json` during agent dev (opened straight in the browser); stored in Live Docs when shared or created by Junior. |
+| **2. Design System Artifacts (`type: 'design-system'`)** | MM Artifacts stored in Live Docs that define a complete visual system (tokens, CSS, components, `DESIGN.md`). Every MM Artifact binds to one (`kit: { id, version }`). Includes (a) the MM-Work Atomic Design System (`3a5c79df`, MM-Work app and modules), (b) the Document/Editorial Design System (reports, checklists, decks, client documents), and future brand/client systems. | Claude Design Systems / theme packs an artifact pulls from on creation | Hosted in Live Docs (`Canlı belgeler`). Only the MM-Work app design system is also exported to npm (`@mutmutco/mmwork-ds`). |
+| **3. Live Docs (`Canlı belgeler`)** | The viewer, library, commenter and A/B picker inside the MM-Work app (`/documents/:id`), where people, Junior and agents view, comment on, version and share MM Artifacts. | Claude's Artifact viewer / workspace panel | Built into MM-Work (`web/src/documents/`, `src/documents.ts`). |
+| **4. Open Design Kit (`@mutmutco/mmwork-ds`)** | The npm package generated from `packages/mmwork-ds/source/` (the source of the MM-Work Atomic Design System), so MM-Work, the 10 suite modules and local app-UI MM Artifacts render real Atoms, Molecules, Organisms, Templates and Pages. | Published React/CSS component kit | `packages/mmwork-ds/source/` → `@mutmutco/mmwork-ds`, synced to Live Docs (`3a5c79df`) and all 10 module roots. |
+| **5. Impeccable (`v4.7.0`)** | The front-loaded design craft and quality engine (`impeccable context`, `craft-floor`, 15 playbooks such as `distill`, `typeset`, `layout`, `colorize`, `clarify`, `polish`, plus `impeccable detect --json` and `DESIGN.md`). Runs in front of every UI or MM Artifact creation so output is readable, well typeset, purposefully coloured and never AI slop. | Design director + mechanical UI linter | `.agents/skills/impeccable` + root `DESIGN.md` and the `design.json` sidecar in `.impeccable`. |
+
+Four owner decisions (2026-10-25T15:35:52Z):
+
+1. **Doc vs. app kit — add a Document Design System too.** Keep the MM-Work Atomic Design System (`3a5c79df-5274-40ad-a1b5-a75e67a74dac`) for MM-Work and module app UI (and as the fallback for now), and add a dedicated Document/Editorial Design System Artifact in Live Docs for reports, checklists, decks and client documents made by Junior or agents.
+2. **Where to save — local HTML for dev, Live Docs for shared.** Coding agents build and open local `.html` MM Artifacts (`node artifacts/review/review.mjs <folder> --standalone [<out.html>] [--open]`) for fast iteration, and publish to Live Docs only for a shared deliverable, an A/B decision canvas or a Design System. Junior inside MM-Work saves directly to Live Docs.
+3. **Artifact shape — single HTML by default, Canvas for A/B.** A single self-contained HTML view for documents, checklists and single-screen work; a multi-board spatial Canvas only for A/B choices or `1440`/`1024`/`390` side-by-side comparisons.
+4. **Kit binding — Live Docs hosts kits; npm only for MM-Work.** Every Design System Artifact in Live Docs stores its tokens/CSS/components and `DESIGN.md` so any HTML artifact can bind to it (`kit: { id, version }`); only the MM-Work app design system is also exported as `@mutmutco/mmwork-ds`, because the MM-Work app and the 10 suite modules compile against it.
+
+Impeccable **v4.7.0 / engine v0.1.16** details:
 
 - Boot once: `impeccable context --target <path>`; `init` captures PRODUCT.md, `document` maintains
   `DESIGN.md` and its `design.json` sidecar, `impeccable doctor --json` reports drift, and `extract`
@@ -58,6 +101,83 @@ Impeccable **v4.7.0 / engine v0.1.16** workflow:
   installer; do not modify shared skills from a module task. Record command + exit + findings,
   kit version and available checks separately from contract identity; reports are not conformance.
 
+Craft essentials every agent applies (owner, 2026-10-25, #8839):
+
+- **Rich module colour and frosted glass — never graywashed.** Give surfaces purposeful module
+  tones (`blue`, `coral`, `teal`, `purple`, `terracotta`, `green`, `pink`, `lime`, `cyan`, `magenta`,
+  `fuchsia`) through kit props: `Card` (`tone`, `icon`/`mark`, `edge="bite"`), `Badge`, `Mark` and
+  `Checkbox` (`lead`). The kit backs them with `--card-tint-dark: 34%`, `--card-tint-light: 22%`
+  and `--card-blur`; never override these tokens locally or flatten a module to gray.
+- **Front-loaded Impeccable v4.7.0, in front of creation.** Run `impeccable context --target <path>`,
+  read `DESIGN.md` and `reference/craft-floor.md`, choose the surface mode (`Operate`, `Read`,
+  `Persuade` or `Experience`) and load the matching playbooks (`shape`, `distill`, `typeset`,
+  `layout`, `colorize`, `clarify`, `polish`, `harden`, `adapt`) before writing markup.
+- **Restraint and hierarchy.** Group related items into clean section `Card`s (`heading: 2` under
+  the page `<h1>`), keep main-column rows concise (`Cluster` with `fill` = `Checkbox` plus one
+  trailing action), and put multi-line inspector detail in the right-hand `HelperCard` as `Stack` +
+  `Text` — never `DataList`, which clips multi-line prose. No walls of text.
+- **Verify the SSR pre-rendered HTML.** `impeccable detect --json` is blind on an unrendered
+  `<div id="root"></div>` file, so verify the output of `review.mjs <folder> --standalone --open`,
+  which pre-renders the board into `#root` first. An empty `#root`, missing fonts or an unrendered
+  detector run is a failed check, not a pass.
+
+### Part 2 — The System-First Autolearn Doctrine (never work around a broken tool in `tmp/`)
+
+Owner ruling 2026-10-25T15:41:41.360Z (#8839): agents learn from their work, mistakes and
+discoveries with the MM open design system and improve the system wherever they can, instead of only
+fixing the current situation. Never patch the moment in `tmp/` and leave the shared system broken.
+If creating, bundling, rendering, checking or opening an MM Artifact or a design-kit change needs a
+custom script in `tmp/`, a patch around a bundler regex, manually inlined fonts, or locally overridden
+broken tokens, that is a **system defect, not a local task**.
+
+The immediate three-step system upgrade reflex:
+
+1. **Step A — fix the shared system at its source.** File or claim an issue, or message the owning
+   suite seat (Design Lead, MM-Work, Jerv-JervCode, MMI-Hub, Jerv-Hub), so the shipped CLI, bundler,
+   token, component or skill is fixed in its repository and no agent ever needs the workaround again.
+   A temporary workaround may unblock the task only when it is named as such and linked to that issue.
+2. **Step B — record it in the autolearn queue** (`jerv_learning_note` in JervCode, or
+   `mmi-cli learning skill-lesson --skill <name> --title <summary> --body-file <path>`): the exact
+   friction and its root cause, so autolearn turns it into a durable doctrine, code or skill fix.
+3. **Step C — record it in Hindsight memory** (`hindsight_ingest_document`): the root cause and the
+   permanent system fix, so every later session recalls it automatically.
+
+Autolearn watches design and artifact work for these signals and escalates each into a shared
+toolchain, kit or skill improvement: ad-hoc build/render/verify scripts under `tmp/`, empty `#root`
+renders, missing fonts, unrendered `impeccable detect` runs, geometry or layout regressions,
+graywashed or untinted surfaces, verbose walls of text, and skipped front-loaded `impeccable context`
+or playbook passes. Reflect after each design task: what would have made this easier for the next
+agent, and is that improvement filed?
+
+### Part 3 — A/B Choosing Architecture & Viewer Rules (owner ruling 2026-10-25T15:57:26.199Z, #8841)
+
+Settled owner ruling: present clear, distinct choices in the existing MM Artifact viewer, not a
+"shell over a shell". These are authoring and viewer requirements, not proof of installed capabilities.
+
+1. **No "shell over a shell" — designer agents build only the alternatives, never their own A/B switcher.**
+   The outer MM Artifact viewer (the local review shell and `CanvasStage` / `CompareView` in Live Docs)
+   already IS the A/B selector shell: it renders the question prompt, Option A / Option B / Neither
+   buttons, notes and board switcher. A `designer` subagent must **NEVER** draw an A/B picker,
+   question header, option cards or a gallery of tiny `ThemePreview` thumbnails inside a board.
+   **One A/B decision = one page with two full-resolution live HTML boards:**
+   - `board-a`: the actual full-size (`1440x900`) live MM-Work screen rendered in **Option A**
+     (for example, Linear Dark).
+   - `board-b`: the exact same full-size (`1440x900`) live MM-Work screen rendered in **Option B**
+     (for example, Apple Black).
+   Never pack multiple themes or multiple options onto a single board.
+2. **Compare the live HTML artifacts directly — never screenshots or low-res thumbnails.**
+   Both options are live, vector-sharp HTML/CSS/React artifacts rendered from `@mutmutco/mmwork-ds`,
+   never raster PNG screenshots or shrunken preview cards. The A/B viewer must let the owner inspect
+   Option A and Option B side-by-side or toggle 1:1 at full crisp resolution, so subtle palette,
+   contrast and typography differences (such as Linear Dark vs. Apple Black) are immediately clear.
+3. **Content-only zoom — zoom the artifact content, never the outer A/B shell.**
+   In the local review viewer and Live Docs (`CanvasStage` / `BoardBridge`), `wheel` events
+   (including `ctrlKey` / `metaKey` pinch-zoom) and keyboard zoom (`Ctrl/Cmd + +/-/0`) on both the
+   outer review shell and inside board iframes (forwarded via `postMessage`) must call
+   `preventDefault()` and zoom **only the artifact canvas/board viewport**. `Ctrl + Mousewheel` and
+   viewer zoom controls must keep the outer A/B selector shell, question bar and controls at a fixed
+   1:1 UI size.
+
 ## Documentation preflight
 
 Before each push or PR, follow this order:
@@ -130,7 +250,7 @@ development. A trunk repository follows its single branch and declared workflow
 - Vercel-hosted repos (registry `deployModel: vercel`) keep their track (direct or full): the push to
   main is the go-live, Vercel deploys each branch itself, and the train waits for that deploy and checks
   the live URL before it announces; on full track rcand does the same for the rc deploy. No version-file
-  bump on these repos. Every branch has a Vercel preview URL; [stage](../../stage/SKILL.md) reports it.
+  bump on these repos. Every branch has a Vercel preview URL reported by the Vercel GitHub app deployment status.
   No box stage.
 - Trunk track: one main branch, without an rc/development promotion train. Follow the repository's
   declared publishing workflow rather than manufacturing train branches.
@@ -166,7 +286,6 @@ Developers need no AWS CLI, AWS identity, or copy of the shared bot key. Keep a
 summary for the supported resume path. A delivery-unknown response requires checking the existing
 message; never resend blindly. Confirmed delivery is recorded per repository and release tag.
 
-For local or private live testing, read [stage](../../stage/SKILL.md).
 For a new product repository, use [bootstrap](../../bootstrap/SKILL.md).
 
 ## Hosting and deploy models

package/skills/stage/SKILL.md

@@ -1,55 +0,0 @@
----
-name: stage
-description: Run a local test stage or personal cloud dev stage with --live.
----
-
-**Host-native invocation:** Claude `/mmi:stage` · Codex `$mmi:stage` · jervcode `/stage` · Hermes skill_view. A backticked `/name` in this doc names the matching workflow (this skill or a sibling), not a literal command.
-
-# /stage — local test environment
-
-A throwaway **local** environment (dev server or local stack, plus Playwright where used) for the current branch. Off the promotion train: no version effect, no deploy. It lives in a gitignored workspace, force-kills the previous stage in this worktree before starting, and is decommissioned when done.
-
-`/stage` is the normal path for previews, smoke tests and Playwright targets; a request to run or preview the app is enough to start it. A manual dev-server command is fine for a bounded diagnostic or a requested bypass; say why. If the stage path fails, diagnose from `mmi-cli stage --json`, `tmp/stage/state.json` and process/port/container evidence, and file Hub/org-default friction instead of silently working around it.
-
-A `tenant-container` repo with `docker-compose.yml` and a Hub registry `portRange` needs no committed config: `mmi-cli stage` derives `docker compose build --no-cache`, `docker compose up -d`, a free port from the range, and the local URL (e.g. `http://127.0.0.1:3700/`). Board, deploy, secret and project facts live in the Hub registry, not a repo file. For vault/env passthrough or build-time secrets, read [reference.md](reference.md).
-
-## Step 0 — inspect the plan
-
-```bash
-mmi-cli stage --json
-```
-
-`source` is `derived`/`local`/`none`; when derived, `url` is the local URL. `none` means no usable recipe or derivable default; the message names the missing fact (deployModel, `docker-compose.yml`, or registry `portRange`; `.env.example` is not required). A missing `portRange` adds `recovery` with `mmi-cli stage port-range <owner/repo>`: assign the block, re-run `/stage` (the Hub registry itself is fine; stage just cannot pick a collision-safe port).
-
-On `deployModel: vercel` the receipt carries `preview` (latest Vercel Preview `state`, `url` from GitHub Deployments); report that URL as the branch preview. No `preview.deployment` = branch unpushed or Vercel GitHub app not connected. There is no box stage on vercel: `--live` refuses.
-
-## Step 1 — run
-
-A stage is per worktree: the CLI stops this worktree's previous stage, runs `stage.build`, starts `stage.up`, records `tmp/stage/state.json` (cwd, branch, commit), picks a free port from the registry range (skipping sibling worktrees' ports), and polls `stage.healthUrl` if set. Sibling worktrees keep their own stages; no need to stop one first. Recipes run in Bash (Git Bash on Windows, or an absolute `SHELL` path to its `bash.exe`; no cmd fallback), so convert `set VAR=value` or `$env:VAR` recipes to Bash or Node. For `jervaise`, continuity keys on branch; use a distinct North Star slug per parallel grind.
-
-```bash
-mmi-cli stage run --apply
-mmi-cli stage run --apply --port 5180            # pin a port
-mmi-cli stage run --apply --timeout-ms 120000    # slow stacks
-```
-
-All artifacts (build output, traces, local DB files) stay under untracked `tmp/stage/`. 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
-
-```bash
-mmi-cli stage stop --apply
-```
-
-Stop when work is done, before switching context, or before another stage; leave it up if the user wants the preview, and report that. For the Docker Compose default, stop runs `docker compose down` from the original working directory, re-fetching the declared dev runtime secrets so `${POSTGRES_PASSWORD:?}` and `${PORT:?}` interpolate (secrets never come from the state file); a vault-native repo with no `.env` gets `PORT` defaulted to the bound port.
-
-For a personal cloud dev stage (`--live`), read [live.md](live.md) before offering, applying or tearing it down.
-
-## Step 3 — report
-
-Stage URL, what's running, workspace path (`tmp/stage/`), teardown command. For Playwright output placement, extra services, or stale Docker/env troubleshooting, read [reference.md](reference.md) Notes.
-
-## Retro
-
-If this skill's instructions misfired (process only, e.g. a teardown that left a port bound), file one lesson (one per run; if the call fails, note it and continue):
-`mmi-cli learning skill-lesson --skill stage --title "<what misfired>" --body "<what; evidence; proposed amendment>"`

package/skills/stage/live.md

@@ -1,34 +0,0 @@
-## /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

@@ -1,98 +0,0 @@
-**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`.
-
-
-
-## Detail moved from SKILL.md (verbatim)
-
-The stage recipe is the **registry-derived default** for plumbing-free product repos: a `tenant-container`
-repo that ships `docker-compose.yml` and has a Hub registry `portRange` needs **no committed config**.
-`mmi-cli stage` derives a default compose stage — run `docker compose build --no-cache`, run `docker compose
-up -d`, choose a free port from the registry range, and report the local URL (e.g. `http://127.0.0.1:3700/`).
-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.
-
-The JSON reports `source` (`derived` / `local` / `none`) and, when derived, the local `url`. `source: none`
-means neither a usable local recipe nor a derivable default exists — the message names the missing fact
-(deployModel, `docker-compose.yml`, or registry `portRange`; `.env.example` is **not** required — #2655).
-On a `deployModel: vercel` repo the receipt also carries `preview` — the current branch's latest
-Vercel **Preview** deployment (`state`, `url`) read from the GitHub Deployments the Vercel GitHub app
-posts — and the text output ends with a `vercel preview (<branch>)` line. Report that URL as the branch
-preview alongside the local stage; no `preview.deployment` means the branch was not pushed yet or the
-Vercel GitHub app is not connected. There is no box stage on a vercel repo: `--live` refuses.
-When the gap is a missing Hub registry `portRange`, the JSON receipt also carries `recovery` with
-`mmi-cli stage port-range <owner/repo>` (#5539) — assign the block, then re-run `/stage`. That gap does not
-mean the repo's Hub registry/org project setup is missing; it means local stage derivation cannot pick a
-collision-safe port until META.portRange exists.
-
-A stage is **per worktree**. The CLI force-stops only the previous stage **in this worktree**, runs
-`stage.build`, starts `stage.up`, records `tmp/stage/state.json`, picks a free port from the registry
-range (skipping ports reserved by sibling worktrees), and polls `stage.healthUrl` when configured.
-Recipes run in Bash, including Git Bash on Windows. Use Bash syntax for build, up and teardown;
-legacy cmd `set VAR=value` and PowerShell `$env:VAR` recipes must be converted to Bash or Node scripts.
-Windows requires Git Bash or an absolute `SHELL` path to its `bash.exe`; there is no cmd fallback.
-Use `--port` to pin a port when needed:
-
-```bash
-mmi-cli stage run --apply
-mmi-cli stage run --apply --port 5180
-```
-
-A local stage is bound to the worktree that started it. Concurrent worktrees on one machine each keep
-their own stage on separate ports — you do not need to stop one before starting another. For `jervaise`, continuity
-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.
-
-Stop the stage when the work is done, before switching context, or before replacing it with another stage.
-If the user clearly wants the preview to stay up, leave it running and report that. The next `/stage` also
-stops the previous recorded stage before starting, so a stale server does not linger between runs. For the
-registry-derived Docker Compose default, stop also runs the recorded compose teardown (`docker compose down`)
-from the original stage working directory. Stop re-fetches the declared dev runtime secrets so that `down`
-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.

package/skills/stage/smoke.md

@@ -1,17 +0,0 @@
-### 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.
-