@crouton-kit/crouter 0.3.26 → 0.3.27

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

@@ -16,6 +16,6 @@ Open this dir whenever a task turns on understanding the runtime itself. Content
 - **storage-tiers** — where every kind of state lives: the three tiers (scope root, per-cwd crouter root, canvas home) and their durability/ownership contracts.
 - **examples/** — worked compositions of the primitives into complete systems (the analogue of pi's `examples/` dir), e.g. the iMessage assistant node.
 
-Adjacent, outside this dir: authoring memory documents (frontmatter, rungs, gates, the asked-to-remember workflow) is owned by the builtin **memory-authoring** skill; making a persona (a custom `--kind`) is owned by the builtin **crouter-development/personas** skills.
+Adjacent, outside this dir: authoring memory documents (kind, rungs, gates, routing line, the asked-to-remember workflow) is owned by `crtr memory write -h` — the authoring guide lives on the help-gate so it surfaces exactly when you write; making a persona (a custom `--kind`) is owned by the builtin **crouter-development/personas** skills.
 
 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/commands/memory/write.js

@@ -10,6 +10,14 @@ export const writeLeaf = defineLeaf({
     help: {
         name: 'memory write',
         summary: 'create or update memory/<name>.md at the resolved scope from frontmatter flags + a stdin body',
+        guide: 'The body is the easy part; the craft is ROUTING — every frontmatter flag decides who sees this doc, when, and at what context cost. Each rung up is paid by every future agent at every boot or read, forever, so default each rung DOWN.\n\n' +
+            'Pick the kind. skill = how to DO something (a repeatable procedure/playbook); reference = what is TRUE or how something WORKS (a fact about the user, a system\u2019s behavior, code docs); preference = how to BEHAVE (a directive, a standing correction). The test that splits the close pair: does it DIRECT behavior ("always lint after authoring" \u2192 preference) or INFORM the world-model ("Silas likes chicken", "the daemon never reloads dist/" \u2192 reference)? A correction yields a preference, a learned fact a reference, a repeatable procedure a skill.\n\n' +
+            'Set the rungs (none < name < preview < content). Kind sets sensible defaults, so the common case needs no visibility flags at all: skill \u2192 name at boot; preference \u2192 preview at boot; reference \u2192 preview on-read, nothing at boot. Reserve `content` (full body injected) for guidance that is BOTH always-relevant AND ~one bullet long \u2014 fail either test and it is `preview`. Situational guidance is `preview` no matter how short; long guidance is `preview` no matter how universal it feels.\n\n' +
+            'Choose the hook \u2014 boot vs file-read. There are exactly two moments a doc can surface. Behavior and procedure (preferences, skills) are relevant whatever file is open \u2192 surface at boot. Knowledge about code (references) belongs NEXT TO the code: put the file in that directory\u2019s .crouter/memory/ and it fires positionally when files there are read, costing nothing at boot. The exception that matters: a reference about a PERSON or PROCESS has no code directory to anchor to, so on-read triggering is meaningless \u2014 set --system-prompt-visibility preview so its routing line surfaces at boot instead.\n\n' +
+            'Write the routing line (--when-and-why-to-read) FIRST, before storing anything: "When <circumstance the agent is in>, this <kind> should be read because <what the read buys>." The test: can a stranger mid-task decide from that one line alone whether to spend the read? If you cannot name the concrete situation that triggers it, you do not yet understand the memory \u2014 ask the user ONE sharp question instead of improvising. ("Remember I like chicken" routes cleanly \u2192 food/meal decisions; "be careful with the API" does not \u2192 which API, careful how, against what failure?) And NEVER paraphrase the advice in the routing line \u2014 a preview that gives away the gist makes every future agent skip the real read. BAD: "\u2026because it carries the placement policy \u2014 -h first, memory only for dev-mode material." GOOD: "\u2026because it carries the standing placement policy."\n\n' +
+            'Find before write. `crtr memory find <topic>` first; grow ONE doc per recurring circumstance rather than minting near-duplicates \u2014 extend `food-preferences`, do not create `likes-chicken`. Group related docs with path names (area/topic). Do not store what is already recorded (code structure, git history, CLAUDE.md) or what only matters to this conversation.\n\n' +
+            'Body: write for a STRANGER \u2014 a future session that shares none of this conversation. State current truth, not the history of getting there (no "as discussed"). Keep the reasoning behind a rule and cut everything else; dense beats complete, since every line costs a mid-task reader.\n\n' +
+            'Gate (--gate, optional): a predicate making the doc eligible only for nodes whose own config matches (e.g. `{ mode: orchestrator }` or `{ orchestration.depth: { gte: 2 } }`); a failing gate hides it from both hooks but it stays findable by search. Default is no gate \u2014 most docs want exactly that. After authoring, validate with `crtr memory lint`.',
         params: [
             { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived identity (e.g. `topic` or `area/topic`) → memory/<name>.md at the resolved scope. Updated in place if it already exists, otherwise created.' },
             { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: true, constraint: 'Document kind.' },

package/dist/commands/memory.js

@@ -20,7 +20,7 @@ export function registerMemory() {
         help: {
             name: 'memory',
             summary: 'list, read, search, and write memory documents — skills, references, preferences',
-            model: '`list` for a human inventory of what is stored — one line per document, the only surface that shows short-form. `read` (leaf) loads one document body by name, resolved project > user > builtin with leaf-name fallback; --frontmatter keeps the YAML header. `find` when you do not yet know which document applies — it ranks by relevance over name/when/why/short-form, --body to also weigh bodies, --grep for an exact regex over bodies. `write` creates or updates memory/<name>.md at a scope from frontmatter flags + a body piped on stdin. `lint` strict-parses the whole bounded corpus and fails on any invalid frontmatter — run it after authoring. Append `-h` at any leaf for its full schema.',
+            model: '`list` for a human inventory of what is stored — one line per document, the only surface that shows short-form. `read` (leaf) loads one document body by name, resolved project > user > builtin with leaf-name fallback; --frontmatter keeps the YAML header. `find` when you do not yet know which document applies — it ranks by relevance over name/when/why/short-form, --body to also weigh bodies, --grep for an exact regex over bodies. `write` creates or updates memory/<name>.md at a scope from frontmatter flags + a body piped on stdin. `lint` strict-parses the whole bounded corpus and fails on any invalid frontmatter — run it after authoring. A directory may carry an `INDEX.md` with the same frontmatter schema as any doc; the dir then renders as one entry at the INDEX\'s rung, and that rung is a ceiling for its whole subtree (`none` hides the dir) — when a doc mysteriously is not surfacing, check its ancestors\' INDEX rungs and its gate. Append `-h` at any leaf for its full schema, and `crtr memory write -h` for the authoring guide.',
         },
         children: [listLeaf, readLeaf, findLeaf, writeLeaf, lintLeaf],
     });

package/dist/core/runtime/naming.d.ts

@@ -6,17 +6,13 @@ export declare function sanitizeSessionName(raw: string): string;
 /** Local fallback: derive a name straight from the prompt (no pi call). Drops
  *  stop-words, takes the first few content words. */
 export declare function slugFromPrompt(prompt: string): string;
-/** Synchronously ask pi for a 3-8 word kebab name for `prompt`. Blocks up to
- *  NAME_TIMEOUT_MS; on any failure (non-zero exit, timeout, empty/garbled
- *  output) falls back to a local slug. Returns '' only for an empty prompt. */
-export declare function generateSessionName(prompt: string): string;
 /** Asynchronously generate a name for `prompt` and persist it to the node's
  *  meta as `description` — only if the node has none yet (so a later message
  *  never clobbers it). Non-blocking: safe to call from inside a live pi event
  *  loop. Best-effort; swallows all errors.
  *
  *  `onNamed` (optional) fires with the freshly-persisted meta the moment the
- *  name lands — the bare-root path passes a callback that calls
+ *  name lands — the canvas-goal-capture naming hook passes a callback that calls
  *  pi.setSessionName(editorLabel(meta)) so the LIVE editor label updates in the
  *  same session, instead of waiting for the next revive/cycle. */
 export declare function generateAndPersistName(nodeId: string, prompt: string, onNamed?: (meta: NodeMeta) => void): void;

package/dist/core/runtime/naming.js

@@ -6,19 +6,16 @@
 // the first prompt by asking pi headlessly (`pi -p`), persisted on the node's
 // meta so it survives revives and shows in every cycle.
 //
-// Two entry points:
-//   • generateSessionName  — synchronous (spawnSync). For the CLI spawn paths
-//     (spawnChild / bootRoot) that run outside any pi event loop, where a brief
-//     block before launching the worker is fine and lets the FIRST pi session
-//     already carry the name.
-//   • generateAndPersistName — async (execFile, non-blocking). For the bare-root
-//     case where the prompt only arrives as the first interactive message inside
-//     a live pi process; it must never block the event loop. Persists the name
-//     to meta so the label picks it up on the next cycle.
+// One entry point: generateAndPersistName — async (execFile, non-blocking).
+// Naming happens INSIDE the named node's own pi process, off the first real
+// message (the kickoff task or a human's first line), never on the spawn path:
+// blocking spawn on an LLM round-trip used to freeze the caller's terminal for
+// 2-3s on every `crtr node new`. The headless namer runs with --no-extensions,
+// so it loads no canvas hooks and can never recurse into another spawn/name.
 //
-// Both are best-effort: a failed/slow/garbled pi call falls back to a local slug
-// of the prompt, so a node always gets a sane name.
-import { spawnSync, execFile } from 'node:child_process';
+// Best-effort: a failed/slow/garbled pi call falls back to a local slug of the
+// prompt, so a node always gets a sane name.
+import { execFile } from 'node:child_process';
 import { getNode, updateNode } from '../canvas/index.js';
 /** Cap on prompt text fed to the namer — a name needs only the gist. */
 const PROMPT_CAP = 2000;
@@ -97,30 +94,27 @@ function nameArgs(prompt) {
     argv.push(nameUserPrompt(prompt));
     return argv;
 }
-/** Synchronously ask pi for a 3-8 word kebab name for `prompt`. Blocks up to
- *  NAME_TIMEOUT_MS; on any failure (non-zero exit, timeout, empty/garbled
- *  output) falls back to a local slug. Returns '' only for an empty prompt. */
-export function generateSessionName(prompt) {
-    const body = (prompt ?? '').trim();
-    if (body === '')
-        return '';
-    try {
-        const r = spawnSync('pi', nameArgs(body), {
-            encoding: 'utf8',
-            timeout: NAME_TIMEOUT_MS,
-            // Don't inherit a TUI; capture stdout only.
-            stdio: ['ignore', 'pipe', 'ignore'],
-        });
-        if (r.status === 0 && typeof r.stdout === 'string') {
-            const name = sanitizeSessionName(r.stdout);
-            if (name !== '')
-                return name;
+/** Ask pi headlessly for a kebab-case name for `body`, async. Resolves to the
+ *  sanitized name, or '' on any failure (non-zero exit, timeout, empty/garbled
+ *  output) so the caller can fall back to a local slug. Owns the subprocess
+ *  mechanics — crucially it hands pi an immediate stdin EOF: `pi -p` reads
+ *  stdin, and execFile's default stdin is an OPEN pipe that never closes, so
+ *  without this pi blocks waiting for EOF and the call exits non-zero (the
+ *  regression that silently lost every LLM name to the slug fallback). */
+function headlessName(body) {
+    return new Promise((resolve) => {
+        try {
+            const child = execFile('pi', nameArgs(body), { encoding: 'utf8', timeout: NAME_TIMEOUT_MS }, (err, stdout) => {
+                if (err || typeof stdout !== 'string')
+                    return resolve('');
+                resolve(sanitizeSessionName(stdout));
+            });
+            child.stdin?.end(); // immediate EOF — see the doc above
         }
-    }
-    catch {
-        // fall through to slug
-    }
-    return slugFromPrompt(body);
+        catch {
+            resolve('');
+        }
+    });
 }
 /** Asynchronously generate a name for `prompt` and persist it to the node's
  *  meta as `description` — only if the node has none yet (so a later message
@@ -128,7 +122,7 @@ export function generateSessionName(prompt) {
  *  loop. Best-effort; swallows all errors.
  *
  *  `onNamed` (optional) fires with the freshly-persisted meta the moment the
- *  name lands — the bare-root path passes a callback that calls
+ *  name lands — the canvas-goal-capture naming hook passes a callback that calls
  *  pi.setSessionName(editorLabel(meta)) so the LIVE editor label updates in the
  *  same session, instead of waiting for the next revive/cycle. */
 export function generateAndPersistName(nodeId, prompt, onNamed) {
@@ -150,17 +144,7 @@ export function generateAndPersistName(nodeId, prompt, onNamed) {
             // best-effort
         }
     };
-    try {
-        execFile('pi', nameArgs(body), { encoding: 'utf8', timeout: NAME_TIMEOUT_MS }, (err, stdout) => {
-            if (err || typeof stdout !== 'string') {
-                persist(slugFromPrompt(body));
-                return;
-            }
-            const name = sanitizeSessionName(stdout);
-            persist(name !== '' ? name : slugFromPrompt(body));
-        });
-    }
-    catch {
-        persist(slugFromPrompt(body));
-    }
+    void headlessName(body).then((name) => {
+        persist(name !== '' ? name : slugFromPrompt(body));
+    });
 }

package/dist/core/runtime/spawn.js

@@ -14,7 +14,6 @@ import { spawnNode, currentNodeContext, resolveBirthSession, nodeSession, rootOf
 import { buildLaunchSpec, buildPiArgv } from './launch.js';
 import { writeGoal } from './kickoff.js';
 import { hasRoadmap, seedRoadmap } from './roadmap.js';
-import { generateSessionName } from './naming.js';
 import { buildIdentityAssertion, buildWakeBearings } from './bearings.js';
 import { installMenuBinding, installNavBindings, installViewNavBindings } from './tmux-chrome.js';
 import { setPresence, updateNode, getNode, fullName } from '../canvas/index.js';
@@ -35,19 +34,16 @@ export function bootRoot(opts) {
     // A born-resident root starts in base mode; it earns the orchestrator persona
     // the first time it delegates (or on promotion). Resident lifecycle either way.
     const { launch } = buildLaunchSpec(kind, 'base', { lifecycle: 'resident', hasManager: false });
-    // A root opened WITH a prompt gets its editor name now (so the first pi
-    // session already carries it). A bare root has no prompt yet — the
-    // goal-capture extension names it from the first message (async, next cycle).
-    const description = opts.prompt !== undefined && opts.prompt.trim() !== ''
-        ? generateSessionName(opts.prompt)
-        : undefined;
+    // Born WITHOUT a name. Naming is async + event-driven: the canvas-goal-capture
+    // extension names the node from its FIRST real message (the kickoff prompt or
+    // a human's first line) inside its own pi process, via a headless `pi -p`.
+    // Never block the front door on an LLM round-trip.
     const meta = spawnNode({
         kind,
         mode: 'base',
         lifecycle: 'resident',
         cwd: opts.cwd,
         name: opts.name ?? kind,
-        description,
         parent: null,
         launch,
     });
@@ -162,14 +158,15 @@ export function spawnChild(opts) {
     // independent root sits top-of-spine with nobody to push to. Mirrors the
     // `parent` set below (root ? null : spawner), so hasManager === parent!==null.
     const { launch } = buildLaunchSpec(opts.kind, mode, { lifecycle, hasManager: !root, model: opts.model });
-    // Name the worker from its task now, so its first editor label carries it.
+    // Born WITHOUT a name — the canvas-goal-capture extension names it async from
+    // its first message (the kickoff task) inside its own pi process, so spawn
+    // never blocks on the LLM naming round-trip (the 2-3s freeze it used to cost).
     const meta = spawnNode({
         kind: opts.kind,
         mode,
         lifecycle,
         cwd: opts.cwd,
         name: opts.name ?? opts.kind,
-        description: generateSessionName(opts.prompt),
         // A root has no spine parent (top-level, nobody subscribes); it still
         // records spawned_by=spawner when a node (not a human shell) spawned it.
         // A child's parent IS its manager.

package/dist/pi-extensions/canvas-goal-capture.js

@@ -3,13 +3,23 @@
 // Loaded into every canvas node's pi process via the node's launch.extensions
 // list. INERT when CRTR_NODE_ID is absent (plain pi session or legacy job agent).
 //
-// A node spawned with a prompt has its goal persisted at birth (writeGoal in
-// spawn.ts). A bare root (`crtr` with no prompt) starts goal-less — its mandate
-// only arrives when the human types their first message. This extension closes
-// that gap: on the FIRST interactive user message, if the node has no goal yet,
-// it persists that message as context/initial-prompt.md. Subsequent messages
-// never clobber it (captureGoalIfAbsent is guarded), and a fresh-revive kickoff
-// prompt is skipped via its sentinel so it can never be mistaken for a mandate.
+// Two first-message jobs, both keyed off the node's first real `input` event:
+//
+//   1. Goal capture (bare roots). A node spawned with a prompt has its goal
+//      persisted at birth (writeGoal in spawn.ts). A bare root (`crtr` with no
+//      prompt) starts goal-less — its mandate only arrives when the human types
+//      their first message; this persists that as context/initial-prompt.md.
+//      Guarded so later messages never clobber it.
+//
+//   2. Naming (every node). Naming is async + event-driven — it does NOT run on
+//      the spawn path (that blocking LLM call froze the caller's terminal for
+//      2-3s on every spawn). On the first real message, if the node has no name
+//      yet, ask pi headlessly (async, non-blocking) for a kebab-case name and
+//      live-update the editor label. The first message may be a human's line OR
+//      a delegated child's kickoff task — naming off the agent prompt is fine.
+//
+// Both skip extension-injected messages (inbox wakes, steering) and the
+// fresh-revive kickoff (its sentinel), so neither is mistaken for a first input.
 //
 // Pure observation — it writes the goal file as a side effect and always lets
 // the message through unchanged (returns nothing ⇒ continue). Registered before
@@ -20,7 +30,7 @@
 // crouter's own tsc build without a dep on the pi packages.
 import { captureGoalIfAbsent, REVIVE_KICKOFF_SENTINEL } from '../core/runtime/kickoff.js';
 import { generateAndPersistName } from '../core/runtime/naming.js';
-import { editorLabel } from '../core/canvas/index.js';
+import { editorLabel, getNode } from '../core/canvas/index.js';
 /**
  * Register the goal-capture handler on `pi`.
  *
@@ -34,26 +44,32 @@ export function registerCanvasGoalCapture(pi) {
             const nodeId = process.env['CRTR_NODE_ID'];
             if (nodeId === undefined || nodeId.trim() === '')
                 return; // not a canvas node
-            // Only a genuine human-typed prompt seeds the mandate — never an RPC or an
-            // extension-injected message (inbox wakes, steering nudges, kickoffs).
-            if (event.source !== 'interactive')
-                return;
             const text = (event.text ?? '').trim();
             if (text === '')
                 return;
-            // A fresh-revive kickoff is delivered as the launch prompt; never let it
-            // masquerade as the user's first mandate.
+            // Never seed a mandate or a name from an extension-injected message (inbox
+            // wakes, steering nudges) or a fresh-revive kickoff (the node is already
+            // named). Both would otherwise masquerade as the node's first real input.
+            if (event.source === 'extension')
+                return;
             if (text.startsWith(REVIVE_KICKOFF_SENTINEL))
                 return;
-            // First mandate for a bare root: persist it as the goal, and ask pi
-            // (async, non-blocking) to name the session from it. The name lands on
-            // meta.description; the onNamed callback pushes the new editor label into
-            // THIS live session via setSessionName, so it updates immediately instead
-            // of only on the next cycle.
-            if (captureGoalIfAbsent(nodeId, text)) {
-                generateAndPersistName(nodeId, text, (meta) => {
+            // Goal capture is bare-root only: a delegated child already had its goal
+            // persisted at birth (writeGoal), so only a genuine human-typed prompt
+            // seeds a mandate here.
+            if (event.source === 'interactive')
+                captureGoalIfAbsent(nodeId, text);
+            // Naming: name the node from its FIRST real message — a human's first line
+            // OR a delegated child's kickoff task (naming off the agent prompt is
+            // fine) — whenever it has no name yet. Async headless `pi -p` with no
+            // canvas extensions, so it never recurses into another spawn/name. The
+            // onNamed callback live-updates THIS session's label instead of waiting
+            // for the next cycle. The unnamed-guard keeps it to one call per node.
+            const meta = getNode(nodeId);
+            if (meta !== null && (meta.description ?? '').trim() === '') {
+                generateAndPersistName(nodeId, text, (named) => {
                     try {
-                        pi.setSessionName?.(editorLabel(meta));
+                        pi.setSessionName?.(editorLabel(named));
                     }
                     catch { /* best-effort */ }
                 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.26",
+  "version": "0.3.27",
   "description": "crtr — fast access to skills, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/dist/builtin-memory/memory-authoring.md

@@ -1,100 +0,0 @@
----
-kind: skill
-when-and-why-to-read: When you are about to write or update a memory document — including any time the user asks you to remember something — or need to debug why a document is (not) surfacing, this skill should be read because it tells you how to choose kind and scope, set the disclosure rungs and gate, size the body, and when to first ask the user a clarifying question.
-short-form: Author excellent memories — kind, scope, visibility rungs, gates, body sizing, and the asked-to-remember workflow.
-system-prompt-visibility: preview
-file-read-visibility: none
----
-
-# Writing memories
-
-A memory is a markdown document whose frontmatter decides **when, where, and how much** of it loads into future agents. The body is the easy part; the craft is routing — deciding who sees it, at what moment, at what context cost. Every frontmatter choice below is a routing choice.
-
-## When asked to remember something
-
-1. **Write the routing line first.** Before storing anything, try to complete: *"When <circumstance>, this <kind> should be read because <payoff>."* If you cannot name the concrete situation a future agent will be in when this matters, you do not understand the memory yet — ask the user **one sharp question** instead of improvising. "Remember I like chicken" routes cleanly (food/meal decisions); "remember to be careful with the API" does not (which API? careful how? against what failure?) — that one needs clarifying before it becomes a memory. The routing line is a comprehension test.
-2. **Find before write.** `crtr memory find <topic>` for an existing doc; update it rather than minting a near-duplicate. Prefer growing `food-preferences` over creating `likes-chicken` — one document per recurring *circumstance*, not one per fact. Group related docs with path names (`area/topic`). Delete memories that turn out wrong.
-3. **Capture the why, not just the what.** Especially for corrections: record what was rejected and the reasoning. The why is what lets a future agent apply the rule to cases you never saw.
-4. **Don't store what's already recorded** — code structure, git history, CLAUDE.md content — or what only matters to this conversation. If asked to remember something the repo already records, ask what was non-obvious about it and store that instead.
-
-## Choosing kind
-
-- **skill** — how to *do* something (a playbook, a procedure you'd repeat).
-- **reference** — what is *true* or how something *works* (a fact about the user, a system's behavior, code docs).
-- **preference** — how to *behave* (a directive, a standing correction).
-
-The reference-vs-preference test: does it direct behavior ("always run lint after authoring") or inform the world-model ("Silas likes chicken", "the daemon never reloads dist/")? A correction usually yields a preference; a learned fact yields a reference; a repeatable procedure yields a skill.
-
-Kind sets sensible default rungs — the common case needs no visibility fields at all:
-
-| kind | at boot | on file-read |
-|---|---|---|
-| skill | name | none |
-| preference | preview | none |
-| reference | none | preview |
-
-## The two hooks — boot vs file-read
-
-There are exactly two moments a doc can surface. `system-prompt-visibility` governs **boot** (the system prompt); `file-read-visibility` governs **on-read** (when a related file is opened).
-
-- Behavior and procedure (preferences, skills) are relevant regardless of which file is open → surface at boot, stay out of file-read. That is what the defaults do.
-- Knowledge about code (references) belongs **next to the code**: put the doc in that directory's `.crouter/memory/` and it fires positionally when files under that directory are read — costing nothing at boot.
-- The exception that matters: a reference about a *person or a process* ("Silas's food preferences") has no code directory to anchor to, so positional triggering is meaningless — set `system-prompt-visibility: preview` so its routing line surfaces at boot instead.
-- `applies-to: <glob or list>` extends the on-read trigger beyond position for cross-cutting docs (e.g. a testing reference that should fire for `**/*.test.ts` anywhere).
-
-## Choosing the rung
-
-`none → name → preview → content`. Each rung up costs more of **every** future agent's context, paid at every boot or read, forever. Default down, not up.
-
-- **content** (full body injected): reserved for guidance that is BOTH always relevant AND ~one bullet's worth of text. Fail either test → preview. Situational guidance is preview *no matter how short*; long guidance is preview no matter how universal it feels.
-- **preview** (the one-sentence routing line): the workhorse. Costs one line; the body is read on demand.
-- **name** (title only): catalog-style docs whose name already routes (`api-reference`).
-- **none**: invisible except to `crtr memory find` — archival or narrowly specialized material.
-
-`short-form` is NOT a rung and never enters an agent's context (an agent handed a summary satisfices and skips the real read). It is the gist a human sees in `crtr memory list` — write it for them, and don't make it do routing work.
-
-## The routing line
-
-`when-and-why-to-read` is **read-routing, never content**: it answers when to open the doc and why the read pays — never why the content should be obeyed, and never a paraphrase of the content. A preview that gives away the gist defeats the ladder: the agent feels informed and skips the body. Shape: *"When <circumstance the agent is in>, this <kind> should be read because <what the read buys>."* The test: can a stranger mid-task decide from this single line alone whether to spend the read?
-
-## Gates — conditioning on who the agent is
-
-An optional `gate:` predicate makes the doc eligible only for nodes whose own config matches. Subject fields: `kind` (node role, free-form), `mode` (base|orchestrator), `lifecycle` (terminal|resident), `hasManager` (bool), `cwd`, `scope` (user|project), `orchestration.depth` (hops to the root orchestrator; root = 0). Matchers: scalar equality, list membership, or operator objects (`{gte: 2}`, `{in: […]}`, `{matches: "…"}`, `exists`, `contains`…), with `all`/`any`/`not` combinators.
-
-```yaml
-gate: { mode: orchestrator }               # only delegating managers
-gate: { orchestration.depth: { gte: 2 } }  # only substantial, scaled-up efforts
-```
-
-Default is no gate — always eligible; most docs want exactly that. An empty `gate: {}` is inert (never matches) — don't write it. A failing gate hides the doc from both hooks, but it stays findable by search.
-
-## Scope — where the file lives
-
-- **user** (`~/.crouter/memory/`): facts about the user, cross-project behavior. The chicken memory goes here.
-- **project** (`<dir>/.crouter/memory/`): anything about a codebase or workspace — and place it in the *specific directory* it describes (any directory can hold a `.crouter/`), so positional on-read fires precisely.
-- **builtin**: ships with crtr itself (contributed via `src/builtin-memory/` in the crouter repo) — docs every crtr agent should have.
-
-Resolution is project > user > builtin with leaf-name fallback (`read <leaf>` finds `area/<leaf>` when unambiguous), so a project doc can shadow a same-named user or builtin doc.
-
-## Mechanics worth knowing
-
-- **Directory entries**: a directory may carry an `INDEX.md` with the same frontmatter schema as any doc; the dir then renders as one entry at the INDEX's rung, and that rung is a **ceiling for its subtree** (`none` hides the whole dir). When a doc mysteriously isn't surfacing, check its ancestors' INDEX rungs and its gate.
-- **CLI**: `crtr memory list` (human inventory) · `read <name>` (names are path-derived, never file paths) · `find <query>` (search ignores gates and rungs) · `write` (author) · `lint` (validate after authoring). Run `-h` on a leaf before first use.
-
-## Body content
-
-Write for a stranger: a future session that shares none of this conversation. No "as discussed", no narration of how you learned it — state current truth, not the history of getting there. Keep the reasoning behind rules; cut everything else. Don't pad: a preference can legitimately be two sentences, and a skill should lead with decisions, not mechanism. A body behind `preview` may be long when it earns it, but every line still costs a reader who is mid-task — dense beats complete.
-
-## Worked example
-
-User says: *"remember that I like chicken."*
-
-```bash
-echo "Silas likes chicken." | crtr memory write food-preferences \
-  --kind reference --scope user \
-  --when-and-why-to-read "When you are choosing or recommending food, meals, or recipes for Silas, this reference should be read because it records his food preferences." \
-  --short-form "Silas's food likes/dislikes" \
-  --system-prompt-visibility preview
-```
-
-Reference (a fact, not a directive) · user scope (about the person, not a repo) · `preview` at boot (no code directory to anchor on-read) · named for the recurring circumstance, so future food facts append to the same doc. After authoring, validate: `crtr memory lint`.