@marcomigozzi/trailhead 0.1.0 → 0.3.0

package/plugins/trailhead/skills/trailhead/SKILL.md

@@ -1,153 +1,181 @@
 ---
 name: trailhead
-description: Start and drive a large project — more than one agent session can hold — as a map of decision tickets on GitHub Issues, resolving one at a time until the way to the destination is clear. Self-contained: map-based onboarding and a discuss→plan→execute→verify engine with atomic commits, with everything — map, discussion, plan, verification — living on the Issues. No dependencies beyond an authenticated gh CLI. Invoke only when the user explicitly runs `/trailhead` (or a `/trailhead:<verb>` command) or asks to chart, adopt, or work a trailhead map — do not auto-invoke for generic planning, project, or task-tracking requests.
-argument-hint: "[new|adopt|work|ticket|inbox|map|config|grill|split|pause|resume|bug|todo|idea|seed|note] [text | ticket]"
+description: "Start and drive a large project (more than one agent session can hold) as a map of decision tickets on GitHub Issues, resolving one at a time until the way to the destination is clear. Self-contained: map-based onboarding and a discuss→plan→execute→verify engine with atomic commits, with everything (map, discussion, plan, verification) living on the Issues. No dependencies beyond an authenticated gh CLI. Invoke only when the user explicitly runs `/trailhead` (or a `/trailhead:<verb>` command) or asks to chart, adopt, or work a trailhead map, and do not auto-invoke for generic planning, project, or task-tracking requests."
+argument-hint: "[new|adopt|work|quick|whiteboard|ticket|inbox|map|config|grill|split|pause|resume|bug|todo|idea|seed|note] [text | ticket]"
 ---
 
-A loose idea has arrived, too big for one session: the way from here to the **destination** isn't visible yet. `trailhead` is where the trail begins. It charts the way as a **shared map on GitHub Issues**, then works its **tickets** — one at a time — until the road is clear and the destination reached.
+A loose idea has arrived, too big for one session: the way from here to the **destination** isn't visible yet. `trailhead` is where the trail begins. It charts the way as a **shared map on GitHub Issues**, then works its **tickets**, one at a time, until the road is clear and the destination reached.
 
-The method fuses two lineages, both as **inspiration** — `trailhead`'s core invokes no other skill and depends on nothing but an authenticated `gh` CLI (the one opt-in exception: `claude.ai/design` mockup mode uses Claude Code's built-in Claude Design, and falls back to disk if it's unavailable):
-- **From Wayfinder — the map.** Question-driven onboarding, the destination named first, the frontier, the fog of war, reference *by name*, one ticket per session.
-- **From GSD — the engine.** Zero-friction capture and the `discuss → plan → execute → verify` cycle with atomic commits that resolves each build ticket *inside* the map.
+The method fuses two halves; `trailhead`'s core invokes no other skill and depends on nothing but an authenticated `gh` CLI (the one opt-in exception: `claude.ai/design` mockup mode uses **DesignSync** (the `claude_design` MCP + `/design-sync` skill) to push to a design-system project, and falls back to disk if it's unavailable):
+- **The map.** Question-driven onboarding, the destination named first, the frontier, the fog of war, reference *by name*, one ticket per session.
+- **The engine.** Zero-friction capture and the `discuss → plan → execute → verify` cycle with atomic commits that resolves each build ticket *inside* the map.
 
-The techniques those lineages package as separate skills (grilling, TDD, systematic debugging, codebase mapping, code review) are **built in here as inline protocols** — see [Techniques](#techniques). `trailhead` is self-contained.
+The techniques commonly packaged as separate skills (grilling, TDD, systematic debugging, codebase mapping, code review) are **built in here as inline protocols** (see [Techniques](#techniques)). `trailhead` is self-contained.
 
 **Everything lives on the Issues.** No `.planning/`: the map is the parent issue, each ticket is a child issue, and discussion / plan / verification are **comments** on the ticket. The repo holds code only.
 
 ## Requirements
 
-Only an **authenticated `gh` CLI** — the tracker is GitHub Issues. Nothing else to install. The subagents `trailhead` spawns (research, codebase-map, review) use the built-in `Agent` tool; every technique is defined inline below.
+Only an **authenticated `gh` CLI**: the tracker is GitHub Issues. Nothing else to install. The subagents `trailhead` spawns (research, codebase-map, review) use the built-in `Agent` tool; every technique is defined inline below.
 
 ## Commands
 
-The **first word** of `$ARGUMENTS` is the verb; the rest is the text (or a ticket number). With no verb, `/trailhead` does **smart entry**: it detects the repo state and proposes — no map → offer *chart* or *adopt*; map present → *work* the next frontier ticket.
+The **first word** of `$ARGUMENTS` is the verb; the rest is the text (or a ticket number). With no verb, `/trailhead` does **smart entry**: it detects the repo state and proposes (no map → offer *chart* or *adopt*, or point at `/trailhead:whiteboard` if the repo has loose `trailhead:whiteboard` tickets but no map; map present with a workable frontier → *work* the next frontier ticket; **map present but its frontier is empty** (everything left is gated or still fog, or the map is complete-except-gated) → don't dead-end, lay out the sensible moves as a short list and **always include `/trailhead:quick "<text>"` right after `/trailhead:map`** as the way to do a discrete piece of work off the map now (`/trailhead:quick <n>` to work a loose ticket), alongside `/trailhead:map` for the full view, `/trailhead:whiteboard` when loose work waits, `/trailhead:new` to chart the next map, the captures (`todo`/`idea`/`bug`/`seed`) for new work, and graduating a fog line into a ticket when it's sharp enough). Smart entry also **self-heals the pinned dashboard**: it ensures the repo's `trailhead:dashboard` index exists and is pinned (create + pin only if missing, re-pin if the pin was dropped; never a body rewrite), so a repo that adopted trailhead before the dashboard existed gets one on the next bare `/trailhead`. See [The dashboard's self-heal note](#the-dashboard-a-pinned-repo-index).
 
-Every verb is also a **namespaced command** — `/trailhead:new`, `/trailhead:work`, `/trailhead:bug`, … — so typing `/trailhead` lists them all in the picker. They're thin wrappers that delegate here; `/trailhead <verb>` and `/trailhead:<verb>` are equivalent.
+**First-time config offer (once per project).** When a project has a map but **no `.trailhead/config.json` yet**, smart entry puts an **explicit two-way choice** to the user and waits for their pick: **(a) accept as-is** (continue on the current/proposed values, which writes an empty `{}`), or **(b) run `/trailhead:config`** to configure everything through the guided menu (models/design/TDD/…). **Always name both paths and let the user choose; never silently take one.** You may show the values you'd default to, but frame the close as this binary: **do not** pre-fill the config keys and ask for an open-ended inline edit ("ok tutto oppure le modifiche"), and **do not** interview the user key-by-key inline (that's exactly what `/trailhead:config`'s menu is for). Ask this **only once**: running config writes the file, and *accept as-is* writes an empty `{}`, so once `.trailhead/config.json` exists it's never offered again (a `{}` file means "reviewed, using defaults"). The same offer is made at the end of chart/adopt (Mode 1/1-bis). It fires on the bare `/trailhead` and when setting a project up, never in the middle of working a ticket.
+
+Every verb is also a **namespaced command** (`/trailhead:new`, `/trailhead:work`, `/trailhead:bug`, …) so typing `/trailhead` lists them all in the picker. They're thin wrappers that delegate here; `/trailhead <verb>` and `/trailhead:<verb>` are equivalent.
 
 **Flow**
 | Command | What it does |
 |---|---|
-| `/trailhead` | smart entry — detect and propose |
+| `/trailhead` | smart entry: detect and propose |
 | `/trailhead:new [idea]` | chart a new map → Mode 1 |
 | `/trailhead:adopt` | adopt an existing project → Mode 1-bis |
 | `/trailhead:work [ticket]` | work the map: the next frontier ticket, or the one you name → Mode 2 |
+| `/trailhead:quick [ticket \| "text"]` | work one ticket whole, off the map: `quick "text"` opens a whiteboard ticket and works it now, `quick <n>` works an existing one; full engine, grills only if needed, never splits |
+| `/trailhead:whiteboard` | show the whiteboard: the loose (map-less) tickets, their frontier and who holds each |
 | `/trailhead:inbox [issue]` | triage issues opened by others and integrate the worthwhile ones into the map |
 | `/trailhead:resume [ticket]` | resume a paused ticket: read its latest `PAUSED` checkpoint and continue |
 | `/trailhead:pause [note]` | checkpoint the ticket in play so it can be resumed later (by you or anyone) |
 | `/trailhead:split [ticket]` | split an oversized ticket into children and supersede the original |
 | `/trailhead:ticket <type> <title>` | open one child ticket of the map on the fly (`type` = decision\|research\|prototype\|build\|bug\|task) |
 | `/trailhead:grill [topic]` | run a standalone grilling session on a decision/topic (or a named ticket) |
-| `/trailhead:map` | show the low-res map (destination, decisions, frontier, fog) |
+| `/trailhead:map [map]` | show the low-res map (destination, decisions, frontier, fog); with several maps open, `[map]` picks one and makes it active, or lists them to choose (see [Multiple maps](#multiple-maps-on-one-repo-parking--concurrency)) |
+| `/trailhead:dashboard` | show the repo dashboard: the pinned index of every open map, the whiteboard, and live counts; regenerates the pinned issue and shows it |
 | `/trailhead:config [get\|set …]` | show the effective config (global + project), or set a key |
+| `/trailhead:update` | check for a newer trailhead and install it where safe (see `references/updating.md`) |
 
-**Capture** — zero friction, one confirmation line, resolves nothing (→ Mode 3):
+**Capture** (zero friction, one confirmation line, resolves nothing → Mode 3):
 | Command | Destination |
 |---|---|
 | `/trailhead:bug [--of <ticket>] <text>` | a `trailhead:bug` ticket on the frontier; `--of` records it as a `Regression of: <ticket>` |
-| `/trailhead:todo <text>` | a small ticket on the frontier — work you *will* do |
+| `/trailhead:todo <text>` | a small ticket on the frontier: work you *will* do |
 | `/trailhead:idea <text>` | a line in *Not yet specified* (the fog); a ticket only if already razor-sharp |
 | `/trailhead:seed <text>` | a blocked ticket with its trigger noted in `## Blocked by` |
 | `/trailhead:note <text>` | a verbatim note (fog; outside a project → `$HOME/.claude/notes/`) |
 
 Missing text in a capture → ask for the line. Unrecognised verb → treat the whole string as `idea`.
 
-**Idea vs todo:** `idea` is a maybe-later thought (fog by default, graduates when the frontier reaches it); `todo` is defined work you will do (born a ticket). The test stays Wayfinder's: can you *phrase* the question precisely now? Yes → ticket, no → fog.
+**Idea vs todo:** `idea` is a maybe-later thought (fog by default, graduates when the frontier reaches it); `todo` is defined work you will do (born a ticket). The test: can you *phrase* the question precisely now? Yes → ticket, no → fog.
 
 ## Principles
 
-- **Execution inside the map (default).** Unlike pure Wayfinder ("plan, don't do"), here the map carries **construction** within it: after the decision tickets, build tickets graduate from the fog and are **executed** as children of the map. The destination is the **working** artifact (a deployed app), not a spec document — the spec is a waypoint. *Override:* a project that must stop at the spec declares it in the map's `## Notes` (that wins over this default).
-- **Refer by name.** Every map and ticket is an issue, so it has a **title**. In everything the human reads, refer by name, never by a bare `#number`. A wall of `#42, #43, #44` is illegible; names read at a glance. The id and URL don't vanish — a name wraps its link — but they ride *inside* the name.
-- **One ticket per session — hard rule.** Resolve **at most one** ticket per session; once one is resolved, do **not** start a second — end the session instead. The only exceptions: `research` tickets (AFK, run in parallel) and `capture` operations (they resolve nothing). On resolving a ticket, close the session with the **[Session handoff](#session-handoff)** ritual.
-- **Commit straight to `main`.** Build tickets commit straight to `main`, conventional commits, no feature branch/PR unless explicitly requested. Never `Co-Authored-By`.
+- **Execution inside the map (default).** Unlike a plan-only approach ("plan, don't do"), here the map carries **construction** within it: after the decision tickets, build tickets graduate from the fog and are **executed** as children of the map. The destination is the **working** artifact (a deployed app), not a spec document; the spec is a waypoint. *Override:* a project that must stop at the spec declares it in the map's `## Notes` (that wins over this default).
+- **Refer by name.** Every map and ticket is an issue, so it has a **title**. In everything the human reads, refer by name, never by a bare `#number`. A wall of `#42, #43, #44` is illegible; names read at a glance. The id and URL don't vanish (a name wraps its link) but they ride *inside* the name. **One exception: a command the user must run.** In `/trailhead:work <ticket>` the argument is machine input, not prose; give the **bare number** there (a long title, with its punctuation and jargon, is awkward and error-prone to type). Name the ticket in the surrounding sentence, put the number in the command.
+- **Result-oriented output.** In the chat, report **what was done and the next step**: refer to tickets by name and give the concrete next command. Do **not** expose trailhead's internal machinery: Mode labels (`Mode 1`, …), protocol/step names (`DISCUSS`/`PLAN`/`VERIFY`, "the build engine", "Session handoff", "graduate the fog", "the frontier"), or wrapper/SKILL.md mechanics. **Nor narrate the conventions and config you are silently obeying**: the git mode (`main`/`pr`), the isolation/worktree decision, submodule commit mechanics (commit-inside + gitlink bump), claim/assignment plumbing, which model ran a step. These are housekeeping you just *do*; reciting them ("the conventions say `git: main`, no worktree isolation, submodule work commits inside + a gitlink bump, and the ticket is already assigned to you") is noise, not a status update. Just act, then report the outcome. Surface a convention only when it **changes what the user must do** (a UAT they run, a release awaiting their command, a genuine claim collision with *another* login) or when they explicitly ask. (A map may reinforce this in its `## Notes`, but it holds regardless.)
+- **No em-dashes.** Write with ordinary punctuation: commas, colons, semicolons, parentheses, periods. Never use an em-dash (U+2014), and never a hyphen standing in for a comma. This holds for **everything trailhead produces**: ticket titles and bodies, engine comments, the map body, commit descriptions, chat output, and the skill's own source docs. En-dashes in numeric ranges (`1–2`) and the arrow `→` in trailhead's notation stay; only the em-dash is banned.
+- **One ticket per session: hard rule.** Resolve **at most one** ticket per session; once one is resolved, do **not** start a second; end the session instead. The only exceptions: `research` tickets (AFK, run in parallel) and `capture` operations (they resolve nothing). On resolving a ticket, close the session with the **[Session handoff](#session-handoff)** ritual.
+- **Git per the repo's conventions.** The default is commit straight to `main`, conventional commits, no feature branch/PR, but the repo's `trailhead:conventions` issue governs: honour its `git:` (`main` | `pr`), `release:` (`command` | `auto`), and `isolation:` (`none` | `worktree`) header. Never `Co-Authored-By`. **Every commit made while resolving a ticket carries a `Refs: #<n>` trailer** (the ticket's issue number) as its last line, so GitHub threads the commit into that ticket's timeline (the commits show up *in* the ticket). Use a **non-closing** reference (`Refs:`): never a closing keyword (`fixes`/`closes`/`resolves #n`), because the ticket is closed **explicitly at Resolve** after Verify passes, not by a commit landing on the trunk. (Charting/config commits not tied to a ticket carry no `Refs:`.)
 
 ## Session handoff
 
-Resolving a ticket **ends the session** — one ticket per session is a hard rule (see [Principles](#principles)). So every resolution closes the same way. After the resolution comment + `gh issue close` + the `Decisions so far` update, **always** sign off with, in order:
+Resolving a ticket **ends the session**: one ticket per session is a hard rule (see [Principles](#principles)). So every resolution closes the same way. After the resolution comment + `gh issue close` + the `Decisions so far` update, **remove the session-ticket marker** (`.trailhead/session-ticket` at the working root, if you wrote one, see Mode 2), then **always** sign off with, in order:
 
 1. **A one-line confirmation** the ticket is resolved, by name (not a bare `#number`).
-2. **An invitation to `/clear`** — start the next ticket with clean context. State it **every time**, not only when context is heavy.
-3. **The concrete next command** — read the frontier and name it: `/trailhead:work <next frontier ticket by name>`. If the frontier is empty, or the choice is ambiguous (several equal candidates), suggest `/trailhead:map` instead so the user picks.
+2. **The next step: a scannable block, `/clear` FIRST, always.** Never bury it in prose, and **never point at the next ticket without leading with `/clear`**. State the `/clear` **every time** (not only when context is heavy): it must come *before* the next command, so the next ticket starts on clean context. Render it as a short labelled list in the user's conversation language, along these lines:
+
+   > **Prossimo passo:**
+   > - `/clear`: per liberare il contesto
+   > - poi `/trailhead:work <numero>` per lavorare **<nome del prossimo ticket>** (oppure `/trailhead:work` che prende **<numero>** in automatico)
+   > - in alternativa `/trailhead:map` per la vista completa e scegliere tu
+   > - oppure `/trailhead:quick` (o `/trailhead:quick "<il pezzo>"` se sai già cosa) per lavorare un pezzo fuori mappa, aperto e portato a termine subito
+
+   Name the next frontier ticket so the user knows what they're taking; put its **number** in the command (never the title). The block is the list of things to do **after the `/clear`** (it leads with it) and stays on screen in the terminal to read from, so each command must be either self-sufficient (a number already known) or safe to type by hand. The commands a handoff block may contain are `/clear`, `/trailhead:work` (bare or `<number>`), `/trailhead:map`, and `/trailhead:quick`; **in a whiteboard session** (the resolved ticket was `trailhead:whiteboard`), also `/trailhead:whiteboard`. **`/trailhead:quick` is the one command that may carry a free-text argument here**: `/trailhead:quick "<short seed>"` when a concrete off-map piece is actually at hand (its argument is forgiving freeform seed text, not an exact title to match, so pre-filling it is helpful, not error-prone), or **bare `/trailhead:quick`** as the generic "if you want to work a piece off the map" offer, which prompts for the piece itself; keep any seed short and quote-safe. **`/trailhead:work` always takes the number, never the title** of an existing ticket, and **never hand the user a `/trailhead:ticket <type> "<title>"`** (or any other title-bearing command): adding a map ticket needs the diverge-first framing (Mode 3), so it is never pre-filled.
+
+   **If the frontier is empty**, that usually means fog that this resolution made specifiable should have been **graduated into a ticket already** (Mode 2 step 5), so the frontier isn't actually empty. If it genuinely is (nothing ticketable yet, or the user must choose which fog item to take next), point the block to **`/trailhead:map`** and offer to open the next ticket *yourself* once they say which one, rather than pre-filling a `/trailhead:ticket` command for them. **In a whiteboard session** the fog-graduation reasoning does not apply (the whiteboard has no fog): point the block at **`/trailhead:whiteboard`** (and `/trailhead:quick <n>` for the next loose ticket), not the map. (The example is Italian; match whatever language you're conversing in.)
+
+**This block is required whenever you point the user at the next ticket**, including in a **later follow-up**, after answering their questions, not only in the instant you resolve the ticket. Never write "next: `/trailhead:work …`" without the `/clear` line above it.
 
 This ritual fires from every **Resolve** step (`build`, `bug`) and from **Mode 2**'s close (which resolves `decision` / `prototype` / `task` too). It does **not** fire after a `capture` (resolves nothing) or a parallel `research` batch (AFK, not session-ending).
 
 ## Substrate: GitHub Issues
 
-The tracker is GitHub via the `gh` CLI (account already authenticated). Conventions:
+The tracker is GitHub via the `gh` CLI (account already authenticated). **Never post a secret to an issue**: everything trailhead writes (ticket bodies, engine comments, the codebase/conventions issues, resolutions) is public tracker text, so redact credentials proactively with `<REDACTED>` or an env-var reference (the Debug **Redact** protocol applies to *all* engine writes, not just debugging). A shipped **secret-guard hook** hard-blocks any `gh` issue/PR write that still contains one. If it fires, treat the block as a **clean-and-retry cue, not a dead end**: redact the flagged value in place (`<REDACTED>` or an env-var reference like `$SUPABASE_KEY`), then re-post, silently, without surfacing the block to the user as a failure. (The hook only *blocks*; it can't rewrite the write, which is deliberate: a fail-safe block never leaks, whereas a silent auto-redact that didn't apply would. The redaction is yours to do.) If the block looks like a false positive, reword so it no longer matches a credential pattern. Conventions:
 
 | Element | How |
 |----------|------|
-| Map | an issue with label `trailhead:map` |
-| Ticket | a child issue with label `trailhead:ticket` + exactly one **type** label: `trailhead:decision` / `trailhead:research` / `trailhead:prototype` / `trailhead:build` / `trailhead:bug` / `trailhead:task` |
-| Child→map link | a `Parent: <map name>(link)` line in the ticket body |
-| Blocking | the `## Blocked by` body section lists *which* tickets block (name+link — GitHub has no native blocking in the API); the **`trailhead:blocked`** label marks *that* it is currently blocked, so the frontier is one query. Add the label when you wire a blocker; **remove it the moment the last blocker closes** (that's what graduates a ticket onto the frontier). |
-| Claim | assign the ticket to yourself: `gh issue edit <n> --add-assignee @me` — the assignee *is* the claim; the claimer owns it end to end and closes it (no approver). Re-check before starting; on a collision, stop and ask the user. See [Working as a team](#working-as-a-team). |
+| Map | an issue with label `trailhead:map`. **Not pinned** (the 3 pinned slots are the repo-scoped [dashboard](#the-dashboard-a-pinned-repo-index) + codebase + conventions): open maps are found via the `trailhead:map` label and listed in the pinned dashboard, so a repo's maps stay one click away without contending for a slot. **When a map is exhausted** (destination reached: no open tickets and no fog left), **ask the user whether to close the map issue**: on a yes, `gh issue close` it (a closed issue is still the durable record) and refresh the dashboard so it drops off; on a no, leave it open. Never close a map unprompted; there is no pin to free either way. Each map's **tickets** share a **`trailhead:map-<n>` label** (n = the map's issue number) that scopes its frontier; the map issue itself is found by its number and does not carry it. |
+| Codebase | a **single per-repo** issue with label `trailhead:codebase`: the distilled codebase map (architecture, stack, conventions, decisions embodied, risks, test/build). It's repo-scoped: **shared by every map of this repo, owned by none**, so it survives when a map is finished. Each map's Notes *links* it (never re-inlines it). Not a `trailhead:ticket`, so it's off the frontier. Written at adopt; a **greenfield map** (`/trailhead:new`) has no code to map at chart, so it's created **later, once the repo has substantial code** (e.g. after the first build tickets land), via the Codebase map technique. **Kept fresh at Resolve**: when a resolved `build`/`bug` ticket **materially changes** the map (a new module or layer, a new dependency/integration, a new seam, a changed build/test command, a new convention), **patch the affected facet of this issue in place** as part of Resolve, one or two lines, not a re-run of the fan-out. Cosmetic or in-facet changes leave it alone; a full re-map is only for major drift. |
+| Conventions | a **single per-repo** issue with label `trailhead:conventions`: the project's **way of working**, readable by everyone. Repo-scoped and linked from every map's Notes, like Codebase. It opens with a small machine-read header the engine obeys, then human prose. Header keys (defaults **bold**): `git:` **`main`** \| `pr` (commit straight to `main`, or feature branch + PR) · `release:` **`command`** \| `auto` (never release without an explicit command, or release automatically per the project's flow) · `isolation:` **`none`** \| `worktree` \| `clone` (work in the current checkout; or give each executing ticket its own `git worktree` + `trailhead/t<n>` branch; or a dedicated per-ticket **clone** at `../<repo>-t<n>` for **path-bound apps a worktree can't build**, e.g. React Native/Expo with a local `node_modules`; see [Working as a team](#working-as-a-team)). **`worktree`/`clone` imply a branch per ticket even under `git: main`** (git won't check the trunk out twice); the branch integrates to the trunk per `git:` at Resolve. Under **`none`** two in-progress tickets with overlapping `Scope:` **serialise** (the second holds at claim). Below the header: the standing "how we work here" notes. **Filled at chart/adopt by a brief conventions brainstorming** (see the Invocation modes), not a `trailhead:ticket`, off the frontier. |
+| Dashboard | a **single per-repo** issue with label `trailhead:dashboard`: the pinned index of the whole trailhead surface. Repo-scoped and permanent, like Codebase and Conventions, and it occupies the **fixed 3rd pinned slot** alongside them (`gh api graphql` `pinIssue` mutation on its node id). It holds: a link to **every open `trailhead:map`** (GitHub renders each map's sub-issue **progress bar natively**, so the dashboard only links, it does not recompute per-ticket progress), the **whiteboard** as a section (or a link to the `/trailhead:whiteboard` view), and dynamic **counts** (untriaged inbox, whiteboard frontier size). **Created and pinned at the first chart/adopt**, then **rewritten on structural events** (a map is charted or exhausted, i.e. a map appears or disappears) **and on demand** via `/trailhead:dashboard`. **Not rewritten on every ticket resolve** (that would churn a pinned issue and its notifications; the native progress bars already track per-ticket progress). See [The dashboard](#the-dashboard-a-pinned-repo-index). |
+| Ticket | a child issue with label `trailhead:ticket` + exactly one **type** label: `trailhead:decision` / `trailhead:research` / `trailhead:prototype` / `trailhead:build` / `trailhead:bug` / `trailhead:task`, plus its map's `trailhead:map-<n>` label and native sub-issue edge (see Child→map link). **A `trailhead:whiteboard` ticket carries none of the map wiring** (no `trailhead:map-<n>`, no sub-issue edge, no `Parent:`); see [The whiteboard](#the-whiteboard-map-less-tickets). |
+| Child→map link | three views of one fact, wired in the same pass (like a blocker): a `Parent: <map name>(link)` line in the ticket body (human-readable); a **native sub-issue** edge to the map (`gh api --method POST repos/{owner}/{repo}/issues/<map>/sub_issues -F sub_issue_id=<ticket .id>`, the structure GitHub renders); and the map's **`trailhead:map-<n>` label** on the ticket (the queryable key that scopes its map's frontier). See [Multiple maps on one repo](#multiple-maps-on-one-repo-parking--concurrency). **A whiteboard ticket has none of the three** (it belongs to no map). |
+| Path scope (monorepo) | an optional `Scope: <path>[, <path>…]` line in the ticket body naming the package/dir(s), or **submodule path(s)**, the ticket works in. It sharpens the [undeclared-coupling check](#working-as-a-team) (disjoint scopes parallelize safely), scopes build/test to the affected package, and scopes an `isolation: worktree` worktree's commits. **List every one it touches** (a ticket spanning two submodules names both). **Omit it in a single-package repo** (the whole tree is the scope); add it only where a repo has independent packages/subtrees or submodules. |
+| Blocking | **Find every blocker first: from the ticket's own Question.** Each still-open ticket whose output this ticket *consumes as an input* is a blocker: a decision that needs another's answer, a build that needs a decision, a formula that needs the very thing another ticket defines. Read the Question and wire **all** of them: miss one and the ticket surfaces on the frontier prematurely and gets worked before its prerequisite. Then wiring a blocker is **three moves**: (1) list *which* tickets block in the `## Blocked by` body section (name+link); (2) create the **native GitHub dependency** so the frontier renders visually in GitHub's own UI: `gh api --method POST repos/{owner}/{repo}/issues/<blocked>/dependencies/blocked_by -F issue_id=<blocker's internal .id>`; (3) add the **`trailhead:blocked`** label. The **label is the frontier's source of truth**: native dependencies aren't cheaply queryable in one search, so the label is what keeps the frontier **one query**. On unblock, **remove the label the moment the last blocker closes** (that's what graduates the ticket onto the frontier); the native edge needs no cleanup: GitHub auto-reflects a closed blocker. **The three moves are one fact in three views: they must name the *same* blocker.** The `## Blocked by` line must link the **real blocker ticket** the native edge targets (its actual number), never a superseded parent, a split-origin, or a by-role placeholder like "child A"; wire the prose line and the native dependency in the same pass, from the same id, so they can't drift. |
+| Claim | assign the ticket to yourself: `gh issue edit <n> --add-assignee @me`: the assignee *is* the claim; the claimer owns it end to end and closes it (no approver). Re-check before starting; on a collision, stop and ask the user. See [Working as a team](#working-as-a-team). |
 | Resolution | comment with the answer → `gh issue close` → update `Decisions so far` on the map |
 
 **State labels** (orthogonal to the type label, on top of `trailhead:ticket`):
-- **`trailhead:blocked`** — has an open blocker; excluded from the frontier. Removed when unblocked.
-- **`trailhead:seed`** — a forward-looking capture parked until a trigger fires (kept blocked); makes seeds auditable.
-- **`trailhead:out-of-scope`** — closed because ruled beyond the destination, *not* resolved; keeps it distinct from resolved tickets and out of `Decisions so far`.
-- **`trailhead:superseded`** — closed because split into child tickets that replace it (see [Working as a team](#working-as-a-team)); *not* resolved, and out of `Decisions so far`.
-- **`trailhead:unverified`** — a `trailhead:*` issue whose provenance isn't trusted (see [Trust & provenance](#working-as-a-team)); quarantined off the frontier until a maintainer adopts or rejects it.
-- **`trailhead:fog`** — an in-scope-but-not-yet-sharp issue (usually an inbound suggestion) **kept open as a clarification space** — visible and tracked, off the frontier and out of the inbox — where the reporter and others discuss until it's sharp enough to graduate into a ticket. See [Inbox](#inbox--issues-opened-by-others).
+- **`trailhead:blocked`**: has an open blocker; excluded from the frontier. Removed when unblocked.
+- **`trailhead:seed`**: a forward-looking capture parked until a trigger fires (kept blocked); makes seeds auditable.
+- **`trailhead:out-of-scope`**: closed because ruled beyond the destination, *not* resolved; keeps it distinct from resolved tickets and out of `Decisions so far`.
+- **`trailhead:superseded`**: closed because split into child tickets that replace it (see [Working as a team](#working-as-a-team)); *not* resolved, and out of `Decisions so far`.
+- **`trailhead:unverified`**: a `trailhead:*` issue whose provenance isn't trusted (see [Trust & provenance](#working-as-a-team)); quarantined off the frontier until a maintainer adopts or rejects it.
+- **`trailhead:fog`**: an in-scope-but-not-yet-sharp issue (usually an inbound suggestion) **kept open as a clarification space** (visible and tracked, off the frontier and out of the inbox) where the reporter and others discuss until it's sharp enough to graduate into a ticket. See [Inbox](#inbox-issues-opened-by-others).
+- **`trailhead:whiteboard`**: a **map-less** ticket, parked on the **whiteboard** (the container for work not tied to any map). **Mutually exclusive with a `trailhead:map-<n>` label**: a ticket is on a map or on the whiteboard, never both, and a whiteboard ticket has no `Parent:` line and no native sub-issue edge. It carries its own frontier (below), off every map's. Captured there when a capture is routed to the whiteboard, or born there by `quick`; see [The whiteboard](#the-whiteboard-map-less-tickets).
 
-**Frontier** = open, unassigned tickets that are **not** `trailhead:blocked` and **not** `trailhead:unverified`. That's the whole query — the labels are the pre-computed answers to "are all blockers closed?" and "is this a trusted trailhead ticket?", so no per-ticket body parsing.
+**Frontier** = open, unassigned tickets that are **not** `trailhead:blocked` and **not** `trailhead:unverified`. That's the whole query: the labels are the pre-computed answers to "are all blockers closed?" and "is this a trusted trailhead ticket?", so no per-ticket body parsing. **With more than one live map on the repo**, add the active map's `trailhead:map-<n>` label to scope the frontier to that map (still one query); with a single map the repo-wide query below is the frontier. See [Multiple maps on one repo](#multiple-maps-on-one-repo-parking--concurrency).
+
+**Map frontier vs whiteboard frontier.** The whiteboard (tickets labelled `trailhead:whiteboard`, map-less) has its **own** frontier, queried by that label with the same open/unassigned/not-blocked/not-unverified filter, and it is **excluded from every map frontier**: the multi-map query already excludes it (whiteboard tickets carry no `trailhead:map-<n>`), and the single-map repo-wide query adds `-label:trailhead:whiteboard`. So a map's frontier and the whiteboard's never overlap. `/trailhead:whiteboard` renders the whiteboard frontier; `/trailhead:map` and bare `/trailhead:work` stay on the map. See [The whiteboard](#the-whiteboard-map-less-tickets).
+
+**Blocked-by reconciliation (drift check).** The `## Blocked by` prose and the native dependency are two copies of one fact, so they can drift (it has happened: a body naming the split-*origin* while the native edge pointed at the sibling). When rendering `/trailhead:map` and before working a ticket, **reconcile them deterministically**: parse the issue numbers in the ticket's `## Blocked by`, read its native `blocked_by` (`gh api repos/{owner}/{repo}/issues/<n>/dependencies/blocked_by`), and if the two sets differ, **surface an advisory** naming both sides (the native edge is the structured reference); never auto-fix, never block. If the body has no parseable `## Blocked by`, report it **uncheckable**, never assume they agree. This is the one deterministic, false-positive-free consistency axis; higher-level "does a ticket contradict the map's decisions" drift is left to human judgement.
 
 Base commands:
 ```bash
 # create the map
 gh issue create --label "trailhead:map" --title "<destination>" --body-file <body>
-# create a child ticket (add trailhead:blocked too if it has an open blocker)
-gh issue create --label "trailhead:ticket,trailhead:build" --title "<question/goal>" --body-file <body>
-# the frontier: open, unassigned, not blocked, not unverified — one query
-gh issue list --label "trailhead:ticket" --state open --search "no:assignee -label:trailhead:blocked -label:trailhead:unverified"
-# unblock a ticket once its last blocker closes
+# create a child ticket (add trailhead:blocked too if it has an open blocker; add trailhead:map-<map> to scope it to its map)
+gh issue create --label "trailhead:ticket,trailhead:build,trailhead:map-<map>" --title "<question/goal>" --body-file <body>
+# link the ticket to its map: native sub-issue (structure/UI) + the map label above (the query)
+gh api --method POST repos/{owner}/{repo}/issues/<map>/sub_issues -F sub_issue_id=$(gh api repos/{owner}/{repo}/issues/<ticket> --jq .id)
+# wire a blocker: native dependency (visual frontier in the UI) + the label (the query)
+gh api --method POST repos/{owner}/{repo}/issues/<blocked>/dependencies/blocked_by -F issue_id=$(gh api repos/{owner}/{repo}/issues/<blocker> --jq .id)
+gh issue edit <blocked> --add-label "trailhead:blocked"
+# the frontier: open, unassigned, not blocked, not unverified, one query (add --label trailhead:map-<map> to scope to one map when several are live; add -label:trailhead:whiteboard to a single-map repo-wide query to keep loose tickets off it)
+gh issue list --label "trailhead:ticket" --state open --search "no:assignee -label:trailhead:blocked -label:trailhead:unverified -label:trailhead:whiteboard"
+# the whiteboard frontier: map-less loose tickets, its own query
+gh issue list --label "trailhead:ticket" --label "trailhead:whiteboard" --state open --search "no:assignee -label:trailhead:blocked -label:trailhead:unverified"
+# unblock a ticket once its last blocker closes (label only; native edge auto-reflects)
 gh issue edit <n> --remove-label "trailhead:blocked"
 # claim
 gh issue edit <n> --add-assignee @me
 # resolve
 gh issue comment <n> --body-file <resolution>   &&   gh issue close <n>
 ```
-On first use in a repo, create any missing labels with `gh label create` (all fourteen: `trailhead:map`, `trailhead:ticket`, the six type labels, `trailhead:blocked`, `trailhead:seed`, `trailhead:out-of-scope`, `trailhead:superseded`, `trailhead:unverified`, `trailhead:fog`).
+**First-use repo setup (do BOTH, every chart or adopt, never skip either):**
+1. Create any missing labels with `gh label create` (all eighteen: `trailhead:map`, `trailhead:codebase`, `trailhead:conventions`, `trailhead:dashboard`, `trailhead:ticket`, the six type labels, `trailhead:blocked`, `trailhead:seed`, `trailhead:out-of-scope`, `trailhead:superseded`, `trailhead:unverified`, `trailhead:fog`, `trailhead:whiteboard`).
+2. **Check the label guard is installed**: `gh api repos/{owner}/{repo}/contents/.github/workflows/trailhead-label-guard.yml`; if it's absent (404), install it: **read `references/teamwork.md` (Trust & provenance → Repo-side enforcement) for the exact steps**. This is part of standing up trailhead in a repo, not an optional extra: *check every time*, so a repo can never end up with the labels but no guard.
 
 ## The Map
 
-A single `trailhead:map` issue, the canonical artifact. It's an **index**, not a store: it lists the decisions made and points at the tickets that hold their detail. A decision lives in exactly one place — its ticket — the map gists it and links.
+A single `trailhead:map` issue, the canonical artifact. It's an **index**, not a store: it lists the decisions made and points at the tickets that hold their detail. A decision lives in exactly one place (its ticket); the map gists it and links.
 
-**`/trailhead:map`** renders this at low resolution as a read-only dashboard (it changes nothing) — the map body plus the live ticket state, by name:
-- **Destination** — the one-line where-we're-headed.
-- **Frontier** — takeable now (open, unassigned, not blocked/unverified), each with its type.
-- **In progress** — claimed tickets, with who holds each.
-- **Blocked** — with what each waits on.
-- **Decisions so far** — the index of what's settled.
-- **Not yet specified** + **parked fog** — the coarse fog, and a count/link of open `trailhead:fog` issues.
-- **Out of scope** — what's been ruled out.
-- **Inbox** — a count of untriaged inbound issues, as a nudge.
+**`/trailhead:map`** renders this at low resolution as a read-only dashboard (it changes nothing on the map itself; see the dashboard self-heal and exhaustion check below), the map body plus the live ticket state, by name:
+- **Destination**: the one-line where-we're-headed.
+- **Frontier**: takeable now (open, unassigned, not blocked/unverified, and **not** `trailhead:whiteboard`, which has its own view), each with its type.
+- **In progress**: claimed tickets, with who holds each.
+- **Blocked**: with what each waits on; flag any **blocked-by drift** (prose `## Blocked by` ≠ native dependency, see [Blocked-by reconciliation](#substrate-github-issues)) as an advisory line.
+- **Decisions so far**: the index of what's settled.
+- **Not yet specified** + **parked fog**: the coarse fog, and a count/link of open `trailhead:fog` issues.
+- **Out of scope**: what's been ruled out; **flag as an advisory** any line that's actually **deferred** rather than truly beyond the destination: it **names a gate/trigger** (*gated by X*, *quando X*, *dipende da X*), carries a **this-only qualifier** (*per questo slice*, *for now*, *in this milestone*), is a **feature wanted later** (another milestone/map), or **is the gate of an existing `trailhead:seed`** (a seed's trigger names it, so it cannot be "ruled out", and that cluster is mis-wired). **Flag only lines not yet properly parked**: a line **already annotated `→ future map`** whose dependent seeds are **wired to a live trigger** is settled, say nothing about it. When one or more **un-parked** such lines are present, **don't stay silent: name them and suggest `/trailhead:inbox` to re-route them** (seed/idea/todo). See [Out of scope](#out-of-scope).
+- **Inbox**: a count of untriaged inbound issues, as a nudge.
+- **Exhaustion check**: if the map is exhausted (no open tickets and no fog left: the destination is reached), **say so and ask whether to close the map issue**, the same ask as Mode 2's hand-off: on a yes, `gh issue close` it and refresh the dashboard so it drops off; on a no, leave it open. Maps aren't pinned, so there's no pin to free either way. Never close unprompted. Route any un-parked deferred *Out of scope* line first (above) so nothing wanted-later is lost. This user-confirmed close is the only change `/trailhead:map` makes to the map, and only on an explicit yes (the dashboard self-heal below touches only the pinned index, never the map).
+
+**Dashboard self-heal.** Before rendering, ensure the repo's pinned `trailhead:dashboard` index exists and is pinned: create + pin it only if missing, re-pin it if the pin was dropped, and otherwise do nothing (never rewrite its body on a render). See [The dashboard's self-heal note](#the-dashboard-a-pinned-repo-index).
 
 Map body (loaded once per session):
 
 ```markdown
 ## 🎯 Destination
-<what reaching the end of this map looks like — the spec, decision, or change this effort tends toward. The working artifact, unless overridden. One or two lines; every session orients to it before choosing a ticket.>
+<what reaching the end of this map looks like: the spec, decision, or change this effort tends toward. The working artifact, unless overridden. One or two lines; every session orients to it before choosing a ticket.>
 
 ## 🗒️ Notes
-<domain; vocabulary (see Domain vocabulary); standing preferences for this effort; any "stop at the spec" override.>
-
-## ⚙️ Config
-<!-- overrides the global ~/.claude/trailhead/config.json; omitted keys inherit global, then defaults. See Configuration. -->
-models: { plan: opus, execute: sonnet, research: sonnet, review: sonnet, debug: opus }
-design: disk                       # disk | claude.ai/design   (mode; project URL auto-cached below)
-design.approval: explicit          # explicit | auto  (require explicit mockup approval before UI code?)
-# design.project:                  # auto-filled at execution when a claude.ai/design project is created
-tdd: seams                         # seams | on | off
-acceptance.browser: auto           # auto | on | off
-testing: { webapp: true, url: http://localhost:3000 }
-plan_review: off                   # off | on | gemini,codex   (external AI review of build PLANs)
-plan_review.rounds: 2
+<domain; vocabulary (see Domain vocabulary); standing preferences for this effort; any "stop at the spec" override; a **link to the repo's `trailhead:codebase` issue** (the codebase map lives there, repo-scoped, never re-inline it here) and a **link to the repo's `trailhead:conventions` issue** (the way of working: git/release + notes). Config is NOT here either: it lives in `.trailhead/config.json` at the repo root; see Configuration.>
 
 ## ✅ Decisions so far
-<!-- the index — one line per closed ticket -->
-- [<closed ticket title>](link) — <one-line gist of the answer>
+<!-- the index: one line per closed ticket -->
+- [<closed ticket title>](link): <one-line gist of the answer>
 
 ## 🌫️ Not yet specified
 <!-- fog of war: in-scope fog not yet ticketable; graduates as the frontier advances -->
@@ -156,15 +184,20 @@ plan_review.rounds: 2
 <!-- work ruled beyond the destination; closed, never graduates -->
 ```
 
-Section names are matched by their **text** — the emoji are cosmetic anchors, so `Decisions so far` / `Not yet specified` / `Out of scope` still refer to these blocks throughout.
+Section names are matched by their **text**: the emoji are cosmetic anchors, so `Decisions so far` / `Not yet specified` / `Out of scope` still refer to these blocks throughout.
 
 ## Configuration
 
-Two optional layers, **project wins over global**, key by key (built-in defaults otherwise):
-- **Global** — `~/.claude/trailhead/config.json` (honour `$CLAUDE_CONFIG_DIR`): your standing defaults across every project.
-- **Project** — the map's `## Config` block: overrides for this map. Omitted keys inherit global, then defaults.
+Three layers, **nearest wins**, key by key; a key unset at one layer inherits the next:
+- **Project**: a `.trailhead/config.json` file at the repo root: overrides for this project, committed so a team shares one config. **Config never lives in the map issue**: the map is an index of decisions, while config is the user's to change at any time, so it stays in a plain file (and never asserted into the map by the agent).
+- **Global**: `~/.claude/trailhead/config.json` (honour `$CLAUDE_CONFIG_DIR`): your standing defaults across every project.
+- **Defaults**: the built-in values documented in `references/configuration.md`.
+
+Load the effective config at the start of a work session, **from the map's project root** (`.trailhead/config.json` at the superproject repo root) plus the global file, **before** any isolation workspace is set up. **Config is a property of the project/map, not the working directory**: an `isolation: worktree`/`clone` workspace **inherits** the config loaded here and must **never re-resolve it from the isolated copy's own root**, because a per-ticket clone (a submodule clone especially) has no `.trailhead/` of its own and would silently fall back to defaults (this is exactly how a `design: claude.ai/design` project ends up wrongly using `disk` in a clone). Config **writes** too (e.g. caching `design.project`) target the project's `.trailhead/config.json` in the original checkout, never the clone. **The main session orchestrates and holds the HITL moments** (the `build`/`bug` Discuss's "stop and ask", Verify's acceptance/UAT); **every model key runs as a subagent** (`plan`, `execute` (an *executor subagent* implementing with atomic commits on `models.execute`), `research`, `review`, `debug`) so the whole per-activity model split applies in one session whatever model it runs on. Run Execute inline only when `models.execute` is unset or equals the session model. The **keys, their values, the model/tdd/acceptance semantics, and the guided menu setup live in `references/configuration.md`**: read it when running `/trailhead:config` or when you need a key's exact meaning. `/trailhead:config` with no args runs the guided setup; `config get` prints the merged config; `config set <key> <value>` writes one key.
 
-Load the effective config at the start of a work session. The **keys, their values, the model/tdd/acceptance semantics, and the guided menu setup live in `references/configuration.md`** — read it when running `/trailhead:config` or when you need a key's exact meaning. `/trailhead:config` with no args runs the guided setup; `config get` prints the merged config; `config set <key> <value>` writes one key.
+**Ticket language (standing engine rule).** Write **all human-authored trailhead prose on the Issues** (ticket titles and bodies, every engine comment (`DISCUSS`/`PLAN`/`VERIFY`/`OPTIONS`/`REPRO`/`DIAGNOSIS`/`PAUSED`/resolution), and the map body sections) **and commit message descriptions** in `config.ticket.language` (ISO 639-1, default `en`). The conventional-commit **type prefix stays English** (`feat:`/`fix:`/…). This is **independent of the language the agent converses in** and never changes it; likewise it never touches code, identifiers, the fixed `trailhead:*` label names, or config keys/values. The skill's own source docs stay English regardless.
+
+**This is the single most-missed rule, and the trap is specific: when you are chatting in one language and go to write a ticket, the body reflexively comes out in the *chat's* language, which is wrong.** The chat language and the ticket language are decoupled on purpose. Before every `gh issue create`/`edit`/`comment` and every commit body, consciously write in `config.ticket.language` (default `en`), not the language of the conversation. This holds for the zero-friction captures too (`bug`/`todo`/`idea`/`seed`/`note`) **and for `quick`** (its `"<text>"` seed is input in the chat's language, but the whiteboard ticket it opens is written in the ticket language): a one-line Italian request still becomes an English ticket. If you catch a ticket, comment, or map section already written in the wrong language, **convert it in place before continuing** any other work.
 
 ## The Tickets
 
@@ -174,12 +207,13 @@ Each ticket is a child issue. Its **title carries the type icon** (see below); t
 Title: 🐛 <clear, specific title>
 
 **Parent:** [<map name>](link)
+<!-- map tickets only; a trailhead:whiteboard ticket omits the Parent line entirely -->
 
 ## Question
 <the decision, investigation, or build goal this ticket resolves>
 
 ## Blocked by
-<!-- names+links of tickets that must close first; empty → write "— nothing (on the frontier)" -->
+<!-- names+links of tickets that must close first; empty → write "nothing (on the frontier)" -->
 ```
 
 The answer isn't in the body: it's recorded on resolution as a comment. Assets created while resolving a ticket are linked from the issue, not pasted in.
@@ -190,16 +224,18 @@ The answer isn't in the body: it's recorded on resolution as a comment. Assets c
 |---|---|---|---|---|
 | `decision` | 🧭 | | Destination | 🎯 |
 | `research` | 🔬 | | Notes | 🗒️ |
-| `prototype` | 🎨 | | Config | ⚙️ |
-| `build` | 🔨 | | Decisions so far | ✅ |
-| `bug` | 🐛 | | Not yet specified | 🌫️ |
-| `task` | 🔧 | | Out of scope | 🚫 |
+| `prototype` | 🎨 | | Decisions so far | ✅ |
+| `build` | 🔨 | | Not yet specified | 🌫️ |
+| `bug` | 🐛 | | Out of scope | 🚫 |
+| `task` | 🔧 | | | |
 
-The map issue title is prefixed 🗺. Keep the icons stable and don't add others — they're anchors, not decoration.
+The map issue title is prefixed 🗺. Keep the icons stable and don't add others: they're anchors, not decoration.
 
 ## Techniques
 
-The ticket engines call these by name. Each technique's full protocol lives in its own file under `references/techniques/` — **read that file the first time a session needs the technique**, so only the ones in play load into context (don't preload them). They are `trailhead`'s own, self-contained (distilled from Wayfinder and GSD); subagents are spawned with the built-in `Agent` tool.
+The ticket engines call these by name. Each technique's full protocol lives in its own file under `references/techniques/`: **read that file the first time a session needs the technique**, so only the ones in play load into context (don't preload them). They are `trailhead`'s own, self-contained; subagents are spawned with the built-in `Agent` tool.
+
+**Pin the subagent type; never borrow a foreign agent.** Every technique subagent carries its full protocol in the prompt (from its `references/techniques/` file), so it needs no specialised agent, and must not use one: **always set `subagent_type` to a built-in agent, never a project- or plugin-provided type** (a specialised `*-reviewer`, `*-researcher`, `*-mapper`, or similarly named agent that another installed tool registered). Even when such an agent's name or description matches the task perfectly, it follows *its own* protocol and artifact conventions (a specialised code-review agent writes its own review file, not trailhead's `VERIFY` ticket comment), so selecting it silently swaps trailhead's engine for another tool's. The split by what the technique touches: **read-only techniques** (Code review, Codebase map, and the Plan step) spawn **`Explore`** (reads, searches, runs tests; no Edit/Write); **repo-modifying techniques** (Research, Execute, Fix, Debug) spawn **`general-purpose`**. On a `subagentToolkit == none` host (Codex) there is no fan-out and this is moot: every technique runs inline in the one session.
 
 | Technique | File | In one line |
 |---|---|---|
@@ -208,7 +244,7 @@ The ticket engines call these by name. Each technique's full protocol lives in i
 | **Prototype** | `references/techniques/prototype.md` | throwaway artifact for "how should it look/behave"; routes UI mockups (disk / claude.ai/design) |
 | **Research** | `references/techniques/research.md` | a focused subagent gathers a decision-ready fact from primary sources |
 | **TDD** | `references/techniques/tdd.md` | RED → GREEN → REFACTOR at the seams; no implementation before a failing test |
-| **Codebase map** | `references/techniques/codebase-map.md` | one-time fan-out of 5 read-only readers, distilled into the map's Notes |
+| **Codebase map** | `references/techniques/codebase-map.md` | one-time fan-out of 5 read-only readers, distilled into the repo's `trailhead:codebase` issue |
 | **Debug** | `references/techniques/debug.md` | scientific method: reproduce → localise → falsifiable hypotheses → confirm cause → verify |
 | **Code review** | `references/techniques/code-review.md` | review the diff on 4 axes, adversarially verify each finding before reporting |
 | **Acceptance testing** | `references/techniques/acceptance-testing.md` | prove it does what the *user* wanted: automated → browser-drive → guided UAT |
@@ -218,212 +254,216 @@ The ticket engines call these by name. Each technique's full protocol lives in i
 
 Every ticket is **HITL** (human in the loop, speaking for themselves) or **AFK** (driven by the agent alone). A HITL ticket resolves only through the live exchange: the agent never stands in for the human's side.
 
-### `decision` — HITL — *default for decision tickets*
-Close a choice — but widen before you narrow:
+### `decision`: HITL, *default for decision tickets*
+Close a choice, but widen before you narrow:
 
-1. **Diverge (only if the option space isn't already clear).** Mapping the frontier usually framed the options already; skip straight to grilling when it did. When it didn't — the ticket names a question but the candidate answers aren't laid out — open the space *first*: brainstorm the plausible options, name each concretely, and post them as an `OPTIONS` comment. Divergence has no judgement yet: surface possibilities, don't rank them. If a missing **fact** is what's blocking clarity, spin a `research` ticket and block on it; if the question is "how could it look/behave", spin a `prototype`. Don't grill a space you haven't opened.
+1. **Diverge (only if the option space isn't already clear).** Mapping the frontier usually framed the options already; skip straight to grilling when it did. When it didn't (the ticket names a question but the candidate answers aren't laid out) open the space *first*: brainstorm the plausible options, name each concretely, and post them as an `OPTIONS` comment. Divergence has no judgement yet: surface possibilities, don't rank them. If a missing **fact** is what's blocking clarity, spin a `research` ticket and block on it; if the question is "how could it look/behave", spin a `prototype`. Don't grill a space you haven't opened.
 2. **Converge.** Run the **Grilling** + **Domain vocabulary** techniques over the options to pick one. Record the decision and the why.
 
-The two phases are distinct on purpose: divergence generates, grilling chooses. Never let the agent invent the options *and* pick for the human — the choice stays theirs.
+The two phases are distinct on purpose: divergence generates, grilling chooses. Never let the agent invent the options *and* pick for the human: the choice stays theirs.
 
-### `research` — AFK
+### `research`: AFK
 Reading docs, third-party APIs, or local resources to surface a fact a decision waits on. Resolved by the **Research** technique. The only type that runs in parallel and more than one per session.
 
-### `prototype` — HITL
-Raise the fidelity of the discussion with a rough, concrete artifact to react to — the **Prototype** technique. Link the prototype as an asset.
+### `prototype`: HITL
+Raise the fidelity of the discussion with a rough, concrete artifact to react to: the **Prototype** technique. Link the prototype as an asset.
 
-### `build` — the engine inside the map
+### `build`: the engine inside the map
 The ticket that *builds*. Lean cycle, all in **ticket comments**:
 
-1. **Discuss** — **never auto-grill.** Start from Plan. If reading the ticket surfaces blocking ambiguity, **stop and ask the user** whether they want a **Grilling** round: don't launch it on your own initiative. Only on their assent run the short round and post a `DISCUSS` comment with the closed choices. The user may also ask for it themselves at any time.
-2. **Plan** — a `PLAN` comment: the steps, the seams, the files touched, the verification criteria. Apply **TDD** per `config.tdd` (`seams`/`on`/`off`). When `config.models.plan` differs from `config.models.execute`, produce this plan via a *planner subagent* on the plan model, then execute in the session on the execute model. If `config.plan_review` is on, run **Cross-AI plan review** before Execute — send the plan to external AI CLIs and converge on their concerns.
-3. **Execute** — implement with **atomic commits straight to `main`** (conventional commits). One commit = one verifiable step.
-4. **Verify** — a `VERIFY` comment: run the tests / the plan's criterion; then the **Code review** technique; then **Acceptance testing** if the change is user-facing (browser-drive it, or hand the user a guided UAT checklist). Report the outcome honestly (if a test fails, say so).
-5. **Resolve** — a resolution comment with what was done → `gh issue close` → update `Decisions so far` on the map. Then close the session with the **[Session handoff](#session-handoff)** ritual (`/clear` + next command).
+1. **Discuss**: **never auto-grill.** Start from Plan. If reading the ticket surfaces blocking ambiguity, **stop and ask the user** whether they want a **Grilling** round: don't launch it on your own initiative. Only on their assent run the short round and post a `DISCUSS` comment with the closed choices. The user may also ask for it themselves at any time.
+2. **Plan**: a `PLAN` comment: the steps, the seams, the files touched, the verification criteria. Apply **TDD** per `config.tdd` (`seams`/`on`/`off`). Produce this plan via a *planner subagent* on `config.models.plan` (spawn it as the built-in **`Explore`** agent, read-only; inline when the model is unset or equals the session model; Execute then runs as its own subagent, see below). If `config.plan_review` is on, run **Cross-AI plan review** before Execute: send the plan to external AI CLIs and converge on their concerns. Now that the files/seam are known, run the [undeclared-coupling check](#working-as-a-team) against in-progress tickets.
+3. **Execute**: **if this ticket changes user-facing UI (a new screen, a redesign, a changed layout), run the [Prototype](#techniques) technique FIRST, before any real UI code**: surface a mockup to react to, routed by `config.design` (disk / claude.ai/design) and gated by `config.design.approval` (`explicit` waits for a go-ahead, `auto` proceeds after surfacing). For a redesign or new screen the default is to offer mockups; don't jump straight to code on a UI ticket. Then implement with **atomic commits** (conventional commits, each with a `Refs: #<n>` trailer for this ticket, see [Principles](#principles)), following the repo's `trailhead:conventions` `git:`, straight to `main` by default, or a feature branch + PR when `git: pr`. **Under `isolation: worktree`, do the work in this ticket's `git worktree`** (`trailhead/t<n>` branch), integrating to the trunk at Resolve (see [Working as a team](#working-as-a-team)). One commit = one verifiable step. Run this via an **executor subagent on `config.models.execute`** (spawn it as the built-in **`general-purpose`** agent, which can Edit/Write/commit; inline when the model is unset or equals the session model); the commits land on `main`, visible. New scope surfacing mid-execute is captured/split, not worked here.
+4. **Verify**: a `VERIFY` comment: run the tests / the plan's criterion; then the **Code review** technique (its subagent reviews *adversarially*: it doesn't defer to a `CLAUDE.md` convention or a "settled decision" memory); then **Acceptance testing** if the change is user-facing (browser-drive it, or **walk the user through a guided UAT conversationally, one step at a time**, never a checklist dumped in a comment). Report the outcome honestly (if a test fails, say so).
+5. **Resolve**: a resolution comment with what was done → `gh issue close` → update `Decisions so far` on the map. **If this change materially altered the codebase** (a new module/layer, dependency, seam, or build/test command), **patch the affected facet of the [`trailhead:codebase`](#substrate-github-issues) issue** in place (a line or two, not a re-map). Then close the session with the **[Session handoff](#session-handoff)** ritual (`/clear` + next command).
 
 New scope that surfaces mid-build (while planning, executing, or testing) → **capture or split, never expand this ticket in flight** (see [Scope that surfaces while working a ticket](#capture-zero-friction--tracker)).
 
-### `bug` — the fix with diagnosis first
+### `bug`: the fix with diagnosis first
 A defect to correct. Unlike `build`, you don't start from implementation: first you **understand**.
 
-**New bug ticket vs reopen — decide first.** A bug in the work of an already-closed ticket almost always means a **new** `bug` ticket, *not* reopening the old one, because `Decisions so far` is append-only history: that ticket really did deliver, and the defect surfaced later is a new event. The one exception is a **premature close** — a ticket closed before its Verify ever passed, i.e. it never actually delivered. The discriminator is sharp: **did that ticket genuinely pass Verify?**
+**New bug ticket vs reopen: decide first.** A bug in the work of an already-closed ticket almost always means a **new** `bug` ticket, *not* reopening the old one, because `Decisions so far` is append-only history: that ticket really did deliver, and the defect surfaced later is a new event. The one exception is a **premature close**: a ticket closed before its Verify ever passed, i.e. it never actually delivered. The discriminator is sharp: **did that ticket genuinely pass Verify?**
 - **Yes** → new bug ticket carrying `Regression of: <closed ticket name+link>` in its body. Leave the original closed. Open it with `/trailhead:bug --of <ticket> <text>` (below), which fills the pointer for you.
 - **No** (closed by mistake, never delivered) → this isn't a new bug, it's a bad close: `gh issue reopen <n>` and finish it.
 
 Then run the cycle, all in ticket comments:
 
-1. **Repro** — a `REPRO` comment: how to reproduce, expected vs observed behaviour.
-2. **Diagnose** — run the **Debug** technique. A `DIAGNOSIS` comment with the root cause.
-3. **Fix** — implement the correction with **atomic commits to `main`**. Where sensible, a test that fails before and passes after (**TDD**).
-4. **Verify** — a `VERIFY` comment: the repro now passes, no regressions; **Code review** on the fix; **Acceptance testing** if the bug was user-facing (browser-drive the fixed flow, or a guided UAT checklist).
-5. **Resolve** — a resolution comment (cause + fix) → `gh issue close` → update `Decisions so far`. Then close the session with the **[Session handoff](#session-handoff)** ritual (`/clear` + next command).
+1. **Repro**: a `REPRO` comment: how to reproduce, expected vs observed behaviour.
+2. **Diagnose**: run the **Debug** technique. A `DIAGNOSIS` comment with the root cause.
+3. **Fix**: implement the correction with **atomic commits** (each with a `Refs: #<n>` trailer for this ticket, see [Principles](#principles); per the repo's `trailhead:conventions` `git:`, `main` by default, else a branch + PR; in this ticket's `git worktree` under `isolation: worktree`), via an **executor subagent on `config.models.execute`** (the built-in **`general-purpose`** agent; inline when unset/same as session). Where sensible, a test that fails before and passes after (**TDD**).
+4. **Verify**: a `VERIFY` comment: the repro now passes, no regressions; **Code review** on the fix; **Acceptance testing** if the bug was user-facing (browser-drive the fixed flow, or **walk the user through a guided UAT conversationally, step by step**, not a checklist to self-serve).
+5. **Resolve**: a resolution comment (cause + fix) → `gh issue close` → update `Decisions so far`. **If the fix materially altered the codebase**, patch the affected facet of the [`trailhead:codebase`](#substrate-github-issues) issue in place (a line or two). Then close the session with the **[Session handoff](#session-handoff)** ritual (`/clear` + next command).
 
 A **blocking** bug that halts other work is worked immediately; an isolated one is a normal frontier ticket. New scope surfacing while fixing → capture or split, never expand this ticket in flight (see [Scope that surfaces while working a ticket](#capture-zero-friction--tracker)).
 
-### `task` — HITL or AFK
+### `task`: HITL or AFK
 Manual work that must happen before a *decision* can be made: signing up for a service to judge its API, provisioning access, moving data to see its shape. The agent drives it alone where it can (AFK); otherwise it hands the human a precise checklist (HITL). Resolved when the work is done; the answer records what was done and the resulting facts (where credentials live, new URLs, row counts) later tickets depend on.
 
+### `quick`: work one ticket whole, off the map
+A streamlined way to just get one ticket done, without map ceremony. `quick "<text>"` opens a **whiteboard** ticket (a `build`, or a `bug` when the text is clearly a defect) and works it end to end now; `quick <n>` works an **existing** ticket (whiteboard or map) the same way. Claim it first; still one ticket per session. **Bare `/trailhead:quick`** (no argument, e.g. offered in a [Session handoff](#session-handoff)) asks for the piece to work, like a capture missing its text, then proceeds as `quick "<text>"`.
+
+It runs the **full engine** (the `build`/`bug` cycle: Discuss → Plan → Execute → Verify → Resolve), differing from `work` on three points:
+- **Grill only if needed** (Discuss): never auto-grill; start from Plan and stop to ask only if a blocking ambiguity surfaces, exactly as the `build` Discuss. The user may ask to grill at any time.
+- **Never splits.** If the ticket turns out large, work it whole anyway: that is the point of `quick`. Do not `split` it and do not spin children. (New scope that surfaces mid-work is still captured out, never folded in, see [Scope that surfaces while working a ticket](#capture-zero-friction--tracker).)
+- **No map narrative book-keeping.** A whiteboard ticket has no map, so there is no `Decisions so far` update, no fog to graduate, no frontier re-scan. Everything else holds: atomic commits with `Refs: #<n>`, TDD / Code review / Acceptance testing per the cycle, the resolution comment + `gh issue close`, and the [Session handoff](#session-handoff). **Exception, `quick <n>` on a *map* ticket: dependent-unblocking still runs** (remove `trailhead:blocked` from any dependent whose last blocker just closed, [Mode 2](#mode-2-work-the-map-trailheadwork) step 4); skipping it would strand those dependents off the frontier for good. Only the *narrative* book-keeping above and the split are skipped, so prefer `work <n>` for a map ticket that has dependents or belongs in the map record.
+- **Same isolation setup as `work`.** Under `isolation: worktree`/`clone`, `quick` sets up the ticket's `trailhead/t<n>` workspace before any edit, re-checks the claim, and writes the `.trailhead/session-ticket` marker, exactly as [Mode 2](#mode-2-work-the-map-trailheadwork) step 2 (no active-map marker: a whiteboard ticket has no map). Under `isolation: none`, the scope-free check applies too.
+
+Type follows the ticket: `quick "<text>"` defaults to `build` (`bug` if a defect); `quick <n>` uses the existing type and its matching engine.
+
 ## Fog of war
 
-The map is *deliberately* incomplete: don't chart what you can't yet see. Beyond the live tickets lies the fog — decisions and investigations you can feel coming but can't yet pin down, because they hang on questions still open. Resolving a ticket clears the fog ahead of it, graduating into fresh tickets whatever has become specifiable — one at a time, until the way to the destination is clear and no tickets remain.
+The map is *deliberately* incomplete: don't chart what you can't yet see. Beyond the live tickets lies the fog: decisions and investigations you can feel coming but can't yet pin down, because they hang on questions still open. Resolving a ticket clears the fog ahead of it, graduating into fresh tickets whatever has become specifiable, one at a time, until the way to the destination is clear and no tickets remain.
 
 **Not yet specified** is where that dim view is written: the suspected question, the area to revisit. Everything here is in scope, just not sharp enough for a ticket.
 
-**Fog or ticket?** The test is whether you can *phrase* the question precisely now — not whether you can *answer* it now.
+**Fog or ticket?** The test is whether you can *phrase* the question precisely now, not whether you can *answer* it now.
 - **Ticket** when the question is already sharp, even if blocked.
 - **Not yet specified** when you can't yet phrase it that sharply. Don't pre-slice the fog into ticket-sized pieces.
 
 ## Out of scope
 
-Fog only ever gathers *toward* the destination. Work beyond the destination is **out of scope**: it isn't fog, it doesn't belong in *Not yet specified*. It gets its own section on the map. It never graduates — the frontier stops at the destination. When an existing ticket turns out to sit beyond the destination, label it **`trailhead:out-of-scope`**, **close it**, and leave one line in *Out of scope* with the why, linking the closed ticket. The label keeps it distinct from a resolved ticket; it stays out of *Decisions so far*, which records the way actually walked.
+Fog only ever gathers *toward* the destination. Work beyond the destination is **out of scope**: it isn't fog, it doesn't belong in *Not yet specified*. It gets its own section on the map. It never graduates: the frontier stops at the destination. When an existing ticket turns out to sit beyond the destination, label it **`trailhead:out-of-scope`**, **close it**, and leave one line in *Out of scope* with the why, linking the closed ticket. The label keeps it distinct from a resolved ticket; it stays out of *Decisions so far*, which records the way actually walked.
+
+**Out of scope vs deferred (ask, never bury).** *Out of scope* is for work ruled beyond the destination **for good**: this effort never does it. It is **not** a parking lot for work that *will* happen but hangs on something **outside this map**, a feature, function, or milestone not ticketed here (e.g. a billing / *bolletta* module that lives elsewhere or comes later, and the items that wait on it). Before filing anything under *Out of scope*, apply the test: **will this actually get done once X exists?** **The tells of a deferred line (any one is enough):** it **names a gate or trigger** (*gated by X*, *quando X*, *once X exists*, *dipende da X / waits on X*); it carries a **this-only scope qualifier** that rules it out *here* but not for good (*per questo slice*, *for now*, *in this milestone*, *not in this map*), which means wanted-later, not rejected; it's a **feature the product will plausibly still want** (a later milestone, another map); or **an existing `trailhead:seed` is gated on it** (some seed's trigger / `## Blocked by` names this line), which makes it a **live gate by definition**. Any one of these is deferred: never wave it through as "genuinely beyond the destination". Only work **decided against for the product** (won't ever be built, wrong approach, explicitly cut, with **no** "for this slice / for now" qualifier) is truly out of scope. **A line that is the gate of a live seed can never be "ruled out"**: finding one means the cluster is mis-wired (the gate was left behind when its dependents became seeds), so re-route the gate too (see below), or those seeds' triggers dangle. If yes, it isn't out of scope, it's **deferred**, so don't close-and-forget it. **Ask the user how to capture it, and which map it belongs to** (this map, or a future / other map); **never decide silently, and every move out of *Out of scope* is user-confirmed** (you propose, the user picks the tier and the map). Route along the [capture spectrum](#capture-zero-friction--tracker): a **`seed`** gated on its trigger (tie it to what it waits on, e.g. *when the bolletta exists*), an **`idea`** to revisit, or a **`todo`** if it's already defined work to do now. **If it belongs to a future map** (defined work wanted for the product, but beyond this effort's arc), don't fabricate a map that isn't charted yet, but **do capture it as a real artifact, asking the user which**: a **`seed`** (a gated todo, a tracked issue that survives the map, is queryable by label, and can be the native `blocked_by` of its dependents) or an **`idea`** (a fog line, lighter, for a maybe-later). **Never leave it as a bare *Out of scope* text line**: that's the fragile case (a finished map's *Out of scope* is easy to lose, and a dependent wired to a text line has no real target). Leave only a one-line *Out of scope* **breadcrumb pointing at the artifact** (`→ future map: <name>, see <seed/idea link>`). It then **graduates into the current map** the moment this effort actually needs it (it "comes up on its own"), or **the next map charted on this repo harvests it**, its chart step asking which parked seeds/todos/ideas to pull in (see [Mode 1](#mode-1-chart-the-map-new-project-trailheadnew) / [Mode 1-bis](#mode-1-bis-adopt-an-existing-project-trailheadadopt)). Whichever way, **the gate and its dependents move together** (a dependent seed's trigger points at the gate's artifact, a live target), never split across "ruled out" and re-routed. **Re-route the gate, not just its dependents.** When the thing a deferred item waits on (its gate X) is itself an *Out of scope* / deferred line, X is deferred by the same test: **re-route X first** (its own `seed`/`idea`/`todo`, or a named future-milestone / another-map pointer), then **tie the dependents to X's new form**, never to a line that stays in *Out of scope*. A seed's trigger must point at a **live** target: a ticket/seed here, a named milestone/map, or a real external condition; a seed gated on a dead "ruled out" line has a trigger that can never fire. **Move a gate and its dependents together**, so the whole cluster leaves *Out of scope* at once (e.g. the *bolletta* becomes its own seed, and the "gated by the bolletta" items become seeds wired to it, none left behind as "ruled out").
+
+Only genuinely-beyond-the-destination work stays in *Out of scope*. The same test applies to **stale *Out of scope* lines** noticed later: `/trailhead:map` (read-only) **flags** any **un-parked** deferred line as an advisory (like blocked-by drift, it changes nothing) **and suggests running `/trailhead:inbox` to re-route them**, while `inbox` or an explicit user go-ahead does the **actual re-route**, a line that's really deferred becoming a seed/idea/todo instead of lingering as "ruled out". A line **already parked** (annotated `→ future map` with its dependent seeds wired to a live trigger) is settled: neither surface flags it again.
 
 ## Capture (zero friction → tracker)
 
-Capture without breaking flow, but with the **tracker** as destination, not scattered files. The verbs are in the **Capture** table under [Commands](#commands); here is the detail of each:
+Capture without breaking flow, to the **tracker** (not scattered files). One capture = one action + one confirmation line; it **resolves nothing**. The verbs are in the **Capture** table under [Commands](#commands); their per-verb detail and the **note · idea · seed · todo** commitment/timing spectrum (raw text → fog → gated ticket → frontier ticket) are in **`references/capture.md`**: read it when a capture verb needs more than the one-line gist. Any captured **ticket** lands either on a **map** or on the **whiteboard** (map-less): **when a map is open, ask the user which** before creating it (active map vs whiteboard; if several maps are open, the same ask picks which map). On a map it gets that map's `trailhead:map-<n>` label + native sub-issue edge (like any ticket; see [Multiple maps on one repo](#multiple-maps-on-one-repo-parking--concurrency)); on the whiteboard it gets the `trailhead:whiteboard` label and **no** map label or `Parent:` (see [The whiteboard](#the-whiteboard-map-less-tickets)). **When no map is open at all, the ticket goes to the whiteboard without asking** (there is nowhere else). This ask applies to the ticket-producing captures (`todo`, `bug`, `seed`, and `idea` only when it is sharp enough to be a ticket); `note` and a non-sharp `idea` stay map-fog and are unaffected. With **no open map** they have no map fog to land in, so a `note` falls back to the global notes location (`$HOME/.claude/notes/`) and a non-sharp `idea` is either sharpened into a whiteboard ticket or recorded as a global note.
+
+**Scope that surfaces while working a ticket.** Testing or building X often sparks new ideas: do **not** grow X in flight; a ticket is one answerable Question, sized to one session. Decide per idea:
+- part of X's Question and small → just do it in X (that's completing X, not expanding it);
+- it balloons X past one session → **`split`** X (children carry the new pieces, supersede the original);
+- separate work or a follow-up beyond X's goal → **capture and continue** (`idea`/`todo`/`ticket`/`bug --of X`), don't derail.
+
+Tickets born this way carry a **`Surfaced from: <ticket name+link>`** line in their body (the same lineage convention as `Split from:` and `Regression of:`) so where an idea came from stays visible. Never let extras become silent lines inside X: the map stays honest by spinning them into their own tickets or fog.
 
-- **`note`** → a verbatim line in `## Not yet specified` (outside a project → `$HOME/.claude/notes/`). No questions, no rewriting.
-- **`idea`** → fog by default in `## Not yet specified`; becomes a ticket only if already phrasable as a sharp question. An idea in the fog is **not executable** — to work it, it must first **graduate** into a ticket (which happens when the frontier reaches it, or when you can now phrase it sharply). A `todo`, by contrast, is born a `build` ticket and is workable immediately.
-- **`todo`** → a small `trailhead:build` ticket on the frontier (defined work you will do — a todo is just a small build ticket). If it's a parking spot *beyond* the destination, it goes in `## Out of scope` instead.
-- **`bug`** → a `trailhead:bug` ticket on the frontier; the repro in the body if you know it. If it blocks the ticket you're working, add it to that ticket's `## Blocked by` and label that ticket `trailhead:blocked`. Pass **`--of <ticket>`** (a number, `#n`, name, or URL) to record it as a `Regression of: <ticket>` pointer in the body — use it for a bug in already-closed work, which is always a *new* ticket, never a reopen (see the `bug` engine for the reopen exception). **Don't derail**: capture and continue — you resolve it in a dedicated session.
-- **`seed`** → a ticket labelled `trailhead:seed` + `trailhead:blocked`, kept in its own `## Blocked by` until the trigger fires; note the trigger in the body. When the trigger fires, drop both labels to graduate it onto the frontier.
+## Multiple maps on one repo (parking & concurrency)
 
-**note · idea · seed · todo form a spectrum** of commitment and timing (`bug` is separate — a defect, not a capture-tier):
+By default a repo has **one live map** and the frontier is the whole repo (as everywhere above). But you can **park a map to work another**, and a teammate can chart a second map on the same repo and work it concurrently. When more than one `trailhead:map` is open, each map carries **its own frontier**, kept separate by two mechanisms wired together (the same "one fact, two views" pattern as a blocker's native edge + label):
 
-| Verb | Lands as | Workable when | Meaning |
-|---|---|---|---|
-| **note** | verbatim text (fog, or global notes) | maybe never — just recorded | *remember this* (not necessarily work) |
-| **idea** | fog (`Not yet specified`) | later, **if** it graduates to a ticket | *maybe I'll do it* |
-| **seed** | a blocked ticket | when a **trigger** fires | *I'll do it when X happens* |
-| **todo** | a frontier ticket | **now** | *I'm doing it* |
+- **Native sub-issue**: every ticket is a **sub-issue of its map** (`gh api --method POST repos/{owner}/{repo}/issues/<map>/sub_issues -F sub_issue_id=<ticket .id>`). This is the structure GitHub renders (the map shows its children + a progress bar); it carries the `Parent:` line's meaning as a real edge.
+- **Per-map label `trailhead:map-<n>`** (n = the map issue's own number): on **every one of its tickets** (not on the map issue itself, which is identified by its number, and would only be redundantly "a member of itself"). This is the **queryable key** that scopes the frontier to one query, because native sub-issues aren't cheaply filterable in a single search (exactly as with `blocked_by`), so the label carries the query.
 
-Discriminator: not even work → `note`; maybe, once it's clear → `idea`; yes, when X happens → `seed`; yes, now → `todo`. The close pairs: `note` vs `idea` — raw text vs a work-candidate meant to graduate; `idea` vs `seed` — waiting on *clarity* vs waiting on a *condition*; `seed` vs `todo` — committed *later* vs committed *now*.
+Both are set at chart and on every ticket **in the same pass** (create the ticket → set its map parent → add its map label), so they can't drift.
 
-One capture = one action + one confirmation line. It resolves nothing.
+**Scoped frontier** (one query, per map):
+```bash
+gh issue list --label "trailhead:ticket" --label "trailhead:map-<n>" --state open \
+  --search "no:assignee -label:trailhead:blocked -label:trailhead:unverified"
+```
 
-**Scope that surfaces while working a ticket.** Testing or building X often sparks new ideas — do **not** grow X in flight; a ticket is one answerable Question, sized to one session. Decide per idea:
-- part of X's Question and small → just do it in X (that's completing X, not expanding it);
-- it balloons X past one session → **`split`** X (children carry the new pieces, supersede the original);
-- separate work or a follow-up beyond X's goal → **capture and continue** (`idea`/`todo`/`ticket`/`bug --of X`), don't derail.
+**Active map.** Which map a session works is the **active map**: a `.trailhead/active-map` marker at the working root (one line `#<n>`, **gitignored**, per-session local state like `session-ticket`, never committed). `/trailhead:work` and `/trailhead:map` default to it; naming a map/ticket explicitly always overrides. Each checkout/clone (so each teammate) has its own.
 
-Tickets born this way carry a **`Surfaced from: <ticket name+link>`** line in their body — the same lineage convention as `Split from:` and `Regression of:` — so where an idea came from stays visible. Never let extras become silent lines inside X: the map stays honest by spinning them into their own tickets or fog.
+**Park & switch** = **pause** the in-flight ticket (`/trailhead:pause`, a `PAUSED` checkpoint), then point the active map at the other's number. Nothing else to save: every map lives on the Issues, durable. Resume later with `/trailhead:resume`, or just `/trailhead:work` once that map is active again.
 
-## Working as a team
+**Discovery.** `gh issue list --label "trailhead:map" --state open` enumerates the live maps. `/trailhead:map` with **no active map and more than one open** lists them and asks which; `/trailhead:map <n>` shows that one and makes it active.
 
-Many people (and their agent sessions) share one map and work it concurrently. The tracker is the single source of truth; these conventions keep concurrent work from colliding.
+**Pinning with several maps.** No map is ever pinned. The 3 pinned slots are the permanent repo anchors: **dashboard + codebase + conventions**. Every open map is found via the `trailhead:map` label and listed in the pinned [dashboard](#the-dashboard-a-pinned-repo-index), so all of them stay reachable regardless of how many are live, without contending for a slot.
 
-### Claiming
-Whoever claims a ticket **owns it end to end** — they work it and close it themselves. "Owner" means only "the current claimer of *this* ticket," never a project-wide approver; there is no gate and no one to wait on to close your own ticket. GitHub assignment isn't an atomic lock, so keep the protocol simple and human-decided:
+**Team.** A teammate charts a new map → it gets its own `trailhead:map-<m>` + sub-issue parentage → their sessions scope to it. The two frontiers **never mix** (distinct labels). Per-ticket **claim/collision** rules are unchanged (the assignee is still the claim). Two maps can still touch the **same code**: the `Scope:` line + `isolation:` serialisation from [Working as a team](#working-as-a-team) now apply **across maps too**, not just within one.
 
-1. **Before claiming, check it's not already being worked.** Read the assignee. If it's already assigned to someone else, it's in progress — don't take it; pick another frontier ticket. (If the user explicitly named this taken ticket, stop and tell them it's assigned to `<login>`.)
-2. **Claim it** — assign it to yourself: `gh issue edit <n> --add-assignee @me`.
-3. **Re-check right before starting work.** Read the assignee again. If someone else got assigned in the meantime, **do not do any work — stop and flag it to the user with a clear message**, e.g.:
+**One-map compatibility.** With a single open map the frontier stays **repo-wide** (minus `trailhead:whiteboard` tickets, which carry their own frontier, see [The whiteboard](#the-whiteboard-map-less-tickets)); the map label + sub-issue are still applied at chart, so concurrency is ready the moment a second map appears. An older map charted before this (tickets lacking the label) needs a one-time **backfill** (add `trailhead:map-<n>` to its open tickets, set their sub-issue parent) only if you add a second map on that repo.
 
-   > ⚠️ **Claim collision on “<ticket name>” (#<n>).** It's now also assigned to **@<other-login>**, who may be working it right now. I've stopped and done nothing. How do you want to proceed?
-   > 1. **Leave it to them** — I'll unassign myself and take the next frontier ticket.
-   > 2. **Take it over** — I'll keep it and post a comment notifying @<other-login> that you're taking it.
+## The whiteboard (map-less tickets)
 
-   Do exactly what the user chooses — never resolve the collision silently.
-4. **Unclaim if you stop.** Pausing or abandoning a ticket → remove your assignment so it returns to the frontier. A claimed-but-idle ticket is invisible work.
-5. **Never touch a ticket someone else holds.** Don't edit its body, labels, or state; contribute via a comment and let its owner incorporate it.
+Not all work belongs to a map. A **bug**, a **todo**, or a one-off **task** may be about something else entirely, or simply not worth charting a map for. The **whiteboard** is where that loose work lives: tickets labelled **`trailhead:whiteboard`**, map-less (no `trailhead:map-<n>` label, no `Parent:` line, no native sub-issue edge). A ticket is on a map **or** on the whiteboard, never both.
 
-### Pausing & resuming
-Switching away from a ticket mid-work — to clear a blocker, chase an urgent bug, or just stop — must not lose the thread.
-- **Pause** (`/trailhead:pause [note]`) — first commit any work-in-progress (atomic) so nothing is stranded, then post a **`PAUSED`** checkpoint comment: what's done, the exact next step, and any local state (branch, how to run it). Keep the claim if you'll return soon; **release it** (unassign) if it's open-ended, so someone else can resume — the checkpoint is what makes that safe.
-- **Resume** (`/trailhead:resume [ticket]`) — read the ticket's latest `PAUSED` checkpoint (and the `DISCUSS`/`PLAN` comments above it), then pick up at the recorded next step. Anyone may resume a *released* ticket; a still-claimed one, only its owner.
-- One ticket per session still holds: pausing A to work B ideally means B in a fresh session. If you must switch within one session, checkpoint A first — never leave it half-done and unrecorded.
+**Ensure the label exists before applying it.** A repo that adopted trailhead before the whiteboard existed never created `trailhead:whiteboard` (first-use setup ran the old label set), so applying it would fail. Every path that puts a ticket on the whiteboard (a whiteboard-routed [capture](#capture-zero-friction--tracker), or [`quick`](#quick-work-one-ticket-whole-off-the-map) creating one) must first create the label if missing, idempotently: `gh label create trailhead:whiteboard --color C5DEF5 --description "Map-less ticket: lives on the whiteboard" 2>/dev/null || true`. This is the same ensure the first-use label step does, just reachable outside chart/adopt.
 
-### Splitting a ticket
-A ticket is sized to one ~100K-token session. When a claimed ticket turns out too big, or fans into distinct pieces, **split it** — don't grind through an oversized ticket:
-1. **Create the child tickets** (create-then-wire): each carries `Parent: <map>`, a `Split from: <original name+link>` line, its type label, and `trailhead:blocked` if it has an open blocker.
-2. **Supersede the original**: post a comment listing the children (`split into <names+links>`), label it **`trailhead:superseded`**, and **close it**. The children fully replace it.
-3. The superseded ticket stays **out of `Decisions so far`** (it wasn't a decision walked — its children are). If other tickets were blocked by the original, re-point their `## Blocked by` at the relevant child and re-evaluate their `trailhead:blocked`.
+Work reaches the whiteboard two ways: a **capture routed there** (a ticket-producing `todo`/`bug`/`seed`/sharp-`idea` sent to the whiteboard instead of a map, see [Capture](#capture-zero-friction--tracker)), or a ticket **born there** by [`quick "<text>"`](#quick-work-one-ticket-whole-off-the-map).
 
-Splitting is not resolving: a superseded ticket delivered nothing itself. (If instead the ticket sits beyond the destination, that's *out of scope*, not a split.)
+It has its **own frontier**, off every map's (see [Substrate](#substrate-github-issues), Map frontier vs whiteboard frontier):
+```bash
+gh issue list --label "trailhead:ticket" --label "trailhead:whiteboard" --state open \
+  --search "no:assignee -label:trailhead:blocked -label:trailhead:unverified"
+```
 
-### Concurrent edits to the map
-The map issue's **body** is a shared mutable document — two sessions appending to `Decisions so far` at once will clobber each other (GitHub doesn't merge bodies). So:
-- **The durable record of a resolution is the ticket's resolution comment**, never the map body. The map's `Decisions so far` is a best-effort index rebuilt from the tickets; if a line is lost to a race, it's recoverable from the closed ticket.
-- **Re-read the map body immediately before editing it**, append your one line, write back — keep the window tiny. Never edit the map from stale content read earlier in the session.
-- **Keep map-body writes small and append-only** where possible; heavy restructuring of the map is a single-session job, done when no one else is mid-write.
-- Ticket-level state (claim, labels, comments, close) is naturally conflict-free — prefer expressing state there over in the map body.
+**`/trailhead:whiteboard`** renders this as a read-only dashboard, a mirror of [`/trailhead:map`](#the-map) minus destination, decisions, and fog (the whiteboard has no direction, only loose work), by name:
+- **Frontier**: takeable now (open, unassigned, not blocked/unverified whiteboard tickets), each with its type.
+- **In progress**: claimed whiteboard tickets, with who holds each.
+- **Blocked**: any blocked whiteboard ticket, with what it waits on (a whiteboard ticket can still block on another).
 
-### Trust & provenance
-`trailhead:*` labels drive the map, so they must not be forgeable by outsiders. GitHub already blocks users without write access from applying labels at all; this layer defends against the rest (triage-level collaborators, automations, or a repo that later loosens permissions).
+**Dashboard self-heal.** Like the map render, ensure the repo's pinned `trailhead:dashboard` index exists and is pinned before rendering (create + pin only if missing, re-pin if the pin was dropped; never rewrite its body here). See [The dashboard's self-heal note](#the-dashboard-a-pinned-repo-index).
 
-**Trust rule.** Treat a `trailhead:map` / `trailhead:ticket` issue as genuine **only if** its `trailhead:*` label was applied by a repo collaborator with **write access or above**, *and* (for a ticket) it carries a valid `Parent:` line pointing at this map. To check the labeller, read the issue timeline — `gh api repos/{owner}/{repo}/issues/{n}/timeline` gives `labeled` events with their `actor` — and confirm the actor's permission with `gh api repos/{owner}/{repo}/collaborators/{actor}/permission` (`admin`/`write`/`maintain` = trusted; `read`/`none` = not).
+**Working the whiteboard.** Take a ticket with [`quick <n>`](#quick-work-one-ticket-whole-off-the-map), or `work <n>` by number; both work a single whiteboard ticket. There is no book-keeping to fold back (no `Decisions so far`, no fog to graduate), so a whiteboard resolution is just the resolution comment, `gh issue close`, and the [Session handoff](#session-handoff). Whiteboard tickets are never pinned and take no map slot.
 
-**On an untrusted match** — a `trailhead:*` issue whose label came from a non-write actor, or a ticket with no valid `Parent:` — do **not** put it on the frontier or act on it. Label it **`trailhead:unverified`**, and surface it to the user as a quarantined item to **adopt** (a maintainer re-applies the real labels + wires `Parent:`) or **reject** (strip the `trailhead:*` labels, leave it a normal issue). Never silently trust a label just because it's present.
+## The dashboard (a pinned repo index)
 
-**Repo-side enforcement (recommended).** trailhead **installs the label guard for you** — don't tell the user to copy files. When charting or adopting a map on a shared repo, offer to install it; on their go-ahead, write the shipped label-guard template (`${CLAUDE_PLUGIN_ROOT}/templates/trailhead-label-guard.yml` for a plugin install, or `~/.claude/trailhead/templates/trailhead-label-guard.yml` for an npm install — take whichever exists) to the repo's `.github/workflows/trailhead-label-guard.yml` and commit it (conventional message; the commit-guard hook keeps it clean). The Action strips any `trailhead:*` label added by a non-write actor and comments why; set an optional `TRAILHEAD_LABEL_ALLOWLIST` repo variable to whitelist extra logins (e.g. a bot trailhead runs as). **Caveat:** pushing a workflow file needs a token with the `workflow` scope — if the push is rejected, run `gh auth refresh -s workflow` and retry (or, as a last resort, tell the user to add the file by hand).
+A repo's trailhead surface is spread across issues: one or more maps, a whiteboard, an inbox. The **dashboard** is the single pinned entry point that indexes all of it: a permanent, repo-scoped issue labelled **`trailhead:dashboard`**, created once at the first chart/adopt and occupying the **fixed 3rd pinned slot** alongside `trailhead:codebase` and `trailhead:conventions` (see [Substrate](#substrate-github-issues)). Maps themselves are **never pinned**: a pin is server-side and global to the repo, but the active map is client-side per-checkout state (`.trailhead/active-map`, gitignored), so no single map is "the" map to pin. The dashboard removes that category error and gives one stable pinned index that scales to any number of maps and to the whiteboard.
 
-## Inbox — issues opened by others
+It holds:
+- a link to **every open `trailhead:map`** (found via the `trailhead:map` label); GitHub renders each map's sub-issue **progress bar natively**, so the dashboard only links, it never recomputes per-ticket progress;
+- the **whiteboard** as its own section (frontier / in-progress / blocked, or a link to the `/trailhead:whiteboard` view);
+- dynamic **counts**: untriaged inbox size, whiteboard frontier size.
 
-People file issues that aren't trailhead tickets — bug reports, feature requests, questions. `/trailhead:inbox [issue]` triages them and **integrates the worthwhile ones into the map**, keeping the reporter's authorship.
+**`/trailhead:dashboard`** regenerates the pinned issue body from the live tracker and shows it, both the render and the on-demand refresh, consistent with `/trailhead:map` and `/trailhead:whiteboard`. It creates and pins the issue if the repo doesn't have one yet (ensuring the `trailhead:dashboard` label first, idempotently, like the whiteboard label).
 
-`/trailhead:inbox` presents **two sections**:
+**Freshness: structural events + on demand.** The pinned issue is rewritten when the surface changes **structurally**, a map is **charted** (Mode 1/1-bis) or **exhausted** (a map appears or disappears), and **on demand** via `/trailhead:dashboard`. It is **not** rewritten on every ticket resolve: that would churn a pinned issue (and its notifications) constantly, and the native progress bars already track per-ticket progress. Links + counts stay good enough refreshed at structural events and on demand.
 
-**A. New — to triage.** Open issues carrying **no** `trailhead:*` label (plus any `trailhead:unverified` from the trust guard):
-```bash
-gh issue list --state open --json number,title,author,labels \
-  | jq '[.[] | select([.labels[].name] | any(startswith("trailhead:")) | not)]'
-```
+**Self-heal (read-only entry points).** A repo that adopted trailhead before the dashboard existed, or one whose pin was later dropped, has no pinned index until the next chart/adopt or an explicit `/trailhead:dashboard`. To close that gap, the frequent **read-only entry points self-heal the pin**: the bare `/trailhead` [smart entry](#commands), the [`/trailhead:map`](#the-map) render, and the [`/trailhead:whiteboard`](#the-whiteboard-map-less-tickets) render each ensure the dashboard exists and is pinned before rendering, idempotently and cheaply, mirroring the "ensure the label exists before applying it" pattern: ensure the `trailhead:dashboard` label, then
+- **if no dashboard issue exists**, create it, write the current surface once, and pin it (the fixed 3rd slot);
+- **if it exists but is unpinned** (a dropped pin is exactly the drift to self-heal), re-pin it;
+- **if it exists and is already pinned**, do nothing.
 
-**B. Parked fog — any ready to graduate?** The open `trailhead:fog` issues, **most-recently-active first** — recent discussion is exactly where the fog has likely cleared, so you review those, not all of them:
-```bash
-gh issue list --label trailhead:fog --state open --search "sort:updated-desc"
-```
-This is **how you notice a fog has cleared**: you don't watch each thread — you run the inbox (as you would to triage new issues), and section B surfaces the parked items that moved. For each, decide: **graduate** (adopt in place — see Fog), **keep parked** (still vague), or **drop** (turned out out-of-scope/dead → `trailhead:out-of-scope` + close). Optionally, a participant can nudge readiness by commenting on the thread; you confirm at graduation.
+**Create + pin only when missing: never rewrite the body on these renders.** They are frequent read-only views, not the on-demand refresh, so the freshness rule above holds unbroken (`/trailhead:dashboard` and structural events stay the only writers of the body). The one body write these paths ever make is the initial one at creation (the dashboard appearing is itself a structural event).
+
+## Working as a team
+
+Many people (and their sessions) share one map concurrently; the tracker is the single source of truth. **Claiming (needed every time you work a ticket):** assign it to yourself before any work (`gh issue edit <n> --add-assignee @me`), re-read the assignee right before starting, and on a **collision stop and ask the user**: never resolve it silently; unclaim if you stop; never touch a ticket someone else holds. Whoever claims a ticket owns it end to end and closes it (no approver).
 
-For each issue in either section, decide — with the user for judgement calls, on your own for clear ones:
+The rest of the concurrency protocol lives in **`references/teamwork.md`**. Read it when you do that thing: **pausing & resuming** (`PAUSED` checkpoints, release vs keep the claim), **parking & switching between concurrent maps** on one repo (see also [Multiple maps on one repo](#multiple-maps-on-one-repo-parking--concurrency)), **splitting** an oversized ticket (children + supersede + re-point blockers), the **undeclared-coupling** check between parallel tickets, safe **concurrent map-body edits**, and **trust & provenance** (the trust rule, the `trailhead:unverified` quarantine, and installing the repo-side **label guard** at first-use).
 
-- **Adopt → a ticket.** Integrate it *in place* (same issue number, so the reporter stays credited): append a trailhead block to the body — `Parent: <map name+link>`, `Adopted-from: opened by @<author>`, a reframed `## Question` (the decision/build the *map* will act on), and `## Blocked by` — **without erasing the reporter's original text above it**. Apply `trailhead:ticket` + the right type label (`bug`/`decision`/`build`/`research`/`task`) as a write-access maintainer (which also satisfies [Trust & provenance](#working-as-a-team)); add `trailhead:blocked` if it has an open blocker. It lands on the frontier. Comment to the reporter that it's been picked up.
-- **Fog.** In scope but not sharp enough to ticket → **keep the issue open and label it `trailhead:fog`** (parked: still visible and tracked, but the `trailhead:*` label drops it out of the inbound query, so it won't re-surface at every triage). Then use the open issue as a **clarification space**: post a comment with the questions that would make it concrete — in the spirit of **Grilling**, but async ("what would *done* look like? which users? where does it show?") — and invite the reporter and anyone interested to refine it in the thread. The fog dissipates through that conversation as much as through other work landing; others can carry the discussion with the reporter without you in the loop. **You don't lose it** — `gh issue list --label trailhead:fog` is the durable list, and the reporter follows their own open issue. When the thread (or the wider work) has made the question sharp, **adopt it in place**: swap `trailhead:fog` for `trailhead:ticket` + the type label, add `Parent:` and the now-answerable `## Question`, and it lands on the frontier — same issue, same reporter, the clarifying discussion preserved above.
-- **Out of scope.** Beyond the destination → label `trailhead:out-of-scope`, close with the why.
-- **Duplicate.** Link the existing ticket and close.
-- **Needs info.** Ask the reporter for a repro or specifics; leave it open.
+## Inbox: issues opened by others
 
-A rogue issue wearing a `trailhead:*` label it shouldn't (now `trailhead:unverified`) is triaged the same way: **adopt** (a maintainer applies the real labels + `Parent:`) or **reject** (strip the `trailhead:*` labels, leave it a normal inbound issue). Never adopt by trusting a label that was already there — you apply the labels on adoption.
+`/trailhead:inbox [issue]` triages issues opened by others (bug reports, requests, questions that aren't trailhead tickets) and integrates the worthwhile ones **in place**: reframing them as tickets, keeping the reporter's authorship, applying the labels on adoption; the rest routes to fog, out-of-scope, duplicate, or needs-info. It also surfaces **parked `trailhead:fog`** whose thread went quiet-then-active (that's how you notice a fog has cleared), **and sweeps the map's own *Out of scope* for lines that are actually [deferred](#out-of-scope)** (a gate/trigger or a wanted-later feature), asking the user to re-route each to a seed/idea/todo (which map) and wiring it gate-first with a live trigger. This is the surface where the map's read-only advisory turns into an actual re-route. **Full protocol (the three sections, the adopt/fog/out-of-scope/duplicate/needs-info routing, the deferred-out-of-scope sweep, the `trailhead:unverified` handling) in `references/inbox.md`**: read it when running inbox.
 
 ## Invocation
 
-### Mode 1 — Chart the map (new project) — `/trailhead:new`
+### Mode 1: Chart the map (new project), `/trailhead:new`
 The user invokes with a loose idea.
 
 1. **Name the destination.** Run the **Grilling** + **Domain vocabulary** techniques to pin down what this map tends toward. The destination fixes the scope, so it's settled first. Default: a working artifact.
-2. **Map the frontier.** Grill again, **breadth-first**: fan out across the whole space rather than deep on one thread, surfacing the open decisions and the first steps takeable now. **If no fog surfaces** — the way is already clear, the whole thing fits one session — you don't need a map: stop and ask how to proceed.
-3. **Create the map** (`trailhead:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into *Not yet specified*.
-4. **Create the tickets you can specify now** as child issues — then wire the blocking in a **second pass** (issues need ids before they can reference each other): fill each blocked ticket's `## Blocked by` and add the `trailhead:blocked` label. Wiring sorts them into frontier (unlabelled) and blocked; the rest stays fog.
+2. **Map the frontier.** Grill again, **breadth-first**: fan out across the whole space rather than deep on one thread, surfacing the open decisions and the first steps takeable now. **If no fog surfaces** (the way is already clear, the whole thing fits one session) you don't need a map: stop and ask how to proceed. **Harvest parked work:** from **earlier maps on this repo**, gather the artifacts their *Out of scope* `→ future map` breadcrumbs point at (**parked seeds/todos**, see [Out of scope](#out-of-scope)) **and the ideas** left in their *Not yet specified* fog, then **ask the user which belong in *this* map**; pull the chosen seeds/todos in as tickets and the chosen ideas in as fog (or as tickets, if now sharp enough), and leave (or update the destination on) the rest.
+3. **Create the map** (`trailhead:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into *Not yet specified*. Run the [first-use repo setup](#substrate-github-issues) now: labels **and** the label-guard check/install. Once the map issue has its number `<n>`, **create its per-map label `trailhead:map-<n>`** (every ticket of this map carries it and is a native sub-issue of the map; the map issue itself is found by its number, so it does **not** carry the label; see [Multiple maps on one repo](#multiple-maps-on-one-repo-parking--concurrency)). **If this repo already has another open `trailhead:map`**, tell the user the new map runs concurrently (its own scoped frontier) and set it as the active map (`.trailhead/active-map`). Then set up **conventions**: if no `trailhead:conventions` issue exists, run a **brief conventions brainstorming** (breadth-first, in the spirit of grilling but short: a handful of questions, not a full session) to surface the project's way of working: `git:` `main`|`pr`, `release:` `command`|`auto`, and `isolation:` `none`|`worktree` (the header, the last asked as *"will more than one session run on a single clone at once?"* → `worktree`; a monorepo leans `worktree`), **plus** the narrative a new contributor would need: release/deploy specifics (environments, manual steps, OTA vs full build, versioning), tooling that must be driven a certain way (a specific MCP/CLI, e.g. a Lovable project piloted via its MCP), code & style rules, testing/UAT norms. Distil into the issue (header + prose); link it from the map's Notes. Don't invent: leave out or ask what you can't determine. If one already exists, just link it (reuse across maps). Finally, **ensure the repo's [`trailhead:dashboard`](#the-dashboard-a-pinned-repo-index) index issue exists**: create and pin it if missing (the fixed 3rd pinned slot, alongside codebase + conventions), then **write it to list this map** (charting a map is a structural event); if it already exists, refresh it.
+4. **Create the tickets you can specify now** as child issues (each with `trailhead:ticket` + its type + this map's `trailhead:map-<n>` label, and set as a **native sub-issue** of the map, see [Child→map link](#substrate-github-issues)), then wire the blocking in a **second pass** (issues need ids before they can reference each other): for each ticket **read its Question and wire a blocker for every still-open ticket whose output it consumes** (don't stop at the first/obvious one), then run the three-move wiring (`## Blocked by` line + native dependency + `trailhead:blocked` label, see [Substrate](#substrate-github-issues)). Wiring sorts them into frontier (unblocked) and blocked; the rest stays fog.
 5. **Fire the research subagents.** For each `research` ticket created, run the **Research** technique in parallel, findings on a `research/<name>` branch with a pointer from the ticket.
-6. Stop — charting is one session's work; it hand-resolves nothing.
+6. **Offer config, then stop.** Charting is one session's work; it hand-resolves nothing. Before ending, make the **first-time config offer** (see [smart entry](#commands)): the project now has a fresh map and no `.trailhead/config.json`, so put the **two-way choice** to the user, **accept as-is** (writes `{}`) or **run `/trailhead:config`** for the guided menu, and let them pick. Name both paths; don't pre-fill the config keys and ask for an inline edit, and don't interview them key-by-key here (that's `/trailhead:config`'s job). Once the file exists it's never offered again. **No `trailhead:codebase` issue is created here**: greenfield has no code to map yet. It's created later, once the repo has substantial code (see Mode 2 step 1 and the [Codebase](#substrate-github-issues) row), so at chart two of the three permanent pins (the dashboard + conventions) are filled and the codebase slot fills in later. Maps are never pinned.
 
-### Mode 1-bis — Adopt an existing project — `/trailhead:adopt`
+### Mode 1-bis: Adopt an existing project, `/trailhead:adopt`
 When the code already exists (project in progress). Like Mode 1, but start from **reality**, not a blank page. One heavy step at entry, then all lean.
 
-1. **Map the codebase (once).** Heavy step, *only* at adoption — it does not repeat per ticket. Run the **Codebase map** technique (a parallel fan-out of reader subagents) for a structured understanding: architecture, stack, decisions already embodied, risk areas. Distil the essence into a `## Codebase` block in the map's *Notes* and discard the raw. The tracker stays the source of truth; the per-ticket cycle stays lean.
+1. **Map the codebase (once per repo).** Heavy step, *only* at adoption: it does not repeat per ticket, and **not per map**. First check for an existing **`trailhead:codebase`** issue: if one exists (an earlier map on this repo created it) and the code hasn't materially drifted, just **link it** from this map's Notes and skip the fan-out. Otherwise run the **Codebase map** technique (a parallel fan-out of reader subagents) for a structured understanding (architecture, stack, decisions already embodied, risk areas) and distil the essence into the repo's **`trailhead:codebase` issue** (create it, label `trailhead:codebase`), then link that issue from the map's Notes. Discard the raw. Because it's a standalone repo-scoped issue, the next map reuses it instead of re-deriving or losing it.
 2. **Name the destination of the remaining stretch.** **Grilling** + **Domain vocabulary**, **seeded by the map you just built**: not "what is the project" but "what's left to reach working / the next milestone".
 3. **Backfill the decisions already made.** Choices already embodied in the code (now visible from the map) or stated by the user go into `Decisions so far` as **ticket-less** lines (they're already closed), so the map reflects reality and doesn't pretend greenfield. Link to code/commits where useful.
-4. **Map the frontier of the remainder** → tickets specifiable now + fog in *Not yet specified*, then wire the blocking and fire the research. As Mode 1, steps 4–6.
+4. **Map the frontier of the remainder** → tickets specifiable now + fog in *Not yet specified*, then wire the blocking and fire the research. **Harvest parked work** (todos *and* ideas) from earlier maps on this repo (their `→ future map` *Out of scope* lines and their *Not yet specified* fog), asking the user which belong here, as in Mode 1 step 2. As Mode 1, steps 4–6.
 
-The tracker is the existing repo's (`gh` in its directory); create any missing `trailhead:*` labels on first use.
+The tracker is the existing repo's (`gh` in its directory); run the [first-use repo setup](#substrate-github-issues) on first use (missing `trailhead:*` labels **and** the label-guard check/install (adopting an existing repo is exactly when the guard tends to be missing)) and set up the `trailhead:conventions` issue via a **brief conventions brainstorming** (see Mode 1 step 3), but here, **seed the questions from what's discoverable** so you confirm rather than ask blind: an existing `CLAUDE.md`/`AGENTS.md`, CI workflows, the PR-vs-`main` git history, package scripts, deploy config. **Detect a monorepo** (a `pnpm-workspace.yaml`, a `workspaces` field, an `nx.json`/`turbo.json`, or several packages under `packages/`|`apps/`) and, if found, propose `isolation: worktree` and note that tickets should carry a `Scope:` line, **unless the buildable units are path-bound** (see below). **Detect git submodules** (a `.gitmodules` file) and, if found, add the prose rule that submodule work is committed **inside the submodule + a gitlink bump in the parent**, isolated at the submodule (not the superproject); a submodule path is a natural `Scope:` (see [Working as a team](#working-as-a-team)). **Before proposing `worktree`, check for path-bound tooling** (a React Native/Expo app, native toolchains, a package whose build depends on a local `node_modules`/bundler cache/absolute-path config): those don't build from a worktree, so for them propose **`isolation: clone`** (a per-ticket clone that installs its own deps and builds), or `isolation: none` + **serialize** if the user doesn't want per-ticket clones. Worktree is for units that build from any path. Propose the values you inferred and let the human correct/complete them; create the issue if absent, link it from the map's Notes. Also **ensure the repo's [`trailhead:dashboard`](#the-dashboard-a-pinned-repo-index) index issue exists**: create and pin it if missing (the fixed 3rd pinned slot, alongside codebase + conventions) and write it to list this map.
 
-### Mode 2 — Work the map — `/trailhead:work`
-The user invokes with a map (URL or number). A ticket is optional — without one, you pick the next decision.
+### Mode 2: Work the map, `/trailhead:work`
+The user invokes with a map (URL or number). A ticket is optional: without one, you pick the next decision.
 
-1. Load the **map** (the low-res view, not every ticket body).
-2. Choose the ticket. If the user names one, use it. Otherwise the first frontier ticket in order. **Claim** it: assign it to yourself before any work, then re-read the assignee before starting — on a collision, stop and ask the user (see [Working as a team](#working-as-a-team)). If the ticket proves too big once you're in it, **split** it rather than grind (same section).
-3. Resolve it with its type's engine — **zoom as needed**: fetch the full body of related/closed tickets on demand. If in doubt on a `decision` ticket, run **Grilling** + **Domain vocabulary**. If in doubt on a `build`, **stop and ask** (see the Discuss step) — never auto-grill.
+1. Load the **map** (the low-res view, not every ticket body). **Pick which map** if the repo has several open: use the one the user named, else the active map (`.trailhead/active-map`); if neither and more than one is open, list them and ask. Set/refresh the active-map marker to the one you're working. See [Multiple maps on one repo](#multiple-maps-on-one-repo-parking--concurrency). **Codebase issue check (greenfield, offer once):** if the repo has **no `trailhead:codebase` issue** (a greenfield map never got one) and now holds **substantial code**, offer once to generate it via the [Codebase map](#techniques) technique, then pin it (one of the three permanent repo pins: dashboard, codebase, conventions) and link it from the map's Notes; if the user declines, don't nag again this session. A repo that already has the issue, or is still too thin to map, skips this.
+2. Choose the ticket. If the user names one, use it (a **named** ticket may be a `trailhead:whiteboard` one: `work <n>` works it whole, off the map, with the normal cycle and split allowed; use [`quick <n>`](#quick-work-one-ticket-whole-off-the-map) for the no-split variant). Otherwise the first frontier ticket in order, **scoped to this map** (add its `trailhead:map-<n>` label to the frontier query when several maps are live) and **never a whiteboard ticket** (bare `work` stays on the map; the whiteboard frontier is reached via `/trailhead:whiteboard` and `quick`). **Claim** it: assign it to yourself before any work, then re-read the assignee before starting; on a collision, stop and ask the user (see [Working as a team](#working-as-a-team)). If the ticket proves too big once you're in it, **split** it rather than grind (same section).
+   - **First, if the conventions header has NO `isolation:` key at all** (never chosen, so silently defaulting to `none`), sanity-check it **once** before working: if there's a real collision risk, don't just work the shared checkout. The risk signals are **another in-progress ticket** (a concurrent session is plausible) or **path-bound tooling in this ticket's `Scope:`** (a React Native/Expo app, native toolchain, a local `node_modules`). On a signal, surface a one-line suggestion naming it and the fitting mode (`worktree` for builds that run from any path, `clone` for path-bound apps) and offer to set it now. Whatever the user picks (**including "keep `none`"**), **write the `isolation:` key into the conventions issue** so the choice is recorded and this never prompts again. If the key is already present (any value, `none` included), it was chosen: respect it and skip this check. This is the one convention worth surfacing (it changes where you work); don't nag beyond writing the key once.
+   - **Under `isolation: none`, check the scope is free before starting** (this is how a submodule/package gets serialised when worktrees don't fit): scan the other in-progress tickets' `Scope:` lines, and if one **overlaps** this ticket's scope, **stop and tell the user** the scope is busy (name the ticket + holder) and offer a disjoint-scope frontier ticket or to wait. See [Working as a team](#working-as-a-team).
+   - **Write the session-ticket marker** (a cheap hint for tooling like a statusline): at the **working root** (the checkout, worktree, or clone you'll edit in), write `.trailhead/session-ticket` as **one line** `#<n> <ticket title>`. **Keep it gitignored** (add `.trailhead/session-ticket` to that repo's `.gitignore` if absent): it's per-session local state, **never committed**. It just lets an external tool show "what am I on" offline; the tracker stays the source of truth. Remove it at Resolve/handoff (see [Session handoff](#session-handoff)); on **Pause** it may stay (you'll return) or be cleared if you release the claim. The **`.trailhead/active-map`** marker (which map this session works) follows the same rules: gitignored, per-session, never committed; see [Multiple maps on one repo](#multiple-maps-on-one-repo-parking--concurrency).
+   - **Under `isolation: worktree` or `clone`, set up the isolated workspace NOW, before any file edit or diagnostic probe** (not later at Execute/Fix): for `worktree`, create/enter this ticket's `git worktree` on a `trailhead/t<n>` branch for the repo the ticket's `Scope:` points at (**the submodule itself for submodule-scoped work**, e.g. `git -C app worktree add ../<repo>-t<n> -b trailhead/t<n>`); for `clone`, make an independent working copy at `../<repo>-t<n>` (branch `trailhead/t<n>`) by whichever is faster: `git clone` + the install step, or a **folder copy that brings `node_modules`** to skip the reinstall (then verify the copy's git is independent, `git -C <copy> rev-parse --absolute-git-dir` resolves inside it, else commits leak back to the original). **Because `clone` is heavy (a full clone + an install), gate it, every time, before cloning: ask the user whether they expect to work more than one ticket at once on this machine this session.** If **no**, **skip the clone** and work this ticket in the current checkout (isolation only exists to stop concurrent workspaces from colliding; a lone ticket has nothing to collide with, so the shared-checkout caveats apply and that is fine, and `git:` still decides the branch as usual); if **yes**, clone as above. The gate is **`clone`-only**: `worktree` is cheap, so set it up without asking. Do every subsequent step in whatever workspace you ended up in. This is the whole point of isolation: if you diagnose and edit in the shared checkout "just to start" while a concurrent workspace exists, you are already colliding. Set the workspace up silently (the `clone` gate-question is the one exception you voice); it's undone at Resolve when the branch integrates and the worktree/clone is removed. See [Working as a team](#working-as-a-team).
+3. Resolve it with its type's engine, **zoom as needed**: fetch the full body of related/closed tickets on demand. If in doubt on a `decision` ticket, run **Grilling** + **Domain vocabulary**. If in doubt on a `build`, **stop and ask** (see the Discuss step): never auto-grill.
 4. Record the resolution: a comment with the answer, `gh issue close`, add the pointer to *Decisions so far*. Then **unblock dependents**: for every ticket this one was blocking, if it was the last open blocker, remove its `trailhead:blocked` label so it graduates onto the frontier.
-5. Add newly-surfaced tickets (create-then-wire, labelling blocked ones `trailhead:blocked`); graduate the fog that became specifiable, clearing the patch from *Not yet specified*. If the answer reveals a ticket sits beyond the destination, **out of scope** (label + close) instead of resolving it. If the decision invalidates other parts of the map, update or delete them.
-6. **Hand off.** Close the session with the **[Session handoff](#session-handoff)** ritual: confirm the ticket is resolved by name, invite `/clear`, and suggest the next command — `/trailhead:work <next frontier ticket by name>`, or `/trailhead:map` if the frontier is empty/ambiguous.
+5. Add newly-surfaced tickets (create-then-wire, labelling blocked ones `trailhead:blocked`); graduate the fog that became specifiable, clearing the patch from *Not yet specified*. If the answer reveals a ticket sits beyond the destination, apply the **out-of-scope vs deferred** test (see [Out of scope](#out-of-scope)): if it's really deferred on something outside the map, ask the user to route it to a `seed`/`idea`/`todo`; only if it's truly beyond the destination rule it **out of scope** (label + close) instead of resolving it. If the decision invalidates other parts of the map, update or delete them.
+6. **Hand off.** Close the session with the **[Session handoff](#session-handoff)** ritual: confirm the ticket is resolved by name, then the scannable **next-step block with `/clear` first** (never the next command without it), naming the next frontier ticket and giving its number, or `/trailhead:map` if the frontier is empty/ambiguous. This holds in any later follow-up too, not only at the moment of resolution. **If this resolution leaves the map exhausted** (no open tickets and no fog left: the destination is reached), say so; but **before closing it out, if *Out of scope* holds any deferred line** (apply the [out-of-scope-vs-deferred](#out-of-scope) tells), **stop and ask the user what to do with each** (a `seed` gated on its trigger, an `idea`, or a `todo`, in this or another map), so nothing wanted-later is lost when the map goes quiet. Only once the deferred items are routed (or the user says leave them), **ask the user whether to close the map issue** now that the destination is reached: `gh issue close` it on a yes (it stays the record), leave it open on a no; never close a map unprompted. Either way **refresh the dashboard** so an exhausted/closed map drops off (a structural event). Maps aren't pinned, so there's no pin to free; the dashboard, codebase, and conventions stay pinned regardless.
 
-### Mode 3 — Capture — `/trailhead:bug|todo|idea|seed|note`
+### Mode 3: Capture, `/trailhead:bug|todo|idea|seed|note`
 The user fires a capture on the fly → route it per the **Capture** section and confirm with one line.
 
-### Auxiliary verbs — `/trailhead:ticket|config|grill|split|pause|resume`
-- **`ticket <type> <title>`** — open ticket(s) of the map on the fly, for any of the six types (`decision`, `research`, `prototype`, `build`, `bug`, `task`) — the escape hatch the capture verbs don't cover. **Adding a ticket is a micro-charting act, so diverge briefly first, don't blind-commit to a single piece:** run a short breadth-first pass around the request — is this really *one* session-sized ticket, or a small **cluster** (a `decision` that needs a `research` before it, a UI `build` that needs a `prototype`, obvious siblings)? Does it imply a blocker? Surface the neighbours, *then* create the ticket(s): each gets `trailhead:ticket` + its `trailhead:<type>`, a `Parent:` line, a `## Question`; put each on the frontier, or wire `## Blocked by` + `trailhead:blocked`. This is a framing brainstorm (is this the right work?), distinct from the `decision` engine's option brainstorm (which choice?). If `<type>` is missing or invalid, ask which of the six. *(The zero-friction captures — `bug`/`todo`/`idea`/`seed`/`note` — deliberately skip this; they're one action, one confirmation.)*
-- **`grill [topic|ticket]`** — run a standalone **Grilling** (+ **Domain vocabulary**) session on a decision or topic, or on a named ticket, without committing to the full work cycle. Record the outcome where it belongs: a ticket's resolution, the map's `Decisions so far`, or a fresh `decision` ticket.
-- **`config`** — a **guided, menu-driven** setup (see [Configuration → Guided setup](#configuration)): pick the scope, then walk each setting as an `AskUserQuestion` menu with icon-labelled options, and write the result. `config get` prints the effective config read-only (global merged with the map's `## Config`, showing which source wins each key); `config set <key> <value>` writes one key directly — to the map's `## Config`, or to `~/.claude/trailhead/config.json` with `--global`.
-- **`split [ticket]`** — split the named (or in-play) ticket per [Splitting a ticket](#working-as-a-team): create children, supersede & close the original.
-- **`pause [note]`** / **`resume [ticket]`** — checkpoint and pick back up per [Pausing & resuming](#working-as-a-team).
+### Auxiliary verbs: `/trailhead:ticket|config|grill|split|pause|resume|update`
+- **`ticket <type> <title>`**: open ticket(s) of the map on the fly, for any of the six types (`decision`, `research`, `prototype`, `build`, `bug`, `task`), the escape hatch the capture verbs don't cover. **Adding a ticket is a micro-charting act, so diverge briefly first, don't blind-commit to a single piece:** run a short breadth-first pass around the request: is this really *one* session-sized ticket, or a small **cluster** (a `decision` that needs a `research` before it, a UI `build` that needs a `prototype`, obvious siblings)? Does it imply a blocker? Surface the neighbours, *then* create the ticket(s): each gets `trailhead:ticket` + its `trailhead:<type>`, a `Parent:` line, a `## Question`; put each on the frontier, or wire `## Blocked by` + `trailhead:blocked`. This is a framing brainstorm (is this the right work?), distinct from the `decision` engine's option brainstorm (which choice?). If `<type>` is missing or invalid, ask which of the six. *(The zero-friction captures, `bug`/`todo`/`idea`/`seed`/`note`, deliberately skip this; they're one action, one confirmation.)*
+- **`grill [topic|ticket]`**: run a standalone **Grilling** (+ **Domain vocabulary**) session on a decision or topic, or on a named ticket, without committing to the full work cycle. Record the outcome where it belongs: a ticket's resolution, the map's `Decisions so far`, or a fresh `decision` ticket.
+- **`config`**: a **guided, menu-driven** setup (see [Configuration → Guided setup](#configuration)): pick the scope, then walk each setting as an `AskUserQuestion` menu with icon-labelled options, and write the result. `config get` prints the effective config read-only (project `.trailhead/config.json` merged over global over defaults, showing which source wins each key); `config set <key> <value>` writes one key directly: to the project `.trailhead/config.json`, or to `~/.claude/trailhead/config.json` with `--global`.
+- **`split [ticket]`**: split the named (or in-play) ticket per [Splitting a ticket](#working-as-a-team): create children, supersede & close the original.
+- **`pause [note]`** / **`resume [ticket]`**: checkpoint and pick back up per [Pausing & resuming](#working-as-a-team).
+- **`update`**: check for a newer trailhead and install it where safe, per **`references/updating.md`** (detect the install channel, compare the installed version with the latest from the matching source, install on a go-ahead). The **`trailhead-check-update.js`** SessionStart hook keeps the check cache fresh; the statusline shows a `⬆ trailhead <version>` flag when one is available.
 
-The user may work unblocked tickets in parallel: expect concurrent sessions editing the tracker — see [Working as a team](#working-as-a-team) for claiming, splitting, and safe map edits.
+The user may work unblocked tickets in parallel: expect concurrent sessions editing the tracker, see [Working as a team](#working-as-a-team) for claiming, splitting, and safe map edits.