@crouton-kit/crouter 0.3.27 → 0.3.29

package/dist/commands/human/queue.d.ts

@@ -1,3 +1,20 @@
+/** Deliver-back + reap an interaction whose answer is on disk but was never
+ *  delivered. The detached `_run` worker's `pushFinal` is normally the SOLE
+ *  deliver-back + reap step; when it never ran (e.g. a broker asker pre-fix, or
+ *  a human draining via `crtr human inbox`, which writes response.json directly
+ *  and never calls pushFinal), the answer strands and the bridge node leaks.
+ *
+ *  Idempotent and self-gating: a no-op unless the bridge node is still LIVE
+ *  (active|idle) AND its interaction is resolved on disk — so it never
+ *  double-delivers an interaction the `_run` worker already finalized (pushFinal
+ *  flips status=done). Reconstructs the same pushFinal body `_run` would have
+ *  emitted, per mode; a canceled-on-disk response reaps the node without
+ *  delivering a result (mirrors `human cancel`). Returns true iff it acted. */
+export declare function finalizeResolvedInteraction(jobId: string): Promise<boolean>;
+/** Sweep every interaction under the cwd's interactions root and deliver-back +
+ *  reap any that are answered-but-undelivered (see finalizeResolvedInteraction).
+ *  Interaction dir names ARE the bridge node ids. Returns how many it healed. */
+export declare function healStrandedInteractions(cwd: string): Promise<number>;
 export declare const humanInbox: import("../../core/command.js").LeafDef;
 export declare const humanList: import("../../core/command.js").LeafDef;
 export declare const humanCancel: import("../../core/command.js").LeafDef;

package/dist/commands/human/queue.js

@@ -6,12 +6,109 @@ import { paginate } from '../../core/pagination.js';
 import { getNode, subscribersOf } from '../../core/canvas/index.js';
 import { transition } from '../../core/runtime/lifecycle.js';
 import { appendInbox } from '../../core/feed/inbox.js';
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { inbox, scanInbox, parseDeck, deckPath, responsePath, isResolved, atomicWriteJson, ask, launchReview, readJson, display, } from '@crouton-kit/humanloop';
 import { killPane } from './shared.js';
 // ---------------------------------------------------------------------------
+// stranded-answer healing
+// ---------------------------------------------------------------------------
+/** A deterministic one-line-per-interaction summary, mirroring humanloop's
+ *  `<id>: <option>[ — <freetext>]` shape. Used when reconstructing a
+ *  ResolutionEnvelope from a bare on-disk response.json (which stores only
+ *  `{responses, completedAt}`), so a healed deliver-back reads like the live one. */
+function summarizeResponses(responses) {
+    return responses
+        .map((r) => {
+        const opt = r.selectedOptionId ?? '';
+        const ft = typeof r.freetext === 'string' && r.freetext.trim() !== '' ? ` — ${r.freetext.trim()}` : '';
+        return `${r.id}: ${opt}${ft}`;
+    })
+        .join('\n');
+}
+/** Deliver-back + reap an interaction whose answer is on disk but was never
+ *  delivered. The detached `_run` worker's `pushFinal` is normally the SOLE
+ *  deliver-back + reap step; when it never ran (e.g. a broker asker pre-fix, or
+ *  a human draining via `crtr human inbox`, which writes response.json directly
+ *  and never calls pushFinal), the answer strands and the bridge node leaks.
+ *
+ *  Idempotent and self-gating: a no-op unless the bridge node is still LIVE
+ *  (active|idle) AND its interaction is resolved on disk — so it never
+ *  double-delivers an interaction the `_run` worker already finalized (pushFinal
+ *  flips status=done). Reconstructs the same pushFinal body `_run` would have
+ *  emitted, per mode; a canceled-on-disk response reaps the node without
+ *  delivering a result (mirrors `human cancel`). Returns true iff it acted. */
+export async function finalizeResolvedInteraction(jobId) {
+    const node = getNode(jobId);
+    if (node === null)
+        return false;
+    if (node.status !== 'active' && node.status !== 'idle')
+        return false;
+    const idir = interactionDir(jobId, node.cwd);
+    if (!isResolved(idir))
+        return false;
+    const rc = readJson(join(idir, 'run.json'));
+    if (rc === null)
+        return false;
+    const resp = readJson(responsePath(idir));
+    if (resp === null)
+        return false;
+    // Canceled out-of-band (a raw canceled response.json, not via `human cancel`):
+    // there is no answer to deliver — just reap the node and tell waiting
+    // subscribers no answer is coming, the same quiet deferred note `human cancel`
+    // emits. (`finalize` is legal from active|idle; the status guard above holds.)
+    if (resp['canceled'] === true) {
+        transition(jobId, 'finalize');
+        const note = typeof resp['reason'] === 'string' && resp['reason'] !== '' ? ` — ${resp['reason']}` : '';
+        for (const sub of subscribersOf(jobId)) {
+            appendInbox(sub.node_id, {
+                from: jobId,
+                tier: 'deferred',
+                kind: 'message',
+                label: `human interaction ${jobId} canceled — no answer is coming${note}`,
+                data: { body: `The human interaction ${jobId} was canceled${note}. No response will arrive.` },
+            });
+        }
+        return true;
+    }
+    const responses = resp['responses'] ?? [];
+    const completedAt = resp['completedAt'] ?? new Date().toISOString();
+    const summary = summarizeResponses(responses);
+    if (rc.mode === 'approve') {
+        const sel = responses.find((r) => r.id === rc.approve_iid)?.selectedOptionId;
+        await pushFinal(jobId, JSON.stringify({ approved: sel === 'yes', summary, responses, responsePath: responsePath(idir), completedAt }));
+    }
+    else {
+        // ask (and any other answered deck): the full ResolutionEnvelope shape.
+        const env = {
+            summary,
+            responsePath: responsePath(idir),
+            schema: 'humanloop.response/v2',
+            responses,
+            completedAt,
+        };
+        await pushFinal(jobId, JSON.stringify(env));
+    }
+    return true;
+}
+/** Sweep every interaction under the cwd's interactions root and deliver-back +
+ *  reap any that are answered-but-undelivered (see finalizeResolvedInteraction).
+ *  Interaction dir names ARE the bridge node ids. Returns how many it healed. */
+export async function healStrandedInteractions(cwd) {
+    const root = interactionsRoot(cwd);
+    if (!existsSync(root))
+        return 0;
+    let healed = 0;
+    for (const ent of readdirSync(root, { withFileTypes: true })) {
+        if (!ent.isDirectory())
+            continue;
+        if (await finalizeResolvedInteraction(ent.name))
+            healed++;
+    }
+    return healed;
+}
+// ---------------------------------------------------------------------------
 // inbox (human-invoked, blocking)
 // ---------------------------------------------------------------------------
 export const humanInbox = defineLeaf({
@@ -23,13 +120,23 @@ export const humanInbox = defineLeaf({
         summary: 'interactively drain pending interactions at your own terminal',
         params: [],
         inputNote: 'No input. Run this at a human terminal — it blocks until the backlog is drained or you quit.',
-        output: [{ name: 'drained', type: 'boolean', required: true, constraint: 'True once the loop returns.' }],
+        output: [
+            { name: 'drained', type: 'boolean', required: true, constraint: 'True once the loop returns.' },
+            { name: 'delivered', type: 'integer', required: true, constraint: 'How many answered-but-undelivered interactions were delivered back to their askers and reaped.' },
+        ],
         outputKind: 'object',
-        effects: ['Resolves pending interactions in the per-project interactions root via the TUI.'],
+        effects: [
+            'Resolves pending interactions in the per-project interactions root via the TUI.',
+            'Delivers any answered-but-undelivered interaction back to its asking node and reaps the bridge node (the deliver-back the detached _run worker would have done).',
+        ],
     },
     run: async () => {
         await inbox([interactionsRoot(process.cwd())]);
-        return { drained: true };
+        // humanloop's inbox() writes response.json but never calls pushFinal — so a
+        // deck drained here would strand (no answer-back, leaked bridge node). Heal
+        // every resolved-but-live interaction: deliver its answer to the asker + reap.
+        const delivered = await healStrandedInteractions(process.cwd());
+        return { drained: true, delivered };
     },
 });
 // ---------------------------------------------------------------------------

package/dist/commands/memory/__tests__/lint-schema.test.js

@@ -9,21 +9,44 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { lintSubstrateSchema } from '../lint.js';
 const ROUTING = 'When you are X, this reference should be read because Y';
+const RUNGS = { 'system-prompt-visibility': 'name', 'file-read-visibility': 'none' };
 test('lint rejects a doc still carrying the retired `when` key', () => {
-    const err = lintSubstrateSchema({ kind: 'reference', when: 'when X' });
+    const err = lintSubstrateSchema({ kind: 'knowledge', when: 'when X' });
     assert.ok(err !== null, 'old-shape `when` must produce a finding');
     assert.match(err, /when-and-why-to-read/, 'the message points at the new field');
 });
 test('lint rejects a doc still carrying the retired `why` key', () => {
-    const err = lintSubstrateSchema({ kind: 'reference', why: 'because Y' });
+    const err = lintSubstrateSchema({ kind: 'knowledge', why: 'because Y' });
     assert.ok(err !== null, 'old-shape `why` must produce a finding');
     assert.match(err, /when-and-why-to-read/, 'the message points at the new field');
 });
 test('lint rejects a substrate doc missing the merged routing field', () => {
-    const err = lintSubstrateSchema({ kind: 'reference' });
+    const err = lintSubstrateSchema({ kind: 'knowledge' });
     assert.ok(err !== null, 'a substrate doc must carry when-and-why-to-read');
     assert.match(err, /when-and-why-to-read/);
 });
 test('lint accepts the merged new-shape frontmatter', () => {
-    assert.equal(lintSubstrateSchema({ kind: 'reference', 'when-and-why-to-read': ROUTING }), null);
+    assert.equal(lintSubstrateSchema({ kind: 'knowledge', 'when-and-why-to-read': ROUTING, ...RUNGS }), null);
+});
+// Visibility is a required, case-by-case authoring call — there is no kind
+// default. lint must reject a doc that omits either rung (the runtime parser
+// silently floors a missing rung to `none`, which is exactly the tolerance this
+// gate exists to catch at authoring time).
+test('lint rejects a substrate doc missing system-prompt-visibility', () => {
+    const err = lintSubstrateSchema({
+        kind: 'knowledge',
+        'when-and-why-to-read': ROUTING,
+        'file-read-visibility': 'none',
+    });
+    assert.ok(err !== null, 'a missing rung must produce a finding');
+    assert.match(err, /missing system-prompt-visibility/);
+});
+test('lint rejects a substrate doc missing file-read-visibility', () => {
+    const err = lintSubstrateSchema({
+        kind: 'knowledge',
+        'when-and-why-to-read': ROUTING,
+        'system-prompt-visibility': 'name',
+    });
+    assert.ok(err !== null, 'a missing rung must produce a finding');
+    assert.match(err, /missing file-read-visibility/);
 });

package/dist/commands/memory/lint.d.ts

@@ -1,8 +1,9 @@
 /** Schema checks for a doc living in a substrate memory dir: a memory store
  *  holds ONLY substrate docs, so a missing/invalid `kind` is an authoring
- *  error here (elsewhere it just means "not a substrate doc"). Rung and gate
- *  values are checked RAW — the runtime parser silently falls back to kind
- *  defaults / inert gates, which is exactly the silent tolerance this lint
- *  exists to catch at authoring time. */
+ *  error here (elsewhere it just means "not a substrate doc"). Both rungs are
+ *  REQUIRED — there is no kind default to lean on, so a missing rung is an
+ *  authoring error. Rung and gate values are checked RAW — the runtime parser
+ *  silently falls back to the neutral floor / inert gates, which is exactly the
+ *  silent tolerance this lint exists to catch at authoring time. */
 export declare function lintSubstrateSchema(fm: Record<string, unknown> | null): string | null;
 export declare const lintLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/memory/lint.js

@@ -17,15 +17,16 @@ const VALID_RUNGS = [...RUNGS, 'always'];
 const RUNG_FIELDS = ['system-prompt-visibility', 'file-read-visibility'];
 /** Schema checks for a doc living in a substrate memory dir: a memory store
  *  holds ONLY substrate docs, so a missing/invalid `kind` is an authoring
- *  error here (elsewhere it just means "not a substrate doc"). Rung and gate
- *  values are checked RAW — the runtime parser silently falls back to kind
- *  defaults / inert gates, which is exactly the silent tolerance this lint
- *  exists to catch at authoring time. */
+ *  error here (elsewhere it just means "not a substrate doc"). Both rungs are
+ *  REQUIRED — there is no kind default to lean on, so a missing rung is an
+ *  authoring error. Rung and gate values are checked RAW — the runtime parser
+ *  silently falls back to the neutral floor / inert gates, which is exactly the
+ *  silent tolerance this lint exists to catch at authoring time. */
 export function lintSubstrateSchema(fm) {
     if (fm === null)
-        return 'missing frontmatter: a memory store doc requires `kind: skill|reference|preference`';
+        return 'missing frontmatter: a memory store doc requires `kind: knowledge|preference`';
     if (!isDocKind(fm.kind)) {
-        return `invalid kind: ${JSON.stringify(fm.kind)} (expected skill|reference|preference)`;
+        return `invalid kind: ${JSON.stringify(fm.kind)} (expected knowledge|preference)`;
     }
     // The retired `when`/`why` pair was merged into one read-routing field. The
     // hard cut is enforced HERE: an old-shape doc must fail, never be silently
@@ -38,7 +39,10 @@ export function lintSubstrateSchema(fm) {
     }
     for (const field of RUNG_FIELDS) {
         const v = fm[field];
-        if (v !== undefined && (typeof v !== 'string' || !VALID_RUNGS.includes(v))) {
+        if (v === undefined) {
+            return `missing ${field}: choose a rung explicitly (${RUNGS.join('|')}) — there is no kind default`;
+        }
+        if (typeof v !== 'string' || !VALID_RUNGS.includes(v)) {
             return `invalid ${field}: ${JSON.stringify(v)} (expected ${RUNGS.join('|')})`;
         }
     }
@@ -52,6 +56,18 @@ export function lintSubstrateSchema(fm) {
         !(Array.isArray(appliesTo) && appliesTo.every((g) => typeof g === 'string'))) {
         return `invalid applies-to: ${JSON.stringify(appliesTo)} (expected a glob or glob list)`;
     }
+    // read-when (Stream A on-read frontmatter trigger): same well-formed-object
+    // contract as gate — a non-object is inert (never fires), so catch it here.
+    const readWhen = fm['read-when'];
+    if (readWhen !== undefined && (readWhen === null || typeof readWhen !== 'object' || Array.isArray(readWhen))) {
+        return `invalid read-when: ${JSON.stringify(readWhen)} (expected a field→matcher object)`;
+    }
+    // A dead on-read trigger: an explicit applies-to/read-when with nothing to
+    // surface (file-read-visibility none) can never fire — flag it loudly rather
+    // than store a silent no-op.
+    if (fm['file-read-visibility'] === 'none' && (appliesTo !== undefined || readWhen !== undefined)) {
+        return 'dead on-read trigger: applies-to/read-when is set but file-read-visibility is `none` — raise the rung or drop the trigger';
+    }
     return null;
 }
 /** Strict-parse one file; push a finding on a YAML error, then run the

package/dist/commands/memory/read.js

@@ -18,7 +18,7 @@ export const readLeaf = defineLeaf({
         ],
         output: [
             { name: 'name', type: 'string', required: true, constraint: 'Resolved document name.' },
-            { name: 'kind', type: 'string', required: true, constraint: 'Resolved kind: skill, reference, or preference.' },
+            { name: 'kind', type: 'string', required: true, constraint: 'Resolved kind: knowledge or preference.' },
             { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was resolved from: project, user, or builtin.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the document on disk.' },
             { name: 'content', type: 'string', required: true, constraint: 'Document body. Frontmatter stripped unless --frontmatter is set.' },
@@ -48,7 +48,7 @@ export const readLeaf = defineLeaf({
                 ? sub.kind
                 : typeof doc.frontmatter?.['kind'] === 'string'
                     ? doc.frontmatter['kind']
-                    : 'reference';
+                    : 'knowledge';
             // --kind asserts the resolved kind; a mismatch falls through to not-found.
             if (kindFilter === undefined || kind === kindFilter) {
                 const content = includeFrontmatter ? readText(doc.path) : doc.body;

package/dist/commands/memory/shared.d.ts

@@ -1,5 +1,5 @@
 import type { Scope } from '../../types.js';
-export declare const MEMORY_KINDS: readonly ["skill", "reference", "preference"];
+export declare const MEMORY_KINDS: readonly ["knowledge", "preference"];
 export declare const VISIBILITY_RUNGS: readonly ["none", "name", "preview", "content"];
 export declare const MEMORY_SCOPES: readonly ["user", "project"];
 /** Scope sort weight matching resolution precedence (project > user > builtin).
@@ -17,6 +17,12 @@ export declare function resolveWriteTarget(scopeArg: string | undefined): {
  *  memory dir, guarding against traversal/absolute escapes. */
 export declare function memoryFilePath(memoryDir: string, name: string): string;
 export declare function coerceGate(raw: string): Record<string, unknown>;
+/** Coerce a `--read-when` string into a predicate tree. Like `--gate`, the
+ *  read-when field MUST be a YAML/JSON object (the field→matcher map the schema
+ *  expects, evaluated against a read file's own frontmatter). A scalar/array
+ *  read-when is inert (never matches), so passing one is always a mistake and is
+ *  caught at authoring time rather than stored. */
+export declare function coerceReadWhen(raw: string): Record<string, unknown>;
 /** Coerce a `--applies-to` string to the schema's glob form: a comma-separated
  *  list becomes an array, a single glob stays a string. */
 export declare function coerceAppliesTo(raw: string): unknown;

package/dist/commands/memory/shared.js

@@ -7,9 +7,10 @@ import { join } from 'node:path';
 import { stringify as yamlStringify, parse as yamlParse } from 'yaml';
 import { usage } from '../../core/errors.js';
 import { scopeMemoryDir, projectScopeRoot, ensureProjectScopeRoot, } from '../../core/scope.js';
-// The three memory kinds — procedural (skill), referential (reference),
-// preferential (preference). Used as the `--kind` enum choices everywhere.
-export const MEMORY_KINDS = ['skill', 'reference', 'preference'];
+// The two memory kinds — knowledge (consult: procedural playbooks + factual
+// references merged) vs preference (behave: standing directives). Used as the
+// `--kind` enum choices everywhere.
+export const MEMORY_KINDS = ['knowledge', 'preference'];
 // Visibility rungs — how much of a document surfaces (none → name → preview →
 // content). Shared by --system-prompt-visibility and --file-read-visibility.
 export const VISIBILITY_RUNGS = ['none', 'name', 'preview', 'content'];
@@ -76,6 +77,19 @@ export function coerceGate(raw) {
     }
     return result;
 }
+/** Coerce a `--read-when` string into a predicate tree. Like `--gate`, the
+ *  read-when field MUST be a YAML/JSON object (the field→matcher map the schema
+ *  expects, evaluated against a read file's own frontmatter). A scalar/array
+ *  read-when is inert (never matches), so passing one is always a mistake and is
+ *  caught at authoring time rather than stored. */
+export function coerceReadWhen(raw) {
+    const result = parseYamlObject(raw);
+    if (typeof result === 'string') {
+        throw usage(`--read-when must be a YAML/JSON object (field→matcher map over a read file's frontmatter): ${result}. ` +
+            `Example: --read-when '{tags: {contains: security}}'`);
+    }
+    return result;
+}
 /** Coerce a `--applies-to` string to the schema's glob form: a comma-separated
  *  list becomes an array, a single glob stays a string. */
 export function coerceAppliesTo(raw) {
@@ -97,6 +111,7 @@ const FRONTMATTER_ORDER = [
     'file-read-visibility',
     'gate',
     'applies-to',
+    'read-when',
 ];
 /** Serialize a substrate frontmatter record + body into a complete `.md`
  *  document. Frontmatter is emitted as a `---` fenced YAML block (the `yaml`

package/dist/commands/memory/write.js

@@ -2,18 +2,18 @@ import { defineLeaf } from '../../core/command.js';
 import { usage } from '../../core/errors.js';
 import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
 import { readText, writeText, pathExists } from '../../core/fs-utils.js';
-import { MEMORY_KINDS, MEMORY_SCOPES, VISIBILITY_RUNGS, resolveWriteTarget, memoryFilePath, coerceGate, coerceAppliesTo, serializeMemoryDoc, } from './shared.js';
+import { MEMORY_KINDS, MEMORY_SCOPES, VISIBILITY_RUNGS, resolveWriteTarget, memoryFilePath, coerceGate, coerceAppliesTo, coerceReadWhen, serializeMemoryDoc, } from './shared.js';
 export const writeLeaf = defineLeaf({
     name: 'write',
     description: 'create or update a memory document',
-    whenToUse: 'you are recording a new skill, reference, or preference — or revising one that already exists. Writes memory/<name>.md at the resolved scope from the frontmatter flags plus a body piped on stdin. Identity is path-derived: if <name> already exists at the scope it is updated in place, otherwise it is created.',
+    whenToUse: 'you are recording a new knowledge document or preference — or revising one that already exists. Writes memory/<name>.md at the resolved scope from the frontmatter flags plus a body piped on stdin. Identity is path-derived: if <name> already exists at the scope it is updated in place, otherwise it is created.',
     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' +
+            'Pick the kind. knowledge = anything you CONSULT \u2014 how to DO something (a repeatable procedure/playbook) OR what is TRUE / 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 them: does it DIRECT behavior ("always lint after authoring" \u2192 preference) or INFORM what you know ("Silas likes chicken", "the daemon never reloads dist/" \u2192 knowledge)? A correction yields a preference; a learned fact or a repeatable procedure yields knowledge.\n\n' +
+            'Set the rungs \u2014 BOTH --system-prompt-visibility (boot) and --file-read-visibility (on-read) are REQUIRED on create. There is no default: the right rung is a case-by-case call, never a function of kind. The ladder, lowest to highest: `none` for niche docs almost nothing should pull into context; `name` for the common case \u2014 references and skills that are relatively uncommon but an agent (or the user, by name) may reach for; `preview` for docs important enough that their routing line is worth its token cost every session (preferences usually land here); `content` (full body injected) for a doc that would be `preview` except its body is already so short you may as well inline it whole. `content` is rare \u2014 when a `content` doc grows past a bullet or two, downgrade it to `preview`. Each axis is independent: usually one carries a real rung and the other is `none` (see the hook paragraph next).\n\n' +
+            'Choose the hook \u2014 boot vs file-read. There are exactly two moments a doc can surface. Behavior (preferences) and how-to procedure are relevant whatever file is open \u2192 surface at boot. Knowledge about code 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 knowledge doc 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' +
@@ -23,10 +23,11 @@ export const writeLeaf = defineLeaf({
             { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: true, constraint: 'Document kind.' },
             { kind: 'flag', name: 'when-and-why-to-read', type: 'string', required: false, constraint: 'The read-routing line, authored as ONE sentence: "When <circumstance>, this <kind> should be read <because <payoff>>." It states WHEN to read this doc and WHY the read is worth it — read-routing, NEVER a justification of why the content should be obeyed. Rendered verbatim as the preview. Required when creating.' },
             { kind: 'flag', name: 'short-form', type: 'string', required: false, constraint: 'Frontmatter short-form — a very abbreviated version of the content, the hook shown in `crtr memory list`.' },
-            { kind: 'flag', name: 'system-prompt-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much of this document auto-loads into the system prompt / CLI help.' },
-            { kind: 'flag', name: 'file-read-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much of this document surfaces when it is read off disk.' },
+            { kind: 'flag', name: 'system-prompt-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much of this document auto-loads into the system prompt / CLI help. Required when creating — there is no kind default; pick a rung explicitly.' },
+            { kind: 'flag', name: 'file-read-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much of this document surfaces when it is read off disk. Required when creating — there is no kind default; pick a rung explicitly.' },
             { kind: 'flag', name: 'gate', type: 'string', required: false, constraint: 'Frontmatter gate — expression/condition that determines when this document applies.' },
             { kind: 'flag', name: 'applies-to', type: 'string', required: false, constraint: 'Frontmatter applies-to — glob/path scope the document applies to.' },
+            { kind: 'flag', name: 'read-when', type: 'string', required: false, constraint: 'Frontmatter read-when — a condition (field→matcher object) over a READ FILE’s own frontmatter that surfaces this doc on-read (a native rule). Same predicate vocabulary as --gate. Example: \'{tags: {contains: security}}\'.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Target scope. Default: project when inside a project, else user.' },
             { kind: 'stdin', name: 'body', required: true, constraint: 'Document body (markdown, no frontmatter). Piped on stdin, or passed as the bare positional after <name>.' },
         ],
@@ -56,6 +57,15 @@ export const writeLeaf = defineLeaf({
         if (created && input['whenAndWhyToRead'] === undefined) {
             throw usage(`creating ${name} requires --when-and-why-to-read: one read-routing sentence "When <circumstance>, this ${kind} should be read <because <payoff>>." (rendered verbatim as the preview).`);
         }
+        // CREATE requires BOTH visibility rungs as an explicit, case-by-case call —
+        // there is no kind default to lean on. UPDATE inherits whatever the existing
+        // doc already carries.
+        if (created && input['systemPromptVisibility'] === undefined) {
+            throw usage(`creating ${name} requires --system-prompt-visibility: pick a rung explicitly (none|name|preview|content) — there is no kind default. See \`crtr memory write -h\` for what each rung means.`);
+        }
+        if (created && input['fileReadVisibility'] === undefined) {
+            throw usage(`creating ${name} requires --file-read-visibility: pick a rung explicitly (none|name|preview|content) — there is no kind default. See \`crtr memory write -h\` for what each rung means.`);
+        }
         // In-place update: start from the existing frontmatter (preserving fields
         // not passed this time), then overlay the provided ones. Create: start clean.
         const frontmatter = created
@@ -77,6 +87,9 @@ export const writeLeaf = defineLeaf({
         if (input['appliesTo'] !== undefined) {
             frontmatter['applies-to'] = coerceAppliesTo(input['appliesTo']);
         }
+        if (input['readWhen'] !== undefined) {
+            frontmatter['read-when'] = coerceReadWhen(input['readWhen']);
+        }
         writeText(path, serializeMemoryDoc(frontmatter, body));
         return {
             name,

package/dist/commands/memory.js

@@ -1,4 +1,4 @@
-// `crtr memory` subtree — the document substrate (skills, references,
+// `crtr memory` subtree — the document substrate (knowledge and
 // preferences) accessed via the CLI. Four flat leaves: list, read, find, write.
 // SKELETON ONLY (task B1): the `-h` contracts here are final; the leaf handlers
 // are stubs that B2 fills in. Mirrors `skill.ts` minus the loaded-skills
@@ -13,13 +13,13 @@ export function registerMemory() {
     return defineBranch({
         name: 'memory',
         rootEntry: {
-            concept: 'a memory document you read on demand — a skill, reference, or preference',
+            concept: 'a memory document you read on demand — knowledge or a preference',
             desc: 'list, read, search, and write memory documents',
-            useWhen: 'a task matches a stored skill, reference, or preference — read it before improvising. `crtr memory read <name>` loads one by name; `crtr memory list` browses the inventory; `crtr memory find` searches by topic when you do not yet know the name. Names are path-derived crtr identifiers, not file paths — never cat or find the markdown off disk.',
+            useWhen: 'a task matches stored knowledge or a preference — read it before improvising. `crtr memory read <name>` loads one by name; `crtr memory list` browses the inventory; `crtr memory find` searches by topic when you do not yet know the name. Names are path-derived crtr identifiers, not file paths — never cat or find the markdown off disk.',
         },
         help: {
             name: 'memory',
-            summary: 'list, read, search, and write memory documents — skills, references, preferences',
+            summary: 'list, read, search, and write memory documents — knowledge and 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. 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/commands/node.d.ts

@@ -7,7 +7,7 @@ export declare function childFollowUp(spawnerId: string | undefined): string;
 /** The live node "in front of you" in a tmux pane, HOST-AGNOSTIC. Defaults to
  *  $TMUX_PANE / the caller's current pane when `pane` is omitted — shared by
  *  `node recycle` / `node demote` / `node lifecycle` / `node close` / `node
- *  cycle`, and the `canvas chord` / `canvas tmux-spread` leaves.
+ *  cycle`, and the `canvas chord` leaf.
  *
  *  Two resolutions, tried in order:
  *    1. VIEWER pane (broker host): a `crtr attach` viewer self-tags its pane with