@crouton-kit/crouter 0.3.33 → 0.3.35

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 knowledge docs 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>.' },
         ],
@@ -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;

package/dist/commands/memory.js

@@ -5,6 +5,7 @@ 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({
@@ -12,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 — to READ a doc go through these commands, 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.',
+            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 — 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. 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.js

@@ -1,4 +1,4 @@
-// `crtr node context` — browse this node's context and reports dirs and those of
+// `crtr node inspect context` — browse this node's context and reports dirs and those of
 // every node it subscribes to, in one read-only nvim file explorer.
 //
 // crtr makes a STRONG CLAIM that nvim is installed (see crouter/CLAUDE.md): the
@@ -10,7 +10,7 @@
 // The symlinks are torn down when nvim exits; the real node dirs are untouched.
 //
 // The /context popup (src/pi-extensions/canvas-context.ts) shells this leaf inside
-// a tmux display-popup, exactly as /view shells `crtr view pick`. Piped / non-TTY
+// a tmux display-popup, exactly as /view shells the surface-view picker. Piped / non-TTY
 // it prints the resolved roster (node · path · file count) and exits 0.
 import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, symlinkSync } from 'node:fs';
@@ -107,7 +107,7 @@ export const nodeContextLeaf = defineLeaf({
     description: 'browse this node + its subscriptions’ context and reports dirs in an nvim popup',
     whenToUse: 'you want to SEE what the nodes you subscribe to have written — open a read-only nvim file explorer over this node’s context and reports dirs and every subscribed node’s context and reports dirs at once. The /context popup shells this. Piped it prints the roster instead',
     help: {
-        name: 'node context',
+        name: 'node inspect context',
         summary: 'open a read-only nvim file explorer over this node’s context and reports dirs and those of every node it subscribes to',
         params: [
             { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node id to root on. Defaults to $CRTR_NODE_ID (the calling node).' },
@@ -144,7 +144,7 @@ export const nodeContextLeaf = defineLeaf({
         if (!nvimAvailable()) {
             throw new InputError({
                 error: 'nvim_missing',
-                message: 'nvim is not on PATH — `crtr node context` opens the context explorer in nvim',
+                message: 'nvim is not on PATH — `crtr node inspect context` opens the context explorer in nvim',
                 next: 'Install Neovim (macOS: `brew install neovim`; Debian/Ubuntu: `apt install neovim`), then retry.',
             });
         }

package/dist/commands/node-snapshot.js

@@ -64,7 +64,7 @@ export const nodeSnapshotLeaf = defineLeaf({
     description: 'read a dormant node session snapshot without launching its broker',
     whenToUse: 'you need a read-only broker-compatible snapshot of a dormant node; it copies the session JSONL before parsing and never revives the node',
     help: {
-        name: 'node snapshot',
+        name: 'node inspect snapshot',
         summary: 'read-only dormant node snapshot in the broker welcome shape',
         params: [{ kind: 'positional', name: 'id', type: 'string', required: true, constraint: 'Canvas node id.' }],
         output: [
@@ -74,6 +74,9 @@ export const nodeSnapshotLeaf = defineLeaf({
         ],
         outputKind: 'object',
         effects: ['Read-only: copies the session JSONL to a temp dir, parses the copy, then deletes the temp dir. Does not launch or revive brokers.'],
+        // Full session reconstruction (every message) for tooling, not a
+        // human/agent glance — collapse it in the attach viewer by default.
+        preview: { suppressOutput: true },
     },
     run: async (input) => {
         const nodeId = input['id'];

package/dist/commands/node.d.ts

@@ -6,11 +6,11 @@ import { type BranchDef } from '../core/command.js';
 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
+ *  `node lifecycle recycle` / `node lifecycle demote` / `node config --lifecycle` / `node lifecycle close` / `node
  *  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
+ *    1. VIEWER pane (broker host): a `crtr surface attach` viewer self-tags its pane with
  *       the node it views (`@crtr_node`). A broker engine runs DETACHED with
  *       window=null, so the window→node lookup never finds it — the pane tag is
  *       the only handle. Checked FIRST because the tag is pane-precise, whereas a