@north-light/crouter 0.3.154

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

@@ -0,0 +1,164 @@
+---
+kind: knowledge
+when-and-why-to-read: When creating a crtr marketplace or contributing plugins
+  to one, this knowledge should be read so indexed plugins install and update
+  coherently without release automation desynchronizing their versions.
+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.
+system-prompt-visibility: name
+file-read-visibility: none
+needs-refinement: true
+---
+
+# Authoring crtr marketplaces
+
+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 install <url> --scope user` — no marketplace needed.
+
+Reach for a marketplace when:
+- You want to publish ≥3 plugins under one brand or theme.
+- Users should install selectively without cloning each plugin's repo.
+- You want centralized version-bump automation across many plugins.
+
+If you have one plugin, ship it standalone. Promote to a marketplace later.
+
+## Directory layout
+
+```
+<marketplace-repo>/
+├── .crouter-marketplace/
+│   └── marketplace.json              # marketplace manifest — required
+└── plugins/
+    ├── plugin-a/
+    │   ├── .crouter-plugin/plugin.json
+    │   └── memory/...
+    └── plugin-b/
+        └── ...
+```
+
+Each entry under `plugins/` is a complete plugin (see [[internal/plugins]]). The marketplace adds an index on top.
+
+## The manifest
+
+`.crouter-marketplace/marketplace.json`:
+
+```json
+{
+  "name": "my-marketplace",
+  "version": "0.3.0",
+  "owner": { "name": "Your Name", "email": "you@example.com" },
+  "plugins": [
+    {
+      "name": "plugin-a",
+      "version": "0.2.1",
+      "source": "https://github.com/<owner>/<repo>",
+      "description": "One sentence."
+    },
+    { "name": "plugin-b", "version": "0.1.0", "source": "…", "description": "…" }
+  ]
+}
+```
+
+| Field | Required | Notes |
+|---|---|---|
+| `name` | yes | Lowercase kebab. |
+| `version` | yes | Semver. Bumps when any plugin bumps or when the marketplace manifest itself changes. |
+| `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.
+
+## Install mechanics — symlinks, not 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`.
+
+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)
+
+Bumping N plugin manifests + the index by hand is error-prone. The canonical pattern is a GitHub Actions workflow that bumps versions from commit subjects (conventional commits):
+
+| Commit subject | Bump |
+|---|---|
+| `feat!: …` or `BREAKING CHANGE` in body | major |
+| `feat: …` | minor |
+| anything else (`fix:`, `chore:`, `docs:`, …) | patch |
+
+Per commit:
+- For each plugin folder touched, both `plugins/<name>/.crouter-plugin/plugin.json` and the matching entry in `marketplace.json` get bumped.
+- Top-level `marketplace.json` version bumps when any plugin bumps OR the manifest itself was edited directly.
+- Newly-added plugins are skipped — they keep the version you committed.
+- Commits whose subject starts with `chore: release` are skipped to avoid loops.
+
+If you adopt this: **never edit `version` fields by hand**. CI will overwrite. Document this in the marketplace's CLAUDE.md.
+
+The crouter-official-marketplace repo's `.github/workflows/auto-bump.yml` is the reference implementation. Copy it.
+
+## Adding a plugin to a marketplace
+
+```bash
+cd <marketplace-repo>
+
+# Create the plugin (see [[internal/plugins]] for plugin layout)
+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-doc.md
+
+# Add the plugin to the marketplace index
+$EDITOR .crouter-marketplace/marketplace.json
+# (append to plugins[] with name, initial version, source, description)
+
+# Validate
+crtr sys doctor                                    # manifest + structure
+crtr memory lint                                   # doc frontmatter
+
+# Commit — CI bumps versions if you've wired up auto-bump
+git add -A
+git commit -m "feat: add my-new-plugin"
+git push
+```
+
+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
+
+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.
+
+## 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).
+
+## Marketplace registration scopes
+
+A marketplace itself registers per-scope:
+
+| Scope | Path | Use case |
+|---|---|---|
+| 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 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
+
+`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.
+
+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).
+
+## Cross-publishing with Claude Code
+
+Some marketplaces ship a parallel `.claude-plugin/` tree so plugins can load directly into Claude Code without crtr. Optional. Sync the two manifests if you adopt it.

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

@@ -0,0 +1,51 @@
+---
+kind: knowledge
+when-and-why-to-read: When you are operating the canvas — spawning or steering nodes, deciding how work reports up, recovering a dormant or crashed node, or reasoning about the daemon — this reference should be read so lifecycle and reporting operations preserve one live engine, deliver results reliably, and recover nodes without corrupting state.
+short-form: Operational model of the agent runtime — nodes on the canvas graph, spawn/delegate, the push/feed spine, lifecycle states, and revive (manual + daemon auto-revive).
+system-prompt-visibility: name
+file-read-visibility: none
+---
+
+# How nodes and the canvas work (operational)
+
+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.
+
+The **daemon** (`crtrd`) is the sole owner of canvas persistent state: it is the only process that opens `canvas.db`, launches brokers, and writes runtime/model-auth, all behind an HTTP+WS API on a unix socket (dockerd model). Every `crtr` command, the web server, and the viewers are pure clients of that `/v1` API — they never open the store. A local interactive viewer still streams a node's broker socket (`view.sock`) directly, because that is broker IPC, not canvas state.
+
+## 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.
+
+- 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: `surface node focus` (put an attach viewer for a node in your pane), `surface attach` (connect to a node's existing broker), `surface node cycle` (DFS-walk neighbors), `surface node id` (copy the current node id), `node message send` (direct-message any node at a wake tier, reviving a dormant target), `node subscription add`/`node subscription remove` (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
+
+Nothing is reported automatically — the feed contains only what a node **pushes**.
+
+- `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 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** — dereference the refs that matter rather than trying to re-read it. An empty feed while workers run is normal — a worker that hasn't pushed yet leaves no pointer; the wake it fires when it does push is automatic, so there's nothing to poll or check in the meantime.
+
+## Lifecycle
+
+Two orthogonal axes:
+
+- **mode**: base (a hands-on worker — finishes its own job, yielding mode-preservingly when an unsplittable task needs another window) ↔ orchestrator (`node promote` — a long-lived, roadmap-holding coordinator that delegates phases and survives context refresh via `node yield`). Promote only when what remains needs decomposition across children, not merely another window.
+- **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 wakes from an **inbox** message (a push, or `node message send`) or from a scheduled **cron** whose bash command performs the action (`node message send`, `node lifecycle revive`, or `node new`). A cron can gate its action on an external condition such as CI or a deploy; inspect or reap schedules with `cron list`/`cron cancel`. 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 terminal node blocked on a one-off message from a parent or controller it holds no live subscription to declares that wait with `node wait controller` before going dormant, so the next inbox delivery from that sender clears the wait rather than the runtime treating the idle as finished. Use `node wait deadline` only for the atomic inbox-versus-deadline race.
+
+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 `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`.
+
+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.

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

@@ -0,0 +1,249 @@
+---
+kind: knowledge
+when-and-why-to-read: When creating a crtr plugin, packaging memory docs for
+  distribution, adding top-level CLI commands via a command manifest, or
+  debugging install/resolution, this knowledge should be read so installs resolve
+  predictably across scopes and command surfaces do not fail from manifest drift or protocol mistakes.
+short-form: How to author a crtr plugin — plugin.json manifest, directory
+  layout, scopes, install mechanics, versioning, and command plugins (top-level
+  CLI commands via commands.json + one executable). Use when creating a plugin,
+  packaging memory docs, contributing commands, or debugging install/resolution.
+system-prompt-visibility: name
+file-read-visibility: none
+---
+
+# Authoring crtr plugins
+
+A **plugin** is a directory shipping substrate docs (knowledge and preferences) and other artifact types like `rules/` and `agents/`. Plugins are how you package that content for sharing across machines, projects, and people.
+
+Audience: LLM agents creating or maintaining a crtr plugin.
+
+## 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 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 [[internal/marketplaces]].
+
+If it's a one-off note for yourself, scope-owned memory docs are simpler. Promote to a plugin later.
+
+## Directory layout
+
+```
+<plugin-name>/
+├── .crouter-plugin/
+│   └── plugin.json                  # manifest — required
+└── memory/
+    ├── <name>.md                    # a kind:knowledge or kind:preference doc
+    └── <area>/
+        ├── INDEX.md                 # optional — a dir surfaces as one entry at its INDEX rung
+        └── <name>.md
+```
+
+The `<plugin-name>` directory IS the plugin. The manifest's `name` field must match the directory name (install renames if needed). Sibling dirs (`rules/`, `agents/`, and future `hooks/`) hold the other artifact types. A plugin that contributes CLI commands adds a `commands.json` manifest plus its executable — see [Command plugins](#command-plugins).
+
+## The manifest
+
+`.crouter-plugin/plugin.json`:
+
+```json
+{
+  "name": "my-plugin",
+  "version": "0.1.0",
+  "description": "One sentence — shown in `crtr pkg plugin list`.",
+  "source": "https://github.com/<owner>/<repo>",
+  "owner": {
+    "name": "Your Name",
+    "email": "you@example.com"
+  }
+}
+```
+
+| Field | Required | Notes |
+|---|---|---|
+| `name` | yes | Must match the directory name. Lowercase kebab. |
+| `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 update --name <name>`. |
+| `owner` | optional | Author info. |
+| `commands` | optional | Plugin-root-relative path to a `commands.json` command manifest. Present ⇒ the plugin contributes top-level `crtr` commands — see [Command plugins](#command-plugins). |
+
+## Scopes
+
+A plugin can live in either scope:
+
+| Scope | Path | Use case |
+|---|---|---|
+| user | `~/.crouter/plugins/<name>/` | Personal, available in all your projects |
+| project | `<project>/.crouter/plugins/<name>/` | Pinned to a specific repo — checked in or vendored |
+
+Project-scope plugins outrank user-scope on resolution. Both outrank marketplace-installed plugins. The builtin `crtr` plugin (ships with the CLI) sits at the bottom.
+
+## Install mechanics
+
+Three ways a plugin lands in a scope:
+
+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 update --name <name>` does `git pull`.
+   - Independent of any marketplace.
+
+2. **From a marketplace** (`crtr pkg plugin install <mkt>/<name>`):
+   - **Symlinks** the marketplace's `plugins/<name>/` into `<scope>/plugins/<name>/`.
+   - `crtr pkg market update --name <mkt>` pulls updates for every installed plugin from that marketplace.
+   - See [[internal/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 install file://$(pwd) --scope project` to clone-install.
+
+## Local development loop
+
+```bash
+# Scaffold dir + manifest + first doc
+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-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 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 install <url> --scope user`.
+
+## Versioning
+
+Standard semver:
+
+| Change | Bump |
+|---|---|
+| Typo, wording polish | patch (0.1.0 → 0.1.1) |
+| 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 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 [[internal/marketplaces]].
+
+## Enable/disable
+
+`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 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 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 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 memory doc conceptually depends on another plugin's doc, link via `## Related` with `` `<plugin>/<doc>` ``. Don't fork content; link it.
+
+## Command plugins
+
+Beyond docs, a plugin may contribute **top-level `crtr` commands** — new noun branches with their own leaves. You declare one pointer in the manifest and ship one executable; crtr owns parsing, help, rendering, and errors, and direct-spawns your executable once per leaf invocation.
+
+### The manifest pointer
+
+Add `commands` to `plugin.json` — a plugin-root-relative path to one static manifest:
+
+```json
+{ "name": "deploy-tools", "version": "0.1.0", "description": "...", "commands": "commands.json" }
+```
+
+Only an installed, **enabled** plugin's `commands` manifest contributes. Discovery is per-invocation: enable/disable/update/remove takes effect on the very next `crtr` call — no daemon restart, no cache to clear.
+
+### commands.json shape
+
+```json
+{
+  "schemaVersion": 1,
+  "executable": "bin/cmd.js",
+  "mounts": [
+    { "parent": [], "node": { "kind": "branch", "name": "app", "...": "..." } }
+  ]
+}
+```
+
+- `schemaVersion` — exactly the integer `1`. Anything else rejects the whole manifest.
+- `executable` — plugin-root-relative path to the one command binary. Must resolve inside the plugin root, be a regular file, and carry the POSIX exec bit.
+- `mounts[]` — each `{ parent: [], node }`. v1 supports **top-level mounts only**: `parent` must be `[]`.
+
+Every top-level `node` is a **branch** (`kind: "branch"`) carrying a `rootEntry { concept, description, whenToUse }` — the representation crtr renders at root help. Branch children are nested branches (no rootEntry) or leaves. A leaf declares `params`, `output` (array of `{ name, type, required, constraint }`), `outputKind: "object"`, and a non-empty `effects` array. Params use crtr's public vocabulary — one positional max, long-form `flag`s (types `string|int|bool|path|enum`, `choices` for enum), `stdin`, `context-file`; kebab-case names, no aliases. Two client-side affordances ride on a `positional` or `flag`: `encoding: "text"|"base64"` on a `type: "path"` param sends the named local FILE's content instead of the path string, and `defaultFromEnv: "UPPER_SNAKE"` fills an omitted `string`/`path` param from that environment variable on the calling machine, counting as supplied (so it satisfies `required` and is sent) — unlike a static `default`, which is a parse convenience only and never ships. `defaultFromEnv` is rejected alongside `default` or `repeatable`. The declaration mirrors crtr's stable help descriptors, not its internal TypeScript defs — no closures, no dynamic state, no renderers.
+
+### Execution: the trust boundary
+
+On explicit leaf invocation — **never on install, help, or discovery** — crtr direct-spawns your executable (no shell) with `--crtr-command-protocol 1`, the caller's cwd, and the full environment. Installed command plugins are **trusted local code running with the caller's authority**: crtr does not sandbox them, filter the environment, mint a credential, or interpret your backend's auth. Your executable owns authentication to its own backend. This is an execution trust boundary, not a sandbox — installed code can already read the caller's files, so env filtering would only imply a security guarantee that does not exist.
+
+### The protocol
+
+crtr writes exactly one JSON request to your executable's stdin:
+
+```json
+{
+  "protocolVersion": 1,
+  "command": ["app", "show"],
+  "input": { "appId": "app_123" },
+  "context": { "cwd": "/caller/cwd", "plugin": { "name": "deploy-tools", "version": "0.1.0", "scope": "project", "root": "/plugin/root" } }
+}
+```
+
+`input` keys are the parser's camelCase form; a declared `stdin` param arrives as an `input` string, not a second stream. Your executable writes exactly one JSON envelope to stdout and nothing else — diagnostics go to stderr:
+
+```json
+{ "protocolVersion": 1, "ok": true, "result": { "app_id": "app_123" } }
+{ "protocolVersion": 1, "ok": false, "error": { "code": "authentication_required", "message": "...", "field": "session", "next": "..." } }
+```
+
+`ok` is the source of truth (a valid envelope is honored regardless of exit code). crtr validates `result` against your declared `output` (top-level field presence + type) and renders it; `--json` mirrors the same object. An error envelope becomes a normal crtr error with your `code` — lowercase snake_case, never crtr-reserved `internal`, `unknown_path`, `command_collision`, or `plugin_protocol_error`. No envelope at all (invalid JSON, empty, extra stdout, output over 10 MiB, signal kill) becomes `plugin_protocol_error`.
+
+### Two rules that prevent silent breakage
+
+- **Generate `commands.json` from your command definitions — never hand-write it.** The manifest must stay in lockstep with the executable's actual command surface; a hand-maintained copy drifts, and a drifted param or output field surfaces as a validation issue or a `plugin_protocol_error` at invocation. Emit it from the same source your executable dispatches on.
+- **A required output field must be non-null.** The adapter treats an explicit `null` for a declared-required field as *absent* → `plugin_protocol_error`. If a value is genuinely optional, declare it `required: false`; if it's required, always return a real value.
+
+### Validating your command manifest
+
+crtr validates command manifests **statically — it never executes your binary** to check them:
+
+- `crtr pkg plugin show <name>` — inventories the manifest path, executable, accepted top-level command names, and every current validation issue (each with received/expected/next).
+- `crtr sys doctor` — validates the manifest + executable path for every effective command plugin and reports structured remediation (disable/update/remove). `--fix` never chmods or rewrites plugin content.
+- `crtr pkg plugin install` / `update` — report the accepted top-level commands and any issues in their result.
+
+A fixed manifest goes live on the next invocation; there is nothing to restart.
+
+## Configured CLIs
+
+A **configured CLI** is the other way a contributor adds `crtr` commands — the CLI analogue of an MCP client. Where a command plugin ships a local **executable**, a configured CLI is **definition + HTTP only**: crtr fetches a manifest from a remote endpoint, stores it locally, renders native `-h` help from it, and runs each leaf as a declarative REST call. There is no local binary to spawn and nothing to sandbox — a strictly narrower trust surface than a command plugin.
+
+The manifest **is** the command-plugin `commands.json` schema (same `schemaVersion 1`, same node/param/output vocabulary, same reject-unknown-keys strictness), differing in exactly three ways: it drops `executable`, allows non-empty mount `parent` paths (a CLI builds a self-contained forest and may mount at depth), and every leaf carries a `rest` mapping (method/path/param placement/streaming flag) instead of `outputKind`. The `rest` mapping is transport — it never appears in generated `-h`, so a configured command is indistinguishable from a native one.
+
+Manage them under `crtr pkg cli` — `register` (records `{name, endpoint, auth-env NAME}` in scope config and fetches+stores the manifest), `remove`, `list`, `show`, `refresh`. crtr stores only the env var **name** holding the bearer token, never the credential. The stored manifest is authoritative with **zero freshness machinery** (no TTL, ETag, or revalidation): it reloads only on a re-register (the guest-boot path — a byte-identical re-register still re-fetches) or an explicit `refresh`, and a registration with no stored manifest (its register-time fetch failed) triggers a one-time hydration fetch on an unknown-first-token miss, the sole moment an absent store is detected. Inspect a CLI's accepted commands and validation/collision issues with `crtr pkg cli show <name>` and `crtr sys doctor`; both read the same unified snapshot dispatch uses. A configured CLI may never mount onto a core, plugin, or other-CLI path — core always wins, cross-contributor path clashes drop all claimants with a `command_collision` issue.
+
+## Validation
+
+`crtr sys doctor` checks each plugin's manifest:
+- Manifest exists and is valid JSON.
+- Manifest `name` matches the directory name.
+- When the plugin declares `commands`, its command manifest + executable path are validated statically (never executed) — see [Command plugins](#command-plugins).
+
+`crtr memory lint` checks the docs under `memory/`: frontmatter parses, valid `kind`, both visibility rungs set. Run `crtr memory write -h` for the authoring + routing guide. Other sibling artifact dirs (`rules/`, `agents/`, `hooks/`) are validated by their respective specs as those land.
+
+## 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 memory docs or commands meaningfully stand alone in the Claude Code surface. Keep manifests in sync if you do.

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

@@ -0,0 +1,41 @@
+---
+name: internal/storage-tiers
+kind: knowledge
+description: Where crouter state belongs
+when-and-why-to-read: When locating crtr state or deciding where a new file belongs, this reference should be read so files are found or placed in the storage tier with the right ownership and durability.
+short-form: The two crtr storage tiers — scope root for durable user/repo content and canvas home for node-graph runtime state, node artifacts, and human tickets.
+---
+
+# Where everything lives (the two storage tiers)
+
+crtr state is split into two tiers with distinct ownership and durability. This is the routing contract; precise resolver behavior lives in `src/core/scope.ts` and `src/core/canvas/paths.ts`.
+
+## 1. Scope root — durable user/repo content and prepared support material
+
+`~/.crouter/` (user scope) or `<project>/.crouter/` (project scope), resolved by `src/core/scope.ts`. Durable content includes `memory/`, `prompts/`, `plugins/`, `marketplaces/`, `personas/`, and `config.json`; user-authored content belongs to the user scope and repo-authored content to the project scope. `prompts/<name>.md` becomes `/<name>` in every node, with nested paths becoming colon-namespaced commands and the nearest resolved scope winning.
+
+`~/.crouter/support/<reference>/` is user-scope prepared local diagnostic material. A reference contains the prepared support bundle and manifest for explicit handling; it is not `memory/`, project memory, a node context artifact, or a project-scoped support store. Preparation is local and zero-egress; submission is an explicit operation to its verified destination. Invocation, output, and artifact details belong on the relevant command leaf `-h` surfaces.
+
+User-wide content with no cwd dimension also belongs here: `~/.crouter/profile-defaults.json` maps realpath'd directories to their selected profile, and `~/.crouter/prompt-reviews/` holds prompt-review exports.
+
+## 2. Canvas home — node-graph runtime state, node artifacts, and bounded diagnostics
+
+`~/.crouter/canvas/` (overridable with `CRTR_HOME`) is the cwd-agnostic node-graph home. `canvas.db` is the SQLite WAL topology store for nodes and edges, including durable tmux-pane focus. `nodes/<node_id>/` owns `meta.json`, `context/`, `mode/`, `reports/`, `messages/`, `inbox.jsonl`, `transcript.jsonl`, `session.ptr`, and `job/` state. Humanloop ticket files (`deck.json`, `run.json`, `response.json`, `review.json`, and `branch-point.jsonl`) live directly in a terminal human bridge node directory; the one registered inbox root is `nodes/`.
+
+Mode-switch specifications and plans are ordinary node-context artifacts. They share the node's lifetime and are removed when that node is reaped.
+
+### Canonical event streams
+
+Canonical diagnostics are bounded NDJSON `EventEnvelope` streams. The synchronous rotating writer retains one active file plus `.1` and `.2` generations at 5 MiB each, and each complete record is bounded to 64 KiB including its newline. Each long-lived daemon, broker, or web process binds one fixed source and writes only that source's file; no caller selects an arbitrary destination.
+
+- `nodes/<node_id>/job/log.jsonl` is the node broker's canonical event stream. A broker-bound event carries that node identity; daemon events about a node stay in the daemon stream instead.
+- `<crtrHome>/crtrd.log` is the root daemon's canonical event stream. It contains daemon-owned events, including node-scoped data carried as `node_id` fields.
+- `<crtrHome>/web.<stream_id>.log.jsonl` is the canonical stream for one web host/port. `stream_id` is deterministic: the first 16 lowercase hexadecimal characters of SHA-256 over normalized lowercase host (IPv6 brackets removed and wildcard aliases mapped to `localhost`), a NUL, and the decimal port.
+
+### Current state and raw residue
+
+`nodes/<node_id>/job/fault` is mutable current fault state, not event history. `nodes/<node_id>/job/telemetry.json` is current node telemetry, not a log; both remain runtime state under the canvas home and are read as state rather than merged into canonical history.
+
+`<crtrHome>/crtrd.err` and `nodes/<node_id>/job/broker.log` are raw process/stdout-stderr residue for runtime warnings, third-party output, and last-resort evidence when canonical emission cannot complete. They are not canonical streams, are not parsed as event envelopes, and do not become JSON event output.
+
+The contributor rule: durable user or repo content → scope root; node-graph state, node-authored deliverables, human tickets, current state, canonical streams, and raw residue → canvas home. Runtime install generations under `~/.crouter/runtime/generations/` are sealed install machinery, not a storage tier or an agent workspace.

package/dist/builtin-memory/planning.md

@@ -0,0 +1,43 @@
+---
+kind: knowledge
+when-and-why-to-read: When shaping a planning roadmap, deciding plan structure, or preparing a consequential plan for implementation, this knowledge should be read so implementation receives a right-sized, parallel-safe execution map whose gaps are caught while they are still cheap to fix.
+short-form: Use when shaping a planning roadmap, deciding plan structure, or preparing a consequential plan for implementation.
+system-prompt-visibility: name
+file-read-visibility: none
+gate:
+  kind:
+    imatches: '^plan($|/)'
+needs-refinement: true
+rationale: >-
+  The original playbook required five parallel plan reviewers before every consequential implementation and made “passes all five lenses” the ready bar. Combined with the plan persona's re-review loop, this turned lenses into agents and resolution into reviewer polling rather than plan-owner judgment.
+---
+
+# Planning Playbook
+
+## Plan Shapes and the Decomposition Decision
+
+Every planning effort produces either a flat plan or a decomposed plan (index + part-plans). Choosing the wrong shape wastes a cycle — a flat plan that is too large forces an implementer to hold too much at once; a decomposed plan for something small adds overhead for no gain.
+
+**Use a flat plan** when the work is a single coherent domain, involves fewer than ~6 files, and can be written at consistent task granularity without exceeding roughly 150–200 lines. A flat plan has an overview, ordered phases, and a verification section. No sub-plans. One file.
+
+**Use a decomposed plan** when the change spans multiple domains (e.g., data layer, API surface, UI), involves 6+ files, or would require a master plan that cannot be written at consistent granularity without ballooning. In this case: produce an index plan (the navigable master) and delegate each domain slice to a `plan`-kind child node, giving each child its slice scope, the relevant portion of the spec, and its place in the dependency graph. A slice that itself decomposes further — multiple sub-domains, more than one window's worth of planning — goes to a `plan` sub-orchestrator created directly (`crtr node new --kind plan --mode orchestrator`), not a base child relied on to promote itself. The index plan is the synthesis artifact — it lists all sub-plans by path, defines phases and their dependencies, and contains a task table the implementation orchestrator can execute directly. Detail lives in sub-plans; the master is not allowed to carry it.
+
+**The decomposition trigger is domain boundary, not size alone.** Three backend files and three frontend files are two domains even if the total count is modest — plan them separately and synthesize, because the integration seam is where bugs live and one agent reading both halves won't catch them as cleanly as two agents each going deep.
+
+After collecting part-plans from children, synthesize before declaring done: resolve file ownership conflicts (two sub-plans naming the same file means you decide the sequence), align naming across all parts, fill integration gaps at domain boundaries, and ensure the task table in the index accurately reflects dependencies exposed only by reading all sub-plans together.
+
+## What a Good Task Looks Like
+
+A task is the atomic unit a single implementation node picks up and executes in one context window. Write tasks so that any implementation agent can pick one up cold and know exactly what to do.
+
+A good task has: a file path (or a small list of paths it exclusively owns), an explicit statement of what changes in that file, a list of its hard dependencies (which other tasks must land first), and a clear output — what type, what function signature, what export the next task can assume exists. If a task requires a type defined by a sibling task in the same phase, that dependency is explicit in the task row.
+
+A good task is **parallel-safe**: its files are not owned by another task in the same phase. If two tasks must touch the same file, serialize them across phases and say so. A task that shares files without serialization is a merge conflict waiting to happen.
+
+A good task is **bounded**: an implementation agent should be able to finish it in one context window without needing to re-read the entire plan. If a task description runs longer than a short paragraph, the task is too large — split it.
+
+## Plan Review
+
+Give a consequential synthesized plan one independent review pass. Use one base `review` node when the plan, requirements, design, and relevant source pointers fit a window; use one bounded `review` orchestrator when they do not. The assignment applies whichever lenses matter — requirements coverage, pattern consistency, code smells, security, and architecture fit — within one verdict. Lenses are questions, not separate reviewer assignments.
+
+Fold that report into the plan once. Resolve every Critical, Major, or implementation-blocking finding in the plan; dismiss a false positive or out-of-scope finding with a reason. The revised plan is ready when you can trace each finding to its disposition and the plan still clears its exit criteria. Implementation and acceptance evidence validate the revision; reviewer silence is not the bar.