@north-light/crouter 0.3.154

package/dist/commands/memory/lint.js

@@ -0,0 +1,217 @@
+// `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 (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, listInstalledPluginsInRoot } from '../../core/resolver.js';
+import { pluginMemoryDir, projectScopeRoots, scopeMemoryDir } from '../../core/scope.js';
+import { loadProfileManifest, profileMemoryDir } from '../../core/profiles/manifest.js';
+import { getDefaultProfileId } from '../../core/profiles/default-binding.js';
+import { isDocKind, RUNGS } from '../../core/substrate/schema.js';
+/** The parser normalizes the `always` alias to `content`, so it lints valid. */
+const VALID_RUNGS = [...RUNGS, 'always'];
+const RUNG_FIELDS = ['system-prompt-visibility', 'file-read-visibility'];
+/** Schema checks for a doc living in a substrate memory dir: a memory store
+ *  holds ONLY substrate docs, so a missing/invalid `kind` is an authoring
+ *  error here (elsewhere it just means "not a substrate doc"). Both rungs are
+ *  REQUIRED — there is no kind default to lean on, so a missing rung is an
+ *  authoring error. Rung and gate values are checked RAW — the runtime parser
+ *  silently falls back to the neutral floor / inert gates, which is exactly the
+ *  silent tolerance this lint exists to catch at authoring time. */
+export function lintSubstrateSchema(fm) {
+    if (fm === null)
+        return 'missing frontmatter: a memory store doc requires `kind: knowledge|preference`';
+    if (!isDocKind(fm.kind)) {
+        return `invalid kind: ${JSON.stringify(fm.kind)} (expected knowledge|preference)`;
+    }
+    // The retired `when`/`why` pair was merged into one read-routing field. The
+    // hard cut is enforced HERE: an old-shape doc must fail, never be silently
+    // read at runtime.
+    if ('when' in fm || 'why' in fm) {
+        return 'retired `when`/`why` keys: merge them into one `when-and-why-to-read` line — "When <circumstance>, this <kind> should be read because <broader downstream payoff>." WHY is the benefit unlocked by reading, not the document summary, rule, or obedience rationale.';
+    }
+    if (typeof fm['when-and-why-to-read'] !== 'string' || fm['when-and-why-to-read'].trim() === '') {
+        return 'missing `when-and-why-to-read`: one routing line — "When <circumstance>, this <kind> should be read because <broader downstream payoff>." WHY is the benefit unlocked by reading, not the document summary, rule, or obedience rationale.';
+    }
+    for (const field of RUNG_FIELDS) {
+        const v = fm[field];
+        if (v === undefined) {
+            return `missing ${field}: choose a rung explicitly (${RUNGS.join('|')}) — there is no kind default`;
+        }
+        if (typeof v !== 'string' || !VALID_RUNGS.includes(v)) {
+            return `invalid ${field}: ${JSON.stringify(v)} (expected ${RUNGS.join('|')})`;
+        }
+    }
+    const gate = fm.gate;
+    if (gate !== undefined && (gate === null || typeof gate !== 'object' || Array.isArray(gate))) {
+        return `invalid gate: ${JSON.stringify(gate)} (expected a field→matcher object)`;
+    }
+    const appliesTo = fm['applies-to'];
+    if (appliesTo !== undefined &&
+        typeof appliesTo !== 'string' &&
+        !(Array.isArray(appliesTo) && appliesTo.every((g) => typeof g === 'string'))) {
+        return `invalid applies-to: ${JSON.stringify(appliesTo)} (expected a glob or glob list)`;
+    }
+    // read-when (Stream A on-read frontmatter trigger): same well-formed-object
+    // contract as gate — a non-object is inert (never fires), so catch it here.
+    const readWhen = fm['read-when'];
+    if (readWhen !== undefined && (readWhen === null || typeof readWhen !== 'object' || Array.isArray(readWhen))) {
+        return `invalid read-when: ${JSON.stringify(readWhen)} (expected a field→matcher object)`;
+    }
+    // A dead on-read trigger: an explicit applies-to/read-when with nothing to
+    // surface (file-read-visibility none) can never fire — flag it loudly rather
+    // than store a silent no-op.
+    if (fm['file-read-visibility'] === 'none' && (appliesTo !== undefined || readWhen !== undefined)) {
+        return 'dead on-read trigger: applies-to/read-when is set but file-read-visibility is `none` — raise the rung or drop the trigger';
+    }
+    const slash = fm.slash;
+    if (slash !== undefined && typeof slash !== 'boolean') {
+        return `invalid slash: ${JSON.stringify(slash)} (expected a boolean)`;
+    }
+    // rationale (maintainer-facing gap this doc closes) is optional everywhere —
+    // no nagging when absent, just a type check when present.
+    const rationale = fm.rationale;
+    if (rationale !== undefined && typeof rationale !== 'string') {
+        return `invalid rationale: ${JSON.stringify(rationale)} (expected a string)`;
+    }
+    return null;
+}
+/** Strict-parse one file; push a finding on a YAML error, then run the
+ *  schema check when the file lives in a substrate store. */
+function lintFile(file, substrateStore, findings) {
+    let fm;
+    try {
+        fm = parseFrontmatterGeneric(readText(file)).data;
+    }
+    catch (e) {
+        const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
+        findings.push({ path: file, error: `invalid YAML frontmatter: ${msg}` });
+        return;
+    }
+    if (!substrateStore)
+        return;
+    const schemaError = lintSubstrateSchema(fm);
+    if (schemaError !== null)
+        findings.push({ path: file, error: schemaError });
+}
+export const lintLeaf = defineLeaf({
+    name: 'lint',
+    description: 'validate frontmatter across the whole bounded document corpus',
+    whenToUse: 'you authored or migrated documents and want the authoring-time gate: strict-parse every doc in the bounded corpus (the substrate memory stores) and fail loudly on any invalid YAML or substrate schema violation; also flags any dir the selected profile manages that lacks an AGENTS.md operating guide and warns when the directory where lint runs lacks a routed INDEX.md front door. Run it before shipping doc changes; CI-friendly (non-zero exit on findings, warnings remain non-fatal).',
+    help: {
+        name: 'memory lint',
+        summary: 'strict-parse frontmatter across the bounded corpus; warn when the working directory lacks an INDEX',
+        params: [],
+        output: [
+            { name: 'checked', type: 'number', required: true, constraint: 'Files linted across all corpora.' },
+            { name: 'corpora', type: 'object', required: true, constraint: 'Per-corpus counts: {memory_stores (files), profile_projects (managed dirs checked for AGENTS.md)}.' },
+            { name: 'findings', type: 'object[]', required: true, constraint: 'One row per failure: {path, error}. Empty when green.' },
+            { name: 'warnings', type: 'string[]', required: true, constraint: 'Non-fatal authoring gaps detected for the directory where lint ran.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only. Exits non-zero when any finding exists.'],
+    },
+    run: async () => {
+        const findings = [];
+        const warnings = [];
+        let memoryCount = 0;
+        // An INDEX gives the directory a discoverable, routed front door. It is
+        // intentionally advisory: lint still validates every available store when
+        // invoked from a directory that has not adopted project memory yet.
+        const workingDirectory = process.cwd();
+        const workingDirectoryIndex = join(workingDirectory, '.crouter', 'memory', 'INDEX.md');
+        if (!pathExists(workingDirectoryIndex)) {
+            warnings.push(`${workingDirectory}: no .crouter/memory/INDEX.md — create the directory's routed front door with \`crtr memory write INDEX -h\``);
+        }
+        // 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.
+        //    Hidden dirs are skipped to mirror doc enumeration (a dot-segment
+        //    path never yields a doc name, so e.g. the maintainer store shipped
+        //    at builtin-memory/.crouter can never register) — lint must not
+        //    flag files the substrate can never load.
+        const lintDir = (dir) => {
+            if (!dir || !pathExists(dir))
+                return;
+            for (const file of walkFiles(dir, (n) => n.endsWith('.md'), (d) => d.startsWith('.'))) {
+                if (!relative(dir, file).split(sep).join('/'))
+                    continue;
+                memoryCount += 1;
+                lintFile(file, basename(file) !== 'MEMORY.md', findings);
+            }
+        };
+        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)
+                    lintDir(pluginMemoryDir(plugin));
+            }
+        }
+        // Profile coverage: the selected profile's manifest names the dirs the
+        // operator manages. Lint the profile's own store, and require every
+        // managed project dir to carry an always-loaded operating guide
+        // (.crouter/memory/AGENTS.md) — a managed dir without one boots every
+        // agent there blind, so its absence is an authoring finding like any
+        // schema violation. (The managed dirs' stores themselves already lint
+        // above: projectScopeRoots folds the profile's project pointers in.)
+        let profileProjects = 0;
+        const profileIdOrName = process.env['CRTR_PROFILE_ID'] || getDefaultProfileId(process.cwd());
+        if (profileIdOrName) {
+            try {
+                const { profileId, manifest } = loadProfileManifest(profileIdOrName);
+                lintDir(profileMemoryDir(profileId));
+                for (const dir of manifest.projects) {
+                    profileProjects += 1;
+                    if (!pathExists(join(dir, '.crouter', 'memory', 'AGENTS.md'))) {
+                        findings.push({
+                            path: dir,
+                            error: `profile "${manifest.name}" manages this dir but it has no .crouter/memory/AGENTS.md — author its always-loaded operating guide (name the doc AGENTS, target the dir with --dir; run \`crtr memory write -h\` first)`,
+                        });
+                    }
+                }
+            }
+            catch {
+                // Unresolvable profile (deleted/corrupt manifest): profile coverage
+                // just doesn't apply — the file corpus above already linted fully.
+            }
+        }
+        const checked = memoryCount;
+        // Warnings are surfaced on stderr and returned structurally, but never
+        // convert a green corpus into a failed authoring gate.
+        for (const warning of warnings)
+            warn(`memory lint: warning: ${warning}`);
+        if (findings.length > 0) {
+            // Human/agent path renders only the message — surface every offender as
+            // a scoped stderr notice (the --json path carries them in details too).
+            for (const f of findings)
+                warn(`memory lint: ${f.path}: ${f.error}`);
+            throw general(`memory lint: ${findings.length} finding(s) across ${checked} files`, {
+                checked,
+                findings: findings.map((f) => ({ path: f.path, error: f.error })),
+                warnings,
+                next: 'Fix each doc (quote YAML values containing `: `; use a valid kind/rung/gate); for a profile-managed dir missing AGENTS.md, author one — run `crtr memory write -h` — then re-run `crtr memory lint`.',
+            });
+        }
+        return {
+            checked,
+            corpora: { memory_stores: memoryCount, profile_projects: profileProjects },
+            findings: [],
+            warnings,
+            follow_up: warnings.length > 0 ? 'Corpus green — resolve the warning above to give this directory a routed memory front door.' : 'Corpus green — zero invalid frontmatter docs.',
+        };
+    },
+});

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

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

package/dist/commands/memory/list.js

@@ -0,0 +1,84 @@
+import { defineLeaf } from '../../core/command.js';
+import { listAllMemoryDocs } from '../../core/memory-resolver.js';
+import { parseSubstrateDoc } from '../../core/substrate/schema.js';
+import { isIndexName, indexDirOf } from '../../core/substrate/ceiling.js';
+import { paginate } from '../../core/pagination.js';
+import { MEMORY_KINDS, MEMORY_SCOPES, scopeRank } from './shared.js';
+export const listLeaf = defineLeaf({
+    name: 'list',
+    description: 'inventory of stored memory documents',
+    whenToUse: 'browse everything stored — one line per document with its name, short-form hook, kind, and scope. This is the one surface that shows short-form. Reach for `crtr memory find` instead when you already have a topic or keyword in mind rather than wanting the whole inventory.',
+    help: {
+        name: 'memory list',
+        summary: 'inventory every memory document across the resolved scopes, one line each',
+        params: [
+            { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: false, constraint: 'Filter to a single kind. Default: all kinds.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Filter to a single scope. Default: all resolved scopes.' },
+            { kind: 'flag', name: 'paths', type: 'bool', required: false, default: false, constraint: 'Include each row\'s absolute file path. Off by default.' },
+            { kind: 'flag', name: 'limit', type: 'int', required: false, default: 50, constraint: 'Default 50, max 200.' },
+            { kind: 'flag', name: 'cursor', type: 'string', required: false, constraint: 'Opaque token from next_cursor. Omit on first call.' },
+        ],
+        output: [
+            { name: 'items', type: 'object[]', required: true, constraint: 'One row per document: {name, short_form, kind, scope, is_dir}. path is included only with --paths. 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: 'next_cursor', type: 'string | null', required: true, constraint: 'Opaque token for the next page; null means no more items.' },
+            { name: 'total', type: 'integer | null', required: true, constraint: 'Exact total across all pages when cheap to compute (always cheap here); never null in practice for this leaf.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands — read a document in full or narrow the inventory.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const kindFilter = input['kind'];
+        const scopeFilter = input['scope'];
+        const includePaths = input['paths'] ?? false;
+        const limitRaw = input['limit'];
+        const limit = limitRaw !== undefined ? Math.min(Math.max(1, limitRaw), 200) : 50;
+        const cursor = input['cursor'];
+        const seen = new Set(); // "scope/name" → first wins
+        const items = [];
+        const addItem = (item) => {
+            const id = `${item.scope}/${item.name}`;
+            if (seen.has(id))
+                return;
+            seen.add(id);
+            items.push(item);
+        };
+        // Substrate memory docs (project > user > builtin precedence).
+        for (const doc of listAllMemoryDocs(scopeFilter)) {
+            const sub = parseSubstrateDoc(doc);
+            if (sub === null)
+                continue;
+            if (kindFilter !== undefined && sub.kind !== kindFilter)
+                continue;
+            // A directory INDEX surfaces as a dir entry: its dir path with a trailing
+            // 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, path: sub.path, shortForm: sub.shortForm, isDir });
+        }
+        items.sort((a, b) => {
+            const sr = scopeRank(a.scope) - scopeRank(b.scope);
+            if (sr !== 0)
+                return sr;
+            const kc = a.kind.localeCompare(b.kind);
+            if (kc !== 0)
+                return kc;
+            return a.name.localeCompare(b.name);
+        });
+        const keyOf = (d) => `${String(scopeRank(d.scope) + 10).padStart(2, '0')}:${d.kind}:${d.name}`;
+        const result = paginate(items, { limit, cursor }, { defaultLimit: 50, maxLimit: 200, keyOf, total: 'count' });
+        return {
+            items: result.items.map((d) => ({
+                name: d.name,
+                short_form: d.shortForm,
+                kind: d.kind,
+                scope: d.scope,
+                is_dir: d.isDir,
+                ...(includePaths ? { path: d.path } : {}),
+            })),
+            next_cursor: result.next_cursor,
+            total: result.total,
+            follow_up: 'Read one in full with `crtr memory read <name>`, or pass --paths for its file path for a small body-only edit (routing/frontmatter/visibility changes go through `crtr memory write`). Narrow with --kind / --scope, page with --cursor, 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,100 @@
+import { defineLeaf } from '../../core/command.js';
+import { CrtrError, notFound } from '../../core/errors.js';
+import { resolveMemoryDoc } from '../../core/memory-resolver.js';
+import { ApiError } from '../../api/index.js';
+import { cliClient } from '../api-client.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: node > project > profile > 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']);
+        // Deref the authoring node through the API; a 404 means it was pruned from
+        // the canvas (node stays null, the follow-up says so).
+        let node = null;
+        if (nodeId !== null) {
+            try {
+                node = await cliClient().getNode(nodeId);
+            }
+            catch (err) {
+                if (!(err instanceof ApiError && err.status === 404))
+                    throw err;
+            }
+        }
+        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.d.ts

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

package/dist/commands/memory/read.js

@@ -0,0 +1,72 @@
+import { defineLeaf } from '../../core/command.js';
+import { CrtrError, notFound } from '../../core/errors.js';
+import { resolveMemoryDoc } from '../../core/memory-resolver.js';
+import { effectiveDocKind } from '../../core/substrate/schema.js';
+import { interpolateNodePaths } from '../../core/canvas/paths.js';
+import { readText } from '../../core/fs-utils.js';
+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 (node > project stack > profile > 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',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`). Resolved across scopes by precedence: node > project stack > profile > user > builtin, with leaf-name fallback.' },
+            { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: false, constraint: 'Narrows resolution when the name is ambiguous across kinds.' },
+            { kind: 'flag', name: 'frontmatter', type: 'bool', required: false, constraint: 'When present, includes the YAML frontmatter in the returned body. Off by default — only the body is returned.' },
+        ],
+        output: [
+            { 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: node, project, profile, user, or builtin.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the document on disk — direct edits here are for a small body-only tweak; any routing/frontmatter/visibility change goes through `crtr memory write`.' },
+            { 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.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const nameRaw = input['name'];
+        const kindFilter = input['kind'];
+        const includeFrontmatter = input['frontmatter'];
+        // Resolve a substrate/memory document across scopes (node > project stack
+        // > profile > user > builtin, with leaf-name fallback). --kind is threaded
+        // INTO resolution (not a post-filter): a nearer wrong-kind doc is skipped
+        // so a farther matching-kind doc is found instead of shadowing it into a
+        // false not_found. The substrate corpus now includes plugin docs (mounted
+        // under <pluginName>/), so this resolves every name.
+        let doc;
+        try {
+            doc = resolveMemoryDoc(nameRaw, { kind: kindFilter });
+        }
+        catch (e) {
+            if (!(e instanceof CrtrError && e.code === 'not_found'))
+                throw e;
+        }
+        if (doc !== undefined) {
+            const kind = effectiveDocKind(doc);
+            const raw = includeFrontmatter ? readText(doc.path) : doc.body;
+            // In-node reads (CRTR_NODE_ID set) get the literal `$CRTR_CONTEXT_DIR`
+            // token swapped for this node's real absolute path, so agents don't
+            // paste it into the non-expanding Write tool. A human/contributor
+            // reading generically (env unset) keeps the token literal.
+            const nodeId = process.env['CRTR_NODE_ID'];
+            const content = nodeId ? interpolateNodePaths(raw, nodeId) : raw;
+            return {
+                name: doc.name,
+                kind,
+                scope: doc.scope,
+                path: doc.path,
+                content,
+                follow_up: 'Use --frontmatter on this same command to inspect the YAML frontmatter, or edit `path` directly for a body-only tweak. Browse the inventory with `crtr memory list`.',
+            };
+        }
+        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.',
+        });
+    },
+});

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

@@ -0,0 +1,54 @@
+import type { MemoryScope } from '../../core/memory-resolver.js';
+export declare const MEMORY_KINDS: readonly ["knowledge", "preference"];
+export declare const VISIBILITY_RUNGS: readonly ["none", "name", "preview", "content"];
+export declare const MEMORY_SCOPES: readonly ["user", "project", "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 declare function scopeRank(scope: MemoryScope): number;
+/** 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 declare function resolveWriteTarget(scopeArg: string | undefined, profileArg?: string, dirArg?: string): {
+    scope: MemoryScope;
+    memoryDir: string;
+};
+/** Map a path-derived name (`topic` or `area/topic`) to its file path under a
+ *  memory dir, guarding against traversal/absolute escapes. */
+export declare function memoryFilePath(memoryDir: string, name: string): string;
+export declare function coerceGate(raw: string): Record<string, unknown>;
+/** Coerce a `--read-when` string into a predicate tree. Like `--gate`, the
+ *  read-when field MUST be a YAML/JSON object (the field→matcher map the schema
+ *  expects, evaluated against a read file's own frontmatter). A scalar/array
+ *  read-when is inert (never matches), so passing one is always a mistake and is
+ *  caught at authoring time rather than stored. */
+export declare function coerceReadWhen(raw: string): Record<string, unknown>;
+/** Coerce 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 declare function coerceAppliesTo(values: 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. */
+export declare function serializeMemoryDoc(frontmatter: Record<string, unknown>, body: string): string;