@north-light/crouter 0.3.163 → 0.3.165

package/dist/builtin-memory/advisor/council.md

@@ -0,0 +1,40 @@
+---
+kind: knowledge
+when-and-why-to-read: When convening an advisor council for a consequential judgment, this knowledge should be read because disciplined independent evidence prevents a confident consensus from concealing a correlated error.
+short-form: Run a bounded, evidence-first advisor council for consequential judgments.
+system-prompt-visibility: none
+file-read-visibility: none
+rationale: >-
+  Everyone's instinct for getting the right answer out of a council is to make the agents
+  debate until they agree — and that instinct is empirically backwards. Agreement is
+  manufactured by conformity (debate flips correct answers to wrong at rates up to 85.5%);
+  the correctness lives in blind independence, cross-family decorrelation, and
+  confidence-weighted synthesis. Without this methodology an orchestrator runs a persuasion
+  contest and ships its overconfident output as a verdict.
+---
+
+# Advisor Council Methodology
+
+Use a council only for a consequential judgment where the cost of being wrong justifies deliberation. An ordinary second opinion needs one advisor or a few un-orchestrated advisors.
+
+## First round
+
+Spawn three to five advisors in parallel. Keep their work blind: no member sees another's analysis. Assign each the same question under a distinct evidence frame, prior to steelman, or decomposition. Select members from the live model configuration; when distinct model families are available, span them to reduce correlated error rather than assuming any particular route.
+
+Ask every member for a recommendation, calibrated numeric confidence, strongest private reason, and key evidence. Members contribute read-only judgment; the council orchestrator is the only verdict writer.
+
+## Synthesis
+
+Synthesize as a chairman, not a vote. Weight recommendations by confidence and evidence quality, retain each original answer, and preserve a well-supported minority. Treat unanimity as a cue to check for correlation or false convergence, not as proof. Commit to the best-supported recommendation rather than averaging independent opinions into an under-confident compromise.
+
+Before finalizing, give one clean-context advisor a prospective-hindsight pre-mortem: the draft verdict was adopted and failed; explain why. Prefer a model family different from the members that dominated the draft. Incorporate confirmed concerns or report them as accepted risks.
+
+## Disagreement
+
+Open one targeted second round only when members disagree on a named, verifiable crux such as code, tests, documentation, or quotable evidence. Share only anonymized claim, reason, and evidence snippets about that crux; remove author, model, and conclusion labels. Have advisors verify and attack those claims directly. Stop after that round when positions stabilize.
+
+A crux about judgment, taste, or values does not earn a persuasion contest. Adjudicate it or surface it to the owner as a named tradeoff.
+
+## Verdict
+
+Deliver one conclusion-first verdict: recommendation and confidence, the strongest opposing case and why it lost, and any residual disagreement with its crux. Do not forward raw member output or dissolve disagreement into false consensus.

package/dist/builtin-memory/design.md

@@ -7,12 +7,9 @@ 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
+system-prompt-visibility: preview
 file-read-visibility: none
-gate:
-  kind:
-    imatches: '^design($|/)'
-needs-refinement: true
+gate: {kind: design}
 ---
 
 ## What a design deliverable is — and is not
@@ -25,11 +22,11 @@ The altitude ceiling: a design stops where implementation detail begins. A plann
 
 ## The design-artifact shape
 
-Write the design to `context/design-<subject>.md`. Structure it with these sections, in order:
+Write the design to `$CRTR_CONTEXT_DIR/design-<subject>.md`. Structure it with these sections, in order:
 
 **Context & constraints** — the problem being solved, the non-goals, the constraints that are not negotiable (existing systems, performance envelopes, team conventions). This is the frame everything else hangs on.
 
-**Architecture** — the high-level structure: what major components or layers exist, how they are arranged, what the topology looks like. Lead with a diagram (mermaid `graph TD`, 3–6 nodes) before prose. Keep it at the level a new engineer would use to orient themselves.
+**Architecture** — the high-level structure: what major components or layers exist, how they are arranged, what the topology looks like. Lead with a diagram (mermaid `graph TD`) before prose. Keep it at the level a new engineer would use to orient themselves.
 
 **Components & responsibilities** — for each component: one-sentence description of what it owns, a responsibilities table, and explicit boundaries (what it does NOT own). Every responsibility must land in exactly one component; gaps and overlaps here become integration bugs.
 
@@ -37,7 +34,7 @@ Write the design to `context/design-<subject>.md`. Structure it with these secti
 
 **Data model** — the key entities, their fields with semantic types ("session ID string", "ISO timestamp"), and their relationships. Tables are the right format. No TypeScript, no SQL — shape and semantics only.
 
-**Key flows** — the 2–4 end-to-end flows that matter most. Walk from trigger to final state, naming which component handles each step and what state changes. This is where seam problems surface; a step whose output doesn't match the next step's expected input is a design gap.
+**Key flows** — the end-to-end flows that matter most. Walk from trigger to final state, naming which component handles each step and what state changes. This is where seam problems surface; a step whose output doesn't match the next step's expected input is a design gap.
 
 **Decisions** — every non-obvious architectural choice, structured as: decision → choice made → alternatives rejected → rationale. If the decision is obvious, omit it. If it closes a real option, it belongs here. This section is what distinguishes a design from a description.
 
@@ -55,8 +52,8 @@ Write the design to `context/design-<subject>.md`. Structure it with these secti
 
 When a design is too large for one context window or covers genuinely independent surfaces, decompose it along clean seams — by component, by subsystem, or by interaction surface. Each sub-design is a bounded unit: it covers one component or subsystem end-to-end (its own context, architecture, interfaces, data model, flows, and decisions).
 
-Before delegating sub-designs, define the shared interface contracts between them explicitly. These contracts are the seams; they must be written down before sub-design begins so that parallel sub-designs don't invent incompatible assumptions. Capture these contracts in a `context/design-contracts.md` that all sub-design agents receive.
+Before delegating sub-designs, define the shared interface contracts between them explicitly. These contracts are the seams; they must be written down before sub-design begins so that parallel sub-designs don't invent incompatible assumptions. Capture these contracts in `$CRTR_CONTEXT_DIR/design-contracts.md` and give that absolute path to every sub-design agent.
 
-Each sub-design agent gets: the overall architecture diagram, the contracts doc, the scope of its piece, and any constraints from the parent design. It writes to `context/design-<component>.md`.
+Each sub-design agent gets: the overall architecture diagram, the contracts doc, the scope of its piece, and any constraints from the parent design. It writes `design-<component>.md` in its own context directory and reports the absolute path.
 
-After sub-designs land, integration is your job: read every sub-design, check that every contract is honored on both sides, that responsibilities don't overlap or gap, that the data models are consistent, and that the key flows compose correctly across component boundaries. Write the integrated design to `context/design-<subject>.md` synthesizing all sub-designs into one coherent artifact — don't just concatenate them. Reconcile any inconsistencies before declaring the design done.
+After sub-designs land, integration is your job: read every sub-design, check that every contract is honored on both sides, that responsibilities don't overlap or gap, that the data models are consistent, and that the key flows compose correctly across component boundaries. Write the integrated design to `$CRTR_CONTEXT_DIR/design-<subject>.md`, synthesizing all sub-designs into one coherent artifact — don't just concatenate them. Reconcile any inconsistencies before declaring the design done.

package/dist/builtin-memory/development.md

@@ -7,12 +7,9 @@ when-and-why-to-read: When shaping or reshaping a build roadmap — choosing a
 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
+system-prompt-visibility: preview
 file-read-visibility: none
-gate:
-  kind:
-    imatches: '^developer$'
-needs-refinement: true
+gate: {kind: developer}
 ---
 
 # Development Playbook
@@ -40,9 +37,9 @@ Pick one style as your primary frame before you write phases. Each fits a differ
 These are concrete phase skeletons. Adapt names and granularity; don't add phases that serve no exit criterion.
 
 ### New feature
-1. **Explore** — map the affected subsystems, identify entry points and constraints, produce `context/explore.md`.
-2. **Spec** — define the interface, behaviour, and acceptance criteria; output `context/spec.md`.
-3. **Plan** — decompose spec into file-level tasks with dependency order; output `context/plan.md`.
+1. **Explore** — map the affected subsystems, identify entry points and constraints, and report the absolute path to the exploration artifact.
+2. **Spec** — define the interface, behavior, and acceptance criteria, then report the absolute path to the spec.
+3. **Plan** — decompose the spec into file-level tasks with dependency order, then report the absolute path to the plan.
 4. **Vertical slice** — implement the thinnest end-to-end path; validate it works before widening.
 5. **Harden** — fill out the remaining logic, edge cases, error paths.
 6. **Review** — non-implementer critique pass on the whole surface.
@@ -65,7 +62,7 @@ These are concrete phase skeletons. Adapt names and granularity; don't add phase
 ### Greenfield
 1. **Explore/research** — understand the problem domain, constraints, and comparable systems.
 2. **Spec** — define the interface and top-level behaviour in enough detail to plan.
-3. **Architecture decision** — commit to the structural shape; record in `context/architecture.md`.
+3. **Architecture decision** — commit to the structural shape and report the absolute path to the architecture artifact.
 4. **Spike** (if technical unknowns exist) — validate the risky piece before building around it.
 5. **Bottom-up build** — primitives first, then composition; validate each layer before building on it.
 6. **Integration** — assemble layers; validate end-to-end.

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

@@ -1,7 +1,7 @@
 ---
 kind: knowledge
 when-and-why-to-read: When you hit a question about how the crtr runtime itself works or how to extend it — how nodes and the canvas behave, where state lives on disk, how to add plugins/commands/marketplaces to crtr, or how the primitives compose into real systems — this index should be read so runtime-sensitive work follows the canonical model instead of fragile inferences from scattered command help.
-short-form: internal/ is the runtime's self- and developer-documentation — operational guides to nodes/canvas and the storage tiers, plugin/marketplace/command-plugin authoring, plus worked example compositions. Open it to understand how crtr works or to extend it.
+short-form: internal/ is the runtime's self- and developer-documentation — operational guides to nodes/canvas and the storage tiers, plugin command and marketplace authoring, plus worked example compositions. Open it to understand how crtr works or to extend it.
 system-prompt-visibility: preview
 file-read-visibility: none
 ---
@@ -14,14 +14,14 @@ Open this dir whenever a task turns on understanding the runtime itself or chang
 
 - **nodes-and-canvas** — the agent-runtime model: nodes on the canvas graph, spawn/delegate, the push/feed spine, lifecycle (mode + lifecycle axes), and revive (manual + daemon auto-revive).
 - **storage-tiers** — where every kind of state lives: the two tiers (scope root and canvas home) and their durability/ownership contracts.
+- **memory-loading** — the memory load model: the two hooks (boot catalog, file-read), the four-rung ladder, gates, applies-to/read-when routing, boot-render ordering, and store mounting/precedence — read when diagnosing why a doc did or didn't load.
 - **agent-shaping** — the when-to-use-which layer over the four dials that shape a node: kinds (the builtin roster, sub-kinds, and custom personas), modes (base vs orchestrator), profiles, and the memory tiers (node/profile/project/user/builtin).
-- **workflow-codification** — the codification loop for repeatable tasks: do the work hands-on under a capture session, mine the HAR, then codify it as scripts (scope-root `scripts/`) + a slash-invokable memory doc, with the self-heal rule that a failed script is re-derived and rewritten.
-- **plugins** — authoring a crtr plugin: the plugin.json manifest, directory layout, scopes, install mechanics, versioning, command plugins (contributing top-level CLI commands via commands.json + one executable), and configured CLIs (contributing commands as definition + HTTP from a remote manifest, no executable).
-- **marketplaces** — authoring a crtr marketplace: the marketplace.json index, plugin entries, symlink-based install, auto-bump CI, dual-publishing.
+- **plugins** — authoring a crtr plugin: the plugin.json manifest, directory layout, scopes, install mechanics, versioning, and command-capable plugins (contributing top-level CLI commands through commands.json plus an exec or HTTP transport).
+- **marketplaces** — authoring a crtr marketplace: the marketplace.json index, local-link and remote-Git plugin sources, auto-bump CI, dual-publishing.
 - **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 that `-h` surface so it surfaces exactly when you write.
 
-Briefly: **plugins** (local command/doc packages), **marketplaces** (indexes that distribute plugins), and **configured CLIs** (remote-defined command surfaces fetched from a backend HTTP endpoint, stored locally, and rendered as native crtr commands — a simpler, non-executable alternative to command plugins for definition-only backends). All three discovery paths live on the **external-command** fallthrough, leaving the core fast-path untouched.
+Briefly: **plugins** package docs and commands, with command execution selected by `plugin.json.transport` (`exec` for a trusted local executable or `http` for a fetched remote REST manifest); **marketplaces** index and distribute plugins. Plugin commands enter the **external-command** fallthrough, leaving the core fast-path untouched.
 
 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/agent-shaping.md

@@ -38,25 +38,23 @@ A kind is a **persona** (gated memory docs at `kinds/<kind>/00-base.md` and `01-
 | **plan** | decompose an approved spec/design into concrete, phased, parallelizable steps with every decision resolved | you have a spec or design and need an executable breakdown a less-capable model can run without re-deciding. A plan 80% right costs more than no plan — pin every decision |
 | **developer** | implement a change and make it *genuinely work* against acceptance criteria, not merely compile | you're building the feature or fix. Green proves it ran, not that it's right — the persona carries the prove-it discipline and the build→review cycle |
 | **review** | critique code, a plan, or a spec once — deliver a complete, severity-rated verdict, **detect don't adjudicate** | substantive work needs one independent check. Use a *separate* node from the author — agents can't self-audit — and prime it neutrally ("review this", never "find what fails", which manufactures false positives) |
-| **product** | discover the real user need behind a request and define the product experience, grounded in comparable products; hands off to spec | the client is non-technical and the *what-and-why* must be found before any spec. **Speculative** — the product→spec baton has not yet run end to end |
-| **personal-assistant** | Silas's standing personal assistant — resident on the canvas, wakes on his iMessage thread, remembers across conversations | only for that standing assistant role (resident lifecycle), not general work |
 
-The discriminators that get missed: **explore vs advisor** (mapping vs judgment — cheap vs expensive tier); **spec vs design** (what to build vs how to build it); **design vs plan** (decide the shape vs sequence a decided shape); **review is always a separate node from the implementer**. Two current truths about the roster itself: **product is speculative** (earns its slot on principle, never run end to end), and **developer is the kind closest to "general with a mood"** — the first merge candidate if the roster ever shrinks.
+The discriminators that get missed: **explore vs advisor** (mapping vs judgment — cheap vs expensive tier); **spec vs design** (what to build vs how to build it); **design vs plan** (decide the shape vs sequence a decided shape); **review is always a separate node from the implementer**. **Developer is the kind closest to "general with a mood"** — the first merge candidate if the roster ever shrinks.
 
 ### Sub-kinds
 
-Specialist sub-personas hang off a parent kind — `plan/reviewers/*` (architecture-fit, code-smells, pattern-consistency, requirements-coverage, security), `product/teardown`, `spec/requirements`. They aren't in the top-level `--kind` list but are valid by exact path (`crtr node new --kind plan/reviewers/security`). Use a sub-persona for one narrowly targeted assignment, not as a mandatory lens roster; discover the available roles with `crtr sys prompt-review --list --kind <kind>`.
+Specialist sub-personas hang off a parent kind — `plan/reviewers/*` (architecture-fit, code-smells, pattern-consistency, requirements-coverage, security) and `spec/requirements`. They aren't in the top-level `--kind` list but are valid by exact path (`crtr node new --kind plan/reviewers/security`). Use a sub-persona for one narrowly targeted assignment, not as a mandatory lens roster; discover the available roles with `crtr sys prompt-review --list --kind <kind>`.
 
 ### Custom personas
 
-The roster is extensible. Add a `kinds.<name>` entry to a `config.json` at user or project scope (fields: `whenToUse` required, plus optional `model`, `orchestratorModel`, `tools`, `extensions`, `availableTo`) and author the persona prose at `kinds/<name>/00-base.md` (and `01-orchestrator.md`) gated `{kind: <name>, mode: ...}`. The registry merges **project > user > builtin**, so a custom kind can add a new role or shadow a builtin one without restating the rest. Reach for a custom kind when a **recurring role** wants its own standing discipline and model/tool defaults that outlast any single task — not for a one-off instruction, which belongs in the spawn prompt.
+The roster is extensible. Add a `kinds.<name>` entry to a `config.json` at user or project scope (fields: `whenToUse` required, plus optional `model`, `orchestratorModel`, `tools`, `extensions`, `availableTo`) and author the persona prose at `kinds/<name>/00-base.md` (and `01-orchestrator.md`) gated `{kind: <name>, mode: ...}`. A standing personal assistant, for example, is a scope-configured custom `personal-assistant` kind rather than a builtin kind. The registry merges **project > user > builtin**, so a custom kind can add a new role or shadow a builtin one without restating the rest. Reach for a custom kind when a **recurring role** wants its own standing discipline and model/tool defaults that outlast any single task — not for a one-off instruction, which belongs in the spawn prompt.
 
 ## Modes — base vs orchestrator
 
 Every kind has both a `base` and an `orchestrator` persona; mode picks which one splices in.
 
-- **base** — hands-on. Do the work yourself and finish it with `crtr push final`. Your scarce resource is the task. Spawn a child only for a cleanly separable unit, never as your first move. When an unsplittable task needs another context window, `crtr node yield` and continue hands-on as base.
-- **orchestrator** — you own a goal too large for one window. Decompose it, delegate each piece, integrate what comes back, hold a `context/roadmap.md` that survives refreshes, and yield (`crtr node yield`) into a clean window when context fills. Your scarce resource is your own context window; the moment you start grinding the goal out by hand you've lost the plot. The shared loop lives in the `orchestration-kernel` doc (auto-gated for orchestrators).
+- **base** — hands-on. Do the work yourself and deliver its artifact path. Your scarce resource is the task. Spawn a child only for a cleanly separable unit, never as your first move. When an unsplittable task needs another context window, `crtr node yield` and continue hands-on as base.
+- **orchestrator** — you own a goal too large for one window. Decompose it, delegate each piece, integrate what comes back, hold a `$CRTR_CONTEXT_DIR/roadmap.md` that survives refreshes, and yield (`crtr node yield`) into a clean window when context fills. Your scarce resource is your own context window; the moment you start grinding the goal out by hand you've lost the plot. The shared loop lives in the `orchestration-kernel` doc (auto-gated for orchestrators).
 
 **When to reach for orchestrator over base.** When the *shape* of the job needs decomposition across children — many phases visible up front, or a base task that keeps getting extended into independently delegable work. Promote *early* (`crtr node promote`), the moment you recognize that shape, not after the window wears down; or spawn the child directly as a sub-orchestrator (`crtr node new --mode orchestrator`) rather than hoping a base worker promotes itself, which is unreliable. An unsplittable task that merely needs another context window stays base: `crtr node yield` and continue hands-on.
 

package/dist/builtin-memory/internal/examples/imessage-assistant.md

@@ -21,7 +21,7 @@ A standing assistant that lives on the canvas, sleeps for free, wakes when a tex
 | Sends replies | `osascript` → Messages.app |
 | Memory | Project-scope substrate (`~/assistants/imessage/.crouter/memory/`) for durable knowledge; context dir for the cursor |
 | Identity/behavior | A custom persona kind |
-| Crash recovery | The daemon auto-revives dead nodes; the watcher's `node message send` also revives a dormant target on its own |
+| Crash recovery | The daemon makes bounded recovery attempts for interrupted live exits; after terminalization, use `node lifecycle revive` or let the watcher's `node message send` wake the resident target |
 
 ## 1. Persona
 
@@ -40,7 +40,7 @@ EOF
 
 ## 3. Wake: event-driven, not polled
 
-A trivial launchd agent watches the Messages write-ahead log and pokes the node's inbox. `node message send` revives a dormant target by itself, so the watcher is the *only* off-canvas piece.
+A trivial launchd agent watches the Messages write-ahead log and pokes the node's inbox. `node message send` wakes the resident target by itself, including after a recoverable disconnection, so the watcher is the *only* off-canvas piece.
 
 ```xml
 <!-- ~/Library/LaunchAgents/com.user.imessage-watch.plist (key parts) -->
@@ -56,7 +56,7 @@ Multiple bursts while the node is mid-turn just append to its inbox and coalesce
 ## 4. Reading chat.db (the verified gotchas)
 
 - The process querying needs **Full Disk Access** (the node's shell inherits the terminal/launchd grant). Read-only — never write to chat.db.
-- Cursor on `message.ROWID`, persisted in the node's context dir (e.g. `context/cursor`); filter `is_from_me = 0`.
+- Cursor on `message.ROWID`, persisted in the node's context dir (e.g. `$CRTR_CONTEXT_DIR/cursor`); filter `is_from_me = 0`.
 - **On modern macOS `message.text` is often NULL** — the body lives in the `attributedBody` blob (NSAttributedString archive). Extract with:
 
 ```python

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

@@ -8,7 +8,6 @@ short-form: How to author a crtr marketplace — marketplace.json index, plugin
   creating a marketplace or contributing plugins to one.
 system-prompt-visibility: name
 file-read-visibility: none
-needs-refinement: true
 ---
 
 # Authoring crtr marketplaces
@@ -42,7 +41,7 @@ If you have one plugin, ship it standalone. Promote to a marketplace later.
         └── ...
 ```
 
-Each entry under `plugins/` is a complete plugin (see [[internal/plugins]]). The marketplace adds an index on top.
+A marketplace can keep a plugin under `plugins/` or index a plugin from another Git repository. Local entries are complete plugins (see [[internal/plugins]]); the marketplace adds an index over either source.
 
 ## The manifest
 
@@ -72,16 +71,16 @@ Each entry under `plugins/` is a complete plugin (see [[internal/plugins]]). The
 | `owner` | optional | |
 | `plugins` | yes | Array. Each entry: `name`, `version`, `source`, `description`. |
 
-The `plugins[]` array IS the index — what's installable. A plugin on disk but not in the index won't resolve. A plugin in the index but missing from disk errors on install.
+The `plugins[]` array IS the index — what's installable. Each entry's `source` is either a marketplace-relative path to a plugin directory or a remote Git URL. A local plugin on disk but not in the index won't resolve; an indexed local path missing from the marketplace errors on install.
 
-## Install mechanics — symlinks, not clones
+## Install mechanics — local links and remote clones
 
-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`.
+When a user runs `crtr pkg plugin install my-marketplace/plugin-a`, crouter looks up `plugin-a` in the marketplace manifest and records the install with `source_marketplace: my-marketplace`.
 
-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.
+- A marketplace-relative `source` is symlinked from the marketplace checkout into the target scope, so `crtr pkg market update --name my-marketplace` updates its content through that checkout.
+- A remote Git `source` is cloned into the target scope. Marketplace update refreshes the index; the installed plugin's own checkout is pulled during that update (or `crtr pkg plugin update`).
+
+No per-plugin re-install is needed for content updates while the indexed source remains unchanged. Changing a remote entry's `source` requires removing and reinstalling that marketplace plugin so its checkout uses the new remote.
 
 ## Version-bump automation (recommended)
 
@@ -133,11 +132,11 @@ Existing users pick it up on their next `crtr pkg market update --name <marketpl
 
 ## Updating an existing plugin
 
-Edit content under `plugins/<name>/`. Commit with a conventional-commit subject. CI bumps the plugin manifest and the marketplace index entry together. No manual sync.
+For a local plugin, edit `plugins/<name>/` and commit the plugin plus marketplace index together. For a remote Git source, update the plugin in its own repository, then update the marketplace entry's version as needed. If its `source` changes, users remove and reinstall the marketplace plugin to clone the replacement remote. Commit with a conventional-commit subject; CI can bump the marketplace index alongside local plugin changes.
 
 ## Removing a plugin
 
-Delete the plugin's directory AND its entry in `marketplace.json` → `plugins[]`. Commit with `feat!: remove <plugin>` to signal a major bump (the marketplace's contract changed for anyone depending on that plugin).
+Delete the entry in `marketplace.json` → `plugins[]`; also delete its directory when it is a local source. Commit with `feat!: remove <plugin>` to signal a major bump (the marketplace's contract changed for anyone depending on that plugin).
 
 ## Marketplace registration scopes
 
@@ -154,10 +153,10 @@ A marketplace itself registers per-scope:
 
 `crtr sys doctor` checks marketplaces:
 - `marketplace.json` is valid JSON.
-- Every entry in `plugins[]` corresponds to a real directory under `plugins/`.
-- Each plugin under `plugins/` passes plugin-level validation.
+- Every marketplace-relative entry in `plugins[]` resolves to a real local plugin directory. Remote-source validation occurs when crouter installs that plugin.
+- Each installed plugin passes plugin-level validation.
 
-A plugin on disk but missing from the manifest is a **warning** (probably forgotten); a plugin in the manifest but missing on disk is an **error** (install would break).
+A local plugin on disk but missing from the manifest is a **warning** (probably forgotten); an indexed local path missing on disk is an **error** (install would break).
 
 ## Cross-publishing with Claude Code
 

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

@@ -0,0 +1,45 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need to know why a memory doc did or didn't load — or are deciding how a new doc should surface — this reference should be read because it names the hook, rung, gate, and ordering that produced the behavior, so you fix loading by turning the right dial instead of guessing at frontmatter.
+short-form: The complete load model — two hooks (boot catalog, file-read), the four-rung ladder, gates, applies-to/read-when routing, boot-render ordering, and store mounting/precedence.
+system-prompt-visibility: name
+file-read-visibility: none
+---
+
+# How memory loads
+
+Every memory doc declares its own loading policy in frontmatter; the runtime never guesses. Loading is two hooks, one four-rung dial per hook, an optional gate, and structural ordering. The authoring contract (flags, routing-line craft) is `crtr memory write -h`; which scope to write to is `internal/agent-shaping`; physical paths are `internal/storage-tiers`. This doc is the mechanics between those: what actually fires, when, and in what order.
+
+## The two hooks
+
+- **System prompt** (`system-prompt-visibility`) — the boot catalog assembled into every node's system prompt at revive.
+- **File read** (`file-read-visibility`) — context attached to the workspace or to files. Two events: **workspace mount** during first-message assembly (docs routed `applies-to: "."`), and a later **matching file read** (docs routed by glob). Nothing positional fires from where the doc happens to sit on disk — only from its declared route.
+
+Each doc sets both rungs explicitly; there is no kind-based default. Usually one axis carries a real rung and the other is `none`.
+
+## The rung ladder
+
+`none` → `name` → `preview` → `content`, per hook:
+
+- `none` — invisible on that hook; findable only by search/read. For archival docs and for the unused axis.
+- `name` — the bare title. The practical floor: an agent can't reach for a doc it has never seen named.
+- `preview` — name + the `when-and-why-to-read` routing line, rendered verbatim. The heart of progressive disclosure: one sentence that lets an agent decide whether to spend the read.
+- `content` — the full body inlined. Reserved for always-relevant docs that are either a bullet's worth of text or a wholly-important operating guide (the root INDEX shape below).
+
+`short-form` is **not** a rung and never enters agent context — it exists for humans browsing `crtr memory list`. Disclosure is name → routing line → whole thing; there is deliberately no "just the summary" level, because agents satisfice on abbreviations and never read the rest.
+
+## Gates and read-when
+
+An optional `gate` predicates visibility on the node's own config — kind, mode, orchestration depth, scope, cwd — using the standard matcher vocabulary (`crtr memory write -h`). No gate means always eligible. Persona prose is just gated content-rung docs (`gate: {kind: developer, mode: base}`); guidance that should scale with effort is one predicate (`orchestration.depth: {gte: 2}`), not a mechanism. `read-when` additionally matches the *read file's* frontmatter on the file-read hook; it refines a route but never replaces the required `applies-to` boundary.
+
+## Store mounting and precedence
+
+At boot/first-message assembly the runtime mounts: builtin docs, the user store (`~/.crouter/memory/`), the selected profile's store, and every project store — ancestor `.crouter/memory/` dirs walking up from cwd plus each project in the profile's purview. Physical duplicates are deduplicated; name collisions resolve nearest-first (project over profile over user over builtin), which is what lets a project doc shadow a builtin one.
+
+A root `INDEX.md` is a workspace's front door: `system-prompt-visibility: none`, `file-read-visibility: content`, `applies-to: "."` — the operating guide loads when that workspace mounts, not in every boot catalog. Multiple mounted roots render broad-to-specific, each under its own envelope name.
+
+## Ordering
+
+The boot render is structural, never a per-doc knob: docs group by rung (content bodies as prose, then previews, then names), and within a group order general-to-specific — scope first (builtin → user → profile → outermost project root → nearest), then tree position (higher directories before deeper), then filename. A numeric `NN-` filename prefix (stripped from the doc's name) is the sparing escape hatch when an exact sequence must be pinned.
+
+`crtr memory lint` is the validator for all of the above: frontmatter schema, both rungs present, routes on every non-`none` file-read rung, rung-scaled body length, dangling `[[links]]`, and each profile-managed project's front door.

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

@@ -14,10 +14,10 @@ The **daemon** (`crtrd`) is the sole owner of canvas persistent state: it is the
 
 ## Spawn & delegate
 
-`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.
+`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. A base node works hands-on and only spawns a child for a cleanly separable unit. An orchestrator delegates its decomposed work by default: a child's reading and tokens land in a fresh context window while the coordinator keeps only the conclusions needed to steer.
 
 - 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.
+- An orchestrator fans **independent** units out concurrently. 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.
 
@@ -46,6 +46,6 @@ Tear-down: `node lifecycle close` cascade-cancels a node + its exclusive subtree
 
 ## Revive & the daemon
 
-A dormant node (done/idle/dead/canceled) is reopened with `node lifecycle revive <id>` (resumes the saved conversation, or `--fresh` to restart clean); mass-reconnecting EVERY disconnected node at once (a reboot/crash recovery) is `canvas revive --all` instead. `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 `surface node focus` / `node lifecycle revive`.
+Use `node lifecycle revive <id>` to reopen one dormant or terminal node. It resumes an existing saved conversation by default; `--fresh` starts a new cycle on its existing session file, or a truly fresh session if no file exists. A finalized node requires `--reopen` before it can take a new mandate. Mass-reconnecting every eligible disconnected node after a reboot or outage is `canvas revive --all` instead. `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 `surface node focus` / `node lifecycle revive`.
 
-The daemon (`crtrd`, managed via `sys daemon start/stop/status`) is also the supervisor: alongside owning the store and serving the API, 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 `node lifecycle revive` for those). When activating source changes, build, run `npm run install-runtime`, then restart the daemon because new daemon/brokers select the atomically switched, immutable generation while live brokers retain their own. Restarting is safe: it never signals running nodes.
+The daemon (`crtrd`, managed via `sys daemon start/stop/status`) supervises live broker exits. It applies a bounded respawn policy to interrupted nonterminal nodes: a cleanly aborted saved turn resumes with a continuation, while a dirty interrupted turn, pending refresh, or pending cycle starts a fresh cycle from the saved session. Repeated short-lived exits and boot failures terminalize the node as `dead`; no automatic recovery occurs after terminalization, so use an explicit lifecycle revive or an inbox wake. It does not host agents or open viewers. When activating source changes, build, run `npm run install-runtime`, then restart the daemon because new daemon/brokers select the atomically switched, immutable generation while live brokers retain their own. Restarting is safe: it never signals running nodes.