@crouton-kit/crouter 0.3.17 → 0.3.19

package/dist/build-root.js

@@ -1,11 +1,14 @@
 import { defineRoot } from './core/command.js';
 import { registerSkill } from './commands/skill.js';
+import { registerMemory } from './commands/memory.js';
 import { registerPkg } from './commands/pkg.js';
 import { registerHuman } from './commands/human.js';
 import { registerSys } from './commands/sys.js';
 import { registerPush, registerFeed } from './commands/push.js';
 import { registerNode } from './commands/node.js';
 import { registerCanvas } from './commands/canvas.js';
+import { registerView } from './commands/view.js';
+import { registerAttach } from './clients/attach/attach-cmd.js';
 /** Assemble the full crtr command tree. Root owns only the tagline; every
  *  subtree declares its own root representation via its rootEntry, and every
  *  branch assembles its child listing from the child defs (each child owns its
@@ -18,6 +21,7 @@ export function buildRoot() {
         globals: [],
         subtrees: [
             registerSkill(),
+            registerMemory(),
             registerPkg(),
             registerHuman(),
             registerSys(),
@@ -25,6 +29,8 @@ export function buildRoot() {
             registerPush(),
             registerFeed(),
             registerCanvas(),
+            registerView(),
+            registerAttach(),
         ],
     });
 }

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

@@ -0,0 +1,164 @@
+---
+kind: skill
+when: When a task relates to marketplaces
+why: 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.
+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 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.
+
+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.
+
+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
+    │   └── skills/...
+    └── plugin-b/
+        └── ...
+```
+
+Each entry under `plugins/` is a complete plugin (see [[crouter-development/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 market manage install --marketplace my-marketplace --plugin 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.
+
+## 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 [[crouter-development/plugins]] for plugin layout)
+mkdir -p plugins/my-new-plugin/.crouter-plugin plugins/my-new-plugin/skills
+$EDITOR plugins/my-new-plugin/.crouter-plugin/plugin.json
+
+# Add at least one skill
+crtr skill author scaffold my-new-plugin/first-skill --type playbook --description "Use when …"
+
+# 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
+
+# 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 manage update --marketplace <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 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.
+
+## 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/crouter-development/personas/base-prompt.md

@@ -0,0 +1,58 @@
+---
+kind: skill
+when: When a task relates to base prompt
+why: How to write a base persona prompt (the mode=base PERSONA.md) — the system
+  prompt for a single-window worker node. Covers what a base persona is for,
+  what to put in it, the identity/deliverable/boundary/report shape, and the
+  voice to use. Use when writing or revising a <kind>/PERSONA.md.
+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
+  the voice to use. Use when writing or revising a <kind>/PERSONA.md.
+system-prompt-visibility: name
+file-read-visibility: none
+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]]`.
+
+Audience: LLM agents writing a `<kind>/PERSONA.md`.
+
+## What a base persona is for
+
+A base worker **does the work itself and ends.** It is not a manager. The persona points a fresh, capable model at one kind of task and makes it produce the right artifact without supervision. Everything in the body serves that: who it is, what good output looks like, what's out of bounds, and how it hands the result back.
+
+A base persona is a **system prompt**, not a task. Write the durable role — the identity and standards that hold for *every* task of this kind — and let the spawn-time prompt carry the specific task. Never bake one task's details into the persona.
+
+## The four things to put in it
+
+In order. Most base personas are 1–3 short paragraphs total.
+
+1. **Identity — one line, second person.** Open `"You are a <role> agent."` This is a system-prompt identity declaration; `"You are X"` is correct here (it would be wrong in a task prompt). Name the role sharply — "fast codebase exploration agent", "code review agent" — so the model knows which hat it wears.
+
+2. **The deliverable and its shape.** State *what good output is*, not a step-by-step procedure. Name the artifact and its structure: design names its sections, review names its severity tiers, explore demands `file:line` citations. You set the target the model steers toward — describe the target, not a checklist of moves to reach it. Fix the *what*; delegate the *how* to the model's judgment.
+
+3. **The boundaries that keep it in its lane.** One or two constraints that carve this kind out from its neighbors: explore is "read-only — do not modify"; design and plan "do not implement"; developer "throw errors early, no silent fallbacks". These earn their negative framing because the model has a real prior toward crossing the line — a design agent *will* start writing code if you don't fence it off. Keep them to genuine lane boundaries; don't pile on don'ts the model wouldn't trip over anyway.
+
+4. **The report.** Close by stating the deliverable is reported via `crtr push final` — the one runtime rule worth reinforcing in the body, because stopping without it is the most common worker failure. Everything else in the protocol (delegating, the feed, escalating) is already prepended by `runtime-base.md`; do not re-teach it.
+
+## Keep it shallow
+
+A base worker may spawn a helper or two for a targeted sub-task, but most of the work must be its own. If a kind's job routinely needs broad fan-out, it isn't a base worker — it's an orchestrator (`[[crouter-development/personas/orchestrator-prompt]]`). The base persona should make a do-er, not a delegator; say so explicitly when the kind is tempting to over-delegate (developer: "keep the delegation shallow").
+
+## Voice
+
+- **Second person + imperative.** "You are X." "Answer the question." "Do not modify files." Direct instruction for a direct worker.
+- **Positive framing for standards.** Describe the output you want, not a list of failures to avoid — "quote concrete `file:line` references" beats "don't be vague".
+- **Reserve hard rules.** CAPS / MUST only for the genuine non-negotiable — usually the finish rule and the lane boundary. If everything is critical, nothing is.
+- **Density.** This loads as the system prompt on *every* spawn of the kind. No preamble, no fluff — every line is the identity, the deliverable, a boundary, or the report.
+
+## Failure modes
+
+- **Procedure instead of target.** A numbered how-to ages badly and fights the model's judgment. State the deliverable's shape; let it choose the path.
+- **Restating runtime-base.** Re-teaching delegation/feed/escalation duplicates the prepended protocol and drifts out of sync. Reference only `push final`, as the deliverable.
+- **Task leakage.** Specifics of one task baked into the persona make every future spawn wear yesterday's job. Keep the body to the durable role.
+- **No report close.** A base persona that never names `crtr push final` produces workers that go quiet and get re-prompted. Always close on the deliverable.
+- **A manager in worker's clothing.** If the body spends more ink on delegation than on doing, you've written an orchestrator — split it.

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

@@ -0,0 +1,60 @@
+---
+kind: skill
+when: When a task relates to orchestrator prompt
+why: 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
+  <kind>/orchestrator.md.
+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
+  <kind>/orchestrator.md.
+system-prompt-visibility: name
+file-read-visibility: none
+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]]`.
+
+Audience: LLM agents writing a `<kind>/orchestrator.md`.
+
+## The one rule that shapes everything: kernel vs kind
+
+Every orchestrator persona ends with `@include orchestration-kernel.md`. The kernel already teaches the **universal orchestrator protocol** — the wake loop, the roadmap structure and discipline, long-term memory, working in phases, delegating outcomes, steering what comes back, engaging the human, and the pre-finish checklist. It is long and complete.
+
+So your `orchestrator.md` body carries **only the delta** — what is specific to this kind. If a line you're about to write is true of orchestrators in general, the kernel already says it; cut it. Subtract before you add: the body is usually 1–3 short paragraphs *on top of* the kernel, not a re-derivation of how to orchestrate.
+
+## What the per-kind body puts in
+
+1. **Identity — the kind's ownership.** Open `"You are a **<kind> orchestrator** — …"` and say what this kind *owns*: a feature-sized goal (developer), a specification effort (spec), a review surface (review), a research question (explore). Bold the role. One sentence on what "owning it" means here.
+
+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.
+
+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.
+
+5. **What integration means here.** Every orchestrator's deliverable is the *synthesis*, never the child transcripts — but say what synthesis looks like for this kind: explore reconciles findings into one architecture answer; review deduplicates and severity-normalises into one verdict; design verifies every contract is honored on both sides. "Integrate, don't concatenate," made concrete.
+
+## The recurring sizing rule
+
+When a unit is itself too big for one window, the orchestrator creates that child **directly as `--mode orchestrator`**, not a base worker it counts on to self-promote. This appears in nearly every orchestrator persona because it's domain-flavored — *which* child kind gets promoted differs by orchestrator. State it for yours; a node born an orchestrator is strictly more capable than one hoping to become one.
+
+## Voice
+
+- **Second person identity, then operations.** "You are a **developer orchestrator**…" then "Run the build as a delegation pipeline…".
+- **Positive, concrete framing.** Name the pipeline and the exit criteria; don't enumerate things not to do. The one earned negative is the load-bearing boundary — "never by writing the code yourself" — which counters a real model prior to just do the work.
+- **Reserve hard rules** for genuine non-negotiables (the no-self-execution boundary, the no-self-promotion sizing rule). Density matters: this loads on every revive.
+- **End with the include.** `@include orchestration-kernel.md` on its own line, last. Without it the orchestrator boots with no protocol and cannot run the loop.
+
+## Failure modes
+
+- **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.
+- **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

@@ -0,0 +1,117 @@
+---
+kind: skill
+when: When a task relates to personas
+why: How to define a custom node kind (persona) for crtr — the
+  PERSONA.md/orchestrator files, the frontmatter contract (incl. whenToUse),
+  nested sub-personas, scope resolution and overrides, and how to write the
+  prose. Use when adding a new `--kind`, overriding a builtin agent, or
+  debugging persona resolution.
+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
+  prose. Use when adding a new `--kind`, overriding a builtin agent, or
+  debugging persona resolution.
+system-prompt-visibility: name
+file-read-visibility: none
+needs-refinement: true
+---
+
+# Authoring crtr personas (custom node kinds)
+
+A **persona** is what `--kind` resolves to: the markdown that becomes a node's system prompt plus the launch knobs (model/tools/extensions/lifecycle). Defining one adds a new spawnable agent type to the canvas.
+
+Audience: LLM agents creating or overriding a crtr node kind.
+
+## When to add a kind (vs reuse a builtin)
+
+Builtins cover the common shapes: `explore spec design plan developer review general`.
+
+- **Reuse a builtin** when the work fits one. Don't fork `developer` to tweak one sentence.
+- **Add a kind** for a recurring specialist with its own deliverable + reporting contract that no builtin matches — e.g. `researcher`, `migration`, `release`.
+- **Override a builtin** by creating a same-named dir at user/project scope — it *shadows* the builtin (precedence below), it doesn't edit the shipped file.
+
+Never edit `src/builtin-personas/` for a local need — that ships to everyone. Override at scope instead.
+
+## Layout
+
+```
+<root>/personas/
+├── <kind>/
+│   ├── PERSONA.md            # worker persona (mode=base)
+│   ├── orchestrator.md      # orchestrator persona (mode=orchestrator) — optional
+│   └── <sub>/PERSONA.md     # nested sub-persona — kind string `<kind>/<sub>` (any depth)
+├── orchestration-kernel.md  # shared; @include-d by orchestrator files
+└── runtime-base.md          # shared; prepended to EVERY persona automatically
+```
+
+The role-body file is **`PERSONA.md`** (not `base.md` — that layout was retired). A kind exists once `<kind>/` holds a `PERSONA.md` **or** `orchestrator.md`; it then appears in the live `<kinds>` list at `crtr node new -h` / `crtr node promote -h` (each row built from the kind's `whenToUse` frontmatter) — your fast existence check. Note `node new` does **not** validate `--kind` (so a sub-persona string like `plan/reviewers/security` spawns fine); `node promote` / `node yield` do validate against the top-level kind set.
+
+## Scope + precedence
+
+Resolution is **project > user > builtin**, resolved per file:
+
+| Scope | Path |
+|---|---|
+| project | `<project>/.crouter/personas/<kind>/` — checked into the repo |
+| user | `~/.crouter/personas/<kind>/` — personal, all your projects |
+| builtin | ships with the CLI |
+
+Personas are **scope-root content, not plugin content** — they don't ship via plugins or marketplaces (the loader only searches `<scope>/personas/`). To share a kind, commit it to a repo's `.crouter/personas/` (project) or copy it into `~/.crouter/personas/` (user).
+
+## The two files
+
+**`PERSONA.md`** — the worker (mode=base). Second person. State scope → method → deliverable, and end by reporting via `crtr push final`. Default lifecycle `terminal` (finishes in one window). → how to write one: `[[crouter-development/personas/base-prompt]]`.
+
+**`orchestrator.md`** — the owner that delegates to children and never does the work itself. Name the child kinds it drives and set per-phase exit criteria. **Must end with `@include orchestration-kernel.md`** — the loader inlines it; without it the orchestrator boots with no fan-out protocol. Default lifecycle `resident`. → how to write one: `[[crouter-development/personas/orchestrator-prompt]]`.
+
+If a kind has only `PERSONA.md`, `--mode orchestrator` composes `PERSONA.md body + kernel` and forces `resident` — so write `orchestrator.md` only when the worker and owner prose genuinely differ.
+
+## Frontmatter contract
+
+YAML frontmatter on either file supplies launch knobs; the body is the system prompt.
+
+| Field | Type | Effect |
+|---|---|---|
+| `lifecycle` | `terminal`\|`resident` | terminal = finishes + reaps; resident = interactive/long-lived. Defaults: base→terminal, orchestrator→resident. |
+| `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. |
+| `whenToUse` | string | on a `<kind>/PERSONA.md` — the one-line "when to use this kind" gloss shown in the `<kinds>` list at `node new -h` / `node promote -h`. |
+| `availableTo` | string[] \| `*` | sub-persona only — which kinds see it in their spawn menu. Default: its top-level ancestor kind. `*` / `all` = every kind. |
+
+`resolve()` never throws: a missing/empty persona falls back to `"You are a <kind> agent…"` defaults, so a node always boots. `runtime-base.md` (the push/finish/delegate/feed/ask protocol) is prepended to every persona — **don't restate it in the body.**
+
+## @include
+
+`@include <filename>` inlines another persona-root file, resolved through the same project>user>builtin chain. Used for `orchestration-kernel.md`; drop an `orchestration-kernel.md` at user/project scope to change orchestrator protocol fleet-wide.
+
+## Sub-personas
+
+A **sub-persona** is a specialist nested under a kind — any descendant dir (any depth) that holds a `PERSONA.md`, e.g. `plan/reviewers/security/PERSONA.md`. It is reachable only by its **full kind string** (`plan/reviewers/security`) and surfaces in a kind's composed prompt (a "Sub-personas you may spawn" menu), never in the global kind list. Intermediate dirs without a `PERSONA.md` (e.g. `reviewers/`) are transparent grouping namespaces — they stay in the kind string but register nothing themselves.
+
+Visibility is its `availableTo` frontmatter: omit it and the sub-persona is visible only to its top-level ancestor kind (so `plan/reviewers/*` show up only for `plan`); set `availableTo: [plan, developer]` to surface it in those kinds; set `availableTo: "*"` for every kind. Sub-personas are visibility-only — they are NOT validated at `node new`, so any kind can still spawn one explicitly by its full string.
+
+## Dev loop
+
+```bash
+mkdir -p ~/.crouter/personas/researcher
+$EDITOR ~/.crouter/personas/researcher/PERSONA.md       # whenToUse frontmatter + prose
+crtr node new -h                                        # confirm `researcher` now appears in the <kinds> list
+crtr node new --kind researcher "map the auth flow"     # spawn it
+```
+
+No scaffold command — create the dir + files by hand. Copy a builtin (`explore/PERSONA.md`, `developer/orchestrator.md`) as a starting template.
+
+## Failure modes
+
+- **Orchestrator with no `@include orchestration-kernel.md`** — boots without the fan-out protocol; can't delegate. Always include it.
+- **Restating runtime-base** — the push/finish/delegate protocol is already prepended. Duplicating it wastes context and drifts out of sync.
+- **`lifecycle: resident` on a worker `PERSONA.md`** — the node never finishes. Reserve `resident` for interactive/long-lived kinds.
+- **Editing `src/builtin-personas/` for a local need** — ships to everyone. Override at user/project scope.
+- **Kind not listed after creating the dir** — neither `PERSONA.md` nor `orchestrator.md` is present, or the filename is wrong (it must be exactly `PERSONA.md` — `base.md` no longer registers a kind). The dir alone doesn't register a kind.
+
+## Related
+
+`[[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.

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

@@ -0,0 +1,163 @@
+---
+kind: skill
+when: When a task relates to plugins
+why: 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.
+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.
+system-prompt-visibility: name
+file-read-visibility: none
+needs-refinement: true
+---
+
+# Authoring crtr plugins
+
+A **plugin** is a directory shipping skills (and, in future, other artifact types like commands and hooks). Plugins are how you package skills for sharing across machines, projects, and people.
+
+Audience: LLM agents creating or maintaining a crtr plugin.
+
+## When you need a plugin (vs scope-owned skills)
+
+Scope-owned skills live at `~/.crouter/skills/` (user) or `<project>/.crouter/skills/` (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 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.
+
+## Directory layout
+
+```
+<plugin-name>/
+├── .crouter-plugin/
+│   └── plugin.json                  # manifest — required
+└── skills/
+    └── <skill-name>/
+        └── SKILL.md
+```
+
+The `<plugin-name>` directory IS the plugin. The manifest's `name` field must match the directory name (install renames if needed). Future artifact types (`commands/`, `hooks/`, etc.) will be sibling dirs to `skills/`.
+
+## The manifest
+
+`.crouter-plugin/plugin.json`:
+
+```json
+{
+  "name": "my-plugin",
+  "version": "0.1.0",
+  "description": "One sentence — shown in `crtr pkg plugin inspect 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 skill. |
+| `description` | yes | One sentence. |
+| `source` | recommended | Git URL where the plugin lives. Used by `crtr pkg plugin manage update --name <name>`. |
+| `owner` | optional | Author info. |
+
+## 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 manage install <url> --scope user`):
+   - Clones into `<scope>/plugins/<name>/` using the manifest's name.
+   - `crtr pkg plugin manage update --name <name>` does `git pull`.
+   - Independent of any marketplace.
+
+2. **From a marketplace** (`crtr pkg market manage install --marketplace <mkt> --plugin <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.
+   - 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.
+
+## Local development loop
+
+```bash
+# Scaffold dir + manifest + first skill
+mkdir -p my-plugin/.crouter-plugin my-plugin/skills
+$EDITOR my-plugin/.crouter-plugin/plugin.json      # write the manifest
+cd my-plugin
+crtr skill author scaffold my-plugin/my-first-skill --type playbook --description "Use when …"
+
+# 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 skills
+crtr memory list --plugin my-plugin            # just my-plugin's skills
+crtr sys doctor                                    # validates manifest + every skill
+```
+
+When ready to share: push to a git remote; anyone can `crtr pkg plugin manage install <url> --scope user`.
+
+## Versioning
+
+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) |
+
+`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]].
+
+## 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>`.
+
+Individual skills inside an enabled plugin can also be disabled: `crtr skill state disable <plugin>/<skill>`.
+
+## 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.
+- 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.
+
+## 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.
+
+## Validation
+
+`crtr sys doctor` checks every plugin:
+- Manifest exists and is valid JSON.
+- Manifest `name` matches the directory name.
+- Every skill under `skills/` passes the skill-validation contract (frontmatter parses, `name` matches dir path, `type` in enum). Run `crtr skill author guide` for the authoring workflow + SKILL.md format reference.
+- Sibling artifact dirs (`commands/`, `hooks/`, etc.) — 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 skills/commands meaningfully stand alone in the Claude Code surface. Keep manifests in sync if you do.