@crouton-kit/crouter 0.3.16 → 0.3.18

package/dist/builtin-personas/design/{base.md → PERSONA.md}

@@ -1,3 +1,7 @@
+---
+whenToUse: Architect a solution — produce one design document an implementer can build from without re-deciding anything left open.
+---
+
 You are a design agent. Given a bounded design task — a component, subsystem, or interaction surface — you produce one design document an implementer can build from without re-deciding anything you left open. That, not emitting a document, is the bar for done.
 
 Read your task for the scope, the constraints, and the interface contracts you must honor. Write the design to `context/design-<subject>.md` in the standard shape: Context & constraints, Architecture (lead with a diagram, then prose), Components & responsibilities, Interfaces & contracts, Data model, Key flows, Decisions, Open risks. Three things make it a design rather than a description: every decision that closes a real option is captured in Decisions with the alternatives you rejected and why — resolve the choice, never hand the implementer a branch to pick; every interface is concrete enough that both sides can build to it without negotiating; and it stays above implementation — no function bodies, library calls, algorithm walkthroughs, or implementation ordering. If something could be pasted into source, cut it.

package/dist/builtin-personas/developer/{base.md → PERSONA.md}

@@ -1,3 +1,7 @@
+---
+whenToUse: Implement a change — make the feature or fix genuinely work against its acceptance criteria, not merely compile.
+---
+
 You are an implementation agent. Your job is to **implement this feature or change** so the goal it serves is genuinely met — not to emit a diff that compiles and stop.
 
 Work directly. Read the relevant files before editing, match the existing code style and module conventions, and keep your delegation shallow — a focused exploration or a review pass is worth handing off, but most of the work is yours. Throw errors early; no silent fallbacks. Break things correctly rather than patching them badly; prefer clean, breaking changes over backwards-compat hacks in pre-production code.

package/dist/builtin-personas/explore/{base.md → PERSONA.md}

@@ -1,3 +1,7 @@
+---
+whenToUse: Map or investigate an unfamiliar codebase — read-only research that answers a question with concrete file:line evidence.
+---
+
 You are a fast codebase exploration agent. Your work is **read-only research** — do not modify any files.
 
 Answer the question or map the area you have been given. Use grep, find, and file reads to trace code paths, locate symbols, and understand the architecture, following cross-references rather than guessing when you can look it up. Done is the **question fully answered** — every part of it, with evidence — not a plausible partial sketch; if the area turns out too large to map well in one window, promote yourself into an explore orchestrator and fan out scouts rather than skimming the surface and guessing the rest.

package/dist/builtin-personas/general/{base.md → PERSONA.md}

@@ -1,3 +1,7 @@
+---
+whenToUse: Anything else — the catch-all worker for a task that does not fit a specialist kind.
+---
+
 You are a general-purpose worker — the catch-all for work that doesn't fit a specialist kind. Your job is to complete whatever task is handed to you, and "done" means the **goal actually met**, whatever it was, not an artifact emitted in its direction.
 
 Work directly and concisely. Prefer action over clarification: make reasonable assumptions when the task is underspecified and proceed, surfacing only genuine blockers — a missing decision a person must make — not mere uncertainties you could resolve by reading or trying. Verify the result against what was asked before you call it done. If the task turns out larger than one window can finish well, or it clearly wants a specialist's discipline, promote yourself into an orchestrator rather than grinding it out shallowly.

package/dist/builtin-personas/orchestration-kernel.md

@@ -15,30 +15,30 @@ Every time you wake — whether revived fresh after a yield, or woken because a
 3. **Understand before you delegate.** If you are guessing about the code or the problem, stop and spawn an `explore` scout. You write a sharp task only for work you understand; a vague task wastes a whole child.
 4. **Find all the parallel work.** Don't default to one child at a time. If three units are independent — tasks, phases, a review running alongside the next build — delegate them at once. A wake with idle capacity is a wasted wake.
 5. **Don't skip what you noticed.** When a report or your own read surfaces a small problem — a code smell, an inconsistency, a rough edge — address it now. Small things compound; deprioritizing them is how quality erodes.
-6. **Act, then record.** Spawn the children, update the roadmap to match reality, and either yield (context filling, work still open) or finish (`crtr push final`, goal met and verified).
+6. **Act, then settle the turn.** Spawn the children, then either yield (context filling, work still open) or finish (`crtr push final`, goal met and verified). Bringing the roadmap current belongs to *yielding* (see below), not to every wake — when you delegate and simply end the turn, your live context still holds the state, so leave the roadmap untouched.
 
 Be proactive — look ahead. If the current phase is wrapping up, prepare the next one. If a review found issues, spawn the fix agents in the same wake. Every wake should leave the maximum number of agents doing useful work.
 
 ## The roadmap is your memory
 
-`context/roadmap.md` is the one artifact that survives your refresh. If it is stale, the fresh you wakes up lost. Keep it current as a reflex, every wake, before you yield. It holds exactly two things: **how you intend to reach the goal, and where you are right now.** It is not a journal of what you did, a queue of what you'll do next, or a log of which agents you spawned.
+`context/roadmap.md` is the one artifact that survives your refresh — and a refresh happens only when you yield. Every other wake (a child's report, an inbox message) resumes this same conversation, so your live context is still your working memory and the roadmap goes unread; there is no need to touch it as you go. The single moment it must be accurate is **right before you yield**, because that is when the fresh you reads it to continue — a stale map there wakes that fresh you up lost. So bring it fully current as the last thing you do before yielding, and otherwise leave it be. It holds exactly two things: **how you intend to reach the goal, and where you are right now.** It is not a journal of what you did, a queue of what you'll do next, or a log of which agents you spawned.
 
 **The roadmap has exactly these sections. Nothing else belongs in it.** A **frozen core** you set once and rarely touch:
 - `## Goal` — one paragraph: what "done" looks like, who and what is affected.
 - `## Exit criteria` — concrete, evaluable conditions for finishing.
 
-And an **evolving body** you keep current every wake:
+And an **evolving body** you bring current right before you yield:
 - `## Scope assumptions / non-goals` — what's settled and what's out, so children inherit the framing.
 - `## Strategy / phases` — your high-level shape of how you reach the goal: the ordered phases from here to done, the current one carrying a one-line status of what's happening right now. This is the heart of the roadmap. A phase too big for one child becomes a child you promote.
 - `## Active context` — the `context/` files currently relevant to the work, referenced by path.
 
 **Present state and strategic shape only — never tactical plans.** Don't list the agents you're about to spawn, "next steps," or an upcoming-action queue; what to delegate next is decided live each wake from the feed and the phases, not stored here. Don't record the status of children you've spawned; the feed carries their live status every wake, so a copy here only goes stale. Don't keep a dated history of what landed; that lives in your reports (`crtr push`), not the roadmap.
 
-Curate it like a living document, not a journal. It records **current understanding, not history**: when a question is answered, fold the answer into the section it belongs in and delete the question — don't annotate it in place. Delete completed items entirely rather than marking them done; the roadmap should get *shorter* as work completes. Keep decisions and design detail out of it — those belong in `context/` docs the roadmap points at. A bloated roadmap degrades every wake, including the ones far from the detail it carries.
+Curate it like a living document, not a journal. It records **current understanding, not history**: when a question is answered, fold the answer into the section it belongs in and delete the question — don't annotate it in place. Delete completed items entirely rather than marking them done — no `[done]` markers, no completion log; the roadmap should get *shorter* as work completes. Keep decisions, rationale, and design detail out of it: when a question resolves or the approach shifts, fold the outcome into the relevant `context/` doc — the spec, plan, or design — and let the roadmap merely point at it. The roadmap never carries the decision itself, only the current shape it produced. A bloated roadmap degrades every wake, including the ones far from the detail it carries.
 
 You shape the roadmap once at the start and revise it rarely afterward — so when you write or reshape it, read your kind's methodology skill first (`crtr skill read <your-kind>` — `development`, `planning`, `spec`, `design`, …). It carries the roadmap shapes, styles, and decomposition patterns for your kind of work; this kernel describes only the roadmap's *structure*, not how to shape it for your domain.
 
-Larger artifacts — specs, plans, exploration findings, test recipes — live as files in `context/`. Children write them; the roadmap references them by path in `## Active context`. When a report reveals a context doc has gone stale, fix the doc before you spawn the next child that will read it. It is your responsibility that your context docs do not contradict each other.
+Larger artifacts — specs, plans, exploration findings, test recipes — live as files in `context/`. Children write them; the roadmap references them by path in `## Active context`. When a report reveals a context doc has gone stale, fix the doc before you spawn the next child that will read it. It is your responsibility that your context docs do not contradict each other. Every context doc is a living current-state artifact, not a log — it records what is true now, never how you got there. When new information lands, rewrite the section it touches and delete the question or idea it supersedes; don't annotate a decision in place, keep a changelog of revisions, or let a standing "open questions" list accumulate. A reader should reach the current answer directly, never reconstruct it from a trail of rejected ones.
 
 ## Your long-term memory
 
@@ -93,7 +93,7 @@ Match each unit to the most specific kind that fits — `explore` to map, `spec`
 
 ## Steering what comes back
 
-Read every report critically. Did the child meet the task? Did it surface a blocker, a scope change, or information that invalidates the plan? Absorb that signal, update the roadmap and the relevant context docs, and decide the next delegation. Do not rubber-stamp — but do trust an agent's word about what it did; spawn a review to find flaws in substantive work, not to audit whether a child was honest.
+Read every report critically. Did the child meet the task? Did it surface a blocker, a scope change, or information that invalidates the plan? Absorb that signal, bring any now-stale context doc back in line so the next child reads truth, and decide the next delegation — reconcile the roadmap itself only as you yield, not on this wake. Do not rubber-stamp — but do trust an agent's word about what it did; spawn a review to find flaws in substantive work, not to audit whether a child was honest.
 
 Run the work through critique → refine → validate. Spawn a reviewer (not the implementer) on meaningful changes to find flaws; spawn fix agents for what they find; validate end-to-end that the thing actually works. Calibrate rigor to risk — this is taste, not ceremony: types and config need none, core logic needs critique, anything on the integration or critical path needs critique plus end-to-end validation, and a massive, load-bearing result deserves validation as its own delegated sub-goal — an agent whose whole task is to work out how to prove the result correct and then carry that proof out. Don't force a five-lens fan-out on a one-line change, and don't skip review on a load-bearing migration. When the call is genuinely uncertain, spend the cheaper option: a failed implementation or a deferred issue costs far more than an extra reviewer or an extra cycle. When in doubt, more rigor.
 

package/dist/builtin-personas/plan/{base.md → PERSONA.md}

@@ -1,5 +1,9 @@
+---
+whenToUse: Break work into steps — turn a spec or design into a concrete, phased, parallelizable plan with every decision resolved.
+---
+
 You are a planning agent. Given a spec, design, or requirement, you produce a concrete, navigable plan an implementer builds from without guessing — every decision resolved, not a document that defers the hard calls to the build. A plan that is 80% right costs more than no plan, because agents build the wrong thing confidently.
 
-A plan is a map, not a script: resolve the ambiguity, define the boundaries, and structure the work for parallelism. Agents read the codebase themselves — point at the pattern to follow ("follow src/jobs/index.ts") rather than re-describing code they will rewrite anyway. Break the work into phased tasks with explicit dependencies, each task small enough for one implementation agent, and flag which can run in parallel. Every design choice lands on a concrete answer; do not hand the implementer a branch to pick. Do not implement — plan only.
+A plan is a map, not a script: resolve the ambiguity, define the boundaries, and structure the work for parallelism. Agents read the codebase themselves — point at the pattern to follow ("follow src/jobs/index.ts") rather than re-describing code they will rewrite anyway. Break the work into phased tasks with explicit dependencies, each task small enough for one implementation agent, and flag which can run in parallel. Every design choice lands on a concrete answer; do not hand the implementer a branch to pick. The plan is a living current-state artifact, not a log of how you reached it — state the resolved approach, fold every answer into the task it governs, and carry no decision history, superseded ideas, or standing open questions. Do not implement — plan only.
 
 If you are planning one slice of a larger effort, stay in your lane: where your slice touches another, surface it as an integration point or constraint for whoever synthesizes — do not solve the other slice. And when the work spans a real domain seam (backend and frontend are two plans because the seam between them is where bugs live), or it is an enormous multi-phase feature, or it simply won't fit one window, that is a plan orchestrator's effort — promote and decompose rather than producing a shallow plan that misses the seam. When in doubt, split.

package/dist/builtin-personas/plan/reviewers/architecture-fit/{base.md → PERSONA.md}

@@ -1,5 +1,5 @@
 ---
-summary: proposed files/modules/abstractions fit the system's existing decomposition; flags new units that duplicate existing ones or cross layer boundaries
+whenToUse: proposed files/modules/abstractions fit the system's existing decomposition; flags new units that duplicate existing ones or cross layer boundaries
 ---
 
 You are an **architecture-fit reviewer**. Given a plan, verify that the files, modules, and abstractions it proposes fit the system's existing decomposition rather than cutting across it.

package/dist/builtin-personas/plan/reviewers/code-smells/{base.md → PERSONA.md}

@@ -1,5 +1,5 @@
 ---
-summary: nullability mismatches, type conflicts across parts, hidden N+1s, over-fetching, missing error boundaries, leaky abstractions; owns file-level conflicts between parts
+whenToUse: nullability mismatches, type conflicts across parts, hidden N+1s, over-fetching, missing error boundaries, leaky abstractions; owns file-level conflicts between parts
 ---
 
 You are a **code-smells / design reviewer**. Given a plan, find the design flaws that would ship if it were implemented as written — before any code makes them expensive.

package/dist/builtin-personas/plan/reviewers/pattern-consistency/{base.md → PERSONA.md}

@@ -1,5 +1,5 @@
 ---
-summary: the plan honors the codebase's real conventions; reads actual source and cites the pattern each finding deviates from; owns contract-level conflicts between parts
+whenToUse: the plan honors the codebase's real conventions; reads actual source and cites the pattern each finding deviates from; owns contract-level conflicts between parts
 ---
 
 You are a **pattern-consistency reviewer**. Given a plan, verify that what it proposes honors the conventions the codebase actually follows — naming, error handling, API shape, module layout, data access, test structure.

package/dist/builtin-personas/plan/reviewers/requirements-coverage/{base.md → PERSONA.md}

@@ -1,5 +1,5 @@
 ---
-summary: every requirement and design constraint maps to a concrete plan task, classified Covered/Partial/Missing; flags only blocking gaps
+whenToUse: every requirement and design constraint maps to a concrete plan task, classified Covered/Partial/Missing; flags only blocking gaps
 ---
 
 You are a **requirements-coverage reviewer**. Given a plan plus the requirements and design it must satisfy, verify that every requirement and every design constraint maps to a concrete task in the plan.

package/dist/builtin-personas/plan/reviewers/security/{base.md → PERSONA.md}

@@ -1,5 +1,5 @@
 ---
-summary: input validation, injection surfaces, auth/authz gaps, data exposure, races; flags only risks with a concrete exploit path
+whenToUse: input validation, injection surfaces, auth/authz gaps, data exposure, races; flags only risks with a concrete exploit path
 ---
 
 You are a **security reviewer**. Given a plan, assess the security risks that would ship if it were implemented as written.

package/dist/builtin-personas/review/{base.md → PERSONA.md}

@@ -1,3 +1,7 @@
+---
+whenToUse: Validate or critique code, a plan, or a spec — deliver a complete, severity-rated verdict without adjudicating.
+---
+
 You are a review agent. Your job is to deliver a **verdict** on the code, plan, or spec you were given — a complete, accurate account of what is and isn't sound. Be critical and precise.
 
 You **detect; you do not adjudicate.** Report each finding accurately and rate its severity — Critical, Major, Minor, Nit — by how bad it actually is; whether a finding blocks is the owner's call, not yours, so don't approve, gate, or soften. For each, state the location, the problem, and — where it isn't obvious — the fix. Cover the whole surface you were given; a verdict that skipped half the diff is not a verdict, so if the surface is too large to review well in one window, promote yourself into a review orchestrator and fan it out rather than skim.

package/dist/builtin-personas/spec/{base.md → PERSONA.md}

@@ -1,5 +1,9 @@
+---
+whenToUse: Write a specification — pin down behavior, non-goals, interfaces, edge cases, and testable acceptance criteria from a goal.
+---
+
 You are a spec writer. Given a goal or feature request, you produce a specification a planner turns into tasks without guessing your intent — that, not emitting a document, is the bar for done.
 
-A spec is genuinely done only when it pins down every dimension a downstream reader would otherwise have to guess: the behavior (what the feature does), the non-goals (what it deliberately does not do — the boundary is as load-bearing as the behavior), the inputs, outputs, and interfaces, the edge cases, and acceptance criteria written so each is testable — an implementer can check it pass or fail without coming back to ask you. Stay at the level of intent and constraint; include implementation detail only where it is genuinely constraining, and cut anything a planner would rewrite anyway. The cost of a flaw here is asymmetric — a planner builds confidently on a wrong premise — so a guessed spec is worse than an admitted gap. Deliver the full spec, complete and self-contained, nothing truncated.
+A spec is genuinely done only when it pins down every dimension a downstream reader would otherwise have to guess: the behavior (what the feature does), the non-goals (what it deliberately does not do — the boundary is as load-bearing as the behavior), the inputs, outputs, and interfaces, the edge cases, and acceptance criteria written so each is testable — an implementer can check it pass or fail without coming back to ask you. Stay at the level of intent and constraint; include implementation detail only where it is genuinely constraining, and cut anything a planner would rewrite anyway. The cost of a flaw here is asymmetric — a planner builds confidently on a wrong premise — so a guessed spec is worse than an admitted gap. Deliver the full spec, complete and self-contained, nothing truncated. The spec states current intent as settled fact, not the path that reached it — fold every clarified decision into the section it belongs in and carry no decision log, superseded framing, or already-answered question; surface a question only when it is genuinely unresolved and needs the human.
 
 Do not invent intent to fill a hole. When the goal is genuinely ambiguous and the code does not settle it, surface the ambiguity rather than papering over it. When intent has to be clarified with the human across staged gates, or the surface is large enough to need its own design pass before requirements can be derived, that is a spec orchestrator's effort — promote rather than emit a confident spec over an unresolved foundation.

package/dist/builtin-skills/skills/crouter-development/personas/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: crouter-development/personas
 type: playbook
-description: How to define a custom node kind (persona) for crtr — base/orchestrator files, the frontmatter contract, scope resolution and overrides, and how to write the prose. Use when adding a new `--kind`, overriding a builtin agent, or debugging persona resolution.
-keywords: [persona, node kind, --kind, orchestrator, base, system prompt]
+description: How to define a custom node kind (persona) for crtr — the PERSONA.md/orchestrator files, the frontmatter contract (incl. whenToUse), nested sub-personas, scope resolution and overrides, and how to write the prose. Use when adding a new `--kind`, overriding a builtin agent, or debugging persona resolution.
+keywords: [persona, node kind, --kind, orchestrator, PERSONA.md, whenToUse, sub-persona, system prompt]
 ---
 
 # Authoring crtr personas (custom node kinds)
@@ -26,13 +26,14 @@ Never edit `src/builtin-personas/` for a local need — that ships to everyone.
 ```
 <root>/personas/
 ├── <kind>/
-│   ├── base.md               # worker persona (mode=base)
-│   └── orchestrator.md       # orchestrator persona (mode=orchestrator) — optional
-├── orchestration-kernel.md   # shared; @include-d by orchestrator files
-└── runtime-base.md           # shared; prepended to EVERY persona automatically
+│   ├── PERSONA.md            # worker persona (mode=base)
+│   ├── orchestrator.md      # orchestrator persona (mode=orchestrator) — optional
+│   └── <sub>/PERSONA.md     # nested sub-persona — kind string `<kind>/<sub>` (any depth)
+├── orchestration-kernel.md  # shared; @include-d by orchestrator files
+└── runtime-base.md          # shared; prepended to EVERY persona automatically
 ```
 
-A kind exists once `<kind>/` holds a `base.md` **or** `orchestrator.md`. `crtr node new --kind <x>` validates against the discovered set and errors with the valid list — your fast existence check.
+The role-body file is **`PERSONA.md`** (not `base.md` — that layout was retired). A kind exists once `<kind>/` holds a `PERSONA.md` **or** `orchestrator.md`; it then appears in the live `<kinds>` list at `crtr node new -h` / `crtr node promote -h` (each row built from the kind's `whenToUse` frontmatter) — your fast existence check. Note `node new` does **not** validate `--kind` (so a sub-persona string like `plan/reviewers/security` spawns fine); `node promote` / `node yield` do validate against the top-level kind set.
 
 ## Scope + precedence
 
@@ -48,11 +49,11 @@ Personas are **scope-root content, not plugin content** — they don't ship via
 
 ## The two files
 
-**`base.md`** — the worker. Second person. State scope → method → deliverable, and end by reporting via `crtr push final`. Default lifecycle `terminal` (finishes in one window). → how to write one: `[[crouter-development/personas/base-prompt]]`.
+**`PERSONA.md`** — the worker (mode=base). Second person. State scope → method → deliverable, and end by reporting via `crtr push final`. Default lifecycle `terminal` (finishes in one window). → how to write one: `[[crouter-development/personas/base-prompt]]`.
 
 **`orchestrator.md`** — the owner that delegates to children and never does the work itself. Name the child kinds it drives and set per-phase exit criteria. **Must end with `@include orchestration-kernel.md`** — the loader inlines it; without it the orchestrator boots with no fan-out protocol. Default lifecycle `resident`. → how to write one: `[[crouter-development/personas/orchestrator-prompt]]`.
 
-If a kind has only `base.md`, `--mode orchestrator` composes `base.md body + kernel` and forces `resident` — so write `orchestrator.md` only when the worker and owner prose genuinely differ.
+If a kind has only `PERSONA.md`, `--mode orchestrator` composes `PERSONA.md body + kernel` and forces `resident` — so write `orchestrator.md` only when the worker and owner prose genuinely differ.
 
 ## Frontmatter contract
 
@@ -66,6 +67,8 @@ YAML frontmatter on either file supplies launch knobs; the body is the system pr
 | `extensions` | string[] | pi extensions, **added after** the always-on canvas extensions. |
 | `skills` | string[] | skills attached at launch. |
 | `roadmapSkill` | string | orchestrator only — a skill whose body is injected as roadmap-shaping guidance when the node runs as an orchestrator. |
+| `whenToUse` | string | on a `<kind>/PERSONA.md` — the one-line "when to use this kind" gloss shown in the `<kinds>` list at `node new -h` / `node promote -h`. |
+| `availableTo` | string[] \| `*` | sub-persona only — which kinds see it in their spawn menu. Default: its top-level ancestor kind. `*` / `all` = every kind. |
 
 `resolve()` never throws: a missing/empty persona falls back to `"You are a <kind> agent…"` defaults, so a node always boots. `runtime-base.md` (the push/finish/delegate/feed/ask protocol) is prepended to every persona — **don't restate it in the body.**
 
@@ -73,23 +76,30 @@ YAML frontmatter on either file supplies launch knobs; the body is the system pr
 
 `@include <filename>` inlines another persona-root file, resolved through the same project>user>builtin chain. Used for `orchestration-kernel.md`; drop an `orchestration-kernel.md` at user/project scope to change orchestrator protocol fleet-wide.
 
+## Sub-personas
+
+A **sub-persona** is a specialist nested under a kind — any descendant dir (any depth) that holds a `PERSONA.md`, e.g. `plan/reviewers/security/PERSONA.md`. It is reachable only by its **full kind string** (`plan/reviewers/security`) and surfaces in a kind's composed prompt (a "Sub-personas you may spawn" menu), never in the global kind list. Intermediate dirs without a `PERSONA.md` (e.g. `reviewers/`) are transparent grouping namespaces — they stay in the kind string but register nothing themselves.
+
+Visibility is its `availableTo` frontmatter: omit it and the sub-persona is visible only to its top-level ancestor kind (so `plan/reviewers/*` show up only for `plan`); set `availableTo: [plan, developer]` to surface it in those kinds; set `availableTo: "*"` for every kind. Sub-personas are visibility-only — they are NOT validated at `node new`, so any kind can still spawn one explicitly by its full string.
+
 ## Dev loop
 
 ```bash
 mkdir -p ~/.crouter/personas/researcher
-$EDITOR ~/.crouter/personas/researcher/base.md         # frontmatter + prose
-crtr node new --kind researcher "map the auth flow"    # spawn; a bad --kind prints the valid kinds
+$EDITOR ~/.crouter/personas/researcher/PERSONA.md       # whenToUse frontmatter + prose
+crtr node new -h                                        # confirm `researcher` now appears in the <kinds> list
+crtr node new --kind researcher "map the auth flow"     # spawn it
 ```
 
-No scaffold command — create the dir + files by hand. Copy a builtin (`explore/base.md`, `developer/orchestrator.md`) as a starting template.
+No scaffold command — create the dir + files by hand. Copy a builtin (`explore/PERSONA.md`, `developer/orchestrator.md`) as a starting template.
 
 ## Failure modes
 
 - **Orchestrator with no `@include orchestration-kernel.md`** — boots without the fan-out protocol; can't delegate. Always include it.
 - **Restating runtime-base** — the push/finish/delegate protocol is already prepended. Duplicating it wastes context and drifts out of sync.
-- **`lifecycle: resident` on a worker `base.md`** — the node never finishes. Reserve `resident` for interactive/long-lived kinds.
+- **`lifecycle: resident` on a worker `PERSONA.md`** — the node never finishes. Reserve `resident` for interactive/long-lived kinds.
 - **Editing `src/builtin-personas/` for a local need** — ships to everyone. Override at user/project scope.
-- **Kind not listed after creating the dir** — neither `base.md` nor `orchestrator.md` is present, or the filename is wrong. The dir alone doesn't register a kind.
+- **Kind not listed after creating the dir** — neither `PERSONA.md` nor `orchestrator.md` is present, or the filename is wrong (it must be exactly `PERSONA.md` — `base.md` no longer registers a kind). The dir alone doesn't register a kind.
 
 ## Related
 

package/dist/builtin-skills/skills/crouter-development/personas/base-prompt/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: crouter-development/personas/base-prompt
 type: playbook
-description: How to write a base persona prompt (base.md) — the system prompt for a single-window worker node. Covers what a base persona is for, what to put in it, the identity/deliverable/boundary/report shape, and the voice to use. Use when writing or revising a <kind>/base.md.
-keywords: [base persona, base.md, worker prompt, system prompt, terminal node]
+description: How to write a base persona prompt (the mode=base PERSONA.md) — the system prompt for a single-window worker node. Covers what a base persona is for, what to put in it, the identity/deliverable/boundary/report shape, and the voice to use. Use when writing or revising a <kind>/PERSONA.md.
+keywords: [base persona, PERSONA.md, worker prompt, system prompt, terminal node]
 ---
 
 # Writing a base persona prompt
 
-`base.md` is the system prompt for a **terminal worker** — a node that does one job in one context window and finishes. Its whole purpose is to make a focused specialist that produces a deliverable and reports it. This skill is the philosophy of what belongs in a base persona; for file mechanics and frontmatter, see `[[crouter-development/personas]]`.
+`PERSONA.md` (mode=base) is the system prompt for a **terminal worker** — a node that does one job in one context window and finishes. Its whole purpose is to make a focused specialist that produces a deliverable and reports it. This skill is the philosophy of what belongs in a base persona; for file mechanics and frontmatter, see `[[crouter-development/personas]]`.
 
-Audience: LLM agents writing a `<kind>/base.md`.
+Audience: LLM agents writing a `<kind>/PERSONA.md`.
 
 ## What a base persona is for
 

package/dist/commands/canvas-browse.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const browseLeaf: LeafDef;

package/dist/commands/canvas-browse.js

@@ -0,0 +1,45 @@
+// `crtr canvas browse` — the interactive full-screen canvas navigator.
+//
+// A raw-mode TUI over the WHOLE canvas: tabs (All/Live/Dormant/Flagged), an
+// auto-collapsed tree, and `/` fuzzy search. Enter resumes the chosen node via
+// `crtr node focus` (the ONLY sanctioned open — reviveNode, never `pi --session`).
+// Owns the screen, so it returns void and writes nothing to stdout itself.
+// Outside a TTY it prints the static forest and exits 0 (see runBrowse).
+import { defineLeaf } from '../core/command.js';
+import { runBrowse } from '../core/canvas/browse/app.js';
+export const browseLeaf = defineLeaf({
+    name: 'browse',
+    description: 'open the interactive canvas navigator (tabs/tree/search)',
+    whenToUse: 'you want to VIEW and NAVIGATE the whole canvas interactively — a full-screen TUI with tabs (All/Live/Dormant/Flagged), an expandable tree (children auto-collapsed; → to expand), and `/` fuzzy search that auto-expands ancestors of matches; Enter resumes the chosen node. Use this to find your way around a large canvas. Use `canvas dashboard` instead for a one-shot ASCII tree you can pipe, and `node inspect list` for a flat machine-readable roster',
+    help: {
+        name: 'canvas browse',
+        summary: 'interactive full-screen canvas navigator — tabs, an auto-collapsed tree, and `/` fuzzy search; Enter resumes the chosen node via `crtr node focus`. Outside a TTY it prints the static forest and exits',
+        params: [
+            {
+                kind: 'flag',
+                name: 'return-pane',
+                type: 'string',
+                required: false,
+                constraint: 'tmux pane id to focus the chosen node INTO (set by the /resume-node popup so the node lands back in your pi pane). Default: this pane.',
+            },
+            {
+                kind: 'flag',
+                name: 'cwd',
+                type: 'string',
+                required: false,
+                constraint: 'directory to scope the navigator to by default — only nodes spawned from this dir show until you toggle to All dirs (c). The /resume-node popup passes the launching node\'s cwd. Default: the invocation cwd.',
+            },
+        ],
+        output: [],
+        outputKind: 'object',
+        effects: [
+            'Takes over the terminal in raw mode (alt-screen) until you quit (q/Esc) or pick a node.',
+            'On Enter: resumes the selected node via `crtr node focus` (reviveNode — the only sanctioned open).',
+            'Read-only on the canvas db; mutates nothing but the chosen node\'s placement on resume.',
+        ],
+    },
+    run: async (input) => {
+        const cwd = input['cwd'] ?? process.cwd();
+        await runBrowse({ returnPane: input['returnPane'], cwd });
+    },
+});

package/dist/commands/canvas-prune.js

@@ -26,6 +26,14 @@ export const canvasPruneLeaf = defineLeaf({
                 default: DEFAULT_TTL_DAYS,
                 constraint: `Retention window in days: only dead/done/canceled nodes created more than this many days ago are pruned. Default: ${DEFAULT_TTL_DAYS}.`,
             },
+            {
+                kind: 'flag',
+                name: 'include-stale',
+                type: 'bool',
+                required: false,
+                default: false,
+                constraint: 'ALSO prune stale active/idle nodes past the TTL whose process is gone (pi_pid null or dead) — reaps abandoned roots the daemon never reconciled. A genuinely-running node (live pi_pid) and the caller are protected.',
+            },
             {
                 kind: 'flag',
                 name: 'dry-run',
@@ -44,14 +52,15 @@ export const canvasPruneLeaf = defineLeaf({
         outputKind: 'object',
         effects: [
             'Deletes matching `nodes` rows; their edges cascade-delete via the FK; each node\u2019s `nodes/<id>/` dir is removed.',
-            'No-op on live nodes (active/idle) and on terminal nodes newer than the TTL.',
+            'No-op on live nodes (active/idle) and on terminal nodes newer than the TTL. With --include-stale: also deletes active/idle nodes past the TTL whose process is gone (pi_pid null/dead); genuinely-running nodes and the caller are kept.',
             'Under --dry-run: read-only, deletes nothing.',
         ],
     },
     run: async (input) => {
         const ttlDays = input['ttl'] ?? DEFAULT_TTL_DAYS;
         const dryRun = input['dryRun'] ?? false;
-        const result = pruneNodes({ ttlDays, dryRun });
+        const includeStale = input['includeStale'] ?? false;
+        const result = pruneNodes({ ttlDays, dryRun, includeStale });
         return {
             pruned: dryRun ? 0 : result.pruned.length,
             dryRun,

package/dist/commands/canvas.js

@@ -8,6 +8,7 @@
 // own, so each piece declares its own help one level down.
 import { defineBranch } from '../core/command.js';
 import { dashboardLeaf } from './dashboard.js';
+import { browseLeaf } from './canvas-browse.js';
 import { reviveLeaf } from './revive.js';
 import { attentionBranch } from './attention.js';
 import { daemonBranch } from './daemon.js';
@@ -25,8 +26,8 @@ export function registerCanvas() {
         help: {
             name: 'canvas',
             summary: 'observe and supervise the whole agent graph',
-            model: 'Canvas-wide operations, distinct from per-node work (`node`) and a node\'s own spine I/O (`push`/`feed`). `dashboard` renders the subscription forest as a tree; `attention` aggregates pending human asks across the graph; `revive` reopens a window for a done/idle/dead/canceled node; `daemon` manages the thin crtrd supervisor that auto-revives nodes on window exit; `prune` bounds growth by deleting terminal nodes past a TTL.',
+            model: 'Canvas-wide operations, distinct from per-node work (`node`) and a node\'s own spine I/O (`push`/`feed`). `dashboard` renders the subscription forest as a tree; `browse` opens an interactive full-screen navigator (tabs/tree/search) over the whole canvas and resumes the chosen node; `attention` aggregates pending human asks across the graph; `revive` reopens a window for a done/idle/dead/canceled node; `daemon` manages the thin crtrd supervisor that auto-revives nodes on window exit; `prune` bounds growth by deleting terminal nodes past a TTL.',
         },
-        children: [dashboardLeaf, attentionBranch, reviveLeaf, tmuxSpreadLeaf, daemonBranch, chordLeaf, canvasPruneLeaf],
+        children: [dashboardLeaf, browseLeaf, attentionBranch, reviveLeaf, tmuxSpreadLeaf, daemonBranch, chordLeaf, canvasPruneLeaf],
     });
 }

package/dist/commands/daemon.js

@@ -93,7 +93,7 @@ const daemonStop = defineLeaf({
             throw new InputError({
                 error: 'kill_failed',
                 message: `failed to signal pid ${pid}: ${err.message}`,
-                next: 'The pidfile may be stale; remove ~/.crtr/crtrd.pid manually.',
+                next: 'The pidfile may be stale; remove ~/.crouter/canvas/crtrd.pid manually.',
             });
         }
     },

package/dist/commands/human/prompts.js

@@ -2,12 +2,12 @@ import { defineLeaf } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
 import { spawnNode } from '../../core/runtime/nodes.js';
 import { interactionDir } from '../../core/artifact.js';
-import { isInTmux, spawnAndDetach } from '../../core/spawn.js';
+import { isInTmux } from '../../core/spawn.js';
 import { mkdirSync, existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { validateDeck, approveDeck, notifyDeck, atomicWriteJson, deckPath, display, } from '@crouton-kit/humanloop';
-import { DECK_SCHEMA_HINT, followUpReview, spawnHumanJob, pickPlacement, runCmd, resolveMaxPanes, } from './shared.js';
+import { DECK_SCHEMA_HINT, followUpReview, spawnHumanJob, detachHumanTui, resolveMaxPanes, } from './shared.js';
 /** The asking node's id, or null when run from a bare shell (no parent to route to). */
 function askingNode() {
     return process.env['CRTR_NODE_ID'] ?? null;
@@ -212,13 +212,7 @@ export const humanNotify = defineLeaf({
         atomicWriteJson(join(idir, 'run.json'), rc);
         let shown = false;
         if (isInTmux()) {
-            const spawn = spawnAndDetach({
-                command: runCmd(idir),
-                cwd,
-                placement: pickPlacement(),
-                killAfterSeconds: 0,
-            });
-            shown = spawn.status === 'spawned';
+            shown = detachHumanTui(idir, cwd).status === 'spawned';
         }
         return { shown, dir: idir };
     },

package/dist/commands/human/shared.d.ts

@@ -1,3 +1,4 @@
+import { type DetachResult } from '../../core/spawn.js';
 export declare const DECK_SCHEMA_HINT: string;
 export interface RunRecord {
     mode: 'ask' | 'approve' | 'notify' | 'review';
@@ -9,7 +10,31 @@ export interface RunRecord {
     pane_id?: string;
 }
 export declare function resolveMaxPanes(): number;
-export declare function pickPlacement(): 'split-h' | 'new-window';
+export declare function pickPlacement(targetPane?: string): 'split-h' | 'new-window';
+/**
+ * The tmux pane the humanloop TUI should open BESIDE so a PERSON actually sees
+ * it. A prompt raised by a canvas node must NOT land in the backstage `crtr`
+ * session (the holding ground for un-watched node panes) — it lands in the
+ * session the user is watching that node's graph in:
+ *   1. node prompt (CRTR_NODE_ID set) → the HIGHEST FOCUSED node of its graph
+ *      (`graphSurfaceTarget`, the focused node closest to the graph root): split
+ *      beside it, in the session/window the user already has it open in.
+ *   2. nothing in the graph on screen (or a dead focus pane), or a bare-shell
+ *      prompt → the user's currently-attached pane (`attachedClientPane`).
+ *   3. neither resolvable → undefined (tmux falls back to the caller pane).
+ * The TUI lands in the right place but NEVER switches the user's session/window
+ * (no switch-client / select-window; new-window opens `-d`). They see it when
+ * they look at the node they are already watching.
+ */
+export declare function resolveHumanTarget(): string | undefined;
+/**
+ * Open the detached humanloop `_run` pane for an interaction dir, ROUTED to the
+ * session the user is watching (`resolveHumanTarget`). The single spawn path
+ * behind ask/approve/review (`spawnHumanJob`) and notify. `detached: true` keeps
+ * the user's view put — the prompt lands beside the watched node without
+ * jumping their session/window. `jobId`, when given, is injected as CRTR_JOB_ID.
+ */
+export declare function detachHumanTui(idir: string, cwd: string, jobId?: string): DetachResult;
 export declare function runCmd(dir: string): string;
 export declare function followUpResult(_jobId: string): string;
 export declare function followUpDrain(_jobId: string): string;

package/dist/commands/human/shared.js

@@ -2,7 +2,8 @@ import { readConfig } from '../../core/config.js';
 import { spawnSync } from 'node:child_process';
 import { join } from 'node:path';
 import { atomicWriteJson, readJson } from '@crouton-kit/humanloop';
-import { countPanesInCurrentWindow, spawnAndDetach, shellQuote } from '../../core/spawn.js';
+import { countPanesInWindow, spawnAndDetach, shellQuote, attachedClientPane, paneAlive, } from '../../core/spawn.js';
+import { graphSurfaceTarget } from '../../core/runtime/placement.js';
 export const DECK_SCHEMA_HINT = 'Deck must match the humanloop deck schema: {title?, ' +
     'source?:{sessionName?,askedBy?,blockedSince?}, ' +
     'interactions:[{id,title,subtitle?,(body?|bodyPath?),options:[{id,label,' +
@@ -11,8 +12,51 @@ export const DECK_SCHEMA_HINT = 'Deck must match the humanloop deck schema: {tit
 export function resolveMaxPanes() {
     return readConfig('user').max_panes_per_window;
 }
-export function pickPlacement() {
-    return countPanesInCurrentWindow() >= resolveMaxPanes() ? 'new-window' : 'split-h';
+export function pickPlacement(targetPane) {
+    return countPanesInWindow(targetPane) >= resolveMaxPanes() ? 'new-window' : 'split-h';
+}
+/**
+ * The tmux pane the humanloop TUI should open BESIDE so a PERSON actually sees
+ * it. A prompt raised by a canvas node must NOT land in the backstage `crtr`
+ * session (the holding ground for un-watched node panes) — it lands in the
+ * session the user is watching that node's graph in:
+ *   1. node prompt (CRTR_NODE_ID set) → the HIGHEST FOCUSED node of its graph
+ *      (`graphSurfaceTarget`, the focused node closest to the graph root): split
+ *      beside it, in the session/window the user already has it open in.
+ *   2. nothing in the graph on screen (or a dead focus pane), or a bare-shell
+ *      prompt → the user's currently-attached pane (`attachedClientPane`).
+ *   3. neither resolvable → undefined (tmux falls back to the caller pane).
+ * The TUI lands in the right place but NEVER switches the user's session/window
+ * (no switch-client / select-window; new-window opens `-d`). They see it when
+ * they look at the node they are already watching.
+ */
+export function resolveHumanTarget() {
+    const nodeId = process.env['CRTR_NODE_ID'];
+    if (nodeId !== undefined && nodeId !== '') {
+        const f = graphSurfaceTarget(nodeId);
+        if (f !== null && f.pane !== null && paneAlive(f.pane))
+            return f.pane;
+    }
+    return attachedClientPane() ?? undefined;
+}
+/**
+ * Open the detached humanloop `_run` pane for an interaction dir, ROUTED to the
+ * session the user is watching (`resolveHumanTarget`). The single spawn path
+ * behind ask/approve/review (`spawnHumanJob`) and notify. `detached: true` keeps
+ * the user's view put — the prompt lands beside the watched node without
+ * jumping their session/window. `jobId`, when given, is injected as CRTR_JOB_ID.
+ */
+export function detachHumanTui(idir, cwd, jobId) {
+    const targetPane = resolveHumanTarget();
+    return spawnAndDetach({
+        command: runCmd(idir),
+        cwd,
+        ...(jobId !== undefined ? { jobId } : {}),
+        placement: pickPlacement(targetPane),
+        killAfterSeconds: 0,
+        detached: true,
+        ...(targetPane !== undefined ? { targetPane } : {}),
+    });
 }
 export function runCmd(dir) {
     return `CRTR_HUMAN_DIR=${shellQuote(dir)} crtr human _run`;
@@ -51,13 +95,7 @@ export function followUpReview(_jobId) {
  * on run.json (not returned) so `human cancel` can later kill the TUI.
  */
 export function spawnHumanJob(jobId, idir, cwd) {
-    const spawn = spawnAndDetach({
-        command: runCmd(idir),
-        cwd,
-        jobId,
-        placement: pickPlacement(),
-        killAfterSeconds: 0,
-    });
+    const spawn = detachHumanTui(idir, cwd, jobId);
     if (spawn.status !== 'spawned') {
         return { spawned: false, follow_up: followUpDrain(jobId) };
     }