@mutmutco/kilo-plugin 3.79.0

package/skills/bootstrap/SKILL.md

@@ -0,0 +1,493 @@
+---
+name: bootstrap
+description: Provision a repo into the org with board, registry, rules, and plugin setup.
+---
+
+# /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 <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.
+
+**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.
+
+## 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). 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` (docs/content;
+  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-app`, `desktop-game`, `mobile-app`, `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).*
+
+
+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 marks it a content-class
+repo). 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.
+
+**Two verify FAILs are un-run manual steps or API lag, not code bugs — diagnose them as such, but never as
+acceptable end states (#2928):**
+- `branch protection exists` / `push allowlist configured` — **`bootstrap apply` does not apply branch
+  protection.** That is **Step 2b**, and it is manual, so these FAIL until you run it. **Step 2b is
+  mandatory**: these are security controls, and they must go green (or be an explicitly master-accepted
+  manual item per the rule above) before the bootstrap is complete. A red branch-protection or
+  push-allowlist check is an **unfinished repo**, never a known-benign FAIL to sign off around.
+- `README has Agent context section — README.md not readable via API` on a README that demonstrably has the
+  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)
+
+gh repo create "$OWNER/$REPO" --private
+gh api -X PUT "repos/$OWNER/$REPO/contents/.gitkeep" \
+  -f message="chore: initial commit" -f content="Cg==" -f branch="$FIRST"
+```
+
+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.
+
+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.
+
+**Create `rc`/`main` server-side, not with `git push` (#3433).** 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 — so a `git push origin development rc main` cannot be run as written. Creating the refs
+through the API is not a force-push, so both the #1660 guard and the `mmi-train-floor` ruleset allow it, and
+it behaves the same on every machine. `development` (or `main`, for a content repo) already exists from
+Step 0b:
+```bash
+sha=$(gh api "repos/$OWNER/$REPO/git/ref/heads/development" --jq '.object.sha')
+
+# full — development (Step 0b) + rc + main
+gh api "repos/$OWNER/$REPO/git/refs" -f ref=refs/heads/rc   -f sha="$sha"
+gh api "repos/$OWNER/$REPO/git/refs" -f ref=refs/heads/main -f sha="$sha"
+gh repo edit "$OWNER/$REPO" --default-branch development
+
+# direct — development (Step 0b) + main, NO rc
+gh api "repos/$OWNER/$REPO/git/refs" -f ref=refs/heads/main -f sha="$sha"
+gh repo edit "$OWNER/$REPO" --default-branch development
+
+# trunk (content) — main only; Step 0b already created it with `-b main`
+gh repo edit "$OWNER/$REPO" --default-branch main
+```
+Re-running a create on a ref that already exists returns `422 Reference already exists` — that is the
+idempotent no-op, not a failure. Verify with `gh api "repos/$OWNER/$REPO/branches" --jq '.[].name'`.
+
+## 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 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 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>`) by re-running `mmi-cli 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 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 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 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.
+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
+
+- **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. 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.
+- **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 (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 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, 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`
+- **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` (its SessionStart hook 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 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 generated by `bootstrap apply`, once (#3545).** The seeded README's first agent
+  instruction is to read it, so it exists from the first commit and `bootstrap verify` requires it. Apply
+  **creates** it and never rewrites it: apply sees the seed list, not the tree, so regenerating an index in a
+  repo that has since added its own docs would silently drop every hand-authored entry. Once the repo has
+  docs of its own, `mmi-cli docs index --write` owns it — that reads the whole tree, and `--check` gates drift.
+- **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.
+- `.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.
+
+## 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.
+Run the apply path with the board variables discovered above, or register the same values with
+`mmi-cli org 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 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 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.
+
+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 stage 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 — seed the org-managed .gitignore block
+
+The org-managed `.gitignore` block is delivered by the `managed-block` bootstrap seed (`skills/bootstrap/seeds/manifest.json`),
+which merges the canonical block into the repo's `.gitignore` in place, preserving the repo's own ignore lines.
+The `doctor` SessionStart heal keeps it current thereafter. The block carries **only** org-universal ignores —
+never agent guides or a spine. The fanout pipeline that used to push this block via App-token PRs is retired
+(Hub#3010), and the whole-spine fanout was retired earlier (hub-v3 WS4.2 #2219).
+
+## 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,
+org-managed `.gitignore` block seeded, 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,30 @@
+# 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/
+# Private GitHub Packages opt-in. Requires compose build.secrets and registry requiredBuildSecrets.
+# RUN --mount=type=secret,id=NODE_AUTH_TOKEN \
+#     npmrc="$(mktemp)"; trap 'rm -f "$npmrc"' EXIT; \
+#     printf '//npm.pkg.github.com/:_authToken=%s\n' "$(cat /run/secrets/NODE_AUTH_TOKEN)" > "$npmrc"; \
+#     NPM_CONFIG_USERCONFIG="$npmrc" npm ci
+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's here
+
+(One bullet per top-level dir/module: what it is, in one line — a map, not a tour.)
+
+## Who runs it
+
+(Owner/operator — who runs this day to day.) Access follows the MMI Future three-level model: read for
+org members, developer as GitHub `write`, project-admin as `write` plus train-branch allowlist. Authority
+detail → [org-architecture §4](https://github.com/mutmutco/MMI-Hub/blob/development/docs/org-architecture.md);
+access runbook → [repo-access](https://github.com/mutmutco/MMI-Hub/blob/development/docs/Guides/repo-access.md).
+
+## Agent context
+
+Read this section at the start of agent work in this repo.
+
+- **Docs entry point:** read `docs/index.md` first — the generated routing index (`mmi-cli docs index
+  --write`); `--check` gates drift, so it can never fall out of sync with the `docs/` tree.
+- **Durable WHY:** `docs/decisions/` — one file per decision, prose only for what was chosen and
+  rejected; never a description of current state.
+- **Current state:** code + `mmi-cli org project get` — release track, board, and deploy coords are
+  registry facts, resolved live, never copied into a doc where they can go stale.
+- **GitHub wikis are retired org-wide** — this repo does not publish to a `.wiki.git`; do not create one.
+- **Stack:** (languages, frameworks, major services)
+- **Run locally:** (install, dev server, `/stage` if non-obvious)
+- **Verify before done:** (exact commands — test, lint, typecheck, repo gate script)
+- **Architecture:** deep build/deploy shape → `architecture.md`
+- **Gotchas:** (ports, env from vault not files, Windows/shell quirks specific to this repo)
+
+## Start
+
+(The one human-readable command/steps to get this running locally.)

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

@@ -0,0 +1,34 @@
+# {{REPO_NAME}} — Architecture
+
+> How this repo is **built** — a short, stable entry, not a runtime inventory. Pair with `README.md`
+> (what it *is*). State current truth, inspect don't narrate: no change-comments or version-era labels
+> (history is in git). (Write fresh — D35.)
+
+## What this repo produces
+
+(What ships from this repo — the product/service/library, in one or two bullets.)
+
+## Layout
+
+```
+(top-level dir)     (what it is, one line)
+(top-level dir)     (what it is, one line)
+```
+
+## Stack
+
+(Languages, frameworks, datastores, major services — inspect the lockfile/manifest, don't assume.)
+
+## Build & deploy
+
+- **Class + release track + stages:** `mmi-cli org project get` (registry SSOT — full = development/rc/main,
+  direct = development/main, trunk = main; never copied here, so it cannot go stale).
+- **Deploys run centrally** via the Hub (`tenant-deploy.yml`); this repo carries no deploy files, unless
+  noted otherwise below.
+- (Build/test commands, CI gate, deploy target.)
+
+## Conventions
+
+Follows the org spine (carried by the MMI plugin per machine). Repo-specific agent guidance:
+`README.md` § Agent context — no agent guide is committed to the repo (the org `mmi-no-agent-files-org`
+ruleset blocks every agent-guide path).

package/skills/bootstrap/seeds/decisions-readme.template.md

@@ -0,0 +1,46 @@
+# Decision records
+
+Prose in this tree is only for **why** — why we chose a shape, what we rejected, what constraint
+bound us. It never describes current implementation and never claims to be current. Code (and
+generated refs) are the only truth about *what is*.
+
+## One file per decision
+
+`docs/decisions/YYYY-MM-DD-<slug>.md`
+
+- **Date** in the filename is the day the decision was recorded (UTC calendar date).
+- **Slug** is a short kebab-case label for the subject (`single-aws-account`, `cowork-plugin-boundary`).
+
+## Frontmatter
+
+```yaml
+---
+date: YYYY-MM-DD
+sha: <git commit sha at which this was true>
+status: decided | superseded
+subjects:
+  - <topic or path this decision binds>
+---
+```
+
+| Field | Meaning |
+| --- | --- |
+| `date` | Same calendar day as the filename prefix. |
+| `sha` | The commit that embodies or records the decision — a pin in history, not a claim that the tree still looks like that. |
+| `status` | `decided` (in force) or `superseded` (replaced by a later record; leave the old file in place). |
+| `subjects` | Short list of topics, paths, or surfaces the decision constrains. |
+
+## Body
+
+1. `# <Title>` — the decision in one line (what was chosen, not how it works today).
+2. `## Why` — the rationale and the binding constraints.
+3. `## Rejected alternatives` — each alternative as a bullet: what it was, why it lost.
+
+Do not narrate live topology, versions, box coordinates, or "how to run it." If a reader needs
+current state, they read the code or a generated ref — not this file.
+
+## Ownership
+
+Bootstrap seeds this README once (`ownership: repo`) and never clobbers it. Individual decision
+files are authored in the same PR as the change (or by the docs janitor as a backstop) and merged
+by a human.