@mutmutco/pi-plugin 4.6.3 → 4.6.4

package/skills/org-guide/references/design.md

@@ -0,0 +1,301 @@
+# Design and MM Artifacts
+
+Read this before any UI, design, document or MM Artifact work. It was split out of the work-and-releases topic (#9460); the rulings below keep their original dates and wording.
+
+Owner ruling 2026-10-25 (#8814, #8816, MM-Work#7629; `docs/decisions/2026-10-06-browser-checks-nightly.md`):
+the required `gate` holds fast deterministic checks only; UI/design uses `@mutmutco/mmwork-ds`
+(`mmwork-check-ui`) and the mandatory Impeccable skill/toolkit. Inspect all applicable toolkit
+capabilities for every design task. Work on the live app; use our own MM Artifacts A/B canvas only
+for owner design choices, with live kit pieces and recorded choice ID / owner-decision reference.
+A canvas is for how something looks or works on screen only (#8986, relay wording): approvals for
+keys, releases, deletions, data access or tooling never go on a canvas; send them to the
+orchestrator, who asks the owner in plain words.
+Functional browser journeys remain opt-in `workflow_dispatch`-only, never design checks or gates.
+
+## The MM Open Design System Bible (#8837, #8839)
+
+Every agent doing UI, design, document or MM Artifact work reads this first: Part 1 builds the
+system, Part 2 improves it, Part 3 governs A/B choosing, Part 4 gates kit changes on visual A/B.
+Handoff and workaround notes cite this section by path and add only the task's own deviation,
+failure and action, never a restatement; new owner rulings are still recorded verbatim.
+
+### 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>`. It runs `check.mjs`, `check-ui.mjs` and
+  `geometry.mjs`, pre-renders the board in `node:vm` via `ReactDOMServer.renderToStaticMarkup` into
+  `#root` and runs `impeccable detect --json` on that SSR-rendered HTML. Interactive owner A/B
+  reviews use the live loopback HTTP review server (`http://127.0.0.1:<port>/`), where the owner's
+  `Send answers` posts back to `POST /answers`; a seat must not open the owner's browser. An A/B is
+  shown as the live canvas link, never as prose (#8987, relay wording). Once the canvas passes review,
+  send the orchestrator only the review URL and issue number, and keep the server running until the
+  owner answers. A kept-alive canvas review server must stay light (no dev/watch build pinning
+  gigabytes); a seat whose canvas needs a heavy local server flags that to the orchestrator instead
+  of holding the RAM silently, and stops it as soon as the owner has answered. The orchestrator opens
+  it on the owner's screen. `--standalone [<out.html>]` is only
+  for offline HTML previews/exports and SSR pre-render verification, never for an interactive owner
+  decision.
+  **Headless seat rule:** `--open` is review.mjs-only; never pass `--open` to `vite`, and never use it from a seat to open the owner's browser for an A/B review.
+  Vite parses its value as a URL path, so `vite --open false` opens the owner's real browser at `/false`;
+  run dev/preview servers with `BROWSER=none` and no `--open` flag.
+- **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 local `.html` MM Artifacts for fast iteration. For interactive owner A/B reviews, serve the canvas on the live loopback HTTP review server (`http://127.0.0.1:<port>/` with `Send answers`) without opening the owner's browser; relay the URL and issue number to the orchestrator and keep the server running until the owner answers (#8987, relay wording). A kept-alive canvas review server must stay light (no dev/watch build pinning gigabytes); a seat whose canvas needs a heavy local server flags that to the orchestrator instead of holding the RAM silently, and stops it as soon as the owner has answered. Use `node artifacts/review/review.mjs <folder> --standalone [<out.html>]` for offline HTML previews/exports or SSR pre-render verification. 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:
+
+- Impeccable is invoked as the installed script at `~/.agents/skills/impeccable/scripts/impeccable` or
+  bare `impeccable` on `PATH` — no Impeccable CLI is published on npm, so never run
+  `npx @impeccable-style/cli ...` (it 404s) or chain `npx` guesses into git/bootstrap commands (#8885).
+  Refresh the local kit cache through MMI-Hub `scripts/kit-adopt.mjs`'s `refreshKitCache({ mmWorkRoot, cacheRoot })`
+  (#9271, #9279). It runs `node "<absolute-MM-Work-root>/scripts/sync-design-system.mjs" "<absolute-MM-Work-root>/packages/mmwork-ds/source" --out "<staging-dir>"`
+  (the source argument is required, #8887) into a staging dir inside the cache root, then publishes that output to
+  `<cache-dir>/<version>/`, `<cache-dir>/latest/` and `version.json`, which is what `scripts/kit-adopt.mjs --local-dir`
+  reads. Run the sync yourself only into such a staging dir: `--out` alone writes the generated files flat and writes no
+  `package.json`, so a bare `--out "<cache-dir>"` fills a cache `--local-dir` cannot resolve. The cache dir is the machine
+  cache `~/.jerv/cache/mmwork-ds`. Never run the two-argument form: without `--out`
+  the sync writes the nine generated kit files and `sync.json` into the MM-Work working tree, where they are
+  post-merge bot output, MM-Work's lane guard refuses a commit touching them, and a lane that already ran it cleans
+  up with `git checkout -- packages/mmwork-ds`. Never commit those files (#9271). Resolve and verify the checkout as described under
+  [shared support-script invocation](#shared-support-script-invocation). A local `npm ci` against `npm.pkg.github.com` that returns
+  `E401` needs the GitHub Packages credential, never the npm one: the Jerv vault key `GH_PACKAGES_READ_TOKEN`, used keyless
+  (`jerv-cli vault use GH_PACKAGES_READ_TOKEN -- sh -c 'NODE_AUTH_TOKEN="$GH_PACKAGES_READ_TOKEN" npm ci --prefix module'`),
+  or your own `gh` login when it carries `read:packages` (`NODE_AUTH_TOKEN=$(gh auth token) npm ci --prefix module`); the
+  org `npm/NPM_TOKEN` belongs to `registry.npmjs.org` and returns `E401` here. Or adopt credential-free
+  with `mmi-cli devops packages adopt-export` (`docs/Guides/package-adopt-export.md`, #8886). To probe a kit
+  version, read the pin from the consumer's module/`package.json` (or `node_modules/@mutmutco/mmwork-ds`); a bare
+  `npm view @mutmutco/...` asks the public registry only and 404s, because the scope lives on GitHub Packages (#9238).
+  A registry read needs the registry flag and a token: in a consumer whose `.npmrc` maps the scope,
+  `NODE_AUTH_TOKEN=$(gh auth token) npm view @mutmutco/mmwork-ds@<v> version --registry https://npm.pkg.github.com`;
+  from a root without that line, pass the token directly —
+  `npm view @mutmutco/mmwork-ds@<v> version --registry https://npm.pkg.github.com --//npm.pkg.github.com/:_authToken=$(gh auth token)`.
+  To see **which** kit versions are actually published, run MMI-Hub's
+  `node scripts/kit-adopt.mjs --list-versions [--limit 5] [--json]` (#9426) instead of deriving it: it reads GitHub
+  Packages `/orgs/mutmutco/packages/npm/mmwork-ds/versions` (newest first, falling back to `npm view` against
+  `https://npm.pkg.github.com` with `GH_PACKAGES_READ_TOKEN`/`NODE_AUTH_TOKEN`), reports the local cache's latest
+  version, and never hits the `registry.npmjs.org` 404 of a bare `npm view @mutmutco/mmwork-ds` (#9264). That is the supported listing read:
+  `mmi-cli devops packages` covers consumer adoption (`adopt-export`) only, so it never names a published
+  version — never carry the packages API as a stopgap.
+- 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`
+  identifies reusable candidates (kit additions still need the Design Lead). Read
+  `reference/craft-floor.md` before UI edits and `reference/operate.md` for app UI.
+- `impeccable hooks on` enables shared `.impeccable/config.json`; local overrides/consent belong in
+  ignored `.impeccable/config.local.json`. Tier 1 scans mechanical problems per edit; Tier 2 deep-scans
+  at turn-end `Stop` on supported hosts. Verify `hooks status` and host support, not config alone.
+  If automatic hooks are unavailable, run `impeccable detect --json <target>` manually on markup
+  files/directories (not CSS-only): **0 clean / 2 findings**. Unavailable or broken scans are not passes.
+- Dual-subagent `critique` keeps design assessment independent from detector evidence and persists via
+  `critique-storage`; disclose degraded runs. `audit` scores accessibility, performance, theming,
+  responsive design and implementation integrity 0–4 each (**20 points**). These evaluations are
+  agent playbooks, not standalone engine CLI verbs; still inspect the live result.
+- Pick relevant playbooks: `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard`, `layout`,
+  `typeset`, `colorize`, `animate`, `delight`, `overdrive`, `clarify`, `adapt`, `optimize` (15 names in
+  v4.7.0, despite the requested “14”). Do not apply conflicting playbooks blindly.
+- Iterate with `live` / `generate` (`live-generate`, `live-poll`, `live-server`); `serve-question`
+  supports choices, while owner A/B decisions use the MM Artifacts canvas.
+  Stop temporary servers. Check installed versions and approved upstream updates via the owning
+  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):
+
+- **Sleek translucent glass cards and zero GPU usage — never color-washed
+  (`2026-10-25T16:21:19.344Z`).** Cards use sleek, modern translucent glass material (neutral
+  translucent surface with a crisp glass rim, `--card-tint-dark: 0%`, `--card-tint-light: 0%`)
+  rather than color-washed card fills in any theme, and zero GPU-compositing blur or shadow
+  (`--card-blur: none`, `--card-blur-frost: none`, `--frost-see-blur: 0px`, `--glass-blur: none`,
+  `--card-shadow-dark: none`; never `backdrop-filter: blur(...)`). Module tones (`blue`, `coral`,
+  `teal`, `purple`, `terracotta`, `green`, `pink`, `lime`, `cyan`, `magenta`, `fuchsia`)
+  belong on `Badge`, `Mark`, `Checkbox` (`lead`), and card `icon`/`mark` accents (`edge="bite"`).
+- **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. For one page-spec module, run
+  `node scripts/design-pack-render.mjs --page-spec <spec.mjs>` (it SSR-renders `renderPage(ctx)` per
+  theme mode and runs `impeccable detect --json` on the HTML), or `node artifacts/review/review.mjs
+  <folder> --standalone` for a pack; never hand-roll an inline `node -e` SSR script, which evaluates
+  as CommonJS and fails on the spec's ESM `import` lines (#8876).
+
+### Shared support-script invocation
+
+Resolve shared support tools from their **known canonical checkout**, not the caller's module/worktree
+layout (#8890). Never guess `../../MMI-Hub/scripts/kit-adopt.mjs`: that can resolve to the
+`mmi-worktrees/MMI-Hub` container, not a checkout, or to a sibling branch without the script.
+
+1. Start with a known absolute MMI-Hub checkout/worktree path supplied by repository or host metadata.
+   If only a Hub task worktree is known, use `git -C "<known-Hub-worktree>" rev-parse --path-format=absolute --git-common-dir`
+   and `git -C "<known-Hub-worktree>" worktree list --porcelain` to identify its canonical/main checkout.
+   Git metadata is repository-specific: a module's common directory cannot locate MMI-Hub. If no Hub
+   checkout is known, ask for it; do not scan drive roots or traverse arbitrary parents.
+2. Verify the selected checkout's identity with `git -C "<absolute-Hub-root>" remote get-url origin`
+   (must identify `mutmutco/MMI-Hub`) and verify `"<absolute-Hub-root>/scripts/kit-adopt.mjs"` exists as
+   a file before invocation. If missing, stop and resolve the correct checkout/version; do not retry
+   sibling guesses or create a replacement script.
+3. Resolve each target/source independently to its intended absolute path. Invoke Node with separate,
+   quoted arguments, for example:
+   `node "<absolute-Hub-root>/scripts/kit-adopt.mjs" --local-dir "<absolute-module-root>" --version <kit-version>`.
+   For cache refresh, verify `<absolute-MM-Work-root>/scripts/sync-design-system.mjs`, then
+   pass the absolute script path, the absolute `packages/mmwork-ds/source` path and `--out "<absolute-cache-dir>"`
+   as shown above: the generated kit files and `sync.json` land in the cache, never in the MM-Work checkout (#9271).
+   These are path patterns, not literal host paths; keep machine-specific roots out of bundled docs.
+
+Verify paths before chaining unrelated operations such as a board claim. Path resolution grants no
+new authority: use only the tool mode and target already authorized; never replay a successful claim
+just because a later script failed to load.
+
+### 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.
+
+**Canvases carry design choices only (#8986, relay wording).** An A/B canvas asks how something
+looks or works on screen. Approvals for keys, releases, deletions, data access or tooling never go on
+a canvas: send them to the orchestrator, who asks the owner in plain words.
+
+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.
+
+4. **A recorded owner answer is decided state — read it back, never re-ask (owner ruling, #9259).**
+   An answer the owner already gave on an A/B canvas is durable decided state, not a pending question.
+   Before re-presenting or re-asking any A/B choice, read the recorded answer — `answers.json` in the
+   canvas folder plus the canvas choice ID Part 4 Stage 2 says to record — and when a canvas is reopened,
+   rebuilt or replaced, carry that pick forward and show the board as already answered. Never tell the
+   owner he has not picked while a recorded pick exists: a decided board reads as decided, naming where
+   and when it was chosen, and the work proceeds instead of stalling behind a closed question.
+
+### Part 4 — Visual A/B Choice via Designer Subagent Before Kit Implementation — Never Prose Specs (owner ruling 2026-10-25T16:29:46.339Z, #8844, #8846, #8848)
+
+Settled owner ruling (verbatim): "You should use a designer to create a couple card designs with my
+specifications and then let me choose then build the complete spec into the design system, replacing
+any other card available atomically. That's the proper way to do it. Learn from this mistake of yours,
+requests like this should follow this structure, not prose guide."
+
+1. **Never reply with a prose specification in chat or jump straight to kit implementation.**
+   When the owner asks to "design the spec for X and add it to the design system" (for example, The One
+   Card), writing a markdown or prose spec in chat violates Principle 7 ("Choices for Jervaise go only
+   on the A/B canvas"). Building one guessed design straight into the kit skips the owner's choice.
+2. **Always follow the visual spec pipeline:**
+   - **Phase 0 — Inspiration via front-loaded Impeccable v4.7.0 and 21st.dev MCP (`https://21st.dev/api/mcp`) only (owner ruling 2026-10-25T21:37:00+03:00, #8854; superseding #8848).**
+     Before building visual A/B boards, use front-loaded **Impeccable v4.7.0** alongside **21st.dev MCP**
+     (`https://21st.dev/api/mcp`; verbatim owner ruling: `"we don't need the mcp better design yet,
+     impeccable and 21st is enough"`, dropping Better Design MCP) to study high-craft reference patterns,
+     layout proportions, and interaction details. Always translate inspired patterns into zero-GPU
+     `@mutmutco/mmwork-ds` tokens (`--card-blur: none`, `--card-tint-dark: 0%`, `--card-tint-light: 0%`,
+     sleek translucent glass cards) and Atomic Design layers; never copy raw third-party CSS/HTML or
+     GPU-heavy effects. `MM-Inspo` is strictly a customer/tenant module inside the MM-Work suite, never
+     an internal tool for designing the MM-Work app or its design system.
+   - **Stage 1 — a designer subagent builds visual A/B alternatives on an MM Artifact canvas.**
+     Dispatch a `designer` subagent with front-loaded Impeccable (`impeccable context`, `craft-floor`,
+     `distill`, `typeset`, `layout`, `colorize`, `polish`) to create 2–3 genuinely distinct visual
+     designs that honor every constraint in the owner's brief: Option A, Option B and optionally
+     Option C, each its own full-resolution `1440x900` live HTML board in one MM Artifact A/B canvas
+     (Part 3 rules: content-only `Ctrl + Mousewheel` zoom, 1:1 or side-by-side live comparison). Serve
+     the verified canvas on the live loopback HTTP review server without opening a browser from the
+     seat, so the owner's `Send answers` posts straight back to `POST /answers`. Once review passes,
+     send the orchestrator only the review URL and issue number, and keep the server running through
+     Stage 2; the orchestrator opens it on the owner's screen (#8987, relay wording). Never open a
+     `--standalone` `file://` export (`Download answers.json`) for an
+     interactive owner A/B decision: `--standalone [<out.html>]` is only for offline previews/exports
+     and SSR detector checks. Spawn a dedicated, fresh
+     `designer` subagent for each distinct design task (item 3); never reuse a busy designer seat.
+   - **Stage 2 — the owner chooses visually on the A/B canvas.** Wait while the owner inspects the
+     live HTML alternatives, zooms into details and picks the preferred design or asks for
+     adjustments, then presses `Send answers` on the live review server page; `review.mjs` writes
+     `answers.json` into the canvas folder and exits. Record the canvas choice ID and the
+     owner-decision reference.
+   - **Stage 3 — atomic replacement in the kit source.** Only AFTER the owner picks on the A/B canvas,
+     build the chosen design into the source folder of packages/mmwork-ds in mutmutco/MM-Work,
+     **atomically replacing** every other legacy or competing variant of that piece across the design
+     system, publish it to `Canlı belgeler` / MM-Work, and propagate it to all 10 suite modules.
+3. **One dedicated `designer` subagent per distinct design task — never overload a designer seat
+   (owner ruling 2026-10-25T16:33:00Z, #8846).**
+   Settled owner ruling (verbatim): "The lead designer sent the card building to the same designer
+   agent, overloading it. I don't think it was a wise idea. Please learn from this."
+   Spawn a separate, fresh `designer` subagent in its own isolated lane for each distinct design task
+   or visual A/B canvas (for example, a theme A/B exploration vs. a unified Card spec A/B). Never steer
+   or queue a second unrelated design task onto an active `designer` seat: overloading one
+   `designer` subagent serializes work that should run in parallel, bloats its context window, and
+   degrades craft quality.

package/skills/org-guide/references/vault.md

@@ -3,14 +3,7 @@
 GitHub repository admins are project-admins on that repository without duplicate registry
 enrollment. Registry-listed admins with repository write access remain supported.
 
-The two tiers describe authority and blast radius, not separate storage products:
-
-- **Your project:** a project-admin can manage their own product's full vault tree, including
-  shared values and dev, rc, and main overrides. Production-stage names do not by themselves
-  require an organization master-admin.
-- **Organization infrastructure:** shared infrastructure secrets are master-admin managed.
-  Project access requires an explicit grant for the relevant names. A read grant permits
-  consumption, not rotation or deletion; do not assume a grant authorizes every operation.
+The two tiers (your own project's vault tree, and organization infrastructure that needs a master grant) and who may use each are defined once in the [secrets skill](../../secrets/SKILL.md); this topic does not restate them.
 
 Read `mmi-cli oracle org access role <owner/repo> --json` and
 `mmi-cli oracle org access capabilities` for your actual authority.
@@ -20,7 +13,7 @@ it does not require installing or querying a personal vault product.
 
 The registry catalog declares secret names before values are set. A shared, stageless value is
 the canonical default; a declared stage override wins for that stage. Avoid accidental duplicate
-copies that hide a rotation. Use `mmi-cli vault secrets catalog` and `mmi-cli vault secrets list`
+copies that hide a rotation. Use `mmi-cli vault secrets list` and `mmi-cli oracle org access capabilities`
 to inspect names and reach, never values.
 
 Consume through `mmi-cli vault secrets use <KEY> -- <command>`: the authorized child receives the