@mutmutco/codex-plugin 4.5.161 → 4.5.163

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/cli",
-  "version": "4.5.161",
+  "version": "4.5.163",
   "description": "MMI Future CLI — the org dev toolbox and shared cross-IDE engine for every registry-declared MMI coding surface.",
   "type": "module",
   "license": "UNLICENSED",

package/package.json

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

package/skills/board/SKILL.md

@@ -44,17 +44,7 @@ Refs are `[RepoName#N](url) · short title` — no `owner/` prefix, no `[type]`
 its essence. **Taken** renders id · status · owner only, never the title. Skip empty sections silently.
 One screen.
 
-> 👋 Welcome back, @dev — here's your board on **MMI-Hub**.
->
-> **On your plate** — two train fixes in flight:
-> - [MMI-Hub#834](https://github.com/mutmutco/MMI-Hub/issues/834) · automated hotfix apply path
-> - [MMI-Hub#841](https://github.com/mutmutco/MMI-Hub/issues/841) · rcand stuck on required checks
->
-> **Up for grabs** — nine open, I can take them in three PRs:
-> - [MMI-Hub#821](https://github.com/mutmutco/MMI-Hub/issues/821) · redesign tenant env-writer
->
-> **Taken**
-> - MMI-Hub#827 · In Progress · @otherdev
+For a rendering example, read [examples.md](examples.md).
 
 Status moves happen automatically as work flows — claim, PR open, merge. Never offer a status move.
 
@@ -114,9 +104,7 @@ the per-item results rather than assuming the batch took. **Route is `oracle boa
 no `oracle issue claim` and no flat `board claim` — both refuse. Guessing either burns a call.
 
 Then one worktree per batch, all batches concurrently. The host owns worktree mechanics; MMI owns board
-and PR facts. On Windows set `git config core.longpaths true` on the main checkout before the first
-`git worktree add` (#5499). Linked worktrees share one `.git`, so serialize `git branch -m` and other ref
-renames across them, or retry serially when the error names `.tmp-renamed-log` (#5485).
+and PR facts. For worktree setup on Windows or concurrent ref renames, read [reference.md](reference.md).
 
 ## Step 5 — land one PR per batch
 
@@ -141,12 +129,7 @@ Materialize the body as a real UTF-8 file and pass its path; do not pipe it to `
 When an issue must stay open, write `Part of #N` or `Refs #N`. **Never** write `Does not close #N` —
 GitHub closes it anyway (JC#495).
 
-A repo running a guidance-learning gate also needs the body's learning line PLANNED here, not patched in
-after a red check: when the batch's touch-set intersects that repo's guidance files (Jerv-JervCode:
-`product/soul.md`, `product/runbooks/**`, `packages/*/skills/**/SKILL.md`), the body must carry a
-standalone `learning: none — <reason>` line unless a closing learning issue's `promote.globs` names a
-changed file. The line must stand alone on its own newline — a literal `\n` inside an inline edit fails
-the gate again.
+When the repo runs a guidance-learning gate, read [reference.md](reference.md) before preparing the PR body.
 
 Landing requires a merged receipt before any cleanup: `state` `MERGED`, the head ref and OID matching the
 local task branch, and a clean worktree. Anything else means retain and report, never clean.

package/skills/board/examples.md

@@ -0,0 +1,12 @@
+> 👋 Welcome back, @dev — here's your board on **MMI-Hub**.
+>
+> **On your plate** — two train fixes in flight:
+> - [MMI-Hub#834](https://github.com/mutmutco/MMI-Hub/issues/834) · automated hotfix apply path
+> - [MMI-Hub#841](https://github.com/mutmutco/MMI-Hub/issues/841) · rcand stuck on required checks
+>
+> **Up for grabs** — nine open, I can take them in three PRs:
+> - [MMI-Hub#821](https://github.com/mutmutco/MMI-Hub/issues/821) · redesign tenant env-writer
+>
+> **Taken**
+> - MMI-Hub#827 · In Progress · @otherdev
+

package/skills/board/reference.md

@@ -0,0 +1,11 @@
+On Windows set `git config core.longpaths true` on the main checkout before the first
+`git worktree add` (#5499). Linked worktrees share one `.git`, so serialize `git branch -m` and other ref
+renames across them, or retry serially when the error names `.tmp-renamed-log` (#5485).
+
+A repo running a guidance-learning gate also needs the body's learning line PLANNED here, not patched in
+after a red check: when the batch's touch-set intersects that repo's guidance files (Jerv-JervCode:
+`product/soul.md`, `product/runbooks/**`, `packages/*/skills/**/SKILL.md`), the body must carry a
+standalone `learning: none — <reason>` line unless a closing learning issue's `promote.globs` names a
+changed file. The line must stand alone on its own newline — a literal `\n` inside an inline edit fails
+the gate again.
+

package/skills/bootstrap/SKILL.md

@@ -15,80 +15,7 @@ invoke the skill (the master holds the App key), not the caller's GitHub role.
 Bootstrap operates on the target repo entirely through the App — **no per-repo checkout**. The repo must
 already be named on the taxonomy `<CATEGORY>-<PascalName>`.
 
-## Seed sources + create-vs-upgrade
-
-The org-standard scaffolding is a **machine-readable manifest** — `skills/bootstrap/seeds/manifest.json`
-(loaded by the CLI; `mmi-cli devops bootstrap apply <repo> [--execute]` consumes it). Every seed carries an **ownership**:
-
-- **`org`** — org-delivered, **overwritten on upgrade** (the org owns it): the issue templates, the gate
-  workflow, and the org-managed `.gitignore` block. `source: self` = copied verbatim from MMI-Hub's own
-  current file. Personal **agent guides** (`AGENTS.md`/`CLAUDE.md`/`.claude/settings.json`) are **never**
-  seeded — they are developer-owned and gitignored, carried per machine by each developer's own plugins
-  (Jervaise's ride Jerv PowerTools), not delivered, overwritten, or fanned out by MMI; the org push ruleset
-  `mmi-no-agent-files-org` even blocks committing them. Board moves are central (the Hub webhook), so **no
-  per-repo board workflow is stamped**.
-- **`repo`** — created **once on a fresh bootstrap**, **never clobbered on upgrade** (the repo owns its
-  content): `README.md`, `architecture.md`.
-  These render `seeds/*.template.*` with `{{PLACEHOLDERS}}`.
-
-So **create** stamps every seed; **upgrade** refreshes the `org` seeds and adds any *missing* `repo` seeds
-without overwriting existing repo-owned files (D35: legacy docs are archived + written fresh, never carried
-over verbatim). The manifest's `labels` list is the canonical label set — three: `bug`, `feature`, `task`.
-Priority is a **board field**, never a label (#1454 retired the four `priority:*` labels; `bootstrap verify`
-checks they are gone). The per-step instructions below
-are the manual path; `bootstrap apply <repo> [--execute]` automates them from this manifest.
-For a registry-configured gate, use `mmi-cli devops bootstrap apply <repo> --only gate.yml --from-config`
-(dry-run) then add `--execute` to propose the file on a review branch + PR. This uses the same
-registry `gate` render as `ci reconcile`. An unstamped legacy gate must first match the registry
-render exactly; the first PR then adopts it by adding a hashed render stamp. After adoption, changing
-the registry config produces an update PR if the committed stamp still verifies. A stamped gate edited
-by hand, or a divergent unstamped gate, is refused with a diff: make the registry config reproduce an
-unstamped file first, then re-run to adopt. Edit the registry config, never the stamped file.
-
-**`bootstrap apply` is a single-repo tool** — fresh bootstrap/onboarding, or refreshing one repo's own
-drifted seed. It is **never** the fleet-wide fan-out for an `org`-owned seed edit: that write path is
-propagation from a Hub merge (#4233), and the seeded `agent-pr.yml` itself now fails the merge gate on
-any repo that receives a hand-edit to an org-owned target path outside a propagation/bootstrap-delivery
-branch (#4241). Running `apply --execute` against every registry repo by hand to fan out a Hub edit is
-exactly the copy-per-repo pattern this rule exists to end — see Hub#4234.
-
-**Rollback is per-repo, never a second fleet overwrite (#4240).** When a propagated `org`-owned seed
-breaks a repo, the recovery is `mmi-cli devops bootstrap rollback <repo> --target <t> [--execute]` — it resolves
-the ONE merge commit that repo's `bootstrap propagate` (#4238) run actually landed (live from the repo's
-`seed-propagate-<slug>` merged-PR history, or replayed from a persisted propagate `--json` report via
-`--record`) and opens an ordinary revert PR of it, through that repo's own gate, on a `seed-rollback-<slug>`
-branch. It refuses — never guesses a commit — when no clean, single-file propagation record resolves for
-that repo+target. **Explicitly forbidden as a rollback path: a fleet-wide `bootstrap apply --execute` of
-"the old bytes"** — that is the second blind fleet overwrite #4233 rules out, and it races the propagation
-lane. **MMI-Hub stays the source of truth during a rollback**: a per-repo revert is the emergency stop, not
-the fix — closure is the Hub reverting (or fixing forward) the bad seed commit on `development`, after
-which reverted repos match the Hub again and the drift alarm closes itself. A per-repo revert with no
-Hub-side follow-up re-alarms as drift within a week, deliberately, so an emergency divergence can never
-silently become permanent.
-
-**Release gap — a new topology value must reach TWO surfaces, and a local dev build only fixes one (#2928).**
-A new `--project-type`, `--deploy-model`, or `--release-track` lands on `development` but is not live until a
-release train ships it — in **both** of these places:
-
-1. **The published/installed `mmi-cli`**, which rejects the unknown enum with no hint that it merely lags
-   `development`. A local dev build routes around this:
-   `node <MMI-Hub checkout>/cli/dist/index.cjs bootstrap apply ...` from a `development` checkout (rebuild
-   `dist` first: `npm --prefix cli ci && npm --prefix cli run build`).
-2. **The deployed registry Lambda**, which carries its *own* copies of the enums
-   (`infra/src/registry-route.ts` validates `projectType` **and** `deployModel`; `releaseTrack` is CLI-side
-   only) and **deploys from `main`**. A local dev build does nothing for this one.
-
-So the local dev build is **not** a workaround for a just-merged enum value — it gets you further and then
-fails at the step that matters. The CLI cheerfully accepts the new value, sends it, and the API rejects it:
-
-```
-ddb register <slug> (failed: HTTP 400 — projectType must be one of:
-  web-app, hub-service, content, desktop-game, non-deployable, cli-tool, worker)
-```
-
-That failure lands **after** seeding, labels, and the ruleset, so the repo is left half-provisioned with an
-almost-empty registry META row. **Bootstrapping against a topology value merged since the last train requires
-a `/release` to `main` first.** The local dev build alone suffices only for values already live in the API.
+Read [reference.md](reference.md) when choosing create vs upgrade, refreshing seeds, rolling back propagation, or using newly released topology values.
 
 ## Step 0 — capability shape (confirm the four axes before any mutation)
 
@@ -154,336 +81,15 @@ acceptable end states (#2928):**
   section — GitHub's contents API lags for a minute or so right after a merge. **Re-run before believing a
   content-read failure**; it clears on its own.
 
-## Step 0b — create the repo (when it does not exist yet)
-
-If `$OWNER/$REPO` is not on GitHub yet, create it and seed an initial commit **before** Step 1 — a brand-new
-repo has no commits, so there is no branch to push and no default branch to set. **Create the first commit
-through the contents API, on every track** (#3655) — an API write is not a push, so neither the #1660
-protected-branch guard nor `mmi-train-floor` objects, and it is the same server-side mechanism Step 1 uses
-for `rc`/`main` (#3433). `$FIRST` is the track's first branch: `development` for **full**/**direct**,
-`main` for **trunk**:
-
-```bash
-FIRST=development     # full / direct
-FIRST=main            # trunk (content)
-
-# One-time namespace + first-ref creation uses the authenticated master-admin GitHub session. The current
-# mmi-cli has no App-backed command for a repository that does not exist; this is the named exception.
-gh repo create "$OWNER/$REPO" --private --disable-wiki
-gh api -X PUT "repos/$OWNER/$REPO/contents/.gitkeep" \
-  -f message="chore: initial commit" -f content="Cg==" -f branch="$FIRST"
-```
-
-`--disable-wiki` seeds `has_wiki=false` at creation: wikis are retired org-wide (compute-at-read, #4206),
-GitHub defaults new repos to `has_wiki=true`, and `bootstrap apply --execute` / `bootstrap reconcile --apply`
-enforce the same rule as drift checks afterwards.
-
-On an empty repo that PUT creates `$FIRST` **and leaves it the default branch**, so no `gh repo edit
---default-branch` is needed here. Skip this step when the repo already exists with the track's default branch.
-
-The two `gh` writes above are authorized by the authenticated master-admin login and are the one-time
-bootstrap exception while no App-backed `mmi-cli` command owns a repository that does not yet exist. They
-are not a general write lane: after the namespace and first ref exist, use the App-backed
-`mmi-cli devops bootstrap apply --execute` path for managed seeds, labels, rulesets, and registry state.
-
-For a **content** repo the API form is not merely tidier, it is the only thing that works: `main` is that
-track's first and only branch, so the initial commit IS a push to `main` and the #1660 guard fences it — and
-the deny's own advice ("land through a CI-gated PR to development") is meaningless on a repo with no commits,
-no `development`, and no CI (#3541).
-
-The old recipe here was a local `git init` + empty commit + `git push` for deployable repos, opening with
-`gh repo create --private --confirm`. **That flag no longer exists** — `gh` removed it, so the first command
-of the first step errored out. The local-git ritual it opened is also unnecessary: the API form above does
-the same job for `development` in one call.
-
-## Step 1 — branches
-
-Determine the repo's **release track** first — the branch set follows the track, not just the class (#1097),
-so a direct-track repo never gets a stray `rc` the `mmi-train-floor` ruleset can't clean up:
-
-- **full** (deployable default) — three permanent branches, default `development`: `development`, `rc`, `main`.
-- **direct** (deployable, skips rc — e.g. cli-tool/worker/Hub) — two permanent branches, default
-  `development`: `development`, `main`.
-- **trunk** (content) — one permanent branch, default `main`: `main` only.
-
-Ensure exactly the track's permanent branches exist and set the default branch — create only what the track
-uses; never create an `rc` for a direct-track repo.
-
-**`bootstrap apply --execute` creates `rc`/`main` server-side from the track's first branch (#6070).** The
-local **#1660 protected-branch push guard** fences every push to `main`/`master`/`rc`, including the
-legitimate *creation* of those refs on a brand-new repo (#3433); a ref created through the API is not a
-force-push, so both the guard and the `mmi-train-floor` ruleset allow it. The apply's train-readiness plan
-prints one `lane-branch` row per track branch — `CREATE` (missing), `SKIP` (already exists), or `GAP`
-(`bootstrap-gap`: the first branch from Step 0b is missing, so there is no source ref) — and the live apply
-creates every `CREATE` row; a `422 Reference already exists` reply is the idempotent no-op, not a failure.
-`development` (or `main`, for a content repo) already exists from Step 0b. Only the default branch stays a
-`gh` write:
-```bash
-gh repo edit "$OWNER/$REPO" --default-branch development   # full / direct
-gh repo edit "$OWNER/$REPO" --default-branch main          # trunk (content)
-```
-Verify with `gh api "repos/$OWNER/$REPO/branches" --jq '.[].name'`, or read the `lane-branch` rows of the
-next dry-run `bootstrap apply`.
-
-## Step 2 — authority (org Ruleset)
-
-Confirm the org-level rulesets already target this repo (they apply org-wide): **`mmi-branch-protection`**
-PR-gates `development` and blocks force-push/deletion there (bypass = org admins + the GitHub App 3026732),
-and **`mmi-train-floor`** blocks force-push/deletion on `rc`/`main` (no PR rule — the train pushes merges and
-tags directly; no bypass). (Definitions mirror live in `.github/rulesets/mmi-branch-protection.json` and
-`.github/rulesets/mmi-train-floor.json`.) MMI-Hub additionally has its own repository ruleset,
-`.github/rulesets/mmi-hub-required-checks.json`, for the Hub-only `cli`, `infra`, and `docs` jobs; do not
-apply those contexts org-wide unless every target repo exposes them.
-
-## Step 2b — lock the train branches (who can push)
-
-The ruleset says *a PR is required*; this says *who may merge it*. `bootstrap apply --execute` applies the
-classic branch protection on `development`/`rc`/`main` for deployable repos, or just `main` for content
-repos, with **"Restrict who can push"** = the org owners + the App (#6070): the owners are resolved live
-from the GitHub org admins (`orgs/$OWNER/members?role=admin`), never a hard-coded user list — an empty
-resolution refuses to write an empty allowlist — and the App is `mmi-github-app`. The repo's full-write
-people get added at Step 4b. Everyone else is `write`-locked on protected branches: they push feature
-branches and open PRs but cannot merge there.
-
-The plan prints one `push-allowlist` row per track branch — `UPDATE` (preserve every existing
-review/status/admin/force-push bit and replace only the push restriction), `SKIP` (exact owners + App
-already present), or `GAP` (`bootstrap-gap`: the protection read failed; zero writes are performed while any
-control-plane read is unverified). Only the master (sole repo `admin`) can change this afterward. Full
-grant/lock mechanics + inspect commands: `docs/Guides/repo-access.md`.
-
-## Step 3 — attach to the repo's Project (one board per repo; confirm)
-
-**One board per repo, named after it** — that is the convention the org actually runs, and what the rest of
-the system assumes: the registry META carries a single `projectId` per `PROJECT#<slug>`, and the Hub webhook
-adds each new issue to that one board. There are no division boards; a `<CATEGORY>`-prefixed default would
-resolve to nothing (#3542). Still **confirm with the master** — repos and projects are genuinely **not 1:1**,
-and joining an existing board remains a legitimate answer for a repo that belongs to an existing effort.
-```bash
-gh project list --owner "$PROJECT_OWNER" --format json   # existing boards to choose from
-```
-- **Attach** to the chosen project:
-  ```bash
-  gh project link "$PROJECT_NUMBER" --owner "$PROJECT_OWNER" --repo "$OWNER/$REPO"
-  ```
-- **Create** the chosen board if it doesn't exist yet — clone the **named template board**, never an
-  arbitrary existing one, so the 4-lane `Status` field (`Todo · In Progress · In Review · Done`), the
-  built-in workflows, **and** the org's view/card-field shape (#4093) all carry over instead of whatever
-  the previous copy-of-a-copy happened to drift to:
-  ```bash
-  gh project copy 4 --source-owner "$PROJECT_OWNER" \
-    --target-owner "$PROJECT_OWNER" --title "<Project>"
-  ```
-  **Project 4 (MMI-Hub's own board) is the template** (#4093) — it already carries the org-standard view
-  triple (`List`/`Board`/`Roadmap`), Board grouping (columns=Status, swimlanes=Repository), and the
-  canonical Board card-field set (`Title, Assignees, Status, Labels, Linked pull requests, Parent issue,
-  Sub-issues progress, Priority`). `bootstrap verify` asserts all three against every board (next note); a
-  freshly copied project starts green on them instead of inheriting a stale source's drift. Copying from
-  anything else re-introduces the "5 card-field variants across 16 boards" problem #4093 was filed to end.
-  Then **interview the master** for the seed short description + README (what it tracks, member repos, links
-  to the repos' `README.md`/`architecture.md`); set them via the `updateProjectV2` mutation
-  (`shortDescription`, `readme`). If cloning, verify the built-in workflows survived (next note).
-- **Built-in workflows:** `mmi-cli devops bootstrap verify` checks these Project workflows are enabled:
-  `Auto-add sub-issues to project`, `Auto-archive items`, `Item added to project`, and `Item closed`. The
-  Todo/In Progress/In Review moves are **central** (the Hub webhook); the built-in `Item closed` sets `Done`
-  on merge. GitHub's public GraphQL schema exposes delete/read surfaces for Project workflows but no
-  create/update/enable mutation; if any required workflow is missing or disabled, repair it in the project's
-  **Workflows** settings before calling the repo ready for developers.
-- **Board shape (#4093):** `mmi-cli devops bootstrap verify` also checks the view triple (`List`/`Board`/`Roadmap`
-  by name **and** layout), the Board view's grouping, and its card fields against the standard the template
-  board (project 4) carries. Grouping (columns=`Status`, swimlanes=`Repository`) has **no** GraphQL create/
-  update mutation (`ProjectV2ViewConfigurationInput` carries only `visibleFieldIds`) — a drifted swimlane or
-  column can only be fixed in the UI: Board view → ⚙ (top-right) → Group by / Swimlanes → Save view. The
-  view triple and the card fields (`Title, Assignees, Status, Labels, Linked pull requests, Parent issue,
-  Sub-issues progress, Priority`) ARE API-writable (`createProjectV2View`/`updateProjectV2View`), so a
-  drifted one can be fixed live instead of only reported.
-
-Record the chosen `projectNumber`/`projectId` plus Status/Priority field ids in the Hub registry META
-(`PROJECT#<slug>`) by re-running `mmi-cli devops bootstrap apply --execute` **after** `gh project link`. Apply reads
-the repo's linked board and derives all of them itself (#3543) — pass `--var PROJECT_ID=<node id>` only to
-override, which is also what you need when the repo is linked to more than one board and apply therefore
-refuses to guess. **Verify the row afterwards** (`mmi-cli oracle org project get <owner/repo>`): a registered repo
-whose META carries no `projectId`/`statusFieldId` looks finished everywhere else while the Hub webhook has
-nothing to move issues with, and `registry project board META exists` is the single check that says so. Going forward the thin Lambda adds each new issue to that project on `issues.opened` and sets
-`Status: Todo`.
-
-**Register the project in the Hub registry.** The same registry META row carries `{name, slug, projectId,
-repos[]}`; do not append to a committed `projects.json`. Repo wikis and doc freshness are owned by
-the repo itself. If attaching this repo to an existing project, merge this repo into that project's `repos[]`
-instead of creating a new project.
-
-## Step 4 — vault tiers + deploy substrate
-
-Provision the repo's vault namespace and deploy substrate from the Hub, not from repo-local Actions
-secrets. Runtime config names live in the two-tier vault (`/mmi-future/<slug>/dev|rc|main/*`) and are
-managed through `/secrets`; never use `gh secret set` for product runtime config.
-
-The default `tenant-container` substrate is a **Hetzner box** (`hetzner-ssh`): the deploy streams the stage's
-vault values into a tmpfs runtime env (no `.env` file) and runs the container via docker-compose, deployed over the Hub's bounded
-SSH lane. Do **not** create an AWS OIDC deploy role or a repo deploy Action for it. **Ask the master for the
-box assignment** — the `sshHost` (and the loopback port) per stage — then write the `DEPLOY#<stage>` rows with
-`mmi-cli oracle org project set-deploy <owner/repo> --stage <dev|rc|main> --ssh-host <host> [--port <p>]` (defaults:
-`substrate: hetzner-ssh`, deploy path `/opt/mmi/<slug>/<stage>`, service = slug, ssh-user `root`). Without those
-rows the tenant cannot deploy (`tenant-deploy.yml` errors on missing `DEPLOY#` coords), so do not skip this.
-`bootstrap apply` prints one `deploy-row` row per track stage for container models (#6070): `SKIP` when the
-registry row exists, `GAP` (`bootstrap-gap`) with the exact `set-deploy` command otherwise (for
-`tenant-container` it carries `--no-env-file true`, matching the fileless compose seed; run it from the tenant
-checkout once that compose is on the stage branch) — a box
-assignment cannot be invented, so this row is the one train-readiness fact the apply never writes itself.
-Keep every runtime config value in the vault; never paste secret values into logs.
-
-Only an AWS `tenant-container` (the exception) provisions the reusable tenant stack: release bucket,
-per-stage OIDC deploy role, and constrained service-control role/document. Either way the deploy path
-trusts the Hub's central `tenant-deploy.yml` / `tenant-control.yml` environments, not a product repo deploy
-workflow.
-
-## Step 4b — developer access
-
-**Repository Environments (#4458, plan-gating #5032)** — the track's deployment environments are
-control-plane state this skill's own `bootstrap verify` asserts, so live apply provisions them itself:
-`mmi-cli devops bootstrap apply --execute` creates `dev`/`rc`/`main` (per the release track: direct has no
-`rc`, trunk has `main` only) with a **deployment-branch policy = protected branches only** — the one
-protection the check exists to carry. On an org plan whose billing entitlement rejects protection rules
-(an explicit `wait_timer` or required `reviewers` comes back 422 naming the plan), apply provisions the
-settable policy and prints `plan-gated protections` for those rules; `bootstrap verify` then reports the
-environment rows as green with an `advisory:` detail naming what the plan cannot set — never a FAIL. The
-policy is set either way, so a repo on the lower plan is still protected and ready for developers.
-
-Grant each developer their **org membership + repo access** through the App (`gh api` with the App token):
-`write` for a developer; for a **full-write** member ("project-admin") also add them to the train-branch
-push allowlist from Step 2b (so they can merge protected development PRs). GitHub's
-collaborator list + the per-branch allowlist are the record — no separate roster. Exact commands:
-`docs/Guides/repo-access.md`.
-
-## Step 4c — CI trigger, labels, templates
-
-- **Enable workflow triggers** — a freshly-provisioned repo can have GitHub Actions auto-trigger stuck off
-  (push/PR never run workflows though dispatch does). Toggle it off→on:
-  ```bash
-  gh api -X PUT repos/$OWNER/$REPO/actions/permissions -F enabled=false
-  gh api -X PUT repos/$OWNER/$REPO/actions/permissions -F enabled=true -f allowed_actions=selected
-  ```
-- **Self-hosted CI is the org default** — the `mmi-automation` runner group is org-wide (all repos), so a
-  new repo needs no manual group join. Any CI workflow it adds uses
-  `runs-on: [self-hosted, linux, x64, mmi-live]` (never `ubuntu-*`/`windows-*`/`macos-*`, which bill
-  GitHub-hosted minutes); jobs needing system packages run in a `container:`. The runner has **six
-  concurrent job lanes** — independent checks belong in separate parallel jobs (each with its own
-  `runs-on`), never chained into one serial job or throttled with unneeded `concurrency` groups. See
-  `docs/Guides/gh-runner-runbook.md`.
-- **Product gate + required checks (#1333, stack-aware #1550)** — deployable repos bootstrap-seed
-  `.github/workflows/gate.yml` (single `gate` job — the simple default for one check command; a repo
-  that grows several independent suites splits them into parallel jobs across the runner's twelve lanes,
-  as MMI-Hub's `cli`/`infra`/`docs` gate does) and a ruleset reference at
-  `.github/rulesets/mmi-product-required-checks.json`. The gate is stack-aware: capture the repo's
-  **runtime** (`node` | `python`), its **check command**, and its **working directory** at interview time
-  and pass them as `--var GATE_RUNTIME=node|python`, `--var GATE_CMD=...`, `--var GATE_WORKDIR=...` (and
-  `--var GATE_CACHE_DEP_PATH=<path/to/package-lock.json>` when the app's Node lockfile is not at the repo
-  root). Defaults: `node` runtime, `npm run check` / `npm ci` at the repo root; a Python repo defaults to
-  `pytest` / `pip install -e ".[dev]"` with `--var GATE_PY_VERSION=` (3.11 default). The runtime selects
-  which setup step (`setup-node` vs `setup-python`) the rendered `if:` fires. The check command runs
-  under the org **wall-clock budget** (#3178): the render pins `run-with-budget` to the CLI's blessed SHA
-  with `--var GATE_MAX_SECONDS=` (300s onboarding default — tighten once the gate is measured, via
-  `--var` or `org project set <repo> --var gate={"maxSeconds":N}`); `ci audit` and the release train
-  both enforce the step, so do not remove it. The tenant-container product image build (#7542)
-  shares that ceiling — no separate knob. Every trigger runs the full `GATE_CMD`. A repo whose checks
-  need a service container or an extra budgeted step declares them in its registry gate config, never by
-  hand-editing the rendered gate (#7407): `gate.services` is keyed by service name with `image`, `env`,
-  `ports`, one-line `options` and `tmpfs` paths; `gate.steps` is a list of `{name, command, env,
-  maxSeconds}` run after the main check under the same budget wrapper. Invalid declarations fail the
-  render by field name; a repo that declares neither renders exactly as before. `bootstrap apply --execute` installs that JSON as the
-  repository ruleset itself (#6070) and reports one `product-ruleset` row: `PARK` (the gate file is not on
-  the base branch yet — installed disabled), `WAIT` (the gate exists but has not emitted a proven-green
-  `gate` context — kept disabled; re-run apply after the gate passes), `ACTIVATE` (gate green — enforcement
-  active), or `SKIP` (already exact). The activation boundary is fail-closed on purpose: a required context
-  that cannot pass yet would lock the seed PR behind itself. `mmi-cli devops ci reconcile --apply --repo
-  $OWNER/$REPO` remains the supported fallback; confirm `product required-check ruleset enforcement active`
-  with `bootstrap verify` before reporting bootstrap complete. MMI-Hub keeps its own three-job gate
-  (`cli`/`infra`/`docs`) — never apply the product ruleset there.
-- **The committed ruleset owns its up-to-date policy.** New repositories default to
-  `strict_required_status_checks_policy: false`. Bootstrap and CI reconciliation preserve that policy
-  when updating contexts, and converge the live ruleset to the committed setting. Repositories may
-  explicitly require an up-to-date head. `pr merge` / `pr land` still update a BEHIND head from the base
-  with a merge commit and re-wait once — see `docs/Guides/train-troubleshooting.md#head-behind-base`.
-- **A brand-new repo cannot pass the gate you just installed — its first commit must carry a real project
-  (#2928).** The seeded `gate.yml` runs `GATE_INSTALL_CMD` + `GATE_CMD` (`npm ci` + `npm run check` by
-  default) **unconditionally**. An empty repo has no `package.json`, so the gate **fails on the seed PR
-  itself** — and since the seed PR is what *installs* the gate, this is the normal first-bootstrap path, not
-  an edge case. The repo cannot go green and `bootstrap verify` cannot pass until the first commit contains a
-  real project satisfying `GATE_CMD`: a `package.json` with a `check` script (or the Python equivalent), plus
-  its lockfile. Landing that minimal project is **part of finishing the bootstrap**, not follow-up work —
-  otherwise the gate is unpassable by construction.
-  **The `check` must be able to fail.** It has to actually compile or lint the code being committed — a
-  script that exits 0 without looking at anything does **not** satisfy `GATE_CMD` and must never be committed
-  to force a green gate. The goal is a gate that catches a broken change, not a green tick wired to nothing.
-  A typecheck plus a lint is enough to start. **Do not seed a test suite to satisfy `GATE_CMD`** — tests are
-  opt-in org-wide (#3562); a new repo seeds tests only for paths its own `test-policy.json` marks mandatory,
-  and an empty `mandatory` array is the normal answer.
-- **Standard labels** — type labels only (the issue templates reference them). **Priority is a Project
-  field, not a label** (#416): never seed `priority:*` labels; `--priority` writes the board field.
-  ```bash
-  gh label create bug     --color d73a4a --description "Something is broken or behaving wrong" -R $OWNER/$REPO
-  gh label create feature --color a2eeef --description "New capability or enhancement"        -R $OWNER/$REPO
-  gh label create task    --color 0052cc --description "Task, chore, or improvement"           -R $OWNER/$REPO
-  ```
-- **Board view (card fields, #4093)** — the Project's Board view must show the org-standard card set:
-  `Title, Assignees, Status, Labels, Linked pull requests, Parent issue, Sub-issues progress, Priority`.
-  Cloning from the template board (project 4, Step 3) already produces this; `bootstrap verify` asserts it
-  (`Board view card fields match the org standard`) on every subsequent run, so drift shows up there rather
-  than only at bootstrap time. Fix via Board view → **Fields**, or `updateProjectV2View(configuration:
-  {visibleFieldIds:[...]})`. Strip any legacy `priority:*` / taxonomy labels with `mmi-cli oracle board doctor --fix`.
-- **Org App credentials** — nothing to register per repo (#494). Board moves are central (the Hub webhook
-  moves Todo/In Progress/In Review for every repo) and the org App token is minted inside the Hub's own
-  central workflows, so `MMI_APP_ID` / `MMI_APP_PRIVATE_KEY` live only on the Hub — a product repo seeds no
-  App var/secret.
-- **Issue templates** — seed `.github/ISSUE_TEMPLATE/` (Bug · Feature · Task + `config.yml`).
-- **Merge settings (org canon)** — every repo: auto-merge on, squash on, automatic merged-branch deletion
-  off. A merged remote branch survives until delayed cleanup proves no open PR still uses it as a base
-  (#5789); deleting it at merge can irreversibly close stacked PRs:
-  `gh api -X PATCH repos/$OWNER/$REPO -f allow_auto_merge=true -f allow_squash_merge=true -F delete_branch_on_merge=false`
-- **Cursor environment** — `.cursor/environment.json` is retired org-wide (#2501): it caused Cursor to
-  auto-spawn cloud agents nobody asked for. Bootstrap no longer seeds it and no
-  repo should carry a tracked copy.
-
-## Step 5 — install the plugin + seed docs
-
-- Bootstrap does **not** seed `.claude/settings.json` or any agent guide (hub-v3 WS4). The developer installs
-  the org plugins per machine: `mmi@mutmutco` (the plugin carries the org tooling + skills) and
-  `superpowers@claude-plugins-official` (Anthropic's skills framework — TDD, debugging, subagent dev).
-  Personal agent guides (`AGENTS.md`/`CLAUDE.md`) are developer-owned and gitignored — MMI never delivers,
-  overwrites, or deletes them; Jervaise's guide rides Jerv PowerTools.
-- Seed `README.md` + `architecture.md` from the templates, then **fill them before finishing** — `bootstrap
-  verify` now fails on any leftover `(placeholder)` or `{{TOKEN}}` (#1520). Fill the code-local fields from
-  what this bootstrap already knows: **Stack / Run locally / Verify** from the Step-4c gate + install commands
-  and the repo's actual code; **Gotchas** and the architecture **Overview / Build & deploy** from the confirmed
-  Step-0 axes (class, project-type, deploy-model). Do **not** write the release track, board number, or deploy
-  coords as a value — the templates point at `mmi-cli oracle org project get` (registry SSOT, never copied, so it cannot drift).
-  Do not write `AGENTS.md` / `CLAUDE.md` — these are developer-owned, gitignored agent guides, never a bootstrapped repo file (the `mmi-no-agent-files-org` ruleset blocks committing them).
-- **`docs/index.md` is an optional generated routing index (#3545).** Apply may create `docs/index.md` once for link routing; it never rewrites it. Once the repo has docs of its own,
-  `mmi-cli oracle docs index --write` owns the routing artifact and `--check` gates drift — it is not product
-  current-state SSOT. Decision records under `docs/decisions/` remain append-only *why*.
-- `.claude/settings.local.json` is local-only and gitignored; bootstrap seeds no committed `.claude/settings.json`.
-- **No agent guide is committed — none, anywhere (#2921).** `mmi-no-agent-files-org` is active with no bypass
-  and restricts `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.claude/**`, `.codex/**`, `.agents/**` **and
-  `.cursor/rules/**`**. Bootstrap used to seed `.cursor/rules/<repo-slug>.mdc`, which the wall refuses with a
-  409 — it wrote a file its own ruleset bans, then verified the file was there. That seed, its template, and
-  the verify check are gone. Repo-specific agent guidance belongs in **`README.md` § Agent context** (stack,
-  verify commands, gotchas) with the deep build truth in `architecture.md`; agents read those. Personal agent
-  guides stay developer-owned and gitignored, carried per machine by each developer's own plugins.
+For a new repo, board selection/creation, access, gate setup, or manual provisioning, read [reference.md](reference.md) Steps 0b–5 before applying; upgrades can use the apply path below.
 
 ## Step 6 — register Hub META
 
 Do not seed a product repo control-plane config file. `mmi-cli` carries the Hub API endpoint and resolves board,
 deploy, secret, and project state from the Hub registry at runtime.
 
-Choose the v2 shape explicitly. Use `--project-type web-app --deploy-model tenant-container` for ordinary
-web tenants, `--project-type desktop-game --deploy-model none --clear-web-profile` for a desktop game,
-`--project-type desktop-app --deploy-model none --clear-web-profile` for a packaged desktop application
-(swap in `--deploy-model registry-publish` when it also publishes a package alongside its installer),
-`--project-type mobile-app --deploy-model none --clear-web-profile` for a phone app distributed through the
-app stores, and
-`--class content --project-type content --deploy-model content --clear-web-profile` for a content/KB repo.
-An **MM-Work module** adds `--var SUITE=mm-work` (#7944): it registers `suite: mm-work` and derives its
-own `dev.<sub>.mutmut.work` + `<sub>.mutmut.work` hosts, with no rc host (the suite serves its rc from the
-live host). Without it, apply derives the `*.mutatismutandis.co` web-app hosts, which a module never uses.
+For project-type/deploy-model flag combinations or an MM-Work module, read [reference.md](reference.md) before choosing the apply flags.
+
 Run the apply path with the board variables discovered above, or register the same values with
 `mmi-cli oracle org project set` from the Hub or from the target project checkout:
 
@@ -507,26 +113,7 @@ 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`.
 
-For a `suite: mm-work` tenant-container module, bootstrap apply selects the MM-Work module seed instead: a live `/health` server and `/module.js`, the example module scaffold, secret-backed image build, and `gate` plus `screens / screens`. It sets `requiredBuildSecrets: ["NODE_AUTH_TOKEN=@github-packages-token"]` and requires only `gate`. Before the first CI/deploy, an org admin must grant the repo Read on both `@mutmutco/mmwork-ds` and `@mutmutco/mmwork-screens` under Package settings → Manage Actions access (no GitHub REST API; verify names the manual step). Add `screens / screens` to `requiredChecks` only after the screens job is green, or every PR blocks.
-
-**Never provision a Google OAuth client for an MM-Work suite module, even if old META declares `oauth`.** Modules sign in through the MM-Work pass and reach Google via `ctx.act`; read the package's GUIDE. The suite seed omits the Google-login guide.
-
-For a non-suite `web-app` that declares `oauth` META, print the canonical OAuth surface and provision the client once:
-
-```bash
-mmi-cli vault org oauth plan --repo "$OWNER/$REPO"        # the exact JS origins + redirect URIs + canonical SSM keys
-```
-
-Register those JS origins + `/api/auth/callback` redirect URIs on the Console client (master, per
-`docs/Guides/oauth-provision.md`), then store the creds in the canonical keys in one step:
-
-```bash
-mmi-cli vault org oauth set-creds --repo "$OWNER/$REPO" < client.json   # the Console "Download JSON" file
-```
-
-The keys are the one stageless pair `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET` at the slug root — every
-stage reads it (#2244/#2528). Never a staged `{dev,rc,main}/GOOGLE_*`, `GOOGLE_OAUTH_CLIENT_*`, or `prod/`
-variant; the runtime reads only the canonical names and declare-first rejects the rest.
+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.
 
 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.