@crouton-kit/crouter 0.3.31 → 0.3.33

package/README.md

@@ -24,3 +24,11 @@ crtr pkg market manage install --marketplace crouter-official-marketplace --plug
 ```
 
 To opt out of the bootstrap (e.g. in CI), set `CRTR_NO_BOOTSTRAP=1`.
+
+## Running crouter on pi
+
+The node runtime hosts the [pi coding agent](https://pi.dev) in each broker. To set your pi install up the way crouter's author runs it, add these to the `packages` array in `~/.pi/agent/settings.json` (neither ships with pi — you add them yourself):
+
+- **[pi-claude-oauth-adapter](https://github.com/minzique/dotfiles-agents/tree/main/packages/pi-claude-oauth-adapter)** — third-party npm package; Anthropic OAuth / Claude Code compatibility adapter for pi. Install with `"npm:pi-claude-oauth-adapter"`.
+- **[pi-personal-extensions](https://github.com/crouton-labs/pi-personal-extensions)** — the author's personal pi extensions (crtr help-gate, slash-command surfacing, provider rotation, frontmatter rules, statusline). Its README documents the full machine setup.
+

package/dist/build-root.js

@@ -12,6 +12,7 @@ const TAGLINE = 'crtr: agentic planning runtime.';
  *  it once yields both registers. */
 const SUBTREE_LOADERS = {
     memory: async () => (await import('./commands/memory.js')).registerMemory(),
+    search: async () => (await import('./commands/search.js')).registerSearch(),
     pkg: async () => (await import('./commands/pkg.js')).registerPkg(),
     human: async () => (await import('./commands/human.js')).registerHuman(),
     sys: async () => (await import('./commands/sys.js')).registerSys(),

package/dist/builtin-memory/crouter-development/marketplaces.md

@@ -1,7 +1,7 @@
 ---
 kind: knowledge
 when-and-why-to-read: When creating a crtr marketplace or contributing plugins
-  to one, this skill should be read.
+  to one, this knowledge should be read.
 short-form: How to author a crtr marketplace — marketplace.json index, plugin
   entries, symlink-based install, auto-bump CI, dual-publishing. Use when
   creating a marketplace or contributing plugins to one.
@@ -112,7 +112,7 @@ mkdir -p plugins/my-new-plugin/.crouter-plugin plugins/my-new-plugin/memory
 $EDITOR plugins/my-new-plugin/.crouter-plugin/plugin.json
 
 # Add at least one doc (`crtr memory write -h` is the authoring + routing guide)
-$EDITOR plugins/my-new-plugin/memory/first-skill.md
+$EDITOR plugins/my-new-plugin/memory/first-doc.md
 
 # Add the plugin to the marketplace index
 $EDITOR .crouter-marketplace/marketplace.json

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

@@ -2,7 +2,7 @@
 kind: knowledge
 when-and-why-to-read: When writing or revising a base persona prompt (a
   <kind>/PERSONA.md, the system prompt for a single-window worker node), this
-  skill should be read.
+  knowledge should be read.
 short-form: 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
@@ -14,7 +14,7 @@ needs-refinement: true
 
 # Writing a base persona prompt
 
-`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]]`.
+`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 knowledge doc 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>/PERSONA.md`.
 

package/dist/builtin-memory/crouter-development/personas/orchestrator-prompt.md

@@ -2,11 +2,11 @@
 kind: knowledge
 when-and-why-to-read: When writing or revising an orchestrator persona prompt (a
   <kind>/orchestrator.md, the system prompt for a resident coordinator node),
-  this skill should be read.
+  this knowledge should be read.
 short-form: How to write an orchestrator persona prompt (orchestrator.md) — the
   system prompt for a resident coordinator node. Covers the kernel-vs-kind
   split, what belongs in the per-kind body, naming the child pipeline, the
-  roadmapSkill pointer, and the @include rule. Use when writing or revising a
+  roadmapKnowledge knowledge-doc pointer, and the @include rule. Use when writing or revising a
   <kind>/orchestrator.md.
 system-prompt-visibility: name
 file-read-visibility: none
@@ -15,7 +15,7 @@ needs-refinement: true
 
 # Writing an orchestrator persona prompt
 
-`orchestrator.md` is the system prompt for a **resident coordinator** — a long-lived node that owns a goal too large for one window and delivers it by decomposing, delegating, integrating, and surviving context refreshes. This skill is the philosophy of what belongs in an orchestrator persona; for file mechanics and frontmatter, see `[[crouter-development/personas]]`.
+`orchestrator.md` is the system prompt for a **resident coordinator** — a long-lived node that owns a goal too large for one window and delivers it by decomposing, delegating, integrating, and surviving context refreshes. This knowledge doc is the philosophy of what belongs in an orchestrator persona; for file mechanics and frontmatter, see `[[crouter-development/personas]]`.
 
 Audience: LLM agents writing a `<kind>/orchestrator.md`.
 
@@ -31,7 +31,7 @@ So your `orchestrator.md` body carries **only the delta** — what is specific t
 
 2. **The child kinds it drives, and the pipeline.** Name the specialists this orchestrator delegates to and the order it runs them: developer drives `explore → spec → plan → developer → review` as a "spec → plan → implement → review → fix → validate" pipeline; spec runs `SHAPE → DESIGN → REQUIREMENTS` stages; review fans `review` children across units. The flow is the kind's signature — make it explicit so delegation isn't ad hoc.
 
-3. **A pointer to the methodology skill — don't inline it.** Set `roadmapSkill: <skill>` in frontmatter and tell the body to read `crtr memory read <kind>` before shaping the roadmap. The methodology (roadmap shapes, styles, decomposition rules) lives in that skill, not the persona. The persona points; the skill teaches.
+3. **A pointer to the methodology knowledge doc — don't inline it.** Set `roadmapKnowledge: <knowledge-doc-name>` in frontmatter and tell the body to read `crtr memory read <kind>` before shaping the roadmap. The methodology (roadmap shapes, styles, decomposition rules) lives in that knowledge doc, not the persona. The persona points; the doc teaches.
 
 4. **The kind's quality bar.** State the domain-specific exit criteria the kernel can't: developer's "implementation is done when provably correct against the spec, review done when a non-implementer cleared all Major/Critical findings, validation done end-to-end in the real runtime." This is where you set the ceiling for *this* kind of work.
 
@@ -52,6 +52,6 @@ When a unit is itself too big for one window, the orchestrator creates that chil
 
 - **Re-teaching the kernel.** Re-explaining the wake loop, roadmap sections, yielding, or memory duplicates the kernel and drifts. If it's universal, delete it.
 - **Missing `@include`.** No kernel = no loop, no roadmap discipline, no finish checklist. Always include it, last.
-- **Inlining the methodology.** Roadmap shapes belong in the `roadmapSkill`, not the persona. Point at it.
+- **Inlining the methodology.** Roadmap shapes belong in the `roadmapKnowledge` knowledge doc, not the persona. Point at it.
 - **No named pipeline.** An orchestrator that doesn't name its child kinds and their order produces scattershot delegation. The flow is the value.
 - **Forgetting the no-self-execution rule.** Without an explicit boundary, the model drifts into doing the work itself and exhausts its context with the goal half-met — the exact failure orchestrators exist to avoid.

package/dist/builtin-memory/crouter-development/personas.md

@@ -1,7 +1,7 @@
 ---
 kind: knowledge
 when-and-why-to-read: When adding a new `--kind`, overriding a builtin agent, or
-  debugging persona resolution, this skill should be read.
+  debugging persona resolution, this knowledge should be read.
 short-form: 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
@@ -72,8 +72,7 @@ YAML frontmatter on either file supplies launch knobs; the body is the system pr
 | `model` | string | pi model override (normalized). Omit to inherit the default. |
 | `tools` | string[] | pi tool allowlist. Omit for all tools. |
 | `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. |
+| `roadmapKnowledge` | string | orchestrator only — a knowledge doc 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. |
 
@@ -110,4 +109,4 @@ No scaffold command — create the dir + files by hand. Copy a builtin (`explore
 
 ## Related
 
-`[[crouter-development/plugins]]` packages *skills* for distribution — personas are distributed differently (committed to a scope's `personas/`), so a kind is never part of a plugin.
+`[[crouter-development/plugins]]` packages memory docs for distribution — personas are distributed differently (committed to a scope's `personas/`), so a kind is never part of a plugin.

package/dist/builtin-memory/crouter-development/plugins.md

@@ -1,10 +1,10 @@
 ---
 kind: knowledge
-when-and-why-to-read: When creating a crtr plugin, packaging skills for
-  distribution, or debugging install/resolution, this skill should be read.
+when-and-why-to-read: When creating a crtr plugin, packaging memory docs for
+  distribution, or debugging install/resolution, this knowledge should be read.
 short-form: How to author a crtr plugin — plugin.json manifest, directory
   layout, scopes, install mechanics, versioning. Use when creating a new plugin,
-  packaging skills for distribution, or debugging install/resolution.
+  packaging memory docs for distribution, or debugging install/resolution.
 system-prompt-visibility: name
 file-read-visibility: none
 ---
@@ -15,16 +15,16 @@ A **plugin** is a directory shipping substrate docs (knowledge and preferences)
 
 Audience: LLM agents creating or maintaining a crtr plugin.
 
-## When you need a plugin (vs scope-owned skills)
+## When you need a plugin (vs scope-owned memory docs)
 
 Scope-owned docs live at `~/.crouter/memory/` (user) or `<project>/.crouter/memory/` (project). They're personal and per-machine/per-repo.
 
 Reach for a **plugin** when:
-- You want to share skills across multiple projects or with other people.
+- You want to share memory docs across multiple projects or with other people.
 - You want versioning + update mechanics (`crtr pkg plugin manage update --name <name>`).
 - You want a marketplace to index the work — see [[crouter-development/marketplaces]].
 
-If it's a one-off note for yourself, scope-owned skills are simpler. Promote to a plugin later.
+If it's a one-off note for yourself, scope-owned memory docs are simpler. Promote to a plugin later.
 
 ## Directory layout
 
@@ -61,7 +61,7 @@ The `<plugin-name>` directory IS the plugin. The manifest's `name` field must ma
 | Field | Required | Notes |
 |---|---|---|
 | `name` | yes | Must match the directory name. Lowercase kebab. |
-| `version` | yes | Semver. Marketplace CI may bump automatically — see marketplaces skill. |
+| `version` | yes | Semver. Marketplace CI may bump automatically — see marketplaces knowledge. |
 | `description` | yes | One sentence. |
 | `source` | recommended | Git URL where the plugin lives. Used by `crtr pkg plugin manage update --name <name>`. |
 | `owner` | optional | Author info. |
@@ -102,7 +102,7 @@ Three ways a plugin lands in a scope:
 mkdir -p my-plugin/.crouter-plugin my-plugin/memory
 $EDITOR my-plugin/.crouter-plugin/plugin.json      # write the manifest
 cd my-plugin
-$EDITOR my-plugin/memory/my-first-skill.md         # author the doc — `crtr memory write -h` is the frontmatter + routing guide
+$EDITOR my-plugin/memory/my-first-doc.md           # author the doc — `crtr memory write -h` is the frontmatter + routing guide
 
 # Symlink for fast iteration — no clone, edits land immediately
 ln -s $(pwd) ~/.crouter/plugins/my-plugin
@@ -110,7 +110,7 @@ ln -s $(pwd) ~/.crouter/plugins/my-plugin
 # Verify
 crtr pkg plugin inspect list                       # my-plugin appears
 crtr pkg plugin inspect show my-plugin             # lists its docs
-crtr memory read my-plugin/my-first-skill          # resolve it under the plugin namespace
+crtr memory read my-plugin/my-first-doc            # resolve it under the plugin namespace
 crtr sys doctor                                    # validates the manifest
 crtr memory lint                                    # validates doc frontmatter
 ```
@@ -124,8 +124,8 @@ Standard semver:
 | Change | Bump |
 |---|---|
 | Typo, wording polish | patch (0.1.0 → 0.1.1) |
-| New skill, new section, new example | minor (0.1.0 → 0.2.0) |
-| Removed skill, renamed skill, changed manifest schema | major (0.1.0 → 1.0.0) |
+| New doc, new section, new example | minor (0.1.0 → 0.2.0) |
+| Removed doc, renamed doc, changed manifest schema | major (0.1.0 → 1.0.0) |
 
 `crtr pkg plugin manage update --name <name>` reads the new version after pulling and updates the local config. Plugins published through a marketplace may have their `version` field bumped automatically by CI — see [[crouter-development/marketplaces]].
 
@@ -133,22 +133,22 @@ Standard semver:
 
 `crtr pkg plugin manage disable <name>` flips the per-scope config without removing files. Disabled plugins are hidden from `crtr memory list` and don't resolve via `crtr memory read <name>`. Re-enable with `crtr pkg plugin manage enable <name>`.
 
-Individual skills inside an enabled plugin are hidden by setting their frontmatter visibility rungs to `none` (or a gate that fails), not by a command — see `crtr memory write -h`.
+Individual memory docs inside an enabled plugin are hidden by setting their frontmatter visibility rungs to `none` (or a gate that fails), not by a command — see `crtr memory write -h`.
 
 ## What goes in a plugin
 
 Good plugin scope:
-- A coherent set of related skills (3–15 typical) sharing a theme.
-- All skills serve the same user persona or workflow.
+- A coherent set of related memory docs (3–15 typical) sharing a theme.
+- All docs serve the same user persona or workflow.
 - Versioned together — a bump means a bump for the whole set.
 
 Bad plugin scope:
-- One mega-plugin with every skill you've ever written. Hard to install selectively, hard to version.
-- A plugin per single skill. No value-add over scope-owned skills.
+- One mega-plugin with every doc you've ever written. Hard to install selectively, hard to version.
+- A plugin per single doc. No value-add over scope-owned memory docs.
 
 ## Cross-plugin etiquette
 
-If your skill conceptually depends on another plugin's skill, link via `## Related` with `` `<plugin>/<skill>` ``. Don't fork content; link it.
+If your memory doc conceptually depends on another plugin's doc, link via `## Related` with `` `<plugin>/<doc>` ``. Don't fork content; link it.
 
 ## Validation
 
@@ -160,4 +160,4 @@ If your skill conceptually depends on another plugin's skill, link via `## Relat
 
 ## Cross-publishing with Claude Code
 
-Some plugins also publish a `.claude-plugin/` manifest alongside `.crouter-plugin/` so they can be loaded directly into Claude Code without going through crtr. Optional. Only worth doing when your skills/commands meaningfully stand alone in the Claude Code surface. Keep manifests in sync if you do.
+Some plugins also publish a `.claude-plugin/` manifest alongside `.crouter-plugin/` so they can be loaded directly into Claude Code without going through crtr. Optional. Only worth doing when your memory docs or commands meaningfully stand alone in the Claude Code surface. Keep manifests in sync if you do.

package/dist/builtin-memory/design.md

@@ -1,13 +1,16 @@
 ---
 kind: knowledge
 when-and-why-to-read: When shaping a design roadmap or producing an
-  architecture/interface design, this skill should be read.
+  architecture/interface design, this knowledge should be read.
 short-form: Use when shaping a design roadmap or producing an
   architecture/interface design — covers what a design deliverable is, the
   design-artifact shape, when to go top-down vs bottom-up, and how to decompose
   a large design into composable sub-designs.
 system-prompt-visibility: name
 file-read-visibility: none
+gate:
+  kind:
+    imatches: '^design($|/)'
 needs-refinement: true
 ---
 

package/dist/builtin-memory/development.md

@@ -2,12 +2,15 @@
 kind: knowledge
 when-and-why-to-read: When shaping or reshaping a build roadmap — choosing a
   development style, selecting a phase skeleton, or setting exit criteria for a
-  software goal — this skill should be read.
+  software goal — this knowledge should be read.
 short-form: Use when shaping or reshaping a build roadmap — choosing a
   development style, selecting a phase skeleton, or setting exit criteria for a
   software goal.
 system-prompt-visibility: name
 file-read-visibility: none
+gate:
+  kind:
+    imatches: '^developer$'
 needs-refinement: true
 ---
 

package/dist/builtin-memory/internal/INDEX.md

@@ -16,6 +16,6 @@ Open this dir whenever a task turns on understanding the runtime itself. Content
 - **storage-tiers** — where every kind of state lives: the three tiers (scope root, per-cwd crouter root, canvas home) and their durability/ownership contracts.
 - **examples/** — worked compositions of the primitives into complete systems (the analogue of pi's `examples/` dir), e.g. the iMessage assistant node.
 
-Adjacent, outside this dir: authoring memory documents (kind, rungs, gates, routing line, the asked-to-remember workflow) is owned by `crtr memory write -h` — the authoring guide lives on the help-gate so it surfaces exactly when you write; making a persona (a custom `--kind`) is owned by the builtin **crouter-development/personas** skills.
+Adjacent, outside this dir: authoring memory documents (kind, rungs, gates, routing line, the asked-to-remember workflow) is owned by `crtr memory write -h` — the authoring guide lives on the help-gate so it surfaces exactly when you write; making a persona (a custom `--kind`) is owned by the builtin **crouter-development/personas** knowledge doc.
 
 The individual files surface at `name` (their titles route; open the one the situation calls for); this index surfaces at `preview` so the dir announces when to come looking.

package/dist/builtin-memory/internal/nodes-and-canvas.md

@@ -8,18 +8,18 @@ file-read-visibility: none
 
 # How nodes and the canvas work (operational)
 
-Every agent is a **node** in one directed graph (the **canvas**). Each node is an independent `pi` process in its own tmux window with its own context dir. The graph's edges are `subscribes_to` — the **spine** — and they decide who-wakes-whom.
+Every agent is a **node** in one directed graph (the **canvas**). Each node has a canvas row, its own context dir, and one detached headless broker engine; tmux panes are only viewer surfaces that attach to a broker. The graph's edges are `subscribes_to` — the **spine** — and they decide who-wakes-whom.
 
 ## Spawn & delegate
 
-`crtr node new "<task>" --kind <kind>` spawns a managed child in a background window and returns its id immediately; you **auto-subscribe** to it, so its finish wakes you. Delegating is the default move, not an optimization: a child's reading and tokens land in a fresh window and only the conclusion comes back, keeping your own context (the scarce resource) free for steering.
+`crtr node new "<task>" --kind <kind>` launches a managed child broker and returns its id immediately; you **auto-subscribe** to it, so its finish wakes you. Delegating is the default move, not an optimization: a child's reading and tokens land in a fresh context window and only the conclusion comes back, keeping your own context (the scarce resource) free for steering.
 
 - Match `--kind` to the work (`explore spec design plan developer review general`, plus any custom persona). See `node new -h`.
 - Fan **independent** units out as concurrent children — a wake with idle workers is wasted. Serialize only true dependencies; never let two live children edit the same files.
 - `--root` spawns an independent node you neither manage nor are woken by (e.g. one a human will drive).
 - Once you delegate a unit, don't also run it yourself — you'll be woken when it finishes.
 
-Navigate/steer: `node focus` (jump a node into your pane), `node cycle` (DFS-walk neighbors), `node msg` (direct-message any node at a wake tier, reviving a dormant target), `node subscribe`/`unsubscribe` (wire edges spawn didn't create). Survey with `canvas dashboard` (ASCII tree), `canvas browse` (interactive navigator), `node inspect list/show`, `canvas attention` (who's blocked on a human).
+Navigate/steer: `node focus` (put an attach viewer for a node in your pane), `attach` (connect to a node's existing broker), `node cycle` (DFS-walk neighbors), `node msg` (direct-message any node at a wake tier, reviving a dormant target), `node subscribe`/`unsubscribe` (wire edges spawn didn't create). Survey with `canvas dashboard` (ASCII tree), `canvas browse` (interactive navigator), `node inspect list/show`, `canvas attention` (who's blocked on a human).
 
 ## The push/feed spine
 
@@ -27,7 +27,7 @@ Nothing is reported automatically — the feed contains only what a node **pushe
 
 - `push update` — routine progress; fans a lightweight pointer to subscribers, no forced wake.
 - `push urgent` — force-wakes every subscriber (you're blocked, scope changed, an error derails the plan).
-- `push final` — the ONLY way any node finishes: writes the canonical result, marks the node done, closes its window. Stopping without it is not finishing. (Guarded on a node working directly with a user — needs `--force` after they confirm.)
+- `push final` — the ONLY way a terminal node finishes: writes the canonical result, marks the node done, and tears down its broker. Stopping without it is not finishing. Resident/user-facing nodes stay dormant instead of finishing unless explicitly forced.
 
 A push fans a ~30-token **pointer** (a ref path), not the content; subscribers dereference lazily. When a subscriber push wakes you, **the wake message already IS the coalesced digest** — don't re-run `feed read` to "open" it (the cursor already advanced); dereference the refs that matter. `feed read` is for proactively polling *before* a wake; `feed peek` shows live state of the nodes below you without draining (use it to confirm workers are alive before you yield). An empty feed while workers run is normal.
 
@@ -44,6 +44,6 @@ Tear-down: `node close` cascade-cancels a node + its exclusive subtree WITHOUT f
 
 ## Revive & the daemon
 
-A dormant node (done/idle/dead/canceled) is reopened with `canvas revive` (resumes the saved conversation, or `--fresh` to restart clean). `reviveNode()` is the **only** sanctioned launcher of `pi --session` — it sets `CRTR_NODE_ID` + canvas extensions and runs `transition('revive')`, keeping the db row and pi session in lockstep. Never spawn `pi --session` raw, and never open a node by spawning pi directly — UIs go through `node focus` / `canvas revive`.
+A dormant node (done/idle/dead/canceled) is reopened with `canvas revive` (resumes the saved conversation, or `--fresh` to restart clean). `reviveNode()` is the **only** sanctioned launcher of a node's broker engine — it builds the pi invocation, sets `CRTR_NODE_ID` + canvas extensions, runs `transition('revive')`, and starts the headless broker host, keeping the db row and broker process in lockstep. Never spawn `pi --session` raw, and never open a node by spawning pi directly — UIs go through `node focus` / `canvas revive`.
 
-The **daemon** (`crtrd`, managed via `canvas daemon start/stop/status`) is a thin supervisor: it polls pane + pi liveness ~every 2s and auto-revives nodes whose window exited. It does NOT host agents and does NOT auto-revive *canceled* nodes (reach for `canvas revive` for those). After rebuilding crouter's `dist/`, restart the daemon — it loads compiled code at start and never reloads it. Restarting is safe: it never signals running nodes.
+The **daemon** (`crtrd`, managed via `canvas daemon start/stop/status`) is a thin supervisor: it polls broker liveness via `pi_pid` and auto-revives active/idle nodes whose broker exited. It does NOT host agents, open viewers, or auto-revive *canceled* nodes (reach for `canvas revive` for those). After rebuilding crouter's `dist/`, restart the daemon — it loads compiled code at start and never reloads it. Restarting is safe: it never signals running nodes.

package/dist/builtin-memory/internal/storage-tiers.md

@@ -1,7 +1,7 @@
 ---
 kind: knowledge
 when-and-why-to-read: When you need to know where a piece of crtr state lives on disk — or you are adding a new kind of file and must decide where it belongs — this reference should be read because it names the three storage tiers and their durability/ownership contracts, so you put (or find) the file in the right place instead of scattering state.
-short-form: The three crtr storage tiers — scope root (durable user/repo content), per-cwd crouter root (per-project working artifacts), and canvas home (node-graph runtime state).
+short-form: The three crtr storage tiers — scope root (durable user/repo content), per-cwd interaction queue, and canvas home (node-graph runtime state).
 system-prompt-visibility: name
 file-read-visibility: none
 ---
@@ -12,11 +12,11 @@ crtr state splits into three tiers, each with a distinct durability and ownershi
 
 ## 1. Scope root — durable, user/repo-authored content
 
-`~/.crouter/` (user scope) or `<project>/.crouter/` (project scope). Resolved by the scope resolver (`src/core/scope.ts`). Holds: `skills/`, `plugins/`, `marketplaces/`, `memory/`, `config.json`. Persists across project changes; belongs to the user or the repo.
+`~/.crouter/` (user scope) or `<project>/.crouter/` (project scope). Resolved by the scope resolver (`src/core/scope.ts`). Holds: `memory/`, `plugins/`, `marketplaces/`, `personas/`, `config.json`. Persists across project changes; belongs to the user or the repo.
 
-## 2. Per-cwd crouter root — per-project working artifacts
+## 2. Per-cwd crouter root — human interaction queue
 
-`~/.crouter/<mangled-cwd>/`, keyed on the originating cwd via `mangleCwd` (`src/core/artifact.ts`). Holds working artifacts like `interactions/` (humanloop decks for the `crtr human` bridge; `interactions/<id>/` holds `deck.json` / `run.json` / `response.json`).
+`~/.crouter/workspaces/<mangled-cwd>/`, keyed on the originating cwd via `mangleCwd` (`src/core/artifact.ts`). Holds `interactions/` for the `crtr human` bridge; `interactions/<id>/` holds `deck.json` / `run.json` / `response.json`. Spec and plan deliverables live in node context under `~/.crouter/canvas/nodes/<node_id>/context/`, not in this tier.
 
 ## 3. Canvas home — node-graph runtime state
 
@@ -27,6 +27,6 @@ crtr state splits into three tiers, each with a distinct durability and ownershi
 
 ## The contributor rule
 
-Durable user content → **scope root**. Per-project working artifacts → **per-cwd crouter root**. Node-graph runtime state (topology, context, reports, inbox, telemetry) → **canvas home**.
+Durable user content → **scope root**. Human decision queue → **per-cwd crouter root**. Node-graph runtime state and node-authored deliverables (topology, context, reports, inbox, telemetry) → **canvas home**.
 
 (The legacy `sessions/` graph and `$XDG_STATE_HOME/crtr/jobs/` tier were removed when the node/canvas runtime replaced the session/job model; node telemetry now lives in each node's `job/telemetry.json` under the canvas home.)

package/dist/builtin-memory/planning.md

@@ -2,11 +2,14 @@
 kind: knowledge
 when-and-why-to-read: When shaping a planning roadmap, deciding plan structure,
   or fanning out plan-review specialists before declaring a plan ready, this
-  skill should be read.
+  knowledge should be read.
 short-form: Use when shaping a planning roadmap, deciding plan structure, or
   fanning out plan-review specialists before declaring a plan ready.
 system-prompt-visibility: name
 file-read-visibility: none
+gate:
+  kind:
+    imatches: '^plan($|/)'
 needs-refinement: true
 ---
 

package/dist/builtin-memory/product.md

@@ -0,0 +1,80 @@
+---
+kind: knowledge
+when-and-why-to-read: When running a product-discovery effort, shaping a product roadmap, or deciding how to stage problem discovery, competitive teardown, and experience definition, this knowledge should be read.
+short-form: Use when running a product-discovery effort or shaping a product roadmap. Covers the three-stage DISCOVER→GROUND→DEFINE methodology, the Mom Test discovery discipline, the four-risks ownership boundary vs the downstream spec, parallel teardown delegation, and what a finished product brief contains.
+system-prompt-visibility: name
+file-read-visibility: none
+gate:
+  kind:
+    imatches: '^product($|/)'
+needs-refinement: true
+---
+
+## The Three Stages
+
+A product-discovery effort runs in this order: **DISCOVER** → **GROUND** → **DEFINE**. GROUND and DEFINE interleave (you ground to inform the definition), but you do not commit a product direction in DEFINE until DISCOVER has cleared its gate. Each stage has a gate; you do not commit the next until the current one is met.
+
+### Stage 1 — Discover (problem-space)
+
+Discover is where you find the real need. A client arrives with a solution in their mouth and a problem in their gut; your job is to reach the problem. Treat the request as a hypothesis, not an order — work the **job-to-be-done**: what the user is hiring this product to accomplish (functional, emotional, and social dimensions), for whom, in what triggering moment, and what they do today instead and why it falls short.
+
+Run discovery with `crtr human ask` using the **Mom Test discipline**: ask about real, specific past behavior and concrete pain ("walk me through the last time you hit this"), never pitch your idea, and never ask hypothetical "would you use…" questions — they invite politeness, not truth. Real pain is validated by current workarounds, emotional language, and evidence of prior spend, not hypothetical enthusiasm. Earn every question: answer what you can yourself by tearing down existing products and reading the codebase first; only judgment-bearing, genuinely unresolved questions reach the human.
+
+Write each core need as a **JTBD statement** — `verb + object + context` ("minimize the time to capture a thought on the go") or `When [situation], I want to [motivation], so I can [outcome]` — across all three dimensions (functional, emotional, social); the emotional and social dimensions are the ones teams skip and are exactly what feed the experience work in Define. Structure the discovery output as an **opportunity solution tree** (Torres): one measurable **outcome** at the root, the **opportunities** (unmet needs/pains, sourced from real evidence) beneath it, and candidate **solutions** each tied to a specific opportunity, with the riskiest **assumptions** to test hanging off them. The tree's whole job is to forbid jumping from the outcome straight to a solution and to force more than one branch — it kills the single-track tunnel vision that order-taking produces.
+
+The request and the real job often diverge. When the asked-for feature does not serve the underlying job, say so and steer — building exactly what was asked when it won't meet the need is the central failure this role exists to prevent.
+
+Gate: the client confirms you have the real problem and the users right — restate the job without correction, and the requested feature is either validated as serving it or consciously redirected.
+
+### Stage 2 — Ground (competitive)
+
+Before committing a direction, study how comparable products solve the same job. This is not a feature survey — it is a teardown of the *experience*: interaction patterns, what each product gets right (borrow), where it fails its users (avoid), and where a new product could beat it (differentiate).
+
+Delegate one `product/teardown` child per comparable product and run them in parallel; each studies one product deeply against the job-to-be-done and returns a verdict. Integrate the teardowns yourself into a single **positioning stance** — borrow / avoid / differentiate — never a concatenation and never a copy. Inspiration becomes a defensible direction only when you can say why you are borrowing or rejecting each pattern *for this job*.
+
+Treat competitor patterns as hypotheses, not proven-optimal truth — their design may never have been tested. Do not chase feature parity; it is easily copied and commoditizes you. Instead find the **market orthodoxy** (what every comparable product does the same way), locate the customer-satisfaction gap that orthodoxy leaves open, and pick an opposite dimension that matters to a specific segment. Express the result as a positioning statement: **"Unlike [competitor], [product] provides [durable outcome] because [verifiable reason to believe]."** The reason must rest on something that *compounds* (proprietary data, domain depth, a unique posture), not a UI tweak or a vague "easier to use" claim.
+
+Gate: a positioning stance exists that names what you will borrow, what you will avoid, and how you will differentiate — on a dimension that compounds.
+
+### Stage 3 — Define (experience)
+
+Define commits the opinionated product direction. It produces: the **use cases** the product serves; **3–7 experience principles** (opinionated, prioritized — "instant over configurable", not platitudes); the **emotional target** ("using this should feel like…"); a **user journey** with its moments of truth — where the product must delight and where it must not fail; and a **product vision + North Star** that names the one outcome the product optimizes. Be opinionated: a definition that lists options without a recommendation has not done the consulting.
+
+Gate: the client aligns on the product direction and the experience — the feel, the use cases, and the vision.
+
+---
+
+## The Four Risks — What This Role Owns
+
+Every product idea carries four risks (Cagan): **value** (will anyone want it), **usability** (can they use it), **feasibility** (can we build it), **viability** (does it work for the business — brand, legal, economics). This role **owns value, usability, and experience**: discovering them and defining for them is the job. It **flags viability** when it surfaces (a direction that risks the brand, a legal exposure, an economics problem) but does not adjudicate it. It **defers feasibility** entirely to engineering — never let "is this buildable" narrow the product direction during discovery; that is the downstream spec and design work, and pre-empting it trades a clean problem for a brittle answer.
+
+Discovery exists to attack these risks *cheaply and early* — with the assumption inventory and small tests, not engineering cycles. Treat the opening problem statement as a set of unproven hypotheses: categorize the claims (behavioral / emotional / economic), rank them by risk, and surface the riskiest first — the ranked inventory is the explicit baton of what still needs validating.
+
+---
+
+## The Boundary With Spec — Where the Baton Passes
+
+This role stops at **the right product to build and how it should feel and look.** It does NOT write acceptance criteria, EARS requirements, user stories, API or data models, or pixel-level UI. Those belong to the downstream `spec` (buildable behavior, interfaces, edge cases) and `design` (architecture, UI structure) kinds.
+
+The baton handed to spec is four things: the **validated problem** (job, users, pain), the **experiential direction** (use cases, experience principles, emotional target, journey), the **competitive grounding** (positioning stance), and the **ranked open assumptions** the spec stage must resolve. A clean baton is a sharp *problem and direction*, not a half-written solution — pre-deciding the spec's job hands it an answer to verify instead of a problem to specify.
+
+---
+
+## What a Finished Product Brief Contains
+
+A product brief is lightweight, living, and decision-driving — not a heavy PRD. It is finished when a spec writer could derive what to build from it without re-discovering the user. It contains:
+
+- **Validated problem / opportunity** — the real job-to-be-done (functional, emotional, social), who has it, the pain, and what they do today.
+- **Use cases** — the concrete situations the product serves, in the user's terms.
+- **Experience definition** — 3–7 opinionated experience principles, the emotional target, and a user journey with its moments of truth (delight points and must-not-fail points).
+- **Competitive grounding + positioning** — what comparable products teach, and the borrow / avoid / differentiate stance.
+- **Product vision + North Star** — the one outcome the product optimizes, and the direction it implies.
+- **Ranked open assumptions** — the value/usability/experience bets the brief is making, risk-ranked, for the next stages to resolve.
+
+A brief that types the request back as a plan, lists options without a recommendation, or smuggles in acceptance criteria and UI specs is not finished. Surface unresolved discovery as ranked assumptions, never as silent guesses.
+
+---
+
+## Roadmap Shape for a Product Effort
+
+The goal section states the product being discovered and for whom. Scope assumptions record the audience and the job in scope and what is explicitly not. `## Strategy / phases` holds exactly three phases: Discover (gate: client confirms the real problem + users), Ground (gate: positioning stance exists), Define (gate: client aligns on direction + experience). The current phase carries a one-line status; completed phases are deleted, not summarized. Human-confirmed decisions and teardown findings fold into context files (`context/product-brief-*.md`, teardown reports), not the roadmap.

package/dist/builtin-memory/spec.md

@@ -1,7 +1,7 @@
 ---
 kind: knowledge
 when-and-why-to-read: When running a specification effort, shaping a spec
-  roadmap, or deciding how to stage design and requirements work, this skill
+  roadmap, or deciding how to stage design and requirements work, this knowledge
   should be read.
 short-form: Use when running a specification effort, shaping a spec roadmap, or
   deciding how to stage design and requirements work. Covers the three-stage
@@ -10,6 +10,9 @@ short-form: Use when running a specification effort, shaping a spec roadmap, or
   finished spec contains.
 system-prompt-visibility: name
 file-read-visibility: none
+gate:
+  kind:
+    imatches: '^spec($|/)'
 needs-refinement: true
 ---
 

package/dist/builtin-personas/advisor/PERSONA.md

@@ -0,0 +1,10 @@
+---
+whenToUse: Debug failures, investigate why something is broken or misbehaving, diagnose live/runtime issues, or give engineering advice and second opinions — reason from evidence and recommend the next move. Use advisor (not explore) whenever the task is to find out what is going wrong.
+model: anthropic/ultra
+---
+
+You are an advisor agent: a senior debugging and engineering judgment partner. Your work is diagnosis, explanation, tradeoff analysis, and recommended next action.
+
+Ground advice in evidence. Inspect the code, logs, repro steps, prior reports, or runtime state needed to understand the situation; do not answer from vibes when the facts are available. For debugging, drive toward the smallest credible root cause: reproduce or trace the failure, separate symptoms from causes, and name the file, command, invariant, or design assumption that explains it.
+
+Your deliverable is the advice: conclusion first, then the evidence and the recommended next move. If the right next move is an implementation, say exactly what should change or hand it to a developer; do not turn advisory work into a broad refactor unless the task explicitly asks you to apply the fix.

package/dist/builtin-personas/design/PERSONA.md

@@ -1,10 +1,10 @@
 ---
 whenToUse: Architect a solution — produce one design document an implementer can build from without re-deciding anything left open.
-model: opus
+model: anthropic/strong
 ---
 
 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.
+Read your task for the scope, the constraints, and the interface contracts you must honor. Write the design to `$CRTR_CONTEXT_DIR/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.
 
 Deliver the design file path plus a tight summary — one sentence per decision, what was chosen and what it closed off. If the surface spans several subsystems with contracts between them, or is too large to design coherently in one window, that is a design orchestrator's effort — promote and own the decomposition rather than producing one sprawling, internally inconsistent doc.

package/dist/builtin-personas/design/orchestrator.md

@@ -1,11 +1,11 @@
 ---
-roadmapSkill: design
-model: opus
+roadmapKnowledge: design
+model: anthropic/strong
 ---
 
 You are a **design orchestrator** — you own a design effort too large for one agent and deliver one coherent design by decomposing it, delegating each sub-design to a `design` child, and integrating what returns into a unified artifact.
 
-Before you shape the roadmap, read `crtr memory read design` for the artifact shape, the top-down vs. bottom-up call, and the decomposition discipline. Your first act after reading it is to define the shared interface contracts between the sub-designs and write them to `context/design-contracts.md` before any child starts — those contracts are the seams that let parallel sub-designs compose instead of collide. Each child gets the overall architecture framing, the contracts doc, and the explicit scope of its piece.
+Before you shape the roadmap, read `crtr memory read design` for the artifact shape, the top-down vs. bottom-up call, and the decomposition discipline. Your first act after reading it is to define the shared interface contracts between the sub-designs and write them to `$CRTR_CONTEXT_DIR/design-contracts.md` before any child starts — those contracts are the seams that let parallel sub-designs compose instead of collide. Each child gets the overall architecture framing, the contracts doc, and the explicit scope of its piece.
 
 Integration is the work, not a formality: read every sub-design, verify each contract is honored on *both* sides, reconcile the inconsistencies that only surface with the whole picture loaded, and synthesize a single document that reads as one voice — not a concatenation of pieces with the decision rationale lost between them. The design is done only when an implementer could build any piece from it without discovering that two pieces disagree.
 

package/dist/builtin-personas/developer/PERSONA.md

@@ -1,6 +1,6 @@
 ---
 whenToUse: Implement a change — make the feature or fix genuinely work against its acceptance criteria, not merely compile.
-model: opus
+model: openai/medium
 ---
 
 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.

package/dist/builtin-personas/developer/orchestrator.md

@@ -1,6 +1,6 @@
 ---
-roadmapSkill: development
-model: opus
+roadmapKnowledge: development
+model: anthropic/strong
 ---
 
 You are a **developer orchestrator** — a senior engineer who owns a feature-sized goal and delivers it by driving specialist children, never by writing the code yourself. Your children are `explore` (to map), `spec` (to specify), `plan` (to decompose), `developer` (to implement), and `review` (to validate). Keep them pointed at the right work with the right context, integrate what they return, and advance the goal phase by phase until it is genuinely done.

package/dist/builtin-personas/explore/PERSONA.md

@@ -1,9 +1,9 @@
 ---
-whenToUse: Map or investigate an unfamiliar codebase — read-only research that answers a question with concrete file:line evidence.
-model: haiku
+whenToUse: Map unfamiliar code or architecture — read-only orientation and code-path research with concrete file:line evidence. Anything diagnostic — investigating a failure, why something is broken or misbehaving, or live/runtime behavior — is advisor, not explore.
+model: anthropic/light
 ---
 
-You are a fast codebase exploration agent. Your work is **read-only research** — do not modify any files.
+You are a fast codebase exploration agent. Your work is **read-only orientation and code-path research** — map unfamiliar code, answer architecture questions, and do not modify any files. If the task asks you to diagnose broken behavior, debug a failure, or recommend an engineering judgment, it belongs to advisor rather than explore.
 
 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/explore/orchestrator.md

@@ -1,9 +1,11 @@
 ---
-model: haiku
+model: anthropic/light
 ---
 
 You are an **exploration orchestrator** — you own a research question too large for one window, and you answer it by fanning out scouts and synthesising what they find. You do not read the whole codebase yourself; that is exactly the context exhaustion you exist to avoid.
 
-Decompose the surface — by subsystem, directory, layer, or sub-question — into areas small enough for one `explore` scout to map well, and delegate each a sharp, self-contained question. Then integrate what they return into one coherent answer: the architecture, the call paths, where things live, with the `file:line` evidence preserved. The question is answered only when every sub-question is — a gap a scout left open is a gap you fill with another scout, not a guess. Reconcile contradictions the same way: when two scouts disagree, spawn a follow-up to settle it rather than picking the answer you like. Your deliverable is the synthesis, not a pile of child transcripts.
+Decompose the surface — by subsystem, directory, layer, or sub-question — into areas small enough for one base `explore` scout to map well, and delegate each a sharp, self-contained question. Do not create more explore orchestrators beneath you; if a slice looks too broad for one scout, split it smaller yourself. Keep fan-out proportional: over-delegating creates transcript churn and synthesis debt, so start with the few scouts needed to cover the real seams and add follow-ups only for concrete gaps or contradictions.
+
+Then integrate what they return into one coherent answer: the architecture, the call paths, where things live, with the `file:line` evidence preserved. The question is answered only when every sub-question is — a gap a scout left open is a gap you fill with another scout, not a guess. Reconcile contradictions the same way: when two scouts disagree, spawn a follow-up to settle it rather than picking the answer you like. Your deliverable is the synthesis, not a pile of child transcripts.
 
 @include orchestration-kernel.md

package/dist/builtin-personas/general/PERSONA.md

@@ -1,6 +1,6 @@
 ---
 whenToUse: Anything else — the catch-all worker for a task that does not fit a specialist kind.
-model: opus
+model: anthropic/strong
 ---
 
 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.

package/dist/builtin-personas/general/orchestrator.md

@@ -1,5 +1,5 @@
 ---
-model: opus
+model: anthropic/strong
 ---
 
 You are a **general orchestrator** — the manager for goals that don't belong to a single specialty. You have no lens of your own; your entire edge is decomposition and routing — reading a goal, breaking it into units, and sending each to the most specific kind that fits.