@thebassclef/lite 1.0.4 → 1.1.1

package/dist/lite/.claude/skills/onboard-repo/SKILL.md

@@ -0,0 +1,1640 @@
+---
+tier: lite
+name: onboard-repo
+description: "Bootstrap the bassclef framework in a new repo. Installs the sync hook. Scaffolds config, whereami, and CLAUDE.md. Modes: default, --with-deploy-host, --with-secrets, --full, --greenfield-from-intent (cold-adopter magic demo)."
+problem: "Setting up bassclef in a new repo takes an hour of trial. Missing directories and wrong hook wiring."
+value: "One command bootstraps everything \u2014 sync hook and config file and whereami scaffold."
+inputs: [Optional flags — --with-deploy-host or --with-secrets or --full]
+outputs: [Installed bassclef-sync hook, Config scaffold, Whereami stub]
+user_invocable: true
+disable_model_invocation: false
+requires:
+  cli: [git, gh]
+  network: true
+modes: [default, --with-deploy-host, --with-secrets, --full, --greenfield-from-intent]
+---
+
+# /onboard-repo — bassclef substrate adoption for a new repo
+
+Brings a repo from "zero bassclef wiring" to "inherits full substrate
+on desktop + mobile" in a single operator-gated session. Distinct from:
+
+- `scripts/boot-bassclef.sh` — **machine-level** one-time setup (gh
+  auth, service account, launchd). Run once per machine.
+- `/autonomous start` — **session-level** scaffolding (iteration goal,
+  phase state, risk register) for a repo that's ALREADY wired into
+  bassclef.
+
+This skill sits between them: it's **repo-level** substrate adoption.
+Run once per new consumer repo.
+
+## When to invoke
+
+- Adding a new repo that will use bassclef
+- Re-onboarding a repo that pre-dates the bassclef substrate
+- Refreshing substrate wiring in an existing consumer (idempotent)
+
+## Which preset fits your setup?
+
+Pick the shape that matches how you plan to work. The picker is the first fork. The procedure below runs the phases that match your pick.
+
+| Preset | For | Runs |
+|---|---|---|
+| **share via GitHub** | A repo you push to GitHub and share | Path A — standard onboarding (Phases 1-3) |
+| **browse first** | Scanning what /onboard-repo does before you commit | Path A read-only walk (dry-run mode) |
+| **just me on this Mac** | A local-only project. No GitHub push. | Path B — empty-repo starter (`--greenfield-from-intent`) |
+
+**Recommended:** `share via GitHub` when you have a GitHub org and repo ready. Otherwise `just me on this Mac`.
+
+If the operator did not name a preset, ask first: `Share via GitHub / Browse first / Just me on this Mac? (g/b/j/skip)`
+
+Path A and Path B stay as internal names for the procedure sections below. Adopter reads the picker at the top. The Path A/B and Phase X labels sit inside the procedure body as reference names.
+
+## Prerequisites (fail fast if missing)
+
+Different prereqs apply to Path A (standard onboarding) vs Path B
+(`--greenfield-from-intent` cold-adopter magic demo). Check the path
+the operator picked before validating.
+
+### Path A — standard onboarding
+
+- `gh` authenticated (`gh auth status`)
+- `claude` resolvable in PATH (`command -v claude`) — required for the
+  acceptance test at the end. If missing from a Zellij/tmux subpane,
+  move `eval "$(/opt/homebrew/bin/brew shellenv)"` from `~/.zprofile`
+  to `~/.zshenv` so non-login shells pick up homebrew's PATH.
+- Target repo exists on GitHub under your org
+- Target repo has a default branch (`main` preferred)
+- Bassclef is cloned as a peer at `$BASSCLEF_DIR` (default `~/src/<your-org>/bassclef`, for
+  desktop `additionalDirectories` resolution)
+- You are currently `cd`'d into the target repo's working directory
+- Claude Code session was started with `--add-dir ~/src/sunj-labs/bassclef`
+  so this skill file is accessible
+
+### Path B — `--greenfield-from-intent` (cold-adopter magic demo)
+
+- `claude` resolvable in PATH
+- `git` available
+- `python3` available (for the localhost gallery server)
+- `jq` available (JSON parsing for bassclef-sync + LLM-pick adapter)
+- `curl` available (bassclef-sync fallback + LLM-pick API calls)
+- No separate API key needed. The skill uses whichever LLM your Claude Code session provides. Per the tier reframe (bassclef-web#190 + #193), tier is about catalog size, not credentials.
+- You are currently `cd`'d into an **empty target directory** (or one
+  with only files Path B is allowed to overwrite — see "Working
+  directory convention" below)
+- `gh` is NOT required (no GitHub repo gets created)
+- A peer bassclef checkout at `~/src/sunj-labs/bassclef` is preferred
+  but not required (the thin-pointer dispatcher falls back to the
+  GitHub tarball when the sibling is absent — Path B's `Phase B.3`
+  installs it)
+
+### When prereqs are missing — operator menu
+
+If a prereq fails, surface it to the operator and present this menu
+verbatim before stopping:
+
+```
+Prerequisite missing for standard onboarding: <name of failed check>.
+
+Pick one:
+
+  1. Empty-repo starter demo — runs /launch --local, no GitHub repo
+     created, no vendor accounts needed. Switches this dispatch to
+     --greenfield-from-intent (Path B below). No separate API key
+     needed — uses the LLM your Claude Code session provides.
+  2. Fix the prereq and re-run standard onboarding (Path A).
+  3. Cancel.
+```
+
+Operator picks `1` → continue under Path B. Picks `2` → stop and wait
+for the operator to fix + re-dispatch. Picks `3` → stop.
+
+Silence is not deferral. Wait for an explicit choice.
+
+## Working directory convention
+
+| Path | Working directory |
+|---|---|
+| Path A — Phases 1–3 | **target repo** (existing GitHub repo) |
+| Path A — Phase 4 | retired (see Phase 4 note below) |
+| Path B — all phases | **target directory** (typically empty; never leaves it) |
+
+For Path A the `pwd` check at the start of each phase exists for a
+reason — don't lose track. Path B runs entirely inside one directory
+and never reaches out to GitHub.
+
+## Procedure
+
+The Procedure branches at the top into **Path A** (standard
+onboarding) or **Path B** (`--greenfield-from-intent` cold-adopter
+magic demo). Decide first, then walk only the phases under the chosen
+path. Do not mix.
+
+### Choosing the path
+
+| Signal | Path |
+|---|---|
+| Operator dispatched `/onboard-repo --greenfield-from-intent ...` | B |
+| Operator picked option `1` from the prereqs-missing menu | B |
+| All Path A prereqs pass + no `--greenfield-from-intent` flag | A |
+| Operator dispatched `/onboard-repo --with-deploy-host` / `--with-secrets` / `--full` | A (with Phase 3.5 chained) |
+
+When in doubt, ask the operator which path; don't infer.
+
+---
+
+### Path B — `--greenfield-from-intent` (cold-adopter magic demo)
+
+**Working directory: empty.** Never leaves it. No GitHub repo. No vendor accounts touched. The path runs in ≤5 steps using the LLM your Claude Code session provides.
+
+The task list the agent generates for Path B MUST be exactly these
+five tasks, in this order. Do not add Phase 1 GitHub work, Phase 1.3
+prod environment, Phase 3.5 follow-on prompts, or Phase 4 matrix PRs.
+Those belong to Path A.
+
+#### Phase B.1 — Confirm intent
+
+Operator pastes a paragraph or voice transcript describing what they
+want to build (the recipe-test example: "a wiki app for sharing
+recipes with family"). Agent echoes the intent back and asks for
+operator confirmation before continuing. No edits hit disk yet.
+
+#### Phase B.2 — Init local git
+
+```bash
+git init
+git commit --allow-empty -m "chore: init repo"
+```
+
+First empty commit so subsequent file writes have a baseline.
+
+#### Phase B.3 — Scaffold the bassclef wiring
+
+Subset of Path A Phase 2 — only the files `/launch --local` actually
+reads. Skip everything that needs a remote.
+
+```bash
+mkdir -p .claude/hooks docs
+
+# Install the thin-pointer dispatcher (same source as Path A Phase 2.1).
+# Sibling-fast-path preferred; the curl fallback works for cold adopters.
+cp ~/src/sunj-labs/bassclef/presence/install/bassclef-sync.dispatcher.template.sh \
+   .claude/hooks/bassclef-sync.sh 2>/dev/null \
+   || curl -sL https://raw.githubusercontent.com/sunj-labs/bassclef/main/presence/install/bassclef-sync.dispatcher.template.sh \
+        -o .claude/hooks/bassclef-sync.sh
+chmod +x .claude/hooks/bassclef-sync.sh
+
+# Minimal settings.json — only the SessionStart hook
+cat > .claude/settings.json <<'JSON'
+{
+  "permissions": {
+    "additionalDirectories": ["../bassclef"]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/bassclef-sync.sh", "timeout": 30 }
+        ]
+      }
+    ]
+  }
+}
+JSON
+
+# Minimal substrate.config.md
+cat > substrate.config.md <<'MD'
+# substrate.config.md
+
+hosting_platform: none
+deploy_targets:
+  prod: false
+budget:
+  session_ceiling: $0
+  iteration_ceiling: $0
+MD
+
+# Minimal .claude/bassclef-configs.jsonc — adopter-default seed (bassclef#1135 WU-4)
+cat > .claude/bassclef-configs.jsonc <<'JSONC'
+// bassclef-configs.jsonc — unified adopter configuration discovery surface.
+// JSON Schema: standards/state-spine/schemas/bassclef-configs.schema.json
+{
+  "sync": { "enabled": false },
+  "model_tier": {
+    "Builder": "balanced",
+    "Closer": "cheap-fast",
+    "Deployer": "cheap-fast",
+    "DocsWriter": "cheap-fast",
+    "Explorer": "cheap-fast",
+    "Orchestrator": "cheap-fast",
+    "Reviewer": "cheap-fast",
+    "Shaper": "capable"
+  },
+  "plan_tier": "tier-1",
+  "prose_discipline": { "kiss_words_turn_prose": true },
+  "testing": { "global_floor": 1, "path_matchers": [] }
+}
+JSONC
+
+# Minimal CLAUDE.md — operator owns this going forward
+cat > CLAUDE.md <<'MD'
+# <repo-name>
+
+## What this repo is
+
+Empty-repo starter demo from a stated intent. Substrate inherited from
+bassclef via `--add-dir ../bassclef` or thin-pointer fetch.
+
+## Stack
+
+To be determined by `/launch --local` output.
+MD
+```
+
+Skip in Path B:
+
+- `gh repo create` (no remote)
+- Phase 1.1 standard labels (no remote to apply them to)
+- Phase 1.2 branch protection (same)
+- Phase 1.3 prod environment (same)
+- `.bassclef-source.json` (only needed for cloud/mobile sessions
+  where the sibling sync isn't available; cold adopters running
+  locally don't need it for the magic demo)
+- Phase 3.5 interactive follow-on prompts (no `/provision-deploy-host`,
+  no `/secrets-bootstrap` — Path B has no vendor surfaces to bind)
+
+#### Phase B.4 — Dispatch `/launch --local --voice-input`
+
+Hand the intent paragraph straight to `/launch`:
+
+```
+/launch medium --local --voice-input "<intent paragraph from Phase B.1>"
+```
+
+Path B's last action is this dispatch. Do not chain `/build` or
+`/launch-preview` afterward — those belong to the extended path for
+operators with vendor bindings.
+
+#### Phase B.5 — `/launch --local` runs
+
+`/launch` writes the full artifact chain to disk (input-artifact, spec,
+prototypes gallery, user stories, decomposition, migration plan) and
+serves the gallery on `localhost:8000+`. The localhost URL is the
+deliverable. Operator inspects, picks a direction, and either keeps
+iterating locally or moves to standard onboarding (Path A) when they're
+ready to push to a GitHub repo.
+
+When `/launch --local` returns, Path B is done. Skip everything below
+this divider.
+
+---
+
+### Path A — standard onboarding
+
+Run each phase in order. Operator confirms before destructive or
+cross-repo actions. Each phase is independently re-runnable.
+
+#### Phase 0 — Refuse to run from main
+
+Substrate changes go through PRs, same as feature work. If `/onboard-repo`
+runs from `main`, every scaffold (`.claude/`, `CLAUDE.md`,
+`docs/whereami.md`, `substrate.config.md`, `.bassclef-source.json`,
+`.gitignore`) lands as a direct-to-main commit by surprise. Path A
+refuses that shape and prints the remediation:
+
+```bash
+CURRENT_BRANCH=$(git branch --show-current 2>/dev/null || echo "")
+
+case "$CURRENT_BRANCH" in
+  main|master)
+    cat >&2 <<'EOF'
+
+🛑 /onboard-repo refuses to run from main.
+
+Why: substrate scaffolding (`.claude/`, `CLAUDE.md`, `docs/whereami.md`,
+`substrate.config.md`, `.bassclef-source.json`, `.gitignore`) is a
+substrate change — it goes through a PR, not a direct commit to main.
+
+Remediation:
+
+    git checkout -b chore/bassclef-bootstrap
+    # re-run /onboard-repo
+
+When you reach the end of Phase 3, /onboard-repo will guide you to
+open the bootstrap PR; merging it lands the substrate on main with
+audit history (this is flywheel turn 1 from the first-use sequence —
+see docs/first-use-sequence.md).
+
+V1 (bassclef#956 follow-up) will auto-create the branch + PR. V0.5
+keeps the operator in the loop on the branching decision.
+
+EOF
+    exit 1
+    ;;
+  "")
+    cat >&2 <<'EOF'
+
+🛑 /onboard-repo cannot detect the current git branch.
+
+The cwd may not be a git repository, OR git is in a detached-HEAD state.
+
+Remediation:
+
+    git init                                  # if not a git repo
+    git checkout -b chore/bassclef-bootstrap # from a fresh branch
+    # re-run /onboard-repo
+
+EOF
+    exit 1
+    ;;
+  *)
+    # Any other branch — proceed
+    ;;
+esac
+```
+
+The remediation message is the contract. If a cold adopter dispatches
+`/onboard-repo` from `main`, they see exactly what to do — no operator
+coaching, no second-guess. V0.5 ships in bassclef#956; V1
+(auto-create branch + PR) is post-launch hardening per the goal's
+operator-decision items.
+
+#### Phase 1 — Set up the GitHub repo (labels, branch protection)
+
+**Working directory: target repo** (`pwd` should match `gh repo view --json name -q .name`).
+
+Idempotent API calls against the target repo via `gh`.
+
+##### 1.1 Create the 11 standard labels
+
+```bash
+# Read from git remote — don't infer from cwd basename (cwd can be renamed)
+REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
+
+declare -A LABELS=(
+  [bassclef-evolution]="A6E0F2:Candidate for promotion to bassclef"
+  [agent-user-proposed]="D4A5F5:Proposed by agent in an app repo"
+  [bassclef-sync]="8FD4A4:Related to bassclef substrate syncing"
+  [review-required]="F5B94A:Blocks — human review required"
+  [bug]="E4443A:Defect"
+  [enhancement]="A2EEEF:New or improved functionality"
+  [security]="FF0000:Security-relevant"
+  [infra]="C9D1D9:Infrastructure / workflows / tooling"
+  [priority-high]="E4443A:High priority"
+  [priority-medium]="F5B94A:Medium priority"
+  [question]="D876E3:Needs operator input or design discussion"
+)
+
+for NAME in "${!LABELS[@]}"; do
+  COLOR="${LABELS[$NAME]%%:*}"
+  DESC="${LABELS[$NAME]#*:}"
+  gh label create "$NAME" --repo "$REPO" --color "$COLOR" --description "$DESC" --force >/dev/null
+done
+```
+
+Uses `--force` so the call is idempotent (updates existing label or
+creates new). This matches the bootstrap logic shipped in bassclef
+#160 (sync hook does the same for `bassclef-evolution` + `agent-user-proposed`);
+this phase adds the broader set up-front so the operator can label issues
+immediately without waiting for a sync cycle.
+
+##### 1.2 Protect main from force-push and deletion
+
+```bash
+DEFAULT_BRANCH=$(gh repo view "$REPO" --json defaultBranchRef -q '.defaultBranchRef.name')
+
+gh api "repos/$REPO/branches/$DEFAULT_BRANCH/protection" \
+  --method PUT \
+  --input - <<EOF
+{
+  "required_status_checks": null,
+  "enforce_admins": false,
+  "required_pull_request_reviews": null,
+  "restrictions": null,
+  "allow_force_pushes": false,
+  "allow_deletions": false
+}
+EOF
+```
+
+Minimum defense: no force-push or deletion of main. PR reviews NOT
+required here — agent-created PRs (bassclef-sync) need to merge
+without human intervention for the mobile-sync story. Add stricter
+rules per-repo in `.github/branch-protection.yml` if the repo warrants.
+
+##### 1.3 Add the production approval gate (if this repo deploys to prod)
+
+If the repo will deploy to production, per `manual-prod-approval.md`:
+
+```bash
+# Prompt operator: "Does this repo deploy to prod? [y/N]"
+# If yes:
+USER_ID=$(gh api user --jq '.id')
+gh api "repos/$REPO/environments/prod" --method PUT \
+  -f "wait_timer=0" \
+  -f "deployment_branch_policy[protected_branches]=false" \
+  -f "deployment_branch_policy[custom_branch_policies]=true"
+
+gh api "repos/$REPO/environments/prod" --method PUT \
+  -F "reviewers[][type]=User" \
+  -F "reviewers[][id]=$USER_ID"
+```
+
+Skip if repo is docs-only (like bassclef itself) or doesn't have a
+production deploy target.
+
+#### Phase 2 — Install bassclef wiring (settings, sync script, config)
+
+**Working directory: target repo.** All file writes happen here.
+
+##### 2.1 Install the auto-update script (off by default per bassclef#939)
+
+```bash
+mkdir -p .claude/hooks
+
+# Install thin-pointer dispatcher from bassclef's own template directory.
+# This is the source-of-truth file consumers vendor.
+cp ~/src/sunj-labs/bassclef/presence/install/bassclef-sync.dispatcher.template.sh \
+   .claude/hooks/bassclef-sync.sh
+
+# OR — if bassclef isn't checked out alongside this repo, fetch from
+# bassclef's main branch on GitHub (public tarball release works too
+# once bassclef itself goes public):
+# curl -sL https://raw.githubusercontent.com/sunj-labs/bassclef/main/presence/install/bassclef-sync.dispatcher.template.sh \
+#   -o .claude/hooks/bassclef-sync.sh
+
+chmod +x .claude/hooks/bassclef-sync.sh
+
+# Verify the version header reads `thin-pointer-2026-05-15` or later:
+head -2 .claude/hooks/bassclef-sync.sh
+```
+
+The thin-pointer dispatcher does NOT vendor bassclef's sync logic.
+It reads `.bassclef-source.json` (Phase 2.4) for the upstream tarball
+URL + auth, fetches it, and execs the included template — always-current.
+Eliminates two prior patching layers: hook content drift (vendored
+template diverging from bassclef's) and URL refresh ceremony.
+
+When the dispatcher can't load the substrate (sibling missing AND curl
+fallback unconfigured / unauthenticated), it prints a plain-language
+explanation with three resolution paths (public adopter, local dev,
+private fork). External adopters get actionable guidance instead of
+internal-vocabulary errors. Closes the adoption-friendliness gap noted
+in bassclef#715.
+
+##### 2.2 Configure Claude Code for this repo
+
+Standard bassclef settings — SessionStart → `bassclef-sync.sh`, +
+other hooks per-agent configuration. Copy from a reference consumer
+(POA or ops) and scrub for repo-specific paths:
+
+```bash
+cat > .claude/settings.json <<'JSON'
+{
+  "permissions": {
+    "additionalDirectories": ["../bassclef"]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/bassclef-sync.sh", "timeout": 30 }
+        ]
+      }
+    ]
+  }
+}
+JSON
+```
+
+Operator confirms — may want to add app-specific hooks (pre-build-gate,
+pre-commit-gate) if the repo has source code.
+
+##### 2.2.1 Wire all Phase 2.2 hooks (13 hooks in one pass)
+
+Phase 2.2 wires 13 bassclef hooks that gate adopter writes, commits, sessions, and role transitions. Read the whole table first. Then apply the canonical jq recipe. Then run the 3 verify blocks.
+
+**Lite adopter note** (bassclef#740 Task 1.2). 6 hooks ship at `tier: standard` and skip on lite. Resolve tier via `lib/tier-check.sh`. The table marks each standard-tier hook with `std`. The bassclef-lite tarball does not carry those 6.
+
+**Symlink all hooks in one pass:**
+
+```bash
+mkdir -p .claude/hooks
+cd .claude/hooks
+for h in turn-prose-kiss-check substrate-clarity-gate artifact-ingestion-gate \
+         pattern-annotation-validate pre-commit-gate state-validate \
+         destructive-command-guard multi-tenancy-check atomic-pr-check \
+         post-write-trace testing-tier-enforce role-entry-gate temperance-gate; do
+  ln -sf "../../../bassclef/.claude/hooks/${h}.sh" "${h}.sh"
+done
+# Two allowlist files paired with hooks that read them:
+ln -sf "../../../bassclef/.claude/hooks/substrate-clarity-allowlist.txt" substrate-clarity-allowlist.txt
+ln -sf "../../../bassclef/.claude/hooks/testing-tier-enforce-allowlist.txt" testing-tier-enforce-allowlist.txt
+cd -
+```
+
+**Hook table:**
+
+| # | Hook | Event | Matcher | Tier | Notes |
+|---|---|---|---|---|---|
+| 1 | turn-prose-kiss-check | Stop | (empty) | lite | Reads `prose_discipline.kiss_words_turn_prose` toggle from bassclef-configs; short-circuits when false; timeout 10s |
+| 2 | substrate-clarity-gate | PreToolUse | Edit\|Write | lite | Reads bassclef baseline allowlist + optional adopter-side `substrate-clarity-allowlist-adopter.txt` |
+| 3 | artifact-ingestion-gate | PreToolUse | Write | lite | Reads `artifact_ingestion.paths` from bassclef-configs; 13 default paths seeded by Phase 2.3.5 |
+| 4 | pattern-annotation-validate | PreToolUse | Edit\|Write\|MultiEdit | std | Reads `tech_stack.lang` for language scoping (Phase 2.3.6) |
+| 5 | pre-commit-gate | PreToolUse | Edit\|Write\|MultiEdit | lite | Runs first; composes testing-tier-enforce internally as one of its check steps |
+| 6 | state-validate | PreToolUse | Edit\|Write\|MultiEdit | lite | Runs after pre-commit-gate; heavier ajv-cli schema check |
+| 7 | destructive-command-guard | PreToolUse | Bash | std | Catches destructive verbs + force flags + amplifiers (rm -rf, FLUSHALL, prisma migrate reset) |
+| 8 | multi-tenancy-check | PreToolUse | Edit\|Write\|MultiEdit | std | Template — customize via `TENANT_MODELS` / `TENANT_CONTEXT_FN` / `TENANT_PARAMS_FN` env vars |
+| 9 | atomic-pr-check | PreToolUse | Bash | std | Fires on `git push` patterns; BLOCKs multi-step branches lacking `bundle: true` in goal frontmatter |
+| 10 | post-write-trace | PostToolUse | Write\|Edit | std | Append-only trace; no override (never blocks) |
+| 11 | testing-tier-enforce | (composed) | (via pre-commit-gate) | lite | Fires inside pre-commit-gate; no separate matcher entry; 60-day allowlist grace |
+| 12 | role-entry-gate | PreToolUse | Edit\|Write\|MultiEdit | std | MVP: source-code file extensions only; reads `state/markers/role/<role>/<session>.marker` |
+| 13 | temperance-gate | PreToolUse | Edit\|Write\|MultiEdit | lite | Fires on high-impact edits (.claude/, standards/, lib/state.sh, SKILL.md) when temperance marker missing |
+
+**Order matters within each matcher block.** Place `pre-commit-gate` before `state-validate` (cheap SDLC checks fire first; heavier schema check runs second). Place `role-entry-gate` and `temperance-gate` LAST — methodology gates fire after structural + format + state checks pass.
+
+**Canonical jq recipe — write settings.json in one pass.** The recipe uses JSON literal syntax so the `"matcher": "..."` and `"command": "..."` keys land verbatim in `.claude/settings.json` for grep-verifiability:
+
+```bash
+# Assumes .claude/settings.json exists from Phase 2.2 (bare SessionStart entry).
+# Reads adopter tier and skips standard-tier hooks on lite.
+TIER=$(bash ../bassclef/lib/tier-check.sh 2>/dev/null || echo lite)
+
+# Lite tier — 7 hooks land in .claude/settings.json (rows 1,2,3,5,6,11,13).
+# Standard/ultra tier — all 13 hooks land in .claude/settings.json.
+jq --arg tier "$TIER" '
+  .hooks.Stop = ((.hooks.Stop // []) + [
+    { "matcher": "", "hooks": [
+      { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/turn-prose-kiss-check.sh", "timeout": 10 }
+    ]}
+  ]) |
+  .hooks.PreToolUse = ((.hooks.PreToolUse // []) + [
+    { "matcher": "Edit|Write|MultiEdit", "hooks": (
+      [
+        { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/substrate-clarity-gate.sh" },
+        { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/pre-commit-gate.sh" },
+        { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/state-validate.sh" },
+        { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/temperance-gate.sh" }
+      ] +
+      (if $tier != "lite" then [
+        { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/pattern-annotation-validate.sh" },
+        { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/multi-tenancy-check.sh" },
+        { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/role-entry-gate.sh" }
+      ] else [] end)
+    )},
+    { "matcher": "Write", "hooks": [
+      { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/artifact-ingestion-gate.sh" }
+    ]}
+  ] + (if $tier != "lite" then [
+    { "matcher": "Bash", "hooks": [
+      { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/destructive-command-guard.sh" },
+      { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/atomic-pr-check.sh" }
+    ]}
+  ] else [] end)) |
+  (if $tier != "lite" then
+    .hooks.PostToolUse = ((.hooks.PostToolUse // []) + [
+      { "matcher": "Write|Edit", "hooks": [
+        { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/post-write-trace.sh" }
+      ]}
+    ])
+  else . end)
+' .claude/settings.json > .claude/settings.json.tmp \
+  && mv .claude/settings.json.tmp .claude/settings.json
+```
+
+**Alternate matcher notes.** The `"matcher": "Edit|Write"` shape (without MultiEdit) appears in older adopter settings.json — the widening to `"matcher": "Edit|Write|MultiEdit"` in this recipe covers MultiEdit for hooks that need it.
+
+**On re-run against existing settings.json** — jq's `+=` appends. Duplicate matcher entries are safe (Claude Code processes all in order), but the cleaner shape merges hooks under one matcher. To dedupe a re-run, strip existing entries with `jq 'del(...)'` before appending.
+
+**Verify block 1 — Stop event:**
+
+```bash
+python3 -c "import json; d=json.load(open('.claude/settings.json')); \
+  hooks=[h.get('command','') for entry in d.get('hooks',{}).get('Stop',[]) for h in entry.get('hooks',[])]; \
+  print('turn-prose-kiss-check wired' if any('turn-prose-kiss-check' in c for c in hooks) else 'NOT wired')"
+```
+
+**Verify block 2 — PreToolUse event (all matchers):**
+
+```bash
+python3 -c "import json; d=json.load(open('.claude/settings.json')); \
+  cmds=[h.get('command','') for entry in d.get('hooks',{}).get('PreToolUse',[]) for h in entry.get('hooks',[])]; \
+  hooks=['substrate-clarity-gate','artifact-ingestion-gate','pre-commit-gate','state-validate','temperance-gate','pattern-annotation-validate','destructive-command-guard','multi-tenancy-check','atomic-pr-check','role-entry-gate']; \
+  [print(f'{h}: {\"wired\" if any(h in c for c in cmds) else \"NOT wired\"}') for h in hooks]"
+```
+
+**Verify block 3 — PostToolUse event:**
+
+```bash
+python3 -c "import json; d=json.load(open('.claude/settings.json')); \
+  cmds=[h.get('command','') for entry in d.get('hooks',{}).get('PostToolUse',[]) for h in entry.get('hooks',[])]; \
+  print('post-write-trace wired' if any('post-write-trace' in c for c in cmds) else 'NOT wired')"
+```
+
+**Rule propagation** — 8 rules load into the adopter session on their own via the `additionalDirectories: ["../bassclef"]` entry Phase 2.2 wrote. No per-rule symlink needed. Rules: `sdlc-gates.md`, `state-schema-validation.md`, `testing-tier-config.md`, `test-list-discipline.md`, `test-sufficiency.md`, `destructive-operations.md`, `pattern-annotation.md`, `pr-strategy.md`. Verify with:
+
+```bash
+for r in sdlc-gates state-schema-validation testing-tier-config test-list-discipline \
+         test-sufficiency destructive-operations pattern-annotation pr-strategy; do
+  test -f ../bassclef/.claude/rules/${r}.md && echo "${r} reachable" || echo "${r} NOT reachable"
+done
+```
+
+**Composed hook: testing-tier-enforce** — Row 11 fires inside `.claude/hooks/pre-commit-gate.sh` as one of its check steps (no separate matcher entry in `.claude/settings.json`). The symlink at `.claude/hooks/testing-tier-enforce.sh` + the allowlist at `.claude/hooks/testing-tier-enforce-allowlist.txt` are enough; the enforcer runs whenever pre-commit-gate fires (PreToolUse Edit|Write|MultiEdit). Grace window: 60 days on the allowlist baseline. When an adopter edits a Tier 0 source file without touching its matching test file, pre-commit-gate calls `.claude/hooks/testing-tier-enforce.sh` and the commit BLOCKs with a structured stderr message.
+
+Sanity check that the hook is reachable and composed into pre-commit-gate:
+
+```bash
+ls -l .claude/hooks/testing-tier-enforce.sh .claude/hooks/testing-tier-enforce-allowlist.txt
+grep -q "testing-tier-enforce.sh" .claude/hooks/pre-commit-gate.sh \
+  && echo "tier-enforce composed in pre-commit-gate" \
+  || echo "NOT composed (pre-commit-gate may be stale; re-run bassclef-sync)"
+```
+
+**Override paths** — each hook honors a `SKIP_*` env var (logged via trace-helper per bassclef override idiom). Use only for one-shot migrations or emergency rescue:
+
+| Hook | Override |
+|---|---|
+| turn-prose-kiss-check | (toggle via `prose_discipline.kiss_words_turn_prose: false` in bassclef-configs) |
+| substrate-clarity-gate | `SKIP_SUBSTRATE_CLARITY=1` |
+| artifact-ingestion-gate | `SKIP_ARTIFACT_INGESTION=1` |
+| pattern-annotation-validate | `SKIP_PATTERN_ANNOTATION=1` |
+| pre-commit-gate | `SKIP_PRE_COMMIT_GATE=1` |
+| state-validate | `SKIP_STATE_VALIDATE=1` |
+| destructive-command-guard | `SKIP_DESTRUCTIVE_GUARD=1` |
+| multi-tenancy-check | `SKIP_MULTI_TENANCY_CHECK=1` |
+| atomic-pr-check | `SKIP_ATOMIC_PR_CHECK=1` |
+| post-write-trace | (none — append-only trace never blocks) |
+| testing-tier-enforce | `SKIP_TESTING_TIER_ENFORCE=1` |
+| role-entry-gate | `SKIP_ROLE_ENTRY=1` |
+| temperance-gate | `SKIP_TEMPERANCE_GATE=1` |
+
+**Not yet wired in bassclef** — `role-entry-gate` and `temperance-gate` ship to adopters first. Bassclef's own settings.json adds them in a follow-on after the marker convention runs in the wild for a few sessions and the multi-role + trigger-taxonomy follow-ons land.
+
+Source: bassclef#1136 T3 (pre-commit-gate + state-validate), bassclef#1137 T4 (substrate-clarity-gate), bassclef#1138 T5 (turn-prose-kiss-check), bassclef#1139 T6 (pattern-annotation-validate), bassclef#1140 T7 (artifact-ingestion-gate), bassclef#1141 T8 (destructive-command-guard + multi-tenancy-check), bassclef#1142 T9 (atomic-pr-check + post-write-trace), bassclef#1143 T10 (testing-tier-enforce), bassclef#1144 T11 (test-discipline rule propagation), bassclef#1145 T13 (role-entry-gate), bassclef#1147 T15 (temperance-gate). Follow-ons deferred: `operator-private-path-check`, `type-check`, `post-skill-friction-check`, `role-entry` skill, multi-role matcher matrix, `standards/temperance-discipline.md`.
+
+##### 2.3 Create the project config file
+
+Copy from `presence/install/substrate-config.md`, then prompt operator
+for:
+
+- `journal_doc_id` (optional — create Google Doc now or later)
+- `changelog_doc_id` (optional)
+- `deploy_targets` (local/staging/prod booleans)
+- `budget.session_ceiling` / `iteration_ceiling` (sequential mode → `$0`)
+- `hosting_platform` (REQUIRED for any consumer that ships a UI). Default
+  to `amplify` per ADR-008 + app-consumer precedent. Set `none` for
+  docs-only / no-UI repos. Enum:
+  `amplify | ec2-tailscale | vercel | netlify | cloudflare-pages | none`.
+  `/bind-subdomain` + `/launch-preview` refuse on `none` unless
+  `BIND_SUBDOMAIN_OVERRIDE=1` is set. Closes bassclef#449.
+
+If operator says "defer", scaffold with placeholders and `TODO:` markers
+so next session surfaces them.
+
+##### 2.3.5 Write the bassclef-configs adopter-default seed
+
+Write `.claude/bassclef-configs.jsonc` with the adopter-default seed.
+Every downstream hook + skill reads from this file; without it, defaults
+are invisible to the adopter. Phase 2.5 (security_scanning) appends to
+this file later in the same Procedure run, so the foundation MUST land
+first.
+
+```bash
+cat > .claude/bassclef-configs.jsonc <<'JSONC'
+// bassclef-configs.jsonc — unified adopter configuration discovery surface
+//
+// Edit the values below. Each block has a comment explaining what it does,
+// what the default is, and which bassclef substrate component reads it.
+//
+// JSON Schema: standards/state-spine/schemas/bassclef-configs.schema.json
+// Full reference: standards/bassclef-configs-schema.md
+{
+  // Whether bassclef's substrate syncs from upstream at SessionStart.
+  // Adopter default: false (opt-in trust posture). Turn on when you want
+  // bassclef to keep itself current automatically.
+  // Pairs with: .claude/hooks/bassclef-sync.sh
+  "sync": { "enabled": false },
+
+  // Per-agent LLM model routing. Most agents stay cheap-fast; Builder
+  // gets balanced for code quality; Shaper gets capable for problem framing.
+  // Pairs with: .claude/agents/<role>.md frontmatter
+  "model_tier": {
+    "Builder": "balanced",
+    "Closer": "cheap-fast",
+    "Deployer": "cheap-fast",
+    "DocsWriter": "cheap-fast",
+    "Explorer": "cheap-fast",
+    "Orchestrator": "cheap-fast",
+    "Reviewer": "cheap-fast",
+    "Shaper": "capable"
+  },
+
+  // Adopter plan tier. Caps parallel agent dispatch per Anthropic plan limits.
+  // tier-1 = single-agent serial (safest); tier-2 = 2-3 parallel after upgrade;
+  // tier-4 = 5+ parallel for operator-scale workflows.
+  // Pairs with: .claude/skills/longrun/SKILL.md parallel-dispatch logic
+  "plan_tier": "tier-1",
+
+  // Plain-English discipline for agent reply prose to operator. When true,
+  // the Stop hook scans the agent's last message for bassclef-internal
+  // jargon and surfaces findings to stderr (advisory). 'strict' makes the
+  // hook block the stop until prose is clean. false disables the scan.
+  //
+  // Optional: kiss_words_strict_places escalates specific places to strict
+  // even when the global toggle stays advisory. V1 places (bassclef#1171):
+  //   - closeout_blocks  — matches a "## Closeout audit" heading
+  //   - summary_tables   — matches a "## Status" heading
+  //   - next_pickup      — matches a "## Next pickup" heading
+  // Adopter default: advisory everywhere; no strict places. Flip to strict
+  // or add places when you want the rule to actually catch you.
+  //
+  // Pairs with: .claude/rules/plain-english-discipline.md
+  //             .claude/hooks/turn-prose-kiss-check.sh
+  "prose_discipline": {
+    "kiss_words_turn_prose": true
+    // "kiss_words_strict_places": ["closeout_blocks"]  // uncomment when ready
+  },
+
+  // Per-path testing-tier enforcement (4 tiers: 0 strict TDD / 1 test-with /
+  // 2 smoke / 3 manual verify). global_floor applies when no path_matcher matches.
+  // Adopter default: floor=1 (WARN on missing test); empty matchers (add your own).
+  // Pairs with: .claude/rules/testing-tier-config.md
+  "testing": {
+    "global_floor": 1,
+    "path_matchers": []
+  }
+
+  // Phase 2.5 below appends "security_scanning" here.
+  // /onboard-repo Phase 2.x or future tickets append "tech_stack", "hook_chain",
+  // "discipline_layers" as those vocabularies stabilize. Per bassclef#1135.
+}
+JSONC
+```
+
+Validate the written file against the schema:
+
+```bash
+perl -pe 's,^\s*//.*$,,; s,/\*.*?\*/,,g' .claude/bassclef-configs.jsonc \
+  | ajv validate -s ~/src/sunj-labs/bassclef/standards/state-spine/schemas/bassclef-configs.schema.json \
+                 -d - --spec=draft2020 -c ajv-formats
+```
+
+Expect a single `valid` line. The file is now the single source of truth for adopter configuration; subsequent Phase 2.x steps APPEND to it (Phase 2.3.6 tech_stack, Phase 2.5 security_scanning, future T-tickets for hook_chain etc.) rather than rewriting from empty.
+
+If the adopter has a pre-existing `.claude/bassclef-configs.jsonc` from a prior SENTINEL_bassclef_version, prompt before overwriting; offer a `--merge` flow (operator-driven; not automated in V1).
+
+##### 2.3.6 Discover and write the tech_stack block
+
+Stack-bound rules + standards in bassclef (`api-conventions.md`, `sdlc-gates.md`, `schema-management.md`, `new-dependency-check.md`, `frontend-stack.md`, `deployment-topology.md`) read `tech_stack:` from `.claude/bassclef-configs.jsonc` to route per-stack discipline. Without the block, non-matching adopters see false-fires (Prisma rules at SQLAlchemy adopters, Next.js API conventions at FastAPI adopters, etc.). This step writes the block so the bleed stops at install time.
+
+Schema reference: `standards/state-spine/schemas/tech-stack.schema.json`. Standard: `standards/tech-stack-config.md`.
+
+**Auto-detection signals** (per `standards/tech-stack-config.md` § Auto-detection at `/onboard-repo`):
+
+| Build file present | Suggests |
+|---|---|
+| `package.json` with `"next"` dep | `frontend: nextjs`, `lang: typescript` (if `tsconfig.json` also present) |
+| `package.json` with `"react"` dep (no `next`) | `frontend: react-vite` (if `vite.config.*` present) |
+| `package.json` with `"prisma"` dep | `orm: prisma` |
+| `package.json` with `"drizzle-orm"` dep | `orm: drizzle` |
+| `package.json` + `pnpm-lock.yaml` | `pkg_manager: pnpm` |
+| `package.json` + `yarn.lock` | `pkg_manager: yarn` |
+| `package.json` + `package-lock.json` | `pkg_manager: npm` |
+| `pyproject.toml` or `requirements.txt` | `lang: python` |
+| `pyproject.toml` with `sqlalchemy` | `orm: sqlalchemy` |
+| `pyproject.toml` with `alembic` | `orm: alembic` |
+| `pyproject.toml` with `fastapi` | `frontend: fastapi`, `backend: python` |
+| `pyproject.toml` with `django` | `frontend: django`, `backend: python` |
+| `Gemfile` | `lang: ruby`, `pkg_manager: gem` |
+| `Gemfile` with `rails` | `frontend: rails`, `backend: ruby` |
+| `go.mod` | `lang: go`, `pkg_manager: go-mod`, `backend: go` |
+| `Cargo.toml` | `lang: rust`, `pkg_manager: cargo`, `backend: rust` |
+| `vercel.json` or `.vercelrc` | `deploy: vercel` |
+| `fly.toml` | `deploy: fly` |
+| `netlify.toml` | `deploy: netlify` |
+| `render.yaml` | `deploy: render` |
+
+No signal → field stays `none` and waits for operator override.
+
+**Operator prompt** (surface this exact text):
+
+```
+Detected stack signals:
+
+  lang:         <detected or "(no signal)">
+  frontend:     <detected or "(no signal)">
+  backend:      <detected or "(no signal)">
+  orm:          <detected or "(no signal)">
+  pkg_manager:  <detected or "(no signal)">
+  deploy:       <detected or "(no signal)">
+
+Stack-bound rules route per-adopter from this block. Without it,
+non-matching adopters see false-fires from rules written for the
+default stack (TypeScript + Next.js + Prisma + EC2-Tailscale).
+
+Three paths:
+
+  [a] Accept detected values
+  [b] Override per field (5-7 short prompts)
+  [c] Skip — write declared_via: deferred and revisit later
+      (rules fall back to operator defaults; expect some false-fires
+      until you set the block)
+
+Pick a/b/c:
+```
+
+**On accept (a):** write the block with detected values + `declared_via: onboard-repo` + `declared_at: <ISO date>`.
+
+**On per-field override (b):** prompt each field in order with detected value as the default. Field-level enums per `standards/tech-stack-config.md` § Fields.
+
+**On skip (c):** write `tech_stack: { declared_via: "deferred", declared_at: <ISO date> }` only. The schema admits all fields as optional; rules fall back gracefully. Operator can revisit by re-running `/onboard-repo` or editing the block directly.
+
+**Append to `.claude/bassclef-configs.jsonc`** using `jq` or in-place edit; the block goes immediately before the closing brace + after `testing`:
+
+```bash
+# Pseudo-procedure; actual implementation reads the operator's path choice
+# and constructs the block from detected + override values.
+cat >> .claude/bassclef-configs.jsonc <<TECH_STACK
+,
+
+  // Tech stack vocabulary. Stack-bound rules read this to route per-
+  // stack discipline (schema-management.md ORM routing, api-conventions
+  // frontend routing, sdlc-gates lang routing, etc.).
+  // Auto-detected at /onboard-repo Phase 2.3.6; operator confirms or
+  // overrides per field.
+  // Pairs with: standards/tech-stack-config.md (schema + semantics),
+  //             standards/state-spine/schemas/tech-stack.schema.json
+  // Schema reference: bassclef#1127 tech_stack discovery
+  "tech_stack": {
+    "lang": "<value>",
+    "frontend": "<value>",
+    "backend": "<value>",
+    "orm": "<value>",
+    "pkg_manager": "<value>",
+    "deploy": "<value>",
+    "declared_at": "<ISO date>",
+    "declared_via": "onboard-repo"
+  }
+TECH_STACK
+```
+
+(In practice the writer holds the file open as JSON-with-comments, mutates the parsed object, re-emits with comments preserved per the comment-aware JSONC editor pattern; the heredoc above is illustrative.)
+
+**Validate after append:**
+
+```bash
+perl -pe 's,^\s*//.*$,,; s,/\*.*?\*/,,g' .claude/bassclef-configs.jsonc \
+  | ajv validate -s ~/src/sunj-labs/bassclef/standards/state-spine/schemas/bassclef-configs.schema.json \
+                 -d - --spec=draft2020 -c ajv-formats
+```
+
+Expect `valid`. If the file fails to validate, revert the append, surface the schema error, and re-prompt.
+
+**Acceptance:**
+
+- After Phase 2.3.6 completes, `.claude/bassclef-configs.jsonc` contains a `tech_stack:` block.
+- Block validates against `tech-stack.schema.json`.
+- `declared_via` is one of `onboard-repo` (path a or b) or `deferred` (path c); `migrated` and `demo-prompt` reserved for other callers.
+- Operator can re-run `/onboard-repo` and the existing block is detected; prompt asks whether to keep, re-detect, or edit per-field.
+
+**Composes with downstream Phase 2.x steps:**
+
+- Phase 2.3.7 (testing-tier path_matchers seed) reads `tech_stack.lang` to pick the per-stack default tier matchers.
+- Phase 2.5 (security scanning) reads `tech_stack.lang` to seed the scanner adapter.
+- Future Phase 2.x for `hook_chain` reads stack signals to pick per-stack hook defaults.
+
+##### 2.3.7 Seed testing.path_matchers per declared tech_stack
+
+Phase 2.3.5 wrote the `testing` block with `global_floor: 1` + empty `path_matchers`. Phase 2.3.6 just discovered + wrote `tech_stack`. This step reads `tech_stack.lang` and seeds `testing.path_matchers` with sensible per-stack defaults so the Tier 0 / Tier 1 enforcer (Phase 2.2.8) fires on the right paths from day one.
+
+**Per-stack default seeds** (operator-eyes design choices):
+
+For `tech_stack.lang: typescript` + `tech_stack.frontend: nextjs` (bassclef default):
+
+```jsonc
+"testing": {
+  "global_floor": 1,
+  "path_matchers": [
+    { "match": "lib/domain/**/*.ts",          "tier": 0 },
+    { "match": "lib/infra/**/*.ts",           "tier": 0 },
+    { "match": "app/api/**/*.ts",             "tier": 1 },
+    { "match": "app/actions/**/*.ts",         "tier": 1 },
+    { "match": "app/_components/**/*.tsx",    "tier": 2 },
+    { "match": "app/**/*.tsx",                "tier": 2 },
+    { "match": "docs/**/*.md",                "tier": 3 }
+  ]
+}
+```
+
+For `tech_stack.lang: python` + `tech_stack.frontend: fastapi`:
+
+```jsonc
+"testing": {
+  "global_floor": 1,
+  "path_matchers": [
+    { "match": "domain/**/*.py",              "tier": 0 },
+    { "match": "infrastructure/**/*.py",      "tier": 0 },
+    { "match": "api/**/*.py",                 "tier": 1 },
+    { "match": "templates/**/*",              "tier": 2 },
+    { "match": "docs/**/*.md",                "tier": 3 }
+  ]
+}
+```
+
+Other stacks (ruby-rails, go-gin, java-spring) ship default seeds as per-stack siblings under `standards/testing-tier-seeds/<stack>.md` — deferred to a follow-on ticket when an adopter on that stack files for them. The pattern is the same: Tier 0 on the essential pure-domain layer; Tier 1 on the API + actions layer; Tier 2 on UI + template surfaces; Tier 3 on docs.
+
+**On `tech_stack.lang: none` or `deferred`** — skip the seed; leave `path_matchers: []` empty. The `global_floor: 1` keeps the WARN posture; adopter can hand-edit later.
+
+**Operator prompt** (surface this exact text after Phase 2.3.6 completes):
+
+```
+Tech stack: <detected lang + frontend>
+
+Seed testing.path_matchers with the per-stack default for <stack>?
+
+  [a] Yes, accept default seed (recommended)
+  [b] Show me the seed first
+  [c] Skip — keep path_matchers empty (manual seed later)
+
+Pick a/b/c:
+```
+
+**On accept (a)** — write the matching per-stack seed into `testing.path_matchers` in `bassclef-configs.jsonc`. Use the comment-aware JSONC editor pattern so the existing comments + `global_floor` survive.
+
+**On show first (b)** — print the seed inline; ask for accept/edit/skip.
+
+**On skip (c)** — leave empty; print "Adopter chose to skip — `testing.path_matchers` stays empty. Set with `/onboard-repo` re-run or hand-edit later."
+
+**Validate after write:**
+
+```bash
+perl -pe 's,^\s*//.*$,,; s,/\*.*?\*/,,g' .claude/bassclef-configs.jsonc \
+  | ajv validate -s ~/src/sunj-labs/bassclef/standards/state-spine/schemas/bassclef-configs.schema.json \
+                 -d - --spec=draft2020 -c ajv-formats
+```
+
+Expect a single `valid` line. The `testing.path_matchers` items must validate against the bassclef-configs schema.
+
+**Stack siblings deferred** — only typescript-nextjs + python-fastapi ship in this step. Adopters on ruby-rails / go-gin / java-spring / rust-axum etc. get `global_floor: 1` + empty matchers (the safe default WARN posture) and can hand-seed per their layout. A follow-on ticket adds per-stack seed siblings under `standards/testing-tier-seeds/<stack>.md` as adopters request them.
+
+Source: bassclef#1143 (this seed step — T10, iteration-2 BLOCKER). Sister rule: `.claude/rules/testing-tier-config.md`. Pairs with Phase 2.2.8 (the enforcer that reads this seed).
+
+##### 2.3.8 Surface the wiki_sync toggle
+
+The `wiki_sync` block in `.claude/bassclef-configs.jsonc` controls whether the adopter's repo gets the bassclef-docs-sync workflow vendored from `presence/install/bassclef-docs-sync.template.yml`. This step surfaces the toggle so adopters see the option exists.
+
+**Phase 1 (this step — bet 2026-06-20b) — minimal stub:**
+
+Read the adopter's `wiki_sync.enabled` value from the bassclef-configs file just written. Print one of the following:
+
+- **`enabled: false`** (default — universal): print
+  > Wiki-sync is OFF. The wiki-as-we-go discipline rule still loads at session-start, but no workflow fires. To enable later: edit `.claude/bassclef-configs.jsonc` `wiki_sync.enabled` to `true` and re-run `/onboard-repo` for the vendoring step (full vendoring lands in Phase 2 of bet 2026-06-20b — see `docs/iteration-bets/2026-06-20b-cold-adopter-mechanism-inheritance.md`).
+- **`enabled: true`**: print
+  > Wiki-sync is ON. Full vendoring of `presence/install/bassclef-docs-sync.template.yml` → `.github/workflows/bassclef-docs-sync.yml` + `presence/install/docs-sync-allowlist.template.md` → `standards/docs-sync-allowlist.md` is **deferred to Phase 2 of bet 2026-06-20b**. For now, copy both templates manually if you need the wiki to update from main pushes today.
+
+**Phase 2 (next session) — full vendoring (deferred):**
+
+- Auto-copy both templates into the adopter's repo
+- Open a follow-up PR for GHA secrets if `target_wiki_repo` requires non-default auth
+- Walk the adopter through the three workflow-edit surfaces (the `on.push.paths` glob, the Filter step's case-glob, the Sync step's source-path → wiki-page mapping)
+- Smoke-test by pushing a docs change and verifying the wiki updates
+
+The Phase 1 stub keeps this step minimal so the goal stays bounded. Adopters who want wiki-sync today can copy the templates by hand from bassclef's `presence/install/` (workflows + cold-adopter assets).
+
+**Composes with:**
+
+- `.claude/skills/docs-sync/SKILL.md` § Adopter mode (read at runtime; surfaces BLOCK if templates not vendored)
+- `.claude/rules/session-artifacts.md` § Wiki-as-we-go discipline (methodology rule that triggers the closeout question)
+
+Source: bassclef#1265 (this surfacing step — wiki-sync mechanism adopter inheritance). Sister bet: `docs/iteration-bets/2026-06-20b-cold-adopter-mechanism-inheritance.md` WU-2.
+
+##### 2.3.9 Write the onboard-repo state marker
+
+Write `.claude/state/onboard-repo.state.json` after Phase 2.3 has
+populated the config file(s). The marker captures which mode was used,
+the ISO timestamp, and which files were written. The configs UI reads
+this marker to render the first-run overlay (per canvas 2026-07-08
+Appendix C). Future audits trace how a repo got wired.
+
+Re-runs append a history entry — the marker keeps prior runs, not
+clobber them.
+
+Invoke the helper script that ships alongside this SKILL:
+
+```bash
+# ONBOARD_MODE is set earlier in Procedure —
+#   default / --with-deploy-host / --with-secrets / --full / --greenfield-from-intent
+bash .claude/skills/onboard-repo/write-state-marker.sh "${ONBOARD_MODE:-default}"
+```
+
+The script writes / updates `.claude/state/onboard-repo.state.json`
+with shape `{mode, timestamp_iso, paths_written[], history[], skill_version}`.
+Tier 0 tests at `.claude/skills/onboard-repo/tests/write-state-marker.test.sh`
+pin all behavior including re-run history append.
+
+**Composes with:**
+
+- Configs UI first-run overlay (`bassclef/configs/`, bet 2026-07-08a WU-7)
+- Future audits reading `.claude/state/onboard-repo.state.json`
+
+Source: bassclef-upstream#664 (state marker for onboard-repo). Part of goal
+`docs/iteration-bets/2026-07-08a-configs-ui-iteration-1.md` WU-4.
+
+##### 2.3.10 Wire the cron installer for auto-save
+
+Goal 27b (PR #937) shipped `presence/install/schedule-auto-save.cron.sh` at
+`tier: lite`. The installer writes a cron entry that fires
+`save-state.sh --auto --quiet` on idle. Sam's magic demo per canvas
+`docs/canvases/2026-07-19-bassclef-lite.md` L67-71 promises session-state
+continuity as part of onboarding. This step wires the installer in.
+
+Behavior per OS:
+
+- **macOS + Linux + WSL** — run the installer directly. It appends one
+  crontab entry and is idempotent (re-running is safe per PR #937 Test 4).
+- **Native Windows (no WSL)** — cron is not available. Point the adopter at
+  `presence/install/schedule-auto-save.taskscheduler.md` for the manual
+  Task Scheduler setup.
+
+```bash
+OS_KIND="$(uname -s)"
+case "$OS_KIND" in
+  Darwin|Linux)
+    if [ -x "$BASSCLEF_DIR/presence/install/schedule-auto-save.cron.sh" ]; then
+      bash "$BASSCLEF_DIR/presence/install/schedule-auto-save.cron.sh" \
+        || echo "WARNING: cron installer failed; run manually to enable auto-save" >&2
+    else
+      echo "WARNING: schedule-auto-save.cron.sh not found; skip auto-save wire" >&2
+    fi
+    ;;
+  MINGW*|CYGWIN*|MSYS*)
+    echo "Native Windows detected. Cron is not available."
+    echo "See presence/install/schedule-auto-save.taskscheduler.md for the"
+    echo "manual Task Scheduler setup that wires auto-save on Windows."
+    ;;
+  *)
+    echo "Unknown OS '$OS_KIND'; skip auto-save wire"
+    ;;
+esac
+```
+
+The installer prints its own progress. Failures do not stop onboarding —
+auto-save is a nice-to-have on first install, and adopters can re-run
+the installer any time via `bash $BASSCLEF_DIR/presence/install/schedule-auto-save.cron.sh`.
+
+**Composes with:**
+
+- `presence/install/schedule-auto-save.cron.sh` (PR #937 — the cron installer)
+- `presence/install/schedule-auto-save.taskscheduler.md` (PR #937 — Windows guide)
+- ADR-046 cross-OS scheduling (accepted; Option C picked)
+
+Source: bassclef-upstream#941 (wire cron into onboard for Sam's magic demo).
+
+##### 2.4 Point at bassclef's source (URL + auth)
+
+The thin-pointer dispatcher installed in 2.1 reads `.bassclef-source.json`
+for the upstream tarball URL + auth metadata when the curl fallback
+fires (Cloud Env / mobile / fresh sandboxes / CI). Schema codified at
+`standards/bassclef-source-config.md`; validation hook at
+`.claude/hooks/bassclef-source-config-validate.sh`.
+
+Before writing the file, prompt the adopter explicitly:
+
+```
+Bassclef can auto-pull the latest skills, rules, and agents into this
+repo at every Claude Code session start. Keeps you current with bassclef's
+evolution; you never manually update.
+
+Off by default. Turn on now? [y/N]
+```
+
+Persist the adopter's answer to the `auto_sync` field. Default is `false` when in doubt.
+
+```bash
+cat > .bassclef-source.json <<JSON
+{
+  "source_url": "https://api.github.com/repos/sunj-labs/bassclef/tarball/main",
+  "auth_method": "Bearer",
+  "token_env": "BASSCLEF_TOKEN",
+  "auto_sync": false,
+  "comment": "Provider: GitHub repo tarball API. Auth: fine-grained PAT 'bassclef-substrate-read' (Contents:read on sunj-labs/bassclef), stored as BASSCLEF_TOKEN in the consumer's Cloud Code environment. Schema: standards/bassclef-source-config.md. auto_sync controls whether SessionStart fetches bassclef's latest substrate; off by default per bassclef#939."
+}
+JSON
+```
+
+**Operator action — out of band, one-time per consumer:**
+
+1. Create fine-grained GitHub PAT scoped to `sunj-labs/bassclef`
+   - Permission: Contents: read
+   - Expiry: 90 days
+   - Name: `bassclef-read-{REPO_SHORT}-{YYYYMMDD}`
+2. Paste into the consumer's Cloud Code environment as `BASSCLEF_TOKEN`.
+3. Track the PAT lifecycle in operator's `substrate.secrets.md` per
+   `standards/secrets-lifecycle.md`.
+
+Provider alternatives (see `standards/bassclef-source-config.md` for
+GitHub public, GitHub private release, ADO Repos, GitLab examples).
+
+After writing the file, run the hook once locally to validate via
+sibling fast-path (no PAT needed for desktop):
+
+```bash
+echo "{\"cwd\":\"$PWD\"}" | bash .claude/hooks/bassclef-sync.sh
+```
+
+Expect: `### BASSCLEF SUBSTRATE — SYNCED` banner; skills/rules/hooks/
+luminaries symlinked into `.claude/`; no errors surfaced.
+
+##### 2.5 Configure security scanning (per bassclef goal 2026-06-17a Phase Y)
+
+Auto-detect the adopter's stack from build files, confirm with the operator, and write the `security_scanning` block to `.claude/bassclef-configs.jsonc`. Adopter copies the matching reference workflow next.
+
+Auto-detection signals (per `standards/security-scanner-adapter.md` § Stack auto-detection):
+
+```bash
+# Detect stack by build-file signal.
+STACK_GUESS="custom"
+if [ -f "package.json" ]; then
+  if grep -q '"typescript"\|"@types/' package.json; then
+    STACK_GUESS="node-typescript"
+  else
+    STACK_GUESS="node-typescript"  # TS opt-out can happen later
+  fi
+elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ] || [ -f "setup.py" ]; then
+  STACK_GUESS="python"
+elif [ -f "Gemfile" ] || ls *.gemspec >/dev/null 2>&1; then
+  STACK_GUESS="ruby"
+elif [ -f "pom.xml" ] || [ -f "build.gradle" ] || ls **/*.java >/dev/null 2>&1; then
+  STACK_GUESS="java"
+elif [ -f "go.mod" ] || ls **/*.go >/dev/null 2>&1; then
+  STACK_GUESS="go"
+fi
+```
+
+Prompt the operator (sample):
+
+```
+Bassclef security scanner adapter detected stack: <STACK_GUESS>
+
+Default scanners for this stack (per standards/security-scanner-adapter.md):
+- node-typescript: eslint-plugin-security + audit-ci + gitleaks
+- python: bandit + safety + gitleaks
+- ruby: brakeman + bundler-audit + gitleaks
+- java: spotbugs-security + dependency-check + gitleaks
+- go: gosec + govulncheck + gitleaks
+- custom: adopter-supplied list
+
+Activate scanners with stack=<STACK_GUESS>? [Y/n/custom/skip]
+```
+
+Persist the answer to the bassclef-configs block. Phase 2.3.5 (bassclef#1135 WU-4) wrote the seed file; this step adds the `security_scanning` block to it via a Python merge to keep the JSONC valid.
+
+```bash
+# Add security_scanning block to .claude/bassclef-configs.jsonc (bassclef#1135).
+# Phase 2.3.5 already wrote the seed; we add a block via JSONC-aware Python merge.
+python3 - "$STACK_GUESS" <<'PY'
+import json, re, sys, pathlib
+path = pathlib.Path('.claude/bassclef-configs.jsonc')
+raw = path.read_text()
+# Strip line + block comments before parsing
+stripped = re.sub(r'/\*.*?\*/', '', re.sub(r'//.*$', '', raw, flags=re.M), flags=re.S)
+data = json.loads(stripped)
+stack = sys.argv[1]
+data['security_scanning'] = {
+    'stack': None if stack in ('null', 'skip', '') else stack,
+    'additional_scanners': [],
+    'block_on_high_severity': True,
+}
+path.write_text(json.dumps(data, indent=2) + '\n')
+PY
+```
+
+Note: the Python merge re-serializes the file without comments. Operators
+keep the schema-doc reference (`standards/bassclef-configs-schema.md`)
+as the bassclef comment-bearing source; the on-disk file is the values.
+A follow-on may add a comment-preserving JSONC writer.
+
+INSTEAD of asking the operator to know the scanner names: the standard supplies the per-stack defaults; the operator confirms the stack choice only.
+
+If the operator answers `skip`, write `"stack": null` — scanners stay off until the next session re-runs the question.
+
+**Operator follow-up — copy the reference workflow:**
+
+After the bassclef-configs block is written, point the operator at the matching reference workflow:
+
+```
+Next step: copy the per-stack reference workflow into your repo's CI.
+
+  cp ~/src/sunj-labs/bassclef/config/security-scanners/<STACK_GUESS>.yml \
+     .github/workflows/security-scan.yml
+
+The workflow auto-skips when the bassclef-configs stack value is null,
+so copying is harmless if you're not ready to activate yet.
+```
+
+For stacks beyond node-typescript + python (which ship reference workflows), the operator authors their own workflow guided by `standards/security-scanner-adapter.md` § Stack reference matrix.
+
+##### 2.6 Set up .gitignore for bassclef's runtime files
+
+If `.gitignore` doesn't exist, create with bassclef runtime markers:
+
+```bash
+[ -f .gitignore ] || cat > .gitignore <<'EOF'
+# Bassclef runtime artifacts (per-machine, not content)
+.claude/LAST_SAVE
+.claude/SESSION_LOCK
+.claude/CHECKPOINT.md
+.claude/settings.local.json
+state/markers/verify/
+EOF
+```
+
+The sync hook will add its managed symlink block on next run; this
+seeds the file with everything else.
+
+#### Phase 3 — Create starter docs (CLAUDE.md, whereami)
+
+**Working directory: target repo.**
+
+##### 3.1 Create the starter CLAUDE.md
+
+Minimal starter. Operator owns this file going forward.
+
+The first non-title line reads `@.claude/bassclef-orientation.md` (per
+ADR-032 + Anthropic's `@filename` convention). This import loads bassclef's
+orientation into every session. The orientation names the gates, the
+luminaries, the tier ladder, and the rules the agent should not break.
+
+The orientation file lands in the adopter repo as a symlink into bassclef.
+The sync template Section 3d-bis writes the symlink.
+Without this symlink, the import resolves only through `additionalDirectories`.
+If that path breaks — rename, delete, corporate laptop with no sibling — the
+import silently no-ops. The symlink closes that gap.
+
+Bassclef updates the file via release. The adopter's CLAUDE.md stays
+adopter-owned outside the import line.
+
+```markdown
+# [repo-name]
+
+@.claude/bassclef-orientation.md
+
+## What this repo is
+
+[One-paragraph description]
+
+## Substrate
+
+Inherits bassclef substrate via `--add-dir ../bassclef` (desktop) and
+S3 tarball sync (mobile). The `@.claude/bassclef-orientation.md` import
+above auto-loads the substrate discipline (gates, luminaries, tier ladder,
+what-NOT-to-do). For the upstream role declaration, see
+`~/src/sunj-labs/bassclef/CLAUDE.md`.
+
+## Stack
+
+[Framework, language, key dependencies — or "documentation only"]
+
+## Current state
+
+[Phase, active iteration, any context a fresh session needs]
+```
+
+##### 3.2 Create the starter docs/whereami.md
+
+```bash
+mkdir -p docs
+cp ~/src/sunj-labs/bassclef/templates/whereami-template.md \
+   docs/whereami.md
+```
+
+Operator fills in phase + iteration section. If repo is fresh,
+`phase: Inception` with `iteration_bet: none — new repo` is fine.
+
+#### Phase 3.5 — Optional: provision the deploy host + bootstrap secrets
+
+**Working directory: target repo.**
+
+After Phase 3 (docs stubs) lands the substrate config files, three opt-in
+flags chain follow-on skills inline so every new sunj-labs repo bootstraps
+in one dispatch instead of four manual steps. Without these flags, the
+operator runs the follow-on skills separately afterward (older pattern,
+still supported).
+
+##### Flag reference
+
+| Invocation | Behavior |
+|---|---|
+| `/onboard-repo` (no flag) | Phases 1–3 only. Interactive prompt at end: "Run /provision-deploy-host now? [Y/n/skip]" + same for /secrets-bootstrap. Skip-state persists per below. |
+| `/onboard-repo --with-deploy-host` | Phases 1–3, then dispatches `/provision-deploy-host` inline (operator-confirms before AWS calls). Skips the interactive prompt for deploy-host. |
+| `/onboard-repo --with-secrets` | Phases 1–3, then dispatches `/secrets-bootstrap` inline (audits + bootstraps env per substrate.secrets.md). Skips the interactive prompt for secrets. |
+| `/onboard-repo --full` | All of the above — substrate scaffolded + Amplify host provisioned + secrets audited in one dispatch. Recommended for new sunj-labs repos. |
+| `/onboard-repo --greenfield-from-intent "<intent>"` | Cold-adopter demo path. Skips Path A entirely and runs Path B — empty directory in, full artifact chain on disk plus localhost gallery URL out. No GitHub repo gets created. No vendor accounts needed. Uses the LLM your Claude Code session provides. For the extended path (deploy mocks to a configured subdomain plus chain to `/build` plus `/launch-preview`), finish Path A first to wire vendor bindings, then dispatch `/launch --voice-input` without `--local`. See `docs/iteration-bets/2026-05-12-phase-v-hey-alexa-mvd.md` and bassclef#923 / PR #924 for the local-mode building block. |
+
+##### Tier gate
+
+Three of the flags above dispatch skills that ship at `tier: standard`.
+Lite adopters running the bassclef-lite tarball do not carry
+`/provision-deploy-host` or `/secrets-bootstrap`. Before dispatching
+`--with-deploy-host`, `--with-secrets`, or `--full`, resolve the
+adopter tier through `lib/tier-check.sh`:
+
+```bash
+source lib/tier-check.sh
+tier=$(resolve_adopter_tier)
+```
+
+The check reads `.claude/bassclef-configs.jsonc` `adopter.tier` field
+first. Falls back to skill probe — presence of `/provision-deploy-host`
+skill returns `standard`. Safe default is `standard`.
+
+Behavior per tier:
+
+| Invocation | tier=lite | tier=standard or pro |
+|---|---|---|
+| `/onboard-repo` (no flag) | Phases 1–3 run. Skip interactive prompts for /provision-deploy-host and /secrets-bootstrap. | Phases 1–3 + interactive prompts. |
+| `/onboard-repo --with-deploy-host` (lite adopter) | Print graceful upgrade message: "--with-deploy-host requires bassclef standard. Reason: /provision-deploy-host is a standard-tier skill. Upgrade path: install bassclef standard, or run Phases 1–3 without the flag and provision the deploy host manually later." Continue Phases 1–3 as if no flag was passed. | Phases 1–3 + `/provision-deploy-host` dispatched inline. |
+| `/onboard-repo --with-secrets` (lite adopter) | Print graceful upgrade message: "--with-secrets requires bassclef standard. Reason: /secrets-bootstrap is a standard-tier skill. Upgrade path: install bassclef standard, or run Phases 1–3 without the flag and manage secrets manually via substrate.secrets.md." Continue Phases 1–3. | Phases 1–3 + `/secrets-bootstrap` dispatched inline. |
+| `/onboard-repo --full` (lite adopter) | Print graceful upgrade message: "--full requires bassclef standard. Reason: /provision-deploy-host and /secrets-bootstrap are both standard-tier skills. Upgrade path: install bassclef standard." Continue Phases 1–3. | Phases 1–3 + both skills dispatched inline. |
+| `/onboard-repo --greenfield-from-intent` | Runs Path B via `/launch --local`. Lite-safe by design. | Same. |
+
+Per canvas 2026-07-19-bassclef-lite Q6 Option E — one SKILL.md file,
+same name in both tiers, body carries runtime tier awareness with
+graceful degrade.
+
+##### Interactive prompt (when no flag)
+
+After Phase 3 completes, agent surfaces follow-on prompts. Prompts are
+gated on artifact existence and the deploy-host prompt
+uses honest platform framing:
+
+```bash
+# Check for substrate.secrets.md (bassclef#961) — silently skip the
+# secrets prompt if the manifest doesn't exist. No point prompting an
+# adopter to bootstrap secrets when they haven't declared any.
+HAS_SECRETS_MANIFEST=0
+if [ -f substrate.secrets.md ]; then
+  HAS_SECRETS_MANIFEST=1
+fi
+```
+
+Then surface (deploy-host always; secrets only when manifest present):
+
+```
+Substrate scaffolded. One or two follow-on steps remain before /launch
+runs cleanly end-to-end:
+
+1. /provision-deploy-host — provisions a preview deploy host. Tested
+   today with AWS Amplify; other platforms (Vercel, Netlify, Cloudflare
+   Pages, GCP, Azure) ship via adapter PRs. If you want a platform that
+   doesn't ship yet, file a ticket — or build the adapter (it's a single
+   shell script following `scripts/adapters/deploy/amplify.sh` as the
+   reference). The provision takes ~1-2h, mostly waiting. Required
+   before /launch can bind a subdomain on the chosen host. Skip if this
+   repo opts out of preview deployment (hosting_platform: none) or if
+   you want to provision later.
+
+2. /secrets-bootstrap — audits + bootstraps env credentials per
+   substrate.secrets.md. Required before /launch, /deploy-prod, or
+   /journal push. Skip if creds are already known-good.
+
+Run /provision-deploy-host now? [Y/n/skip]
+Run /secrets-bootstrap now? [Y/n/skip]
+```
+
+When `HAS_SECRETS_MANIFEST=0` (no substrate.secrets.md on disk), the
+agent OMITS step 2 entirely + the second prompt — no "(likely no-op)"
+hedge, no prompt asking the adopter to bootstrap secrets they haven't
+declared. The numbered list collapses to "One follow-on step remains".
+
+Each `Y` triggers the inline dispatch (operator-confirms any destructive
+substep — AWS calls, env writes). Each `n` defers to a later session.
+Each `skip` persists in `substrate.config.md` so re-running /onboard-repo
+on this repo doesn't re-prompt for that step.
+
+The deploy-host prompt wording matters: cold adopters reading it should
+understand bassclef's posture on multi-platform support without
+operator coaching. "Tested with AWS Amplify; other platforms via
+adapter PRs" reads as honest (we have one tested path + a clear
+contribution route) instead of overpromising. Filing a ticket for an
+unsupported platform is invited, not gated.
+
+##### Skip-state persistence
+
+When operator chooses `skip` (not `n`) for a follow-on step, the agent
+writes one of these fields to `substrate.config.md`:
+
+```yaml
+# === Onboarding follow-on skip state (bassclef#522) ===
+#
+# Set by /onboard-repo when the operator explicitly skips a follow-on
+# step. Re-runs of /onboard-repo do NOT re-prompt for skipped steps;
+# operator can dispatch the underlying skill directly when ready, or
+# unset the field to re-enable the prompt.
+onboarding_deploy_host_skipped: true   # set when operator answers 'skip'
+onboarding_secrets_skipped: true       # set when operator answers 'skip'
+```
+
+`n` (decline-this-time) does NOT persist — re-runs re-prompt because the
+operator didn't say skip-permanently.
+
+`Y` sets the per-platform provisioning indicator (e.g., `amplify_app_id`) on success. Chain pre-flight Check 6 reads that indicator when /launch dispatches. Without it, /launch BLOCKs with three-path remediation. The two flags pair well. `--with-deploy-host` pre-empts the BLOCK. The default flow lets the BLOCK surface the missing setup.
+
+##### Composes with
+
+| Skill | Role |
+|---|---|
+| `/provision-deploy-host` | Inline dispatch when `--with-deploy-host` or interactive `Y`. Populates `amplify_app_id` (or platform-equivalent indicator). |
+| `/secrets-bootstrap` | Inline dispatch when `--with-secrets` or interactive `Y`. Audits creds against `substrate.secrets.md`. |
+| `/bind-subdomain <subdomain>` | Separate dispatch — not chained from /onboard-repo (subdomain choice is repo-specific; no good default). Run after deploy host provisioned. |
+| `/launch` | First substantive dispatch after onboarding completes. Chain pre-flight Check 6 verifies the provisioning indicator before variant generation runs. |
+
+#### Phase 3.6 — Closing handoff
+
+After Phase 3 (and Phase 3.5 if any flag fired), Path A surfaces a
+closing handoff. Two templates — adopter-mode and operator-mode —
+mirror the same split documented at `.claude/skills/launch/SKILL.md`
+Phase 14b.
+
+##### Adopter-mode auto-chain (default when context signals cold-adopter)
+
+Cold-adopter signals: `/onboard-repo` was invoked from a fresh
+directory (no prior chronicle / no whereami / no iteration-goal), OR
+the `--greenfield-from-intent "<paragraph>"` flag was used. In either
+shape, the agent has a paragraph in hand (either from the flag or
+asked at Phase 1 as part of the "what is this repo for?" prompt).
+
+The adopter-mode handoff template re-uses that paragraph and offers
+the build:
+
+```
+Your repo is wired. Two things you can do next — pick one:
+
+1. Build something now. I'll take the paragraph you gave me earlier
+   ("<INTENT_PARAGRAPH>") and run /launch --local. About 4 minutes
+   later you'll have four clickable mock directions to pick from on
+   your phone or laptop. After you pick a direction, I'll write the
+   formal artifacts + the app code for that direction only (~15 min
+   total). You'll have a working local version to play with.
+
+2. Stop here and come back later. I'll save your spot. When you come
+   back, just open Claude Code in this repo and say "/launch --local"
+   to pick up where we left off.
+
+Build now? [Y/n]
+```
+
+`Y` triggers `/launch --local "<INTENT_PARAGRAPH>"` inline in the
+same session — no context switch, no second dispatch. `n` writes
+the paragraph to `docs/whereami.md` under "Pending intent" so the
+next session's `/sprint` surfaces it.
+
+Substitute `<INTENT_PARAGRAPH>` with the actual paragraph (from
+`--greenfield-from-intent` flag value OR from the Phase 1 "what is
+this repo for?" prompt — operator confirms it's still accurate before
+the auto-chain fires).
+
+The adopter-mode handoff **skips entirely**:
+- "Run /sprint to orient" — adopter has no work in flight to orient
+  to
+- "Run /whereami" — same
+- Bare command names (`/launch`) without the plain-English explanation
+  of what /launch produces
+
+##### Operator-mode handoff (non-cold-adopter context)
+
+This mode fires when cold-adopter signals are absent. Signals absent means: the repo has prior chronicles, whereami is populated, OR the operator passed `--no-auto-chain`. The agent uses this wording:
+
+```
+Your bassclef is ready.
+
+What landed this session:
+- Skills, rules, and hooks synced from bassclef
+- GitHub labels + branch protection set up
+- Session-start wiring wired
+
+Best single next move — try /sprint in a fresh session. It reads
+your current state and proposes the next work.
+
+Other useful next moves:
+- /whereami — current state in one glance
+- /launch <tier> "<paragraph>" — start a new feature; see /launch
+  SKILL.md for sizes + flags
+- /launch --local "<paragraph>" — same as above but writes artifacts
+  to disk + serves the gallery on localhost (no vendor accounts
+  needed)
+
+Run any of those in a fresh session.
+```
+
+Operator-mode keeps a hard break between onboard and build. Operators often onboard a repo as one task. They pick up build work later in a fresh session.
+
+##### Composes with
+
+| Skill | How it composes |
+|---|---|
+| `/launch --local` | Adopter-mode auto-chain dispatch. Inline in same session. |
+| `/sprint` | Operator-mode orientation skill. Surfaces "Pending intent" if `n` was chosen for the build-now prompt. |
+| `/whereami` | Same. |
+
+#### Phase 4 — Bassclef-side matrix PRs
+
+**Phase 4 retired under bassclef goal 2026-05-03-consumer-bassclef-sync-rollout WU-7.**
+
+Under thin-pointer architecture (Phase 2.1 + 2.4 above), the `bassclef-template-sync.yml` workflow is deleted (no more auto-PRs). The `bassclef-s3-publish.yml` URL-refresh matrix is unused by thin-pointer (no `.bassclef-url`); a follow-on issue tracks its retirement separately.
+
+**No matrix-PR step is needed for new consumers.** The thin-pointer dispatcher reads from `.bassclef-source.json` directly; bassclef's matrix list is no longer the source of truth for which consumers receive substrate updates — every consumer fetches HEAD on every session-start.
+
+Skip this phase entirely. Phase 5 (Verify) below validates that the consumer is correctly wired without any bassclef-side matrix change.
+
+#### Historical note
+
+Pre-2026-05-03, this phase added the new consumer to BOTH `bassclef-s3-publish.yml` and `bassclef-template-sync.yml` matrices. The 2026-04-18 lesson (#166 caught a one-of-two miss after #158) drove the bassclef-workflow-parity rule. With both workflows retired/unused under thin-pointer, the parity rule no longer applies to this surface.
+
+## Verify (acceptance)
+
+Acceptance differs per path.
+
+### Path A — verify everything's wired correctly (after Phases 1–3 + 3.5 if flagged)
+
+- [ ] `gh label list --repo "$REPO"` shows all 11 standard labels
+- [ ] `gh api repos/$REPO/branches/$DEFAULT_BRANCH/protection` returns 200
+- [ ] (If applicable) `gh api repos/$REPO/environments/prod` shows required_reviewers
+- [ ] `.claude/hooks/bassclef-sync.sh` is executable
+- [ ] `.claude/settings.json` validates as JSON
+- [ ] `substrate.config.md` has no `TODO:` markers (or operator approved deferring them)
+- [ ] `.bassclef-source.json` exists, validates against bassclef schema (`standards/bassclef-source/schemas/bassclef-source.schema.json`), references a valid `BASSCLEF_TOKEN` env var, and has an explicit `auto_sync` value (true OR false) set by the adopter at Phase 2.4 — silence is not deferral here
+- [ ] Running the sync hook produces no errors; banner shows `### BASSCLEF SUBSTRATE — SYNCED`; symlinks resolve
+- [ ] `CLAUDE.md` exists with at least a one-paragraph description
+- [ ] `docs/whereami.md` exists with phase + iteration filled in
+- [ ] **(Retired)** ~~Bassclef PR opened with both workflow matrices updated~~ — Phase 4 retired under bassclef goal 2026-05-03 WU-7
+- [ ] Test session in target repo: `claude` → SessionStart hook fires → no BLOCKED items from missing substrate
+
+### Path B acceptance — after Phases B.1–B.5
+
+- [ ] Generated task list had at most 5 tasks (Phase B.1–B.5); no Path A phases queued
+- [ ] No `gh` calls fired during the dispatch
+- [ ] No `gh repo create`, no `gh api .../environments/prod`, no branch-protection writes
+- [ ] `.git/` exists with at least one commit
+- [ ] `.claude/hooks/bassclef-sync.sh` is executable
+- [ ] `.claude/settings.json` validates as JSON
+- [ ] `substrate.config.md` exists with `hosting_platform: none`
+- [ ] `CLAUDE.md` exists
+- [ ] `/launch --local --voice-input` was the final dispatch (not extended `/launch` and not `/build` and not `/launch-preview`)
+- [ ] `/launch` emitted a `localhost:80xx` URL pointing at the generated gallery
+- [ ] Operator opened the URL and saw the variants gallery
+
+## What NOT to do
+
+- **Do not** restore Phase 4 — the bassclef-template-sync.yml workflow is retired. Adding new consumers to a deleted matrix produces nothing.
+- **Do not** vendor `bassclef-sync.template.sh` directly — that was the pre-2026-05-03 pattern. The thin-pointer dispatcher reads `.bassclef-source.json` and fetches bassclef's CURRENT logic at fire-time. Vendoring reproduces the drift problem WU-7 retires.
+- **Do not** auto-merge the bassclef-side PR. Bassclef is the trust
+  root; every matrix change needs operator review.
+- **Do not** hardcode the presigned URL anywhere — read from
+  `.bassclef-url` at runtime.
+- **Do not** copy `.claude/settings.local.json` from another repo — it's
+  machine-local per-operator permission grants.
+- **Do not** commit secrets. The sync URL expires in ~7 days; don't
+  treat it as a secret, but don't commit long-lived tokens either.
+- **Do not** mix Path A and Path B in one dispatch. If the operator picked
+  Path B at the prereqs-missing menu, skip every Path A phase — don't
+  generate a task list that walks Phase 1.1 / 1.2 / 1.3 / 2.4 / 3.5 /
+  Phase 4. The whole point of Path B is the ≤5-step task list ending
+  in `/launch --local --voice-input`. Any Path A task that leaks into a
+  Path B run is the bassclef#934 regression.
+- **Do not** chain `/build` or `/launch-preview` after Path B's final
+  dispatch. Path B's deliverable is the localhost URL `/launch --local`
+  emits; the extended chain belongs to operators with vendor bindings.
+
+## Relationship to other skills
+
+- **`/autonomous start`** — runs AFTER `/onboard-repo` to set up iteration
+  scaffolding. `/onboard-repo` does the one-time wiring; `/autonomous
+  start` does the per-iteration setup.
+- **`/substrate-check`** — validates substrate wiring AFTER onboarding.
+  Run it as a post-flight check.
+- **`/promote`** — once onboarded, the new repo can file
+  `bassclef-evolution` issues. The labels bootstrapped in Phase 1.1
+  make them scannable.
+
+## Source
+
+Ritual observed 4x on 2026-04-17: four consumer repos (refresh). Each took ~15 minutes by hand.
+Codified here so the fifth, sixth, and nth take ~3 minutes.
+
+Closes bassclef #164.
+
+Path B added 2026-06-13. Cold-adopter smoke test on `new-recipe-test`
+2026-06-13 01:30am showed PR #931's edit to the flag-row description
+was cosmetic — `--greenfield-from-intent` still queued 12 standard
+onboarding tasks because the Procedure was monolithic. Refactor splits
+Procedure into Path A (standard, unchanged) and Path B (≤5 steps, no
+GitHub-remote operations, ends in `/launch --local --voice-input`).
+Closes bassclef#934.
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.