@crouton-kit/crouter 0.3.32 → 0.3.34

package/README.md

@@ -19,8 +19,16 @@ crtr --help
 Browse and install plugins from it:
 
 ```bash
-crtr pkg market inspect browse --marketplace crouter-official-marketplace
-crtr pkg market manage install --marketplace crouter-official-marketplace --plugin <plugin>
+crtr pkg market browse crouter-official-marketplace
+crtr pkg plugin install crouter-official-marketplace/<plugin>
 ```
 
 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

@@ -1,17 +1,18 @@
 import { defineRoot } from './core/command.js';
-const TAGLINE = 'crtr: agentic planning runtime.';
+const TAGLINE = 'crtr: agentic runtime.';
 /** Lazy registry: subtree name → dynamic importer that builds its BranchDef.
  *  The whole point is that each `import()` only compiles that one subtree's
  *  module graph. The hot path (`crtr node focus …`, `crtr feed`, …) dispatches
  *  into a single leaf, so it must load ONE subtree — not the attach-TUI
  *  (babel/highlight.js), the web/vite command, and every other subtree it never
  *  touches. `crtr` cold-start is dominated by Node module loading; keeping the
- *  other 11 subtrees off the path is the biggest, lowest-risk win.
+ *  other subtrees off the path is the biggest, lowest-risk win.
  *
  *  Naming note: `push` and `feed` are two subtrees from one module — importing
  *  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(),
@@ -19,10 +20,7 @@ const SUBTREE_LOADERS = {
     push: async () => (await import('./commands/push.js')).registerPush(),
     feed: async () => (await import('./commands/push.js')).registerFeed(),
     canvas: async () => (await import('./commands/canvas.js')).registerCanvas(),
-    view: async () => (await import('./commands/view.js')).registerView(),
-    attach: async () => (await import('./clients/attach/attach-cmd.js')).registerAttach(),
-    workspace: async () => (await import('./commands/workspace.js')).registerWorkspace(),
-    web: async () => (await import('./clients/web/web-cmd.js')).registerWeb(),
+    surface: async () => (await import('./commands/surface.js')).registerSurface(),
 };
 /** Every shipped subtree name. Cheap (no module loading) — the front-door
  *  recursion guard and the dispatcher's first-token routing need only names. */

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.
@@ -12,13 +12,13 @@ needs-refinement: true
 
 # Authoring crtr marketplaces
 
-A **marketplace** is a git repo that indexes multiple plugins. Users register it once, then `crtr pkg market manage install --marketplace <mkt> --plugin <plugin>` symlinks any plugin from it. `crtr pkg market manage update --marketplace <mkt>` pulls updates for every installed plugin at once.
+A **marketplace** is a git repo that indexes multiple plugins. Users register it once, then `crtr pkg plugin install <mkt>/<plugin>` symlinks any plugin from it. `crtr pkg market update --name <mkt>` pulls updates for every installed plugin at once.
 
 Audience: LLM agents creating a marketplace or adding plugins to an existing one.
 
 ## When you need a marketplace (vs a single-plugin repo)
 
-A solo plugin ships from any git URL via `crtr pkg plugin manage install <url> --scope user` — no marketplace needed.
+A solo plugin ships from any git URL via `crtr pkg plugin install <url> --scope user` — no marketplace needed.
 
 Reach for a marketplace when:
 - You want to publish ≥3 plugins under one brand or theme.
@@ -75,12 +75,12 @@ The `plugins[]` array IS the index — what's installable. A plugin on disk but
 
 ## Install mechanics — symlinks, not clones
 
-When a user runs `crtr pkg market manage install --marketplace my-marketplace --plugin plugin-a`:
+When a user runs `crtr pkg plugin install my-marketplace/plugin-a`:
 1. Crouter looks up `plugin-a` in the marketplace's manifest.
 2. **Symlinks** `<marketplace-clone>/plugins/plugin-a/` → `<user-scope>/plugins/plugin-a/`.
 3. Records the install in the scope config with `source_marketplace: my-marketplace`.
 
-Therefore `crtr pkg market manage update --marketplace my-marketplace` (which does `git pull` in the marketplace clone) updates every installed plugin from it — no per-plugin re-install, no second clone.
+Therefore `crtr pkg market update --name my-marketplace` (which does `git pull` in the marketplace clone) updates every installed plugin from it — no per-plugin re-install, no second clone.
 
 ## Version-bump automation (recommended)
 
@@ -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
@@ -128,7 +128,7 @@ git commit -m "feat: add my-new-plugin"
 git push
 ```
 
-Existing users pick it up on their next `crtr pkg market manage update --marketplace <marketplace-name>` (or on the next auto-update tick if they've set `auto_update.content: "apply"`).
+Existing users pick it up on their next `crtr pkg market update --name <marketplace-name>` (or on the next auto-update tick if they've set `auto_update.content: "apply"`).
 
 ## Updating an existing plugin
 
@@ -147,7 +147,7 @@ A marketplace itself registers per-scope:
 | user | `~/.crouter/marketplaces/<name>/` | Private to your machine — your personal subscriptions |
 | project | `<project>/.crouter/marketplaces/<name>/` | Checked into the repo — anyone cloning gets the same marketplace pinned |
 
-`crtr pkg market manage add --url <git-url> --scope user` is the default. Use `--scope project` when the marketplace is integral to how the repo expects to be developed.
+`crtr pkg market add <git-url> --scope user` is the default. Use `--scope project` when the marketplace is integral to how the repo expects to be developed.
 
 ## Validation
 

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 versioning + update mechanics (`crtr pkg plugin manage update --name <name>`).
+- You want to share memory docs across multiple projects or with other people.
+- You want versioning + update mechanics (`crtr pkg plugin 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
 
@@ -49,7 +49,7 @@ The `<plugin-name>` directory IS the plugin. The manifest's `name` field must ma
 {
   "name": "my-plugin",
   "version": "0.1.0",
-  "description": "One sentence — shown in `crtr pkg plugin inspect list`.",
+  "description": "One sentence — shown in `crtr pkg plugin list`.",
   "source": "https://github.com/<owner>/<repo>",
   "owner": {
     "name": "Your Name",
@@ -61,9 +61,9 @@ 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>`. |
+| `source` | recommended | Git URL where the plugin lives. Used by `crtr pkg plugin update --name <name>`. |
 | `owner` | optional | Author info. |
 
 ## Scopes
@@ -81,19 +81,19 @@ Project-scope plugins outrank user-scope on resolution. Both outrank marketplace
 
 Three ways a plugin lands in a scope:
 
-1. **From a git URL** (`crtr pkg plugin manage install <url> --scope user`):
+1. **From a git URL** (`crtr pkg plugin install <url> --scope user`):
    - Clones into `<scope>/plugins/<name>/` using the manifest's name.
-   - `crtr pkg plugin manage update --name <name>` does `git pull`.
+   - `crtr pkg plugin update --name <name>` does `git pull`.
    - Independent of any marketplace.
 
-2. **From a marketplace** (`crtr pkg market manage install --marketplace <mkt> --plugin <name>`):
+2. **From a marketplace** (`crtr pkg plugin install <mkt>/<name>`):
    - **Symlinks** the marketplace's `plugins/<name>/` into `<scope>/plugins/<name>/`.
-   - `crtr pkg market manage update --marketplace <mkt>` pulls updates for every installed plugin from that marketplace.
+   - `crtr pkg market update --name <mkt>` pulls updates for every installed plugin from that marketplace.
    - See [[crouter-development/marketplaces]].
 
 3. **Authored in place** (you're writing the plugin in a working repo):
    - Symlink for tight dev loop: `ln -s $(pwd) ~/.crouter/plugins/<name>`.
-   - Or `crtr pkg plugin manage install file://$(pwd) --scope project` to clone-install.
+   - Or `crtr pkg plugin install file://$(pwd) --scope project` to clone-install.
 
 ## Local development loop
 
@@ -102,20 +102,20 @@ 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
 
 # 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 pkg plugin list                       # my-plugin appears
+crtr pkg plugin show my-plugin             # lists its docs
+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
 ```
 
-When ready to share: push to a git remote; anyone can `crtr pkg plugin manage install <url> --scope user`.
+When ready to share: push to a git remote; anyone can `crtr pkg plugin install <url> --scope user`.
 
 ## Versioning
 
@@ -124,31 +124,31 @@ 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]].
+`crtr pkg plugin 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]].
 
 ## Enable/disable
 
-`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>`.
+`crtr pkg plugin 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 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/examples/imessage-assistant.md

@@ -16,7 +16,7 @@ A standing assistant that lives on the canvas, sleeps for free, wakes when a tex
 |---|---|
 | Its own home | Dedicated dir (e.g. `~/assistants/imessage/`), node spawned with `--cwd` pinned there |
 | Always-on, never "finishes" | `--root` spawn → resident lifecycle; dormant between messages costs nothing |
-| Hears incoming texts | launchd watcher on `chat.db-wal` → `crtr node msg <id>` (event-driven; the spine delivers, the node never polls) |
+| Hears incoming texts | launchd watcher on `chat.db-wal` → `crtr node msg <body> --to <id>` (event-driven; the message delivers and revives, the node never polls) |
 | Reads messages | sqlite against `~/Library/Messages/chat.db`, cursored by ROWID |
 | Sends replies | `osascript` → Messages.app |
 | Memory | Project-scope substrate (`~/assistants/imessage/.crouter/memory/`) for durable knowledge; context dir for the cursor |
@@ -47,11 +47,11 @@ A trivial launchd agent watches the Messages write-ahead log and pokes the node'
 <key>WatchPaths</key><array><string>/Users/YOU/Library/Messages/chat.db-wal</string></array>
 <key>ProgramArguments</key><array>
   <string>/bin/zsh</string><string>-c</string>
-  <string>crtr node msg NODE_ID "iMessage activity — check chat.db since your cursor"</string>
+  <string>crtr node msg "iMessage activity — check chat.db since your cursor" --to NODE_ID</string>
 </array>
 ```
 
-Multiple bursts while the node is mid-turn just append to its inbox and coalesce — no dedupe logic needed. Trust the runtime: do **not** also arm a recurring `node wake at` as a backstop. A self-scheduled wake is only the fallback if you choose not to run a watcher at all (pure polling — workable, but pays a window per tick and adds latency).
+Multiple bursts while the node is mid-turn just append to its inbox and coalesce — no dedupe logic needed. Trust the runtime: do **not** also arm a recurring `node msg --self --every` as a backstop. A self-scheduled message is only the fallback if you choose not to run a watcher at all (pure polling — workable, but pays a window per tick and adds latency).
 
 ## 4. Reading chat.db (the verified gotchas)
 

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 <body> --to <node>` (direct-message any node at a wake tier, reviving a dormant target), `node subscribe`/`node 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.
 
@@ -36,14 +36,14 @@ A push fans a ~30-token **pointer** (a ref path), not the content; subscribers d
 Two orthogonal axes:
 
 - **mode**: base (a terminal worker — does one job in one window and ends) ↔ orchestrator (`node promote` — a long-lived, roadmap-holding coordinator that delegates phases and survives context refresh via `node yield`). Don't promote for work that fits one window.
-- **lifecycle**: terminal (owes a final up the spine, reaps when done) ↔ resident (`node lifecycle` / interactable — stays dormant, wakes on inbox/human, never forced to finish). `node demote` is the friendly flip-to-terminal-in-place.
+- **lifecycle**: terminal (owes a final up the spine, reaps when done) ↔ resident (`node config --lifecycle <value>` / interactable — stays dormant, wakes on inbox/human, never forced to finish). `node lifecycle demote` is the friendly flip-to-terminal-in-place.
 
-A dormant node has two wake triggers: an **inbox** message (push/msg) and the **clock** (`node wake` arms timed/recurring wakeups). To monitor your own children you arm nothing — you auto-subscribe on spawn, so their finish/crash/close wakes you; a deadline to chase a delegate is a belt-and-suspenders the runtime makes redundant.
+A dormant node has two wake triggers: an **inbox** message (a push, or a direct `node msg`) and the **clock** (`node msg --self --at/--every` for a self-scheduled message, `node new --at/--every` for a deferred spawn, `node triggers list`/`cancel` to inspect or reap them). To monitor your own children you arm nothing — you auto-subscribe on spawn, so their finish/crash/close wakes you; a deadline to chase a delegate is a belt-and-suspenders the runtime makes redundant.
 
-Tear-down: `node close` cascade-cancels a node + its exclusive subtree WITHOUT finishing (revivable, nothing deleted); `node recycle` finishes the agent in your pane and reboots a fresh root in place; `canvas prune` deletes terminal nodes past a TTL.
+Tear-down: `node lifecycle close` cascade-cancels a node + its exclusive subtree WITHOUT finishing (revivable, nothing deleted); `node lifecycle recycle` finishes the agent in your pane and reboots a fresh root in place; `canvas prune` deletes terminal nodes past a TTL.
 
 ## 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
 ---