@mutmutco/opencode-mmi 2.48.0

package/skills/bootstrap/SKILL.md

@@ -0,0 +1,419 @@
+---
+name: bootstrap
+description: Provision a repo into the MMI org — branches, ruleset, the Project board, registry META, secrets + OIDC, the plugin, and doc seed. Master-admin only. Use when onboarding, adding, or provisioning a repo into the org, setting up a new project repo, making a repo a first-class org citizen, or invoking /bootstrap.
+---
+
+# /bootstrap — provision a repo into the org
+
+The one-time onboarding that turns a repo into a first-class org citizen. **Master-admin only, run from
+`MMI-Hub` (the hub).** Every step operates org-level resources (Project, Ruleset, org secrets, member
+access) **through the GitHub App's installation token** — not a human credential — so the gate is who may
+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 bootstrap --apply` consumes it). Every seed carries an **ownership**:
+
+- **`org`** — org-delivered, **overwritten on upgrade** (the org owns it): `.claude/settings.json`, the issue
+  templates, and the spine `AGENTS.md`/`CLAUDE.md`. `source: self` = copied verbatim from MMI-Hub's own
+  current file, so the spine is **seeded at bootstrap** (a fresh repo verifies green immediately, #927); the
+  fanout pipeline (`.github/fanout-targets.json`) still owns ongoing spine-change **updates**. 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`, `.cursor/environment.json`, `.cursor/rules/<slug>.mdc`.
+  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 7-label set. The per-step instructions below
+are the manual path; `--apply` automates them from this manifest.
+
+**CLI-release gap.** A new topology value (a `--project-type`, `--deploy-model`, or `--release-track` added
+since the last release train) lands on `development` but is not in the published/installed `mmi-cli` until a
+release train ships it. So bootstrapping a repo that needs a just-merged topology requires a CLI that
+includes it: run a `/release` train first, **or** invoke a local dev build —
+`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`) — instead of the installed `mmi-cli`. The
+installed CLI rejects an unknown enum with no hint that it merely lags `development`.
+
+## Step 0 — capability shape (confirm the four axes before any mutation)
+
+Bootstrap is **destructive to undo**: a wrong shape means converting in place later — deleting protected
+branches, temporarily disabling the org-wide `mmi-train-floor` ruleset (which affects every repo for that
+window), and tearing down train artifacts (#1450, the MMD-UI case). So **before Step 0a touches anything**,
+surface and **confirm all four topology axes with the master** — present the recommended default for each,
+never apply it silently. Use the structured-question UI; one question per axis (or one grouped confirm).
+
+- **`class`** — `deployable` (ships an app/service; full or direct train) · `content` (KB/docs/design-system;
+  trunk, `main`-only). *Controls the branch model.* Recommend from what the repo **is**, not a fixed default.
+- **`project-type`** — e.g. `web-app`, `cli-tool`, `worker`, `desktop-game`, `content`. *Controls which Hub
+  services attach.*
+- **`deploy-model`** — e.g. `tenant-container`, `none`, `content`. *Controls the deploy path.*
+- **`release-track`** — `full` (development·rc·main) · `direct` (development·main, skips rc) · `trunk`
+  (`main` only). *The branch set follows the track, not just the class (#1097).*
+
+**Dashboard opt-in (`--dashboard`, #1452).** Orthogonal to the four axes — an **additive** flag, not a new
+type. Pass `--dashboard` when the repo is an MMI dashboard that consumes the `@mutmutco` design system; it
+persists `dashboard: true` on the registry META and seeds one extra repo-owned file, `components.json`,
+pre-pointed at the registry (`https://ui.mutatismutandis.co/r/{name}.json`) plus `design-system.paths.json`
+(tsconfig path aliases → the gitignored `.mmi/design-system/components/` cache doctor maintains). Registry
+component **files are not committed** — `mmi-cli doctor --apply` pulls them into `.mmi/` when stale. List
+desired components in `components.json` → `mmi.installed`. It changes **no** other
+axis — a dashboard is still the standard deployable `web-app` / `tenant-container` (commonly `direct` track,
+like MMD-UI). The app UI itself is scaffolded from the MMD-UI `apps/starter` (a separate step), not copied by
+bootstrap. Recommend it for a new dashboard repo; omit it everywhere else (a plain repo's META and seed set
+are byte-identical to before this flag existed). After register, registry META `dashboard` is the SSOT —
+`bootstrap apply` re-seeds dashboard-gated files when META is true (no `--dashboard` needed); toggle with
+`mmi-cli project set <repo> --var dashboard=true|false` (project-admin or master). See the dashboard guide:
+MM-KB `kb/guides/dashboard-ui.md`.
+
+For a **deployable** repo, also capture the **gate runtime** (`node` | `python`), the **check command**, and
+the **working directory** — these feed the product gate (`--var GATE_RUNTIME=`, `--var GATE_CMD=`,
+`--var GATE_WORKDIR=`, and `--var GATE_CACHE_DEP_PATH=` for a non-root Node lockfile; see Step 5 / the
+"Product gate + required checks" note below). Default to `node` at the repo root; recommend `python` when the
+repo's app is Python.
+
+A **content/trunk** choice provisions: `main`-only (no `rc`), **no** `.github/workflows/gate.yml` and **no**
+product required-check ruleset, and a `projects.json` entry with `branch: main` (which derives the content
+fanout lane). A clean content repo then verifies green — `bootstrap verify --class content` no longer reports
+the deployable gate checks as FAIL (#1450).
+
+Record the confirmed axes; Step 0a runs `verify --class <confirmed>`, Step 0b creates the repo on the
+track's default branch, and the apply flags (`--project-type` / `--deploy-model` / `--release-track`) carry
+the confirmed values — no silent defaulting.
+
+## Step 0a — no-mutation verifier
+
+Before mutating anything, run the verifier so the current gaps are concrete:
+```bash
+mmi-cli bootstrap verify "$OWNER/$REPO" --class deployable --json
+# or for content repos:
+mmi-cli bootstrap verify "$OWNER/$REPO" --class content --json
+```
+
+Run it again after Step 7. A repo is not ready for real developers until every check is green, or the report
+names an explicitly manual-only item that the master has accepted for that repo.
+
+## 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 `development` branch to push and no default branch to set:
+```bash
+gh repo create "$OWNER/$REPO" --private --confirm
+tmpdir=$(mktemp -d)
+git -C "$tmpdir" init -b development
+git -C "$tmpdir" commit --allow-empty -m "chore: initial commit"
+git -C "$tmpdir" remote add origin "https://github.com/$OWNER/$REPO.git"
+git -C "$tmpdir" push -u origin development
+rm -rf "$tmpdir"
+gh repo edit "$OWNER/$REPO" --default-branch development
+```
+
+For a **content** repo (`trunk` track), use `-b main` and push `main` instead. Skip this step when the repo
+already exists with the track's default branch.
+
+## 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 push an `rc` for a direct-track repo:
+```bash
+# full
+git push origin development rc main      # create any missing
+gh repo edit "$OWNER/$REPO" --default-branch development
+
+# direct
+git push origin development main         # create any missing — NO rc
+gh repo edit "$OWNER/$REPO" --default-branch development
+
+# trunk (content)
+git push origin main                     # create if missing
+gh repo edit "$OWNER/$REPO" --default-branch main
+```
+
+## 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*. Apply classic branch protection on
+`development`/`rc`/`main` for deployable repos, or just `main` for content repos, with **"Restrict who can
+push"** = the master + the 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. Run per
+protected branch (App token):
+
+```bash
+BRANCHES="development rc main"           # full
+BRANCHES="development main"               # direct (no rc)
+BRANCHES="main"                          # trunk / content
+
+mapfile -t MASTER_USERS < <(gh api --paginate "orgs/$OWNER/members?role=admin" --jq '.[].login')
+if [ "${#MASTER_USERS[@]}" -eq 0 ]; then
+  echo "No org owners resolved for $OWNER; stop before writing branch protection." >&2
+  exit 1
+fi
+USERS_JSON=$(printf '%s\n' "${MASTER_USERS[@]}" | node -e "const fs=require('fs'); const users=fs.readFileSync(0,'utf8').trim().split(/\r?\n/).filter(Boolean); process.stdout.write(JSON.stringify(users));")
+
+for b in $BRANCHES; do
+  node - "$USERS_JSON" <<'NODE' | gh api --method PUT repos/$OWNER/$REPO/branches/$b/protection --input -
+const users = JSON.parse(process.argv[2]);
+process.stdout.write(JSON.stringify({
+  required_status_checks: null,
+  enforce_admins: false,
+  required_pull_request_reviews: null,
+  restrictions: { users, teams: [], apps: ['mmi-github-app'] },
+}, null, 2));
+NODE
+done
+```
+
+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 configured Project (default by prefix; confirm)
+
+Division boards exist as defaults — the repo's `<CATEGORY>` prefix picks the starting recommendation
+(`MMI-*` → the **MMI** project, `MMG-*` → **MMG**, `MMS`/`MMD`/`MMC` likewise, `MM-*` → **MM**). **Confirm
+with the master** whether the repo joins that board, joins another existing board, or gets a dedicated
+product/initiative board; repos/projects are **not 1:1**.
+```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 an existing board so the 4-lane `Status` field
+  (`Todo · In Progress · In Review · Done`) **and its built-in workflows carry over**:
+  ```bash
+  gh project copy <existing-project#> --source-owner "$PROJECT_OWNER" \
+    --target-owner "$PROJECT_OWNER" --title "<Project>"
+  ```
+  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 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.
+
+Record the chosen `projectNumber`/`projectId` plus Status/Priority field ids in the Hub registry META
+(`PROJECT#<slug>`) via `mmi-cli bootstrap apply --execute` or `mmi-cli project set` after the board is
+known. Going forward the thin Lambda adds each new issue to that project on `issues.opened` and sets
+`Status: Todo`.
+
+**Register the project for cloud agents.** The same registry META row carries `{name, slug, projectId,
+wikiRepo, repos[]}`; do not append to a committed `projects.json`. This is what makes `wiki-keeper` run for
+the project (the launcher fans one run per registered project, generating its wiki + refreshing its board).
+`kb-keeper`, `saga-keeper`, and `northstar-keeper` are org-wide and need no per-project entry. 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 box writes the release
+`.env` from the registry + vault 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 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.
+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
+
+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, wiki
+
+- **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:`. 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) 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. After apply,
+  master-admin must **activate** that JSON as a repository ruleset (GitHub → Settings → Rules → Rulesets →
+  Import/create from the committed reference) so the `gate` context is required on train branches. MMI-Hub
+  keeps its own three-job gate (`cli`/`infra`/`docs`) — never apply the product ruleset there.
+- **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 (Priority chip)** — the Project's board view must **show the Priority field on cards**, not
+  the Labels field (GitHub's API can't set view columns): Board view → **Fields** → remove **Labels**, add
+  **Priority**. Otherwise cards show label soup and no priority chip. Strip any legacy `priority:*` /
+  taxonomy labels with `mmi-cli board prune-priority-labels`.
+- **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, delete-branch-on-merge on, so a
+  green allowlisted PR can land itself and never leaves a dead branch:
+  `gh api -X PATCH repos/$OWNER/$REPO -f allow_auto_merge=true -f allow_squash_merge=true -f delete_branch_on_merge=true`
+- **Wiki** — `gh api -X PATCH repos/$OWNER/$REPO -F has_wiki=true`, then **create the wiki's first page once**
+  in the UI (an empty page is enough — GitHub blocks programmatic first-page creation). **MMI-Keeper**
+  generates and maintains the wiki thereafter (on release + weekly); no further manual edits.
+- **Cursor environment** — commit `.cursor/environment.json` with the repo's dependency `install` command
+  (e.g. `npm ci`, `npm --prefix infra ci`, `pip install -r requirements.txt`). Cursor honors repo-level
+  config and auto-snapshots after install, so the repo's cloud agents (keepers) get fast cold starts with
+  no dashboard step. A repo needing system packages can instead use `build.dockerfile` (a committed
+  `.cursor/Dockerfile`, layer-cached). No snapshot-by-ID (that path needs the dashboard wizard).
+
+## Step 5 — install the plugin + seed docs
+
+- Write the repo's `.claude/settings.json` (marketplace + `enabledPlugins`) so Claude Code prompts the
+  developer to install the org plugins: `mmi@mutmutco` (its SessionStart hook keeps the rules current) and
+  `superpowers@claude-plugins-official` (Anthropic's skills framework — TDD, debugging, subagent dev). Mirror
+  the hub's own `.claude/settings.json` verbatim. Fanout keeps this file current after bootstrap —
+  it is org-owned and delivered verbatim like the spine.
+- 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 project get` (registry SSOT, never copied, so it cannot drift). Write
+  the delivered `AGENTS.md` / `CLAUDE.md` verbatim (org-owned, whole-file — identical in every repo; no markers,
+  no tail).
+- **Push the mandated fill past the active ruleset (#1807).** Deployable repos activate
+  `mmi-product-required-checks` during apply (its `bypass_actors` is empty by design), so the `gate` check is
+  required on `development`/`main` before the seeded README + architecture have ever produced a green run. The
+  fill above (#1520) then cannot be pushed, and not even `gh pr merge --admin` clears it (GH013 on push /
+  GraphQL rule violation on admin-merge). Sanctioned final step: in GitHub Settings > Rules > Rulesets >
+  `mmi-product-required-checks`, set **Enforcement** to **Disabled**, push/merge the filled `README.md` +
+  `architecture.md`, then set **Enforcement** back to **Active**. Programmatic equivalent: PUT the ruleset
+  with `enforcement: disabled` (a PATCH is rejected, #917/#922), push the fill, then PUT it back to
+  `active` (or re-run `bootstrap apply`, which re-activates the ruleset idempotently). Never leave enforcement
+  disabled.
+- Make sure the target repo's `.gitignore` does **not** ignore `.claude/settings.json`; only
+  `.claude/settings.local.json` is local-only.
+- **Reserve the spine filenames.** `AGENTS.md` / `CLAUDE.md` are the org spine — never repo-specific. Seed
+  `.cursor/rules/<repo-slug>.mdc` (frontmatter `alwaysApply: true`) with repo-specific agent guidance (what
+  the repo is, services/deps, build/test, conventions). Include the saga startup pattern for non-Claude
+  agents: `mmi-cli saga health --json`, `mmi-cli saga show`, then explicit `mmi-cli saga note` at handoff or
+  meaningful checkpoints. This gives Cursor's setup agent a home so it does not hijack `AGENTS.md`; Cursor
+  cloud agents read `.cursor/rules` automatically.
+
+## Step 6 — register Hub META
+
+Do not seed a product repo `.mmi/config.json`. `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, and
+`--class content --project-type content --deploy-model content --clear-web-profile` for a content/KB repo.
+Run the apply path with the board variables discovered above, or register the same values with
+`mmi-cli project set` from the Hub or from the target project checkout:
+
+```bash
+mmi-cli bootstrap apply "$OWNER/$REPO" --class deployable \
+  --project-type web-app --deploy-model tenant-container --execute \
+  --var PROJECT_OWNER="$PROJECT_OWNER" \
+  --var PROJECT_NUMBER="$PROJECT_NUMBER" \
+  --var PROJECT_ID="$PROJECT_ID" \
+  --var STATUS_FIELD_ID="$STATUS_FIELD_ID" \
+  --var STATUS_TODO="$STATUS_TODO" \
+  --var STATUS_IN_PROGRESS="$STATUS_IN_PROGRESS" \
+  --var STATUS_IN_REVIEW="$STATUS_IN_REVIEW" \
+  --var STATUS_DONE="$STATUS_DONE"
+```
+
+Tenant-container repos must carry a `docker-compose.yml` and Dockerfile that build from the shipped source
+archive; the train does not ship a prebuilt `dist/`. **Bootstrap seeds both files** for
+`deployModel: tenant-container` from `skills/bootstrap/seeds/` (rendered from
+`docs/Reference/tenant-runtime/docker-compose.yml` and `docs/Reference/tenant-runtime/Dockerfile`). The box
+writes the release `.env` from the registry + vault at deploy time; the compose file carries `env_file: .env`
+and the app reads plain env vars — it must **not** self-load SSM and must **not** ship a committed `.env`.
+
+For a `web-app` that declares `oauth` META, print the canonical OAuth surface and provision the client once:
+
+```bash
+mmi-cli 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 oauth set-creds --repo "$OWNER/$REPO" < client.json   # the Console "Download JSON" file
+```
+
+The keys are `{dev,rc,main}/GOOGLE_CLIENT_ID|SECRET` — never a `GOOGLE_OAUTH_CLIENT_*` or `prod/` variant; the
+runtime reads only the canonical names.
+
+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:** run `mmi-cli port-range <Repo>` to assign (idempotently) the repo's local port block
+from the central registry. 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.
+
+## Step 7 — register for fanout
+
+Add the repo to `.github/fanout-targets.json` so future org-spine changes reach it via App-token PRs. Use
+`branch: "development"` for deployable repos and `branch: "main"` for content repos.
+
+## Step 8 — report
+
+Repo, default branch, ruleset applied, train branches locked (push allowlist), project attached/created
+(+ info seeded, Status lanes and Labels field verified), secrets set (names only), developer access, plugin
+installed, docs seeded, registry META written, issue templates committed, org App credentials registered,
+fanout registered, and the final `mmi-cli bootstrap verify "$OWNER/$REPO" --class ... --json` result.
+
+## Retro — one check before you finish
+Before your final report, answer one question honestly: did **this skill's own instructions** misfire
+this run — ambiguous wording, a misleading message, or an environment failure it should have warned
+about? (Process only — never the user's code or task; e.g. an ambiguous seed, registry, or OIDC step, or
+a guard that fired on a healthy repo.) If yes, file **one** lesson and move on; a clean run is silent
+(hard cap: one per run). It lands on the Hub board (deduped) and is fixed only via a reviewed PR — never
+edit the skill live; the retro is advisory, so if the call fails, note it and continue:
+`mmi-cli skill-lesson --skill bootstrap --title "<what misfired>" --body "<what; evidence; proposed amendment>"`

package/skills/bootstrap/seeds/Dockerfile.template

@@ -0,0 +1,25 @@
+# Tenant-container reference Dockerfile — seeded at bootstrap (#1593).
+# Adapt package manager and build commands to the project; keep the image building from source.
+FROM node:24-alpine AS deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+# npm workspaces: copy EVERY workspace package.json before `npm ci` so adding a workspace later
+# does not break the image. Add one COPY line per workspace directory (apps/*, packages/*, …).
+# COPY apps/my-app/package.json ./apps/my-app/
+RUN npm ci
+
+FROM node:24-alpine AS build
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+RUN npm prune --omit=dev
+
+FROM node:24-alpine AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=build /app/package*.json ./
+COPY --from=build /app/node_modules ./node_modules
+COPY --from=build /app/dist ./dist
+EXPOSE 3000
+CMD ["node", "dist/index.js"]

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

@@ -0,0 +1,36 @@
+# {{REPO_NAME}}
+
+> One paragraph: what this repo **is** — the product/service and who it's for. (Write fresh — D35: do
+> not carry a legacy README over verbatim; the old docs are archived under `docs/Archive/`.)
+
+## What it is
+
+(Describe the product/service.)
+
+## Agent context
+
+Read this section at the start of agent work in this repo.
+
+- **Stack:** (languages, frameworks, major services)
+- **Run locally:** (install, dev server, `/stage` if non-obvious)
+- **Verify before done:** (exact commands — test, lint, typecheck, repo gate script)
+- **Release track + coords:** `mmi-cli project get` (registry SSOT for release track, stages, board, and deploy coords; not copied here, so it cannot go stale).
+- **Architecture:** deep build/deploy shape → `architecture.md`
+- **Gotchas:** (ports, env from vault not files, Windows/shell quirks specific to this repo)
+
+## Develop
+
+(How to run, build, and test locally. How it's *built* lives in `architecture.md`.)
+
+## Access
+
+Repo access follows the MMI Future three-level model: read for org members, developer as GitHub `write`,
+and project-admin as `write` plus train-branch allowlist (registry `projectAdmins` on this project).
+What each level can **do** is in `AGENTS.md` § Authority and `docs/org-architecture.md` §4 in `MMI-Hub`;
+agents check `mmi-cli access role <owner/repo> --json` before redirecting anyone to the master. Grant/revoke
+mechanics (master-only) are `docs/Guides/repo-access.md` in `MMI-Hub`.
+
+## Org
+
+Part of **Mutatis Mutandis** · class **{{CLASS}}** · board **{{PROJECT_OWNER}} #{{PROJECT_NUMBER}}**.
+Agent rules: `AGENTS.md` (the org spine). Architecture: `architecture.md`.

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

@@ -0,0 +1,19 @@
+# {{REPO_NAME}} — Architecture
+
+> How this repo is **built** — present truth. Pair with `README.md` (what it *is*). State current truth;
+> no change-comments or version-era labels (history is in git). (Write fresh — D35.)
+
+## Overview
+
+(System shape: components, data flow, deploy model.)
+
+## Build & deploy
+
+- **Class:** {{CLASS}}
+- **Release track + stages:** `mmi-cli project get` (registry SSOT: full = development/rc/main, direct = development/main, trunk = main; never copied here).
+- **Deploys run centrally** via the Hub (`tenant-deploy.yml`); this repo carries no deploy files.
+- (Build/test commands, CI gate, deploy target.)
+
+## Conventions
+
+Follows the org spine (`AGENTS.md`). Repo-specific agent guidance: `.cursor/rules/{{REPO_SLUG}}.mdc`.

package/skills/bootstrap/seeds/components.json.template

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "radix-nova",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "app/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "rtl": false,
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "menuColor": "default",
+  "menuAccent": "subtle",
+  "registries": {
+    "@mutmutco": "https://ui.mutatismutandis.co/r/{name}.json"
+  },
+  "mmi": {
+    "cacheDir": ".mmi/design-system/components",
+    "installed": []
+  }
+}

package/skills/bootstrap/seeds/cursor-environment.template.json

@@ -0,0 +1,3 @@
+{
+  "install": "{{INSTALL_CMD}}"
+}

package/skills/bootstrap/seeds/cursor-rules.template.mdc

@@ -0,0 +1,11 @@
+---
+alwaysApply: true
+---
+
+# {{REPO_NAME}} — agent context
+
+Read **`README.md` § Agent context** first (stack, verify commands, gotchas). Deep build truth: `architecture.md`.
+
+Org behavior: `AGENTS.md` / `CLAUDE.md` — never edit here. This file is the Cursor always-on pointer + repo-specific notes only.
+
+(Saga: plugin hooks call `mmi-cli` automatically; without plugin see `docs/Guides/cursor-saga.md` in MMI-Hub.)

package/skills/bootstrap/seeds/design-system.paths.template.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "paths": {
+      "@/components/ui/*": ["./.mmi/design-system/components/ui/*"]
+    }
+  }
+}

package/skills/bootstrap/seeds/docker-compose.template.yml

@@ -0,0 +1,17 @@
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    restart: unless-stopped
+    # The box control document writes registry coords + stage-scoped SSM secret values into the
+    # release ./.env before `docker compose up`; env_file is what delivers them into the container.
+    env_file: .env
+    environment:
+      NODE_ENV: production
+      MMI_STAGE: ${MMI_STAGE:-dev}
+      MMI_PORT: ${MMI_PORT:-3000}
+      PORT: ${PORT:-3000}
+      MMI_EDGE_DOMAIN: ${MMI_EDGE_DOMAIN:-}
+    ports:
+      - "${MMI_PORT:-3000}:${PORT:-3000}"

package/skills/bootstrap/seeds/gate.template.yml

@@ -0,0 +1,42 @@
+name: gate
+# Org-standard green-before-merge gate for product repos (#1333). Runs on PRs, train-branch pushes,
+# and v* tags so /release and /hotfix can discover required contexts on the tagged SHA.
+#
+# Runner: self-hosted mmi-runner (mmi-live) — see docs/Guides/gh-runner-runbook.md in MMI-Hub.
+# Stack-aware (#1550): the runtime is rendered into the setup-step `if:` — both the Node and Python
+# setup steps live in the file but only the one matching GATE_RUNTIME runs. Knobs (override at
+# bootstrap with --var):
+#   GATE_RUNTIME       — node | python (selects which setup step fires)
+#   GATE_CMD           — the check command ({{GATE_CMD}})
+#   GATE_INSTALL_CMD   — the dependency-install command ({{GATE_INSTALL_CMD}})
+#   GATE_WORKDIR       — app working directory when not the repo root ({{GATE_WORKDIR}})
+#   GATE_CACHE_DEP_PATH— npm lockfile path for the setup-node cache ({{GATE_CACHE_DEP_PATH}})
+#   GATE_PY_VERSION    — Python version for setup-python ({{GATE_PY_VERSION}})
+on:
+  pull_request:
+  push:
+    branches: {{GATE_PUSH_BRANCHES_YAML}}
+    tags: ['v*']
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+permissions:
+  contents: read
+
+jobs:
+  gate:
+    if: ${{ github.event_name != 'push' || github.ref_name == '{{GATE_FULL_RUN_BRANCH}}' || github.ref_type == 'tag' }}
+    runs-on: [self-hosted, linux, x64, mmi-live]
+    defaults:
+      run: { working-directory: {{GATE_WORKDIR}} }
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - if: ${{ '{{GATE_RUNTIME}}' == 'node' }}
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with: { node-version: 24, cache: npm, cache-dependency-path: {{GATE_CACHE_DEP_PATH}} }
+      - if: ${{ '{{GATE_RUNTIME}}' == 'python' }}
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with: { python-version: '{{GATE_PY_VERSION}}' }
+      - run: {{GATE_INSTALL_CMD}}
+      - run: {{GATE_CMD}}