@north-light/crouter 0.3.154

package/dist/commands/memory/shared.js

@@ -0,0 +1,225 @@
+// 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 { existsSync, realpathSync, statSync } from 'node:fs';
+import { join, resolve as resolvePath } from 'node:path';
+import { stringify as yamlStringify, parse as yamlParse } from 'yaml';
+import { usage } from '../../core/errors.js';
+import { CRTR_DIR_NAME } from '../../types.js';
+import { scopeMemoryDir, projectScopeRoot, ensureProjectScopeRoot, resetScopeCache, } from '../../core/scope.js';
+import { loadProfileManifest, profileMemoryDir } from '../../core/profiles/manifest.js';
+import { memoryDir as nodeMemoryDir } from '../../core/runtime/memory.js';
+// 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'];
+// Scope choices for filtering / targeting (builtin is read-only, not writable).
+// `node` is the this-node store, writable only inside a running node.
+export const MEMORY_SCOPES = ['user', 'project', 'profile', 'node'];
+/** Scope sort weight matching resolution precedence (node > project stack >
+ *  profile > user > builtin). Used by `list` for its "scope then kind then
+ *  name" ordering. */
+export function scopeRank(scope) {
+    return scope === 'node' ? -1 : scope === 'project' ? 0 : scope === 'profile' ? 1 : scope === 'user' ? 2 : 3;
+}
+/** Resolve the write target scope + its memory dir. Default: project when a
+ *  project scope exists for the cwd, else user. An explicit `--scope project`
+ *  with no project scope yet scaffolds one (ensureProjectScopeRoot). User scope
+ *  always resolves. `--scope profile` is NEVER a default — it requires a
+ *  selected profile, from `profileArg` (an explicit `--profile <id-or-name>`)
+ *  or else the process's `CRTR_PROFILE_ID`, resolved through the centralized
+ *  `loadProfileManifest` (never a raw path join). `dirArg` (an explicit
+ *  `--dir <path>`) pins the EXACT project directory, cwd-free: the target is
+ *  `<dir>/.crouter/memory/`, scaffolded if absent, never the cwd-ancestor walk
+ *  — the way a profiled agent writes into any project in its purview, and the
+ *  only way to target a dir shadowed by an ancestor store. `--scope node`
+ *  targets the this-node store (`nodes/<CRTR_NODE_ID>/context/memory/`) and
+ *  requires a running node. Returns the absolute `<root>/memory` dir to write
+ *  under. */
+export function resolveWriteTarget(scopeArg, profileArg, dirArg) {
+    if (dirArg !== undefined && dirArg !== '') {
+        if (scopeArg !== undefined && scopeArg !== 'project') {
+            throw usage(`--dir targets a project store and cannot combine with --scope ${scopeArg}`);
+        }
+        if (profileArg !== undefined && profileArg !== '') {
+            throw usage('--profile only applies to --scope profile; --dir targets a project store', {
+                received: profileArg,
+                next: 'Drop --profile when using --dir.',
+            });
+        }
+        const abs = resolvePath(dirArg);
+        if (!existsSync(abs) || !statSync(abs).isDirectory()) {
+            throw usage(`--dir does not exist or is not a directory: ${dirArg}`, {
+                received: dirArg,
+                next: 'Pass an existing project directory.',
+            });
+        }
+        let real = abs;
+        try {
+            real = realpathSync(abs);
+        }
+        catch {
+            /* fall back to the resolved path */
+        }
+        // The scaffold (mkdir of `.crouter/memory/`) happens at write time via the
+        // writer's ensureDir; drop the scope cache so this process's later
+        // resolves see the new root.
+        resetScopeCache();
+        return { scope: 'project', memoryDir: join(real, CRTR_DIR_NAME, 'memory') };
+    }
+    let scope;
+    if (scopeArg === 'user' || scopeArg === 'project' || scopeArg === 'profile' || scopeArg === 'node') {
+        scope = scopeArg;
+    }
+    else if (scopeArg !== undefined) {
+        throw usage(`invalid --scope: ${scopeArg} (expected user|project|profile|node)`);
+    }
+    else {
+        scope = projectScopeRoot() !== null ? 'project' : 'user';
+    }
+    if (profileArg !== undefined && profileArg !== '' && scope !== 'profile') {
+        throw usage(`--profile only applies to --scope profile (resolved scope: ${scope})`, {
+            received: profileArg,
+            next: 'Drop --profile, or pass --scope profile to target a specific profile store.',
+        });
+    }
+    if (scope === 'node') {
+        // The this-node store: `nodes/<CRTR_NODE_ID>/context/memory/`. Available
+        // only inside a running node; the same dir render.ts's nodeLocalDocs loads
+        // at boot, so a doc written here rides into this node's knowledge block.
+        const nodeId = process.env['CRTR_NODE_ID'] || '';
+        if (nodeId === '') {
+            throw usage('node scope requires a running node (CRTR_NODE_ID unset); rerun inside a node');
+        }
+        return { scope: 'node', memoryDir: nodeMemoryDir(nodeId) };
+    }
+    if (scope === 'profile') {
+        const profileIdOrName = profileArg && profileArg !== '' ? profileArg : process.env['CRTR_PROFILE_ID'] || '';
+        if (profileIdOrName === '') {
+            throw usage('profile scope requires a selected profile; rerun inside a profiled node or pass --profile');
+        }
+        const { profileId } = loadProfileManifest(profileIdOrName);
+        return { scope: 'profile', memoryDir: profileMemoryDir(profileId) };
+    }
+    let memoryDir = scopeMemoryDir(scope);
+    if (!memoryDir && scope === 'project') {
+        // Explicit --scope project with no project root yet → scaffold it.
+        memoryDir = join(ensureProjectScopeRoot(), 'memory');
+    }
+    if (!memoryDir)
+        throw usage(`no ${scope} scope available for writing memory documents`);
+    return { scope, memoryDir };
+}
+/** Map a path-derived name (`topic` or `area/topic`) to its file path under a
+ *  memory dir, guarding against traversal/absolute escapes. */
+export function memoryFilePath(memoryDir, name) {
+    const segments = name.split('/').filter((s) => s.length > 0);
+    if (segments.length === 0)
+        throw usage('memory document name required');
+    if (segments.some((s) => s === '.' || s === '..')) {
+        throw usage(`invalid memory document name: ${name}`);
+    }
+    return join(memoryDir, ...segments) + '.md';
+}
+/** Coerce a `--gate` string into a predicate tree. The gate field MUST be a
+ *  YAML/JSON object (the field→matcher map the schema expects). Throws a usage
+ *  error when the input fails to parse or does not parse to a non-null,
+ *  non-array object — a scalar or array gate silently makes a doc never-eligible
+ *  (the matcher engine ignores non-object predicates), so passing one is always
+ *  a mistake and must be caught at authoring time rather than stored. */
+function parseYamlObject(raw) {
+    const parsed = yamlParse(raw);
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        return parsed;
+    }
+    return `expected an object, got ${JSON.stringify(parsed)}`;
+}
+export function coerceGate(raw) {
+    const result = parseYamlObject(raw);
+    if (typeof result === 'string') {
+        throw usage(`--gate must be a YAML/JSON object (field→matcher map): ${result}. ` +
+            `Example: --gate '{kind: design}' or --gate '{orchestration.depth: {gte: 2}}'`);
+    }
+    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 repeatable `--applies-to` values (already an array from the argv
+ *  parser) to the schema's glob form: one value stays a bare string, several
+ *  become an array. Each value is trimmed; empty entries are rejected loudly
+ *  (a silently-dropped glob is a routing bug waiting to happen). */
+export function coerceAppliesTo(values) {
+    const cleaned = values.map((v) => v.trim());
+    if (cleaned.some((v) => v.length === 0)) {
+        throw usage('--applies-to values must not be empty');
+    }
+    return cleaned.length === 1 ? cleaned[0] : cleaned;
+}
+// Canonical frontmatter field order for a substrate document. Known fields come
+// 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',
+    'short-form',
+    'system-prompt-visibility',
+    'file-read-visibility',
+    'gate',
+    'applies-to',
+    'read-when',
+    'rationale',
+    '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. */
+export function serializeMemoryDoc(frontmatter, body) {
+    const ordered = {};
+    for (const key of FRONTMATTER_ORDER) {
+        if (frontmatter[key] !== undefined)
+            ordered[key] = frontmatter[key];
+    }
+    for (const key of Object.keys(frontmatter)) {
+        if (!(key in ordered) && frontmatter[key] !== undefined)
+            ordered[key] = frontmatter[key];
+    }
+    const yamlText = yamlStringify(ordered).replace(/\n+$/, '');
+    const cleanBody = body.replace(/^\n+/, '').replace(/\s+$/, '');
+    return `---\n${yamlText}\n---\n\n${cleanBody}\n`;
+}

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

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

package/dist/commands/memory/write.js

@@ -0,0 +1,142 @@
+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, buildOrigin, coerceGate, coerceAppliesTo, coerceReadWhen, serializeMemoryDoc, } from './shared.js';
+// A topic's memory set stays usable only when authors treat cohesion as a creation
+// gate; otherwise small corrections accumulate as overlapping leaves whose routing
+// lines cannot tell a future reader which one owns the topic.
+export const writeLeaf = defineLeaf({
+    name: 'write',
+    description: 'create or update a memory document',
+    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. 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' +
+            'Store reusable current truth, not session notes. Useful memories are non-obvious procedures, gotchas, durable preferences, cross-repo conventions, and amendments to plans/specs that future agents must honor. Put plan/spec amendments under path names like `projects/<topic>/...`; add `projects/<topic>/INDEX.md` with `name` visibility so the topic is discoverable without loading the whole body. Do not store chat summaries, implementation history, or facts already recorded in the repo.\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 scope. `project` is for facts any agent in one repo needs. `user` is for person-wide facts and preferences that should follow the user everywhere. `profile` is for the profile’s bundle of dirs: cross-repo conventions, how the pieces relate, or the user’s stance toward that body of work. `node` is the narrowest — the this-node store (`nodes/<CRTR_NODE_ID>/context/memory/`), scratch memory only this running node sees; it rides straight into this node’s knowledge block and dies with the node. When unsure, choose the narrowest scope that will still reach the next agent who needs it.\n\n' +
+            'AGENTS.md is the one special doc: a store’s always-loaded operating guide, and every dir a profile manages should carry one (`crtr memory lint` flags the gaps). Name the doc AGENTS, target the exact dir with --dir, and set system-prompt-visibility to `content` so every agent working there boots with it. It is a front door, not a manual — constraints and gotchas, the key commands, a few sentences of architecture orientation, and only the conventions that differ from defaults. Every line is paid by every session in that dir forever: prefer a pointer (“when X, run Y -h / read Z, because W”) over inlined how-to, and cut any line that would not change an agent’s behavior.\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/ (`--dir <project-dir>` targets it exactly, from anywhere) 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 <broader downstream payoff>." WHY is the READER’s payoff — the consequence they secure for the task in front of them by spending the read — never what the document says, its rule, or why it should be obeyed. The trap most authors fall into is the DISGUISED restatement: a because-clause that reads like a benefit but is just the doc’s own thesis reworded as an outcome. It still fails. The test: if you could derive the because-clause by paraphrasing the doc’s advice, it is a restatement, not a payoff — a real payoff names a consequence in the reader’s world that the document itself never asserts. Bad (naked restatement): "because only genuine first principles belong in taste memory." Bad (restatement in benefit’s clothing): "because keeping the test loop fast and free of speculative tests protects the development pace" — that is the doc’s rule in outcome costume, derivable straight from its advice. Good: "because identifying throughlines in user taste lets future decisions be made faster and with less re-litigation." The stranger test: someone mid-task who has NOT read the doc must be able to decide from this one line alone whether the read is worth it. 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.\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. Prefer slightly expanding an existing document, nesting genuinely separate depth under its topic, and updating the existing `when-and-why-to-read` (plus its INDEX router when present) over creating another similar memory. A new document earns its own identity only when it has a distinct read trigger and a coherent body that would make the existing document harder to route or use. 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. Run `crtr memory lint` — the frontmatter validator — after authoring.\n\n' +
+            '--rationale is the gap this doc exists to close — the observed agent failure that prompted it, captured from user signal (a correction, a mistake you watched happen) rather than inferred from the doc’s own content. The bar: if the rationale is guessable from reading the doc, it is not the real one — a guessable gap is one agents do not actually fall into, so a merely-plausible-sounding reason is not worth recording. It is maintainer-facing only and NEVER ships in a delivered surface (boot render, on-read injection, `memory read` content) — it lives in frontmatter, visible only via `memory read --frontmatter`. Omit it when you have no such gap to record; omitting the flag on an update always preserves whatever rationale already exists.',
+        params: [
+            { 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: 'ONE routing sentence: "When <circumstance>, this <kind> should be read because <broader downstream payoff>." WHY is the reader’s payoff — the consequence they secure for their task by reading — NEVER the doc summary, its rule, or that rule reworded as an outcome (a benefit-shaped restatement still fails). 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 — 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, repeatable: true, constraint: 'Frontmatter applies-to — one glob/path scope per flag occurrence. Repeat --applies-to for multiple globs (e.g. --applies-to "src/**" --applies-to "docs/**").' },
+            { 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: 'slash', type: 'bool', required: false, default: false, constraint: 'Presence flags this doc invocable as a pi slash command (`/<name>`, `/` in a nested name rendered as `:`) — the doc body becomes the command’s injected prompt. Default false: most docs are consulted, not invoked.' },
+            { kind: 'flag', name: 'rationale', type: 'string', required: false, constraint: 'Frontmatter rationale — the observed agent failure that made this doc necessary. Maintainer-facing only: never ships in any delivered surface (boot render, on-read injection, `memory read` content), visible only via `memory read --frontmatter`. Omitting this flag on an update PRESERVES an existing rationale unchanged.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Target scope. Default: project when inside a project, else user. `project` resolves to the NEAREST ancestor `.crouter/` walking up from cwd — in a nested workspace that can be a parent’s store, not the dir you are standing in; pass --dir to pin the exact project directory. `profile` requires a selected profile (CRTR_PROFILE_ID) or an explicit --profile. `node` writes to the this-node store (`nodes/<CRTR_NODE_ID>/context/memory/`) — the nearest scope, seen only by this running node, requires a node context.' },
+            { kind: 'flag', name: 'dir', type: 'string', required: false, constraint: 'Exact project directory to write under — targets `<dir>/.crouter/memory/` regardless of cwd or ancestor stores, scaffolding `.crouter/` there if absent. THE way to place a doc in a specific project’s store (e.g. another project in your profile’s purview) without cd’ing there, and the only way to target a dir shadowed by an ancestor store. Implies --scope project; rejects --scope user/profile.' },
+            { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Profile id or name to write under, for --scope profile. Default: the process CRTR_PROFILE_ID (the node\u2019s selected profile). Resolved through the same profile lookup as `crtr profile show`. Rejected (usage error) unless --scope profile is also selected \u2014 never silently ignored for another scope.' },
+            { kind: 'stdin', name: 'body', required: true, constraint: 'Document body (markdown, no frontmatter). Piped on stdin only — this leaf already claims the one positional for NAME, so a second bare argv token is rejected, not silently accepted as the body.' },
+        ],
+        output: [
+            { 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, project, profile, or node.' },
+            { 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: 'frontmatter', type: 'object[]', required: true, constraint: 'The frontmatter options selected by this invocation, in document field order. Each: {key, value}. Preserved fields omitted from an update are not repeated.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands — read it back or list the inventory.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Creates or overwrites memory/<name>.md at the resolved scope with the given frontmatter fields + stdin body.',
+        ],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const kind = input['kind'];
+        const scopeArg = input['scope'];
+        const profileArg = input['profile'];
+        const body = input['body'] ?? '';
+        const dirArg = input['dir'];
+        const { scope, memoryDir } = resolveWriteTarget(scopeArg, profileArg, dirArg);
+        const path = memoryFilePath(memoryDir, name);
+        const created = !pathExists(path);
+        // CREATE requires the read-routing line that becomes the preview — without
+        // it every preview renders empty. UPDATE inherits it from the existing doc.
+        if (created && input['whenAndWhyToRead'] === undefined) {
+            throw usage(`creating ${name} requires --when-and-why-to-read: one read-routing sentence "When <circumstance>, this ${kind} should be read because <broader downstream payoff>." WHY is the reader’s payoff — what the read secures for their task — not the document summary, its rule, or that rule reworded as an outcome.`);
+        }
+        // CREATE requires BOTH visibility rungs as an explicit, case-by-case call —
+        // there is no kind default to lean on. UPDATE inherits whatever the existing
+        // doc already carries.
+        if (created && input['systemPromptVisibility'] === undefined) {
+            throw usage(`creating ${name} requires --system-prompt-visibility: pick a rung explicitly (none|name|preview|content) — there is no kind default. See \`crtr memory write -h\` for what each rung means.`);
+        }
+        if (created && input['fileReadVisibility'] === undefined) {
+            throw usage(`creating ${name} requires --file-read-visibility: pick a rung explicitly (none|name|preview|content) — there is no kind default. See \`crtr memory write -h\` for what each rung means.`);
+        }
+        // In-place update: start from the existing frontmatter (preserving fields
+        // not passed this time), then overlay the provided ones. Create: start clean.
+        const frontmatter = created
+            ? {}
+            : { ...(parseFrontmatterGeneric(readText(path)).data ?? {}) };
+        // 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;
+        };
+        setIf('when-and-why-to-read', input['whenAndWhyToRead']);
+        setIf('short-form', input['shortForm']);
+        setIf('system-prompt-visibility', input['systemPromptVisibility']);
+        setIf('file-read-visibility', input['fileReadVisibility']);
+        if (input['gate'] !== undefined)
+            frontmatter['gate'] = coerceGate(input['gate']);
+        if (input['appliesTo'] !== undefined) {
+            frontmatter['applies-to'] = coerceAppliesTo(input['appliesTo']);
+        }
+        if (input['readWhen'] !== undefined) {
+            frontmatter['read-when'] = coerceReadWhen(input['readWhen']);
+        }
+        if (input['slash'] === true)
+            frontmatter['slash'] = true;
+        setIf('rationale', input['rationale']);
+        writeText(path, serializeMemoryDoc(frontmatter, body));
+        // Confirm exactly the frontmatter choices made by this invocation. On an
+        // update, inherited fields stay in the file but do not masquerade as newly
+        // selected options in the result or its collapsed viewer preview.
+        const selectedKeys = [
+            'kind',
+            ...(input['whenAndWhyToRead'] !== undefined ? ['when-and-why-to-read'] : []),
+            ...(input['shortForm'] !== undefined ? ['short-form'] : []),
+            ...(input['systemPromptVisibility'] !== undefined ? ['system-prompt-visibility'] : []),
+            ...(input['fileReadVisibility'] !== undefined ? ['file-read-visibility'] : []),
+            ...(input['gate'] !== undefined ? ['gate'] : []),
+            ...(input['appliesTo'] !== undefined ? ['applies-to'] : []),
+            ...(input['readWhen'] !== undefined ? ['read-when'] : []),
+            ...(input['slash'] === true ? ['slash'] : []),
+            ...(input['rationale'] !== undefined ? ['rationale'] : []),
+        ];
+        const selectedFrontmatter = selectedKeys.map((key) => ({ key, value: frontmatter[key] }));
+        return {
+            name,
+            kind,
+            scope,
+            path,
+            created,
+            frontmatter: selectedFrontmatter,
+            follow_up: `Read it back with \`crtr memory read ${name}\`, edit ${path} directly for a later body-only tweak, or browse the inventory with \`crtr memory list\`.`,
+        };
+    },
+});

package/dist/commands/memory.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerMemory(): BranchDef;

package/dist/commands/memory.js

@@ -0,0 +1,26 @@
+// `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 { deleteLeaf } from './memory/delete.js';
+import { originLeaf } from './memory/origin.js';
+import { lintLeaf } from './memory/lint.js';
+export function registerMemory() {
+    return defineBranch({
+        name: 'memory',
+        rootEntry: {
+            concept: 'a memory document you read on demand — knowledge or a preference',
+            desc: 'list, read, search, and write memory documents',
+            useWhen: 'durable knowledge and preferences shared across nodes and sessions — use when prior guidance may apply to the current task, or when a non-obvious reusable truth should outlive this conversation. Names are path-derived crtr identifiers, not file paths — read docs through the command surface, never cat or find the markdown off disk.',
+        },
+        help: {
+            name: 'memory',
+            summary: 'list, read, search, and write memory documents — knowledge and preferences',
+            model: 'Documents have path-derived identities and resolve across layered scopes in precedence order: node > project stack > profile > user > builtin. Discover a document with `find` when its name is unknown; address it directly with `read`/`write` when known. A directory may carry an `INDEX.md` with the same frontmatter schema as any doc — it 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.',
+        },
+        children: [listLeaf, readLeaf, findLeaf, writeLeaf, deleteLeaf, 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;

package/dist/commands/node-context.js

@@ -0,0 +1,157 @@
+// `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
+// file explorer + file viewer are nvim, not a hand-rolled view-contract surface.
+// We synthesize a temp dir of LABELLED NODE DIRS — `self` first, then one per
+// subscription — and place `context` / `reports` symlinks inside each label dir
+// for the node's existing on-disk dirs. We then open `nvim -R` on the temp tree
+// (read-only: this is a viewer into siblings' state, edits never write back).
+// The symlinks are torn down when nvim exits; the real node dirs are untouched.
+//
+// Re-plumbed onto the API (Stage B-3): the ROSTER (self + the nodes it
+// subscribes to) comes from crtrd (`GET /v1/nodes/{id}/context`). The nvim
+// viewer tail stays a local viewer surface — the symlink tree is built from pure
+// `contextDir`/`reportsDir`/`nodeDir` path helpers over the roster's node ids,
+// and the on-disk existence filter is a local fs read (neither touches canvas
+// state). The /context popup (src/pi-extensions/canvas-context.ts) shells this
+// leaf inside a tmux display-popup. Piped / non-TTY it prints the roster.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, symlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { contextDir, nodeDir, reportsDir } from '../core/canvas/paths.js';
+import { cliClient, rethrowAsCliError } from './api-client.js';
+/** Make a node label safe as a directory name (netrw shows it verbatim). */
+function sanitize(s) {
+    return s.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'node';
+}
+/** Resolve the current node + every node it subscribes to into browse roots via
+ *  the API, keeping any node whose `context/` or `reports/` dir exists on disk.
+ *  `self` is always first and labelled `self-<name>`. The API roster is
+ *  UNFILTERED (self + all subscriptions); the on-disk existence filter is
+ *  applied locally, and the label/dir are derived from pure path helpers to
+ *  match the pre-API output. */
+async function resolveRoots(selfId) {
+    const listing = await cliClient().getContext(selfId);
+    const roots = [];
+    for (const r of listing.roots) {
+        const ctx = contextDir(r.node_id);
+        const reports = reportsDir(r.node_id);
+        if (!existsSync(ctx) && !existsSync(reports))
+            continue;
+        const short = r.node_id.slice(0, 8);
+        const label = r.self ? `self-${sanitize(r.label)}` : `${sanitize(r.label)}-${short}`;
+        roots.push({
+            nodeId: r.node_id,
+            label,
+            dir: nodeDir(r.node_id),
+            self: r.self,
+            fileCount: r.files,
+            contextDir: ctx,
+            reportsDir: reports,
+        });
+    }
+    return roots;
+}
+/** Is `nvim` on PATH and runnable? */
+function nvimAvailable() {
+    const r = spawnSync('nvim', ['--version'], { stdio: 'ignore' });
+    return r.error === undefined && (r.status === 0 || r.status === null);
+}
+/** Build a temp dir of labelled node dirs. Self's label is prefixed `0-` so it
+ *  sorts first in netrw; each label dir contains `context` and `reports` symlinks
+ *  for whichever of those dirs exist on disk. */
+function buildSymlinkTree(roots) {
+    const tree = mkdtempSync(join(tmpdir(), 'crtr-context-'));
+    for (const r of roots) {
+        const name = r.self ? `0-${r.label}` : r.label;
+        const nodeRoot = join(tree, name);
+        mkdirSync(nodeRoot, { recursive: true });
+        try {
+            if (existsSync(r.contextDir)) {
+                symlinkSync(r.contextDir, join(nodeRoot, 'context'), 'dir');
+            }
+            if (existsSync(r.reportsDir)) {
+                symlinkSync(r.reportsDir, join(nodeRoot, 'reports'), 'dir');
+            }
+        }
+        catch {
+            /* best-effort: a label collision or symlink failure just drops that node */
+        }
+    }
+    return tree;
+}
+export const nodeContextLeaf = defineLeaf({
+    name: 'context',
+    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 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).' },
+        ],
+        output: [
+            { name: 'roots', type: 'object[]', required: true, constraint: 'Resolved browse roots: {node_id, label, dir, self, files}. Returned on the piped/non-TTY path.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'TTY: builds a temp dir of labelled node dirs, symlinking each available `context`/`reports` dir inside it, then execs `nvim -R` on the tree; the temp links are removed on exit (real dirs untouched).',
+            'Requires nvim on PATH (a crtr strong dependency). Missing nvim -> error with an install hint.',
+            'Non-TTY / piped: prints the resolved roster and exits 0; opens nothing.',
+        ],
+    },
+    run: async (input) => {
+        const selfId = input['node']?.trim() || process.env['CRTR_NODE_ID'];
+        if (selfId === undefined || selfId === '') {
+            throw new InputError({
+                error: 'no_node',
+                message: 'no current node: $CRTR_NODE_ID is unset and --node was not given',
+                field: 'node',
+                next: 'Run this from inside a canvas node (the /context popup does), or pass --node <id>.',
+            });
+        }
+        let roots;
+        try {
+            roots = await resolveRoots(selfId);
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+        const rosterOut = roots.map((r) => ({ node_id: r.nodeId, label: r.label, dir: r.dir, self: r.self, files: r.fileCount }));
+        // Non-TTY: print the roster and exit. Opens nothing.
+        if (!process.stdout.isTTY) {
+            return { roots: rosterOut };
+        }
+        if (!nvimAvailable()) {
+            throw new InputError({
+                error: 'nvim_missing',
+                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.',
+            });
+        }
+        const tree = buildSymlinkTree(roots);
+        try {
+            // `nvim -R .` opens netrw (or the user's dir handler) read-only, cwd = the
+            // symlink tree, so the explorer roots on `self` + each subscription.
+            spawnSync('nvim', ['-R', '.'], { cwd: tree, stdio: 'inherit' });
+        }
+        finally {
+            rmSync(tree, { recursive: true, force: true }); // removes symlinks only; targets untouched
+        }
+        return { roots: rosterOut };
+    },
+    render: (result) => {
+        const roots = result['roots'] ?? [];
+        if (roots.length === 0)
+            return 'No node dirs to show (no subscriptions with written context or reports, and this node’s own context/reports dirs are empty/absent).';
+        const lines = roots.map((r) => {
+            const tag = r['self'] === true ? ' (self)' : '';
+            return `  ${String(r['label'])}${tag}\t${String(r['files'])} files\t${String(r['dir'])}`;
+        });
+        return [`Context roots (${roots.length}):`, ...lines].join('\n');
+    },
+});

package/dist/commands/node-inspect-artifacts.d.ts

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