@crouton-kit/crouter 0.3.28 → 0.3.30

package/dist/commands/dashboard.js

@@ -8,7 +8,7 @@
 import { defineLeaf } from '../core/command.js';
 import { InputError } from '../core/io.js';
 import { getNode, listNodes } from '../core/canvas/index.js';
-import { renderTree, renderForest, dashboardRows, dashboardRowsAll } from '../core/canvas/render.js';
+import { renderTree, renderForest, dashboardRows, dashboardRowsAll, enrichRows } from '../core/canvas/render.js';
 // ---------------------------------------------------------------------------
 // dashboard show — the main leaf
 // ---------------------------------------------------------------------------
@@ -57,7 +57,11 @@ export const dashboardLeaf = defineLeaf({
         }
         // Full forest: all nodes on the canvas.
         const allNodes = listNodes();
+        // dashboardRowsAll is the cheap-boot builder: ctx_tokens/asks are 0 and `name`
+        // is the handle only until enriched. The JSON consumer wants the real values,
+        // so fold the deferred fields in before emitting (the rendered TREE is unaffected).
         const rows = dashboardRowsAll();
+        enrichRows(rows);
         return {
             tree: renderForest(),
             nodes: allNodes.length,

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

@@ -11,22 +11,22 @@ 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, ...RUNGS }), 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
@@ -34,7 +34,7 @@ test('lint accepts the merged new-shape frontmatter', () => {
 // gate exists to catch at authoring time).
 test('lint rejects a substrate doc missing system-prompt-visibility', () => {
     const err = lintSubstrateSchema({
-        kind: 'reference',
+        kind: 'knowledge',
         'when-and-why-to-read': ROUTING,
         'file-read-visibility': 'none',
     });
@@ -43,7 +43,7 @@ test('lint rejects a substrate doc missing system-prompt-visibility', () => {
 });
 test('lint rejects a substrate doc missing file-read-visibility', () => {
     const err = lintSubstrateSchema({
-        kind: 'reference',
+        kind: 'knowledge',
         'when-and-why-to-read': ROUTING,
         'system-prompt-visibility': 'name',
     });

package/dist/commands/memory/lint.js

@@ -24,9 +24,9 @@ const RUNG_FIELDS = ['system-prompt-visibility', 'file-read-visibility'];
  *  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
@@ -56,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' +
+            '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 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' +
+            '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' +
@@ -27,6 +27,7 @@ export const writeLeaf = defineLeaf({
             { 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>.' },
         ],
@@ -86,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