@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/commands/human/shared.js

@@ -8,7 +8,7 @@ export const DECK_SCHEMA_HINT = 'Deck must match the humanloop deck schema: {tit
     'source?:{sessionName?,askedBy?,blockedSince?}, ' +
     'interactions:[{id,title,subtitle?,(body?|bodyPath?),options:[{id,label,' +
     'description?}],multiSelect?,allowFreetext?,freetextLabel?,' +
-    "kind?:'notify'|'validation'|'decision'|'context'|'error'}]}.";
+    "kind?:'notify'|'decision'|'context'|'error'}]}.";
 export function resolveMaxPanes() {
     return readConfig('user').max_panes_per_window;
 }
@@ -42,7 +42,7 @@ export function resolveHumanTarget() {
 /**
  * Open the detached humanloop `_run` pane for an interaction dir, ROUTED to the
  * session the user is watching (`resolveHumanTarget`). The single spawn path
- * behind ask/approve/review (`spawnHumanJob`) and notify. `detached: true` keeps
+ * behind ask/review (`spawnHumanJob`) and notify. `detached: true` keeps
  * the user's view put — the prompt lands beside the watched node without
  * jumping their session/window. `jobId`, when given, is injected as CRTR_JOB_ID.
  */
@@ -90,7 +90,7 @@ export function followUpReview(_jobId) {
  *
  * Completion routing needs no bookkeeping here: the human node was created
  * under the asking node as its parent (spawnNode auto-subscribes the parent),
- * so the `pushFinal` the `_run` worker emits — for ask, approve, AND review —
+ * so the `pushFinal` the `_run` worker emits — for ask AND review —
  * fans the answer straight into the asking node's inbox. The pane id is recorded
  * on run.json (not returned) so `human cancel` can later kill the TUI.
  */

package/dist/commands/human.js

@@ -1,41 +1,42 @@
 // `crtr human` subtree — in-process humanloop bridge.
 //
-// Kickoff leaves (ask/approve/review) create a kind:'human' node under the
+// Kickoff leaves (ask/review) create a kind:'human' node under the
 // asking node, write deck.json/run.json into the per-cwd interaction dir, spawn
 // a detached `crtr human _run` pane, and return immediately. The human's answer
 // is pushed as the node's final report, which fans out to the asking node's
 // inbox — no polling surface. notify/show create no node. _run runs the blocking
 // humanloop call at the pane TTY and pushes the result itself.
 //
-// TTY safety: every leaf is argv-only — none declares a stdin parameter, so
-// the spawned pane's TTY stays free for humanloop's raw-mode input. Control
-// params travel via CRTR_HUMAN_DIR (set inline in the spawned command) +
-// run.json, never stdin.
+// TTY safety: kickoff/TUI leaves are argv-only, so the spawned pane's TTY stays
+// free for humanloop's raw-mode input. Control params travel via CRTR_HUMAN_DIR
+// (set inline in the spawned command) + run.json, never stdin. The noninteractive
+// resolve leaf is the only stdin-taking child and does not spawn a TUI pane.
 import { defineBranch } from '../core/command.js';
-import { humanAsk, humanApprove, humanReview, humanNotify, humanShow } from './human/prompts.js';
-import { humanInbox, humanList, humanCancel, humanRun } from './human/queue.js';
+import { humanAsk, humanReview, humanNotify, humanShow } from './human/prompts.js';
+import { humanInbox, humanList, humanDeck, humanResolve, humanCancel, humanRun } from './human/queue.js';
 export function registerHuman() {
     return defineBranch({
         name: 'human',
         rootEntry: {
             concept: 'human-in-the-loop decisions, document review, and live display',
-            desc: 'ask, approve, review, notify, show, cancel, inbox, list',
-            useWhen: 'you have a question for the user, want their feedback, or are presenting them with options or a choice — always reach for human instead of guessing or assuming, or laying a choice out as prose, when a person can decide; and whenever the user wants to review a spec, plan, or requirements document, this is the command (use `human review` for anchored line-by-line comments)'
+            desc: 'ask, review, notify, show, cancel, inbox, list',
+            useWhen: 'you have a question for the user, want their feedback, or are presenting them with options or a choice — always reach for human instead of guessing or assuming, or laying a choice out as prose, when a person can decide; and whenever the user wants to review a spec, plan, or requirements document, this is the command for anchored line-by-line comments.'
         },
         help: {
             name: 'human',
             summary: 'human-in-the-loop decisions, document review, and live display',
-            model: "Every body and displayed file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one. ask, approve, and review are kickoffs: they create a kind:'human' node under you and return instantly, never blocking — the human's response is pushed to your inbox when they answer, so keep working (or just end your turn) and you'll be woken with it. review puts a .md live on the human's screen for anchored comments and tracks the file, so edit in place rather than canceling and re-presenting. notify and show create no node.",
+            model: "Every body and displayed file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one. ask and review are kickoffs: they create a kind:'human' node under you and return instantly, never blocking — the human's response is pushed to your inbox when they answer, so keep working (or just end your turn) and you'll be woken with it. ask covers everything from a yes/no sign-off gate (two options) to an open-ended judgment call; review puts a .md live on the human's screen for anchored comments and tracks the file, so edit in place rather than canceling and re-presenting. notify and show create no node.",
         },
         children: [
             humanAsk,
-            humanApprove,
             humanReview,
             humanNotify,
             humanShow,
             humanCancel,
             humanInbox,
             humanList,
+            humanDeck,
+            humanResolve,
             humanRun,
         ],
     });

package/dist/commands/memory/find.js

@@ -57,7 +57,7 @@ export const findLeaf = defineLeaf({
         ],
         output: [
             { name: 'query', type: 'string', required: true, constraint: 'Echo of the input query.' },
-            { name: 'hits', type: 'object[]', required: true, constraint: 'Ranked mode — each: {name, kind, scope, score, short_form}, sorted by score descending. Under --grep instead — each: {path, line, text} for every body line matching the regex, sorted by path then line ascending.' },
+            { name: 'hits', type: 'object[]', required: true, constraint: 'Ranked mode — each: {name, kind, scope, path, score, short_form}, sorted by score descending; path is the absolute file on disk — edit it directly to tweak the doc. Under --grep instead — each: {path, line, text} for every body line matching the regex, sorted by path then line ascending.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands for reading a hit in full or refining the search.' },
         ],
         outputKind: 'object',
@@ -133,10 +133,11 @@ export const findLeaf = defineLeaf({
                 name: h.unit.name,
                 kind: h.unit.kind,
                 scope: h.unit.scope,
+                path: h.unit.path,
                 score: h.score,
                 short_form: h.unit.shortForm,
             })),
-            follow_up: 'Read a hit in full with `crtr memory read <name>`. Add --body to weigh body text, or --grep for an exact regex.',
+            follow_up: 'Read a hit in full with `crtr memory read <name>`, or edit its `path` directly to tweak it. Add --body to weigh body text, or --grep for an exact regex.',
         };
     },
 });

package/dist/commands/memory/lint.js

@@ -1,16 +1,16 @@
 // `crtr memory lint` — the permanent valid-YAML gate over the bounded corpus
 // (the CTO green-checkpoint: zero frontmatter parse errors at authoring time,
 // so an invalid doc fails HERE instead of being silently isolated at runtime).
-// Bounded corpus = the substrate memory dirs (project/user/builtin). Never a
-// filesystem-wide scan.
-import { basename, relative, sep } from 'node:path';
+// Bounded corpus = the substrate memory dirs (ancestor projects/user/builtin).
+// Never a filesystem-wide scan.
+import { basename, join, relative, sep } from 'node:path';
 import { defineLeaf } from '../../core/command.js';
 import { general } from '../../core/errors.js';
 import { warn } from '../../core/output.js';
 import { pathExists, readText, walkFiles } from '../../core/fs-utils.js';
 import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
-import { listInstalledPlugins } from '../../core/resolver.js';
-import { pluginMemoryDir, scopeMemoryDir } from '../../core/scope.js';
+import { listInstalledPlugins, listInstalledPluginsInRoot } from '../../core/resolver.js';
+import { pluginMemoryDir, projectScopeRoots, scopeMemoryDir } from '../../core/scope.js';
 import { isDocKind, RUNGS } from '../../core/substrate/index.js';
 /** The parser normalizes the `always` alias to `content`, so it lints valid. */
 const VALID_RUNGS = [...RUNGS, 'always'];
@@ -107,8 +107,8 @@ export const lintLeaf = defineLeaf({
     run: async () => {
         const findings = [];
         let memoryCount = 0;
-        // Substrate memory stores (project/user/builtin), schema-aware. A scope's
-        // corpus is its NATIVE memory dir plus each enabled plugin's memory dir —
+        // Substrate memory stores (ancestor projects/user/builtin), schema-aware.
+        // A source's corpus is its NATIVE memory dir plus each enabled plugin's memory dir —
         // plugin docs are substrate docs and lint through the same schema gate.
         //    MEMORY.md index files are not substrate docs — YAML-parse only.
         const lintDir = (dir) => {
@@ -121,7 +121,14 @@ export const lintLeaf = defineLeaf({
                 lintFile(file, basename(file) !== 'MEMORY.md', findings);
             }
         };
-        for (const scope of ['project', 'user', 'builtin']) {
+        for (const root of projectScopeRoots()) {
+            lintDir(join(root, 'memory'));
+            for (const plugin of listInstalledPluginsInRoot('project', root)) {
+                if (plugin.enabled)
+                    lintDir(pluginMemoryDir(plugin));
+            }
+        }
+        for (const scope of ['user', 'builtin']) {
             lintDir(scopeMemoryDir(scope));
             for (const plugin of listInstalledPlugins(scope)) {
                 if (plugin.enabled)

package/dist/commands/memory/list.js

@@ -14,7 +14,7 @@ export const listLeaf = defineLeaf({
             { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Filter to a single scope. Default: all resolved scopes.' },
         ],
         output: [
-            { name: 'items', type: 'object[]', required: true, constraint: 'One row per document. Each: {name, title, short_form, kind, scope, is_dir}. A directory INDEX.md surfaces as a dir entry (is_dir true, name = the directory path with a trailing slash); is_dir is false for an ordinary doc. short_form is the abbreviated hook — shown here and nowhere else. Sorted by scope then kind then name ascending.' },
+            { name: 'items', type: 'object[]', required: true, constraint: 'One row per document. Each: {name, title, short_form, kind, scope, path, is_dir}. path is the absolute file on disk — edit it directly to tweak the doc. A directory INDEX.md surfaces as a dir entry (is_dir true, name = the directory path with a trailing slash, path = its INDEX.md); is_dir is false for an ordinary doc. short_form is the abbreviated hook — shown here and nowhere else. Sorted by scope then kind then name ascending.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands — read a document in full or narrow the inventory.' },
         ],
         outputKind: 'object',
@@ -43,7 +43,7 @@ export const listLeaf = defineLeaf({
             // slash, flagged is_dir, so the inventory distinguishes it from a doc.
             const isDir = isIndexName(sub.name);
             const name = isDir ? indexDirOf(sub.name) + '/' : sub.name;
-            addItem({ name, kind: sub.kind, scope: sub.scope, shortForm: sub.shortForm, isDir });
+            addItem({ name, kind: sub.kind, scope: sub.scope, path: sub.path, shortForm: sub.shortForm, isDir });
         }
         items.sort((a, b) => {
             const sr = scopeRank(a.scope) - scopeRank(b.scope);
@@ -61,9 +61,10 @@ export const listLeaf = defineLeaf({
                 short_form: d.shortForm,
                 kind: d.kind,
                 scope: d.scope,
+                path: d.path,
                 is_dir: d.isDir,
             })),
-            follow_up: 'Read one in full with `crtr memory read <name>`. Narrow with --kind / --scope, or search a topic with `crtr memory find <query>`.',
+            follow_up: 'Read one in full with `crtr memory read <name>`, or edit its `path` directly to tweak it. Narrow with --kind / --scope, or search a topic with `crtr memory find <query>`.',
         };
     },
 });

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

@@ -0,0 +1 @@
+export declare const originLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/memory/origin.js

@@ -0,0 +1,88 @@
+import { defineLeaf } from '../../core/command.js';
+import { CrtrError, notFound } from '../../core/errors.js';
+import { resolveMemoryDoc } from '../../core/memory-resolver.js';
+import { getNode } from '../../core/canvas/canvas.js';
+import { contextDir } from '../../core/canvas/paths.js';
+export const originLeaf = defineLeaf({
+    name: 'origin',
+    description: 'deref a memory document back to the node + conversation that created it',
+    whenToUse: 'you are looking at a stored memory and want to know WHERE it came from — which node authored it, in what conversation, when, and in which project. Reads the `origin` provenance block the runtime stamps at creation and derefs the node pointer to its live session conversation, context dir, and current state. Docs hand-authored or created before provenance capture carry no origin — the command says so rather than guessing.',
+    help: {
+        name: 'memory origin',
+        summary: 'resolve a doc name to its creation provenance and deref the originating node',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`). Resolved across scopes: project > user > builtin.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'Resolved document name.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the document on disk.' },
+            { name: 'origin_recorded', type: 'boolean', required: true, constraint: 'true when the doc carries an `origin` provenance block; false for hand-authored or pre-provenance docs.' },
+            { name: 'created', type: 'string', required: false, constraint: 'ISO timestamp the doc was created. Absent when origin_recorded is false.' },
+            { name: 'cwd', type: 'string', required: false, constraint: 'Working directory the authoring conversation ran in.' },
+            { name: 'node', type: 'string', required: false, constraint: 'Node id that authored the doc, or null when written by a human at the CLI (no node).' },
+            { name: 'node_present', type: 'boolean', required: false, constraint: 'true when that node still exists on the canvas (deref below is live); false when it has been pruned.' },
+            { name: 'node_kind', type: 'string', required: false, constraint: 'Kind of the authoring node (only when node_present).' },
+            { name: 'node_mode', type: 'string', required: false, constraint: 'Mode of the authoring node (only when node_present).' },
+            { name: 'node_status', type: 'string', required: false, constraint: 'Current lifecycle status of the authoring node (only when node_present).' },
+            { name: 'node_description', type: 'string', required: false, constraint: 'The authoring node\u2019s description (only when node_present).' },
+            { name: 'session_file', type: 'string', required: false, constraint: 'Absolute path to the originating conversation\u2019s pi session .jsonl (only when node_present and a session was captured) \u2014 read it to see the conversation that produced the doc.' },
+            { name: 'context_dir', type: 'string', required: false, constraint: 'Absolute path to the authoring node\u2019s context dir (its shared document store).' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands to inspect the origin.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const nameRaw = input['name'];
+        let doc;
+        try {
+            doc = resolveMemoryDoc(nameRaw);
+        }
+        catch (e) {
+            if (!(e instanceof CrtrError && e.code === 'not_found'))
+                throw e;
+        }
+        if (doc === undefined) {
+            throw notFound(`memory document not found: ${nameRaw}`, {
+                memory: nameRaw,
+                next: 'Run `crtr memory find <query>` to discover documents, or `crtr memory list` to browse the inventory.',
+            });
+        }
+        const origin = doc.frontmatter?.['origin'];
+        if (origin === undefined || typeof origin !== 'object') {
+            return {
+                name: doc.name,
+                path: doc.path,
+                origin_recorded: false,
+                follow_up: 'No provenance recorded \u2014 this doc was hand-authored or created before provenance capture. Read its body with `crtr memory read ' +
+                    doc.name +
+                    '`.',
+            };
+        }
+        const str = (v) => (typeof v === 'string' ? v : null);
+        const nodeId = str(origin['node']);
+        const node = nodeId !== null ? getNode(nodeId) : null;
+        const sessionFile = str(node?.pi_session_file);
+        const followUp = node !== null
+            ? `Read the originating conversation at \`${sessionFile ?? '(no session captured)'}\`, browse its shared docs at \`${contextDir(nodeId)}\`, or attach live with \`crtr surface attach ${nodeId}\`.`
+            : nodeId !== null
+                ? `The authoring node \`${nodeId}\` has been pruned from the canvas; its context dir may persist at \`${contextDir(nodeId)}\`.`
+                : 'Authored by a human at the CLI \u2014 no node conversation to deref.';
+        return {
+            name: doc.name,
+            path: doc.path,
+            origin_recorded: true,
+            created: str(origin['created']) ?? undefined,
+            cwd: str(origin['cwd']) ?? undefined,
+            node: nodeId ?? undefined,
+            node_present: nodeId !== null ? node !== null : undefined,
+            node_kind: node?.kind ?? undefined,
+            node_mode: node?.mode ?? undefined,
+            node_status: node?.status ?? undefined,
+            node_description: node?.description ?? undefined,
+            session_file: sessionFile ?? undefined,
+            context_dir: nodeId !== null ? contextDir(nodeId) : undefined,
+            follow_up: followUp,
+        };
+    },
+});

package/dist/commands/memory/read.js

@@ -7,7 +7,7 @@ import { MEMORY_KINDS } from './shared.js';
 export const readLeaf = defineLeaf({
     name: 'read',
     description: 'load a memory document body by name',
-    whenToUse: 'a task in front of you matches a stored document and you already know its name — read it before improvising. Resolves the path-derived name across scopes by precedence (project > user > builtin), with leaf-name fallback like skills. You name the document by its crtr identifier, never a file path — do not cat or find the markdown off disk. Reach for `crtr memory find` first when you do not yet know which document applies.',
+    whenToUse: 'a task in front of you matches a stored document and you already know its name — read it before improvising. Resolves the path-derived name across scopes by precedence (project > user > builtin), with leaf-name fallback. You name the document by its crtr identifier, never a file path — do not cat or find the markdown off disk. Reach for `crtr memory find` first when you do not yet know which document applies.',
     help: {
         name: 'memory read',
         summary: 'resolve a path-derived name to its document body, frontmatter stripped unless --frontmatter',
@@ -20,7 +20,7 @@ export const readLeaf = defineLeaf({
             { name: 'name', type: 'string', required: true, constraint: 'Resolved document name.' },
             { 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: 'path', type: 'string', required: true, constraint: 'Absolute path to the document on disk — edit this file directly to tweak the doc in place.' },
             { name: 'content', type: 'string', required: true, constraint: 'Document body. Frontmatter stripped unless --frontmatter is set.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Hints at variant flags or next commands.' },
         ],
@@ -58,7 +58,7 @@ export const readLeaf = defineLeaf({
                     scope: doc.scope,
                     path: doc.path,
                     content,
-                    follow_up: 'Add --frontmatter to include the YAML header. Browse the inventory with `crtr memory list`.',
+                    follow_up: 'Read the raw file at `path` to view the YAML frontmatter or edit this memory. Browse the inventory with `crtr memory list`.',
                 };
             }
         }

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

@@ -26,11 +26,16 @@ 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;
+/** Provenance for a doc at the moment it is created: when, where, and which
+ *  node's conversation authored it. Read from the env the runtime injects into
+ *  every node's pi process (CRTR_NODE_ID/KIND/MODE/NODE_CWD); when invoked
+ *  outside a node (a human at the CLI) only `created` + `cwd` are recorded.
+ *  Stamped ONCE at create and preserved verbatim on every later update —
+ *  `crtr memory origin <name>` derefs the `node` pointer back to the live node
+ *  (its session conversation, context dir, current state). */
+export declare function buildOrigin(): Record<string, unknown>;
 /** Serialize a substrate frontmatter record + body into a complete `.md`
  *  document. Frontmatter is emitted as a `---` fenced YAML block (the `yaml`
  *  package — the same one the parser uses — so nested gate maps and applies-to
- *  arrays round-trip), in canonical field order with preserved extras last. The
- *  skill-shaped `serializeFrontmatter` in core can only represent
- *  name/description/type/keywords, so it cannot carry the substrate fields —
- *  hence this focused serializer. */
+ *  arrays round-trip), in canonical field order with preserved extras last. */
 export declare function serializeMemoryDoc(frontmatter: Record<string, unknown>, body: string): string;

package/dist/commands/memory/shared.js

@@ -1,8 +1,8 @@
-// Shared constants + helpers for the `crtr memory` command family (task B2).
-// The leaf handlers (list/read/find/write) consume the resolver, substrate
-// schema, scope, and skill-resolver modules and build their documented output
-// objects on top of the small helpers here. Nothing in this file forks on kind
-// or re-implements the schema/gate/resolver — it only composes them.
+// Shared constants + helpers for the `crtr memory` command family. The leaf
+// handlers (list/read/find/write) consume the resolver, substrate schema, and
+// scope modules and build their documented output objects on top of the small
+// helpers here. Nothing in this file forks on kind or re-implements the
+// schema/gate/resolver — it only composes them.
 import { join } from 'node:path';
 import { stringify as yamlStringify, parse as yamlParse } from 'yaml';
 import { usage } from '../../core/errors.js';
@@ -102,7 +102,9 @@ export function coerceAppliesTo(raw) {
     return parts.length === 1 ? parts[0] : parts;
 }
 // Canonical frontmatter field order for a substrate document. Known fields come
-// first in this order; any preserved-on-update extras append after.
+// first in this order; any preserved-on-update extras append after. `origin` is
+// provenance the runtime stamps at creation (never the author) — it sorts last
+// of the known fields so the authoring contract stays at the top of the block.
 const FRONTMATTER_ORDER = [
     'kind',
     'when-and-why-to-read',
@@ -112,14 +114,30 @@ const FRONTMATTER_ORDER = [
     'gate',
     'applies-to',
     'read-when',
+    'origin',
 ];
+/** Provenance for a doc at the moment it is created: when, where, and which
+ *  node's conversation authored it. Read from the env the runtime injects into
+ *  every node's pi process (CRTR_NODE_ID/KIND/MODE/NODE_CWD); when invoked
+ *  outside a node (a human at the CLI) only `created` + `cwd` are recorded.
+ *  Stamped ONCE at create and preserved verbatim on every later update —
+ *  `crtr memory origin <name>` derefs the `node` pointer back to the live node
+ *  (its session conversation, context dir, current state). */
+export function buildOrigin() {
+    const env = process.env;
+    const origin = {
+        created: new Date().toISOString(),
+        cwd: env['CRTR_NODE_CWD'] ?? process.cwd(),
+    };
+    const nodeId = env['CRTR_NODE_ID'];
+    if (nodeId !== undefined && nodeId !== '')
+        origin['node'] = nodeId;
+    return origin;
+}
 /** Serialize a substrate frontmatter record + body into a complete `.md`
  *  document. Frontmatter is emitted as a `---` fenced YAML block (the `yaml`
  *  package — the same one the parser uses — so nested gate maps and applies-to
- *  arrays round-trip), in canonical field order with preserved extras last. The
- *  skill-shaped `serializeFrontmatter` in core can only represent
- *  name/description/type/keywords, so it cannot carry the substrate fields —
- *  hence this focused serializer. */
+ *  arrays round-trip), in canonical field order with preserved extras last. */
 export function serializeMemoryDoc(frontmatter, body) {
     const ordered = {};
     for (const key of FRONTMATTER_ORDER) {

package/dist/commands/memory/write.js

@@ -2,7 +2,7 @@ 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, coerceReadWhen, serializeMemoryDoc, } from './shared.js';
+import { MEMORY_KINDS, MEMORY_SCOPES, VISIBILITY_RUNGS, resolveWriteTarget, memoryFilePath, buildOrigin, coerceGate, coerceAppliesTo, coerceReadWhen, serializeMemoryDoc, } from './shared.js';
 export const writeLeaf = defineLeaf({
     name: 'write',
     description: 'create or update a memory document',
@@ -10,24 +10,23 @@ 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. 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' +
-            '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`.',
+        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. knowledge is consulted for facts or procedures; preference directs behavior. The kind choice is about how the doc is used, not about how long it is.\n\n' +
+            'Set both visibility rungs explicitly on create. There is no kind default. `none`, `name`, `preview`, and `content` move from least to most loaded: `none` keeps the doc out of auto-load and on-read surfaces, `name` is the bare doc tag only, `preview` is the name + envelope + routing line (`when-and-why-to-read`), and `content` inlines the whole body when the body is short enough to justify it. Each axis is independent; usually one carries a real rung and the other is `none`. When a doc is short enough to state in a single sentence — a one-line preference, or a knowledge fact that fits in a sentence — skip `preview` and use `name` or `content` directly: the routing line would run longer than the doc itself, so a `preview` rung just adds words. Sentence-length `content` docs are not just acceptable, they are correct. Never pad a memory to be more verbose than the rule or fact it carries.\n\n' +
+            'Choose the hook — boot vs file-read. Behavior and how-to procedure surface at boot. Knowledge about code belongs next to the code: put the file in that directory’s .crouter/memory/ and it fires positionally when files there are read, costing nothing at boot. A knowledge doc about a person or process has no code directory to anchor to, so on-read triggering is meaningless — route it through boot instead and set the boot rung to `preview` when you want the routing line to surface.\n\n' +
+            'Write the routing line (--when-and-why-to-read) first, before storing anything: "When <circumstance>, this <kind> should be read because <payoff>." The test is whether a stranger mid-task can 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 — ask the user one sharp question instead of improvising. Never paraphrase the advice in the routing line; keep it about when to read and why the read is worth it.\n\n' +
+            'Gate and read-when share the same predicate language: a field map is AND-ed across fields; dotted fields resolve nested values; field matchers may be scalar, array, or object. Scalar matchers do exact equality, with arrays matching any element. Array matchers do membership or intersection. Object matchers accept `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, and `lte`. Combinators are `all`, `any`, and `not`; sibling field matchers next to them are AND-ed in. An empty condition is inert. An unknown op never matches.\n\n' +
+            'Find before write. Group related docs with path names (area/topic). Do not store what is already recorded or what only matters to this conversation. Body is for current truth, not history. Provenance is automatic on create and preserved on update. Validate after authoring.',
         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: 'positional', name: 'name', required: true, constraint: 'Path-derived identity: one segment, or several joined with `/` to nest the document under a directory and group it with related docs → 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.' },
             { 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. 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: 'gate', type: 'string', required: false, constraint: 'Frontmatter gate — YAML/JSON object predicate over node config using the same field/matcher vocabulary described in the guide.' },
             { 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: 'read-when', type: 'string', required: false, constraint: 'Frontmatter read-when — YAML/JSON object predicate over a read file’s own frontmatter using the same field/matcher vocabulary described in the guide.' },
             { 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>.' },
         ],
@@ -35,7 +34,7 @@ export const writeLeaf = defineLeaf({
             { name: 'name', type: 'string', required: true, constraint: 'The path-derived document name written.' },
             { name: 'kind', type: 'string', required: true, constraint: 'Kind recorded in frontmatter.' },
             { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was written to: user or project.' },
-            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the written document.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the written document — edit this file directly for later body tweaks instead of re-running write.' },
             { name: 'created', type: 'boolean', required: true, constraint: 'true when a new document was created, false when an existing one was updated in place.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands — read it back or list the inventory.' },
         ],
@@ -74,6 +73,12 @@ export const writeLeaf = defineLeaf({
         // kind is required, always set. Optionals only overlay when provided so an
         // update never erases a field the caller did not mention.
         frontmatter['kind'] = kind;
+        // Provenance is runtime-stamped ONCE, at creation — who/when/where authored
+        // this doc. An update inherits the existing `origin` via the spread above and
+        // never overwrites it, so it always points at the conversation that created
+        // the doc, not the last one to touch it. `crtr memory origin <name>` derefs it.
+        if (created)
+            frontmatter['origin'] = buildOrigin();
         const setIf = (key, value) => {
             if (value !== undefined)
                 frontmatter[key] = value;
@@ -97,7 +102,7 @@ export const writeLeaf = defineLeaf({
             scope,
             path,
             created,
-            follow_up: `Read it back with \`crtr memory read ${name}\`, or browse the inventory with \`crtr memory list\`.`,
+            follow_up: `Read it back with \`crtr memory read ${name}\`, edit ${path} directly for later tweaks, or browse the inventory with \`crtr memory list\`.`,
         };
     },
 });

package/dist/commands/memory.js

@@ -1,13 +1,11 @@
-// `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
-// catalog dynamicState.
+// `crtr memory` subtree — the document substrate (knowledge and preferences)
+// accessed via the CLI. Flat leaves: list, read, find, write, lint.
 import { defineBranch } from '../core/command.js';
 import { listLeaf } from './memory/list.js';
 import { readLeaf } from './memory/read.js';
 import { findLeaf } from './memory/find.js';
 import { writeLeaf } from './memory/write.js';
+import { originLeaf } from './memory/origin.js';
 import { lintLeaf } from './memory/lint.js';
 export function registerMemory() {
     return defineBranch({
@@ -15,13 +13,13 @@ export function registerMemory() {
         rootEntry: {
             concept: 'a memory document you read on demand — knowledge or a preference',
             desc: 'list, read, search, and write memory documents',
-            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.',
+            useWhen: 'a task matches stored knowledge or a preference — read it before improvising. Use read to load one document, list to browse the inventory, and find to search by topic when you do not yet know the name. Names are path-derived crtr identifiers, not file paths — read docs through the command surface, never cat or find the markdown off disk. To edit one in place, every command emits the doc’s absolute path — edit that file directly.',
         },
         help: {
             name: 'memory',
             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.',
+            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 — use it for new docs and frontmatter changes; for a quick body tweak, edit the `path` every leaf emits directly. `lint` strict-parses the whole bounded corpus and fails on any invalid frontmatter — run it after authoring. `origin` derefs a doc back to its provenance — the node, conversation, and project that created it (the runtime stamps an `origin` block at write time; this reads it and resolves the node pointer to its live session + context dir). 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],
+        children: [listLeaf, readLeaf, findLeaf, writeLeaf, originLeaf, lintLeaf],
     });
 }

package/dist/commands/node-context.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const nodeContextLeaf: LeafDef;