@north-light/crouter 0.3.208 → 0.3.209

package/dist/commands/memory/move.js

@@ -0,0 +1,195 @@
+import { appendFileSync, renameSync, rmSync } from 'node:fs';
+import { dirname, resolve as resolvePath } from 'node:path';
+import { defineLeaf } from '../../core/command.js';
+import { CrtrError, notFound, usage } from '../../core/errors.js';
+import { ensureDir, pathExists, readText, realpathOrSelf, writeText } from '../../core/fs-utils.js';
+import { listAllMemoryDocs, resolveMemoryDoc } from '../../core/memory-resolver.js';
+import { findDocLinks, isDocLinkName } from '../../core/memory/doc-link-grammar.js';
+import { appendHistoryRecord, buildHistoryRecord, historyLogPathFor } from '../../core/memory/history.js';
+import { docsByName, isDirName } from '../../core/substrate/listings.js';
+import { normalizeDocName } from '../../core/substrate/schema.js';
+import { MEMORY_SCOPES, literalBodySegment, memoryFilePath, pruneEmptyParents } from './shared.js';
+/** Replace every `[[oldName]]` doc link in a full document source with
+ *  `[[newName]]`, splicing only within the literal body segment so the
+ *  frontmatter block is never touched. Link spans come from the shared
+ *  doc-link grammar (code blocks and inline code excluded), applied back to
+ *  front so earlier offsets stay valid. */
+function rewriteRefs(source, oldName, newName) {
+    const body = literalBodySegment(source);
+    const prefixLen = source.length - body.length;
+    const links = findDocLinks(body).filter((l) => l.name === oldName);
+    let text = source;
+    for (let i = links.length - 1; i >= 0; i -= 1) {
+        const l = links[i];
+        text = text.slice(0, prefixLen + l.start) + `[[${newName}]]` + text.slice(prefixLen + l.end);
+    }
+    return { text, count: links.length };
+}
+export const moveLeaf = defineLeaf({
+    name: 'move',
+    description: 'rename or relocate a memory document, rewriting inbound links',
+    whenToUse: 'a stored document should answer to a different name — renamed in place or relocated under another directory. The sanctioned way to move one, so you never mv the markdown off disk: this verb carries the document’s revision history along and rewrites every inbound `[[ref]]` across writable stores, so authored links break loudly or not at all. Moves stay within the document’s own store; one document per move — a directory never moves as a unit, so relocate its members individually.',
+    help: {
+        name: 'memory move',
+        summary: 'move memory/<name>.md to memory/<new-name>.md in its store, rewriting inbound [[refs]] corpus-wide',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`), resolved as `read` resolves it: exact identity/direct path by precedence node > project stack > profile > user, then bare leaf fallback. Builtin and installed-plugin docs are read-only and refuse to move. A directory name is rejected — move member docs individually.' },
+            { kind: 'flag', name: 'to', type: 'string', required: true, constraint: 'The new canonical name, in the same store: `/`-joined segments of [A-Za-z0-9_-], no `NN-` ordering prefix (identity is prefix-stripped, so a prefixed name would not answer to itself). Must not already answer to any document in the corpus.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Restrict resolution to this scope before moving. Use it to disambiguate a name present at multiple scopes. builtin is not a choice — builtin docs ship with the package and cannot move.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'The document’s new canonical name.' },
+            { name: 'previous_name', type: 'string', required: true, constraint: 'The name it answered to before the move.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'Scope of the store the document moved within: node, user, project, or profile.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path of the document at its new location.' },
+            { name: 'moved', type: 'boolean', required: true, constraint: 'Always true on success — the file and its revision log now live at the new name.' },
+            { name: 'log_path', type: 'string', required: true, constraint: 'Absolute path to the revision log at its new location, ending in a `move` record that names the previous canonical name.' },
+            { name: 'refs_rewritten', type: 'object[]', required: true, constraint: 'Documents whose bodies were rewritten from `[[<previous_name>]]` to `[[<name>]]`. Each: {name, scope, path, refs}. Empty when nothing linked to the document — or when the moved document was shadowed by a same-named doc at a nearer scope, in which case inbound refs keep resolving to that survivor and are left alone.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands — read it back at the new name, verify the corpus with lint.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Moves memory/<name>.md to memory/<new-name>.md within its store (creating parent directories, pruning any it leaves empty) and moves memory/.history/<name>.jsonl with it, appending a `move` record naming the previous canonical name.',
+            'Rewrites every inbound `[[<name>]]` doc link across writable stores to `[[<new-name>]]`, appending an `edit` record to each rewritten document’s revision log. Aborts before any write when a read-only (builtin or installed-plugin) document carries such a link.',
+        ],
+    },
+    run: async (input) => {
+        const nameRaw = input['name'];
+        const newName = (input['to'] ?? '').trim();
+        const scopeArg = input['scope'];
+        let doc;
+        try {
+            doc = resolveMemoryDoc(nameRaw, { includeDescendants: true, ...(scopeArg !== undefined ? { scope: scopeArg } : {}) });
+        }
+        catch (e) {
+            if (e instanceof CrtrError && e.code === 'not_found') {
+                const dirName = normalizeDocName(nameRaw.replace(/\/+$/, ''));
+                if (dirName !== '' && isDirName(docsByName(listAllMemoryDocs(undefined, true, true)), dirName)) {
+                    throw usage(`${dirName} is a directory, and a directory never moves as a unit — move its member docs individually.`, {
+                        memory: dirName,
+                        next: `Run \`crtr memory read ${dirName}\` to list the members, then \`crtr memory move <member> --to <new-name>\` per doc.`,
+                    });
+                }
+                throw notFound(`memory document not found: ${nameRaw}`, {
+                    memory: nameRaw,
+                    next: 'Run `crtr memory find <query>` to locate it, or `crtr memory list` to browse the inventory. If it exists at another scope, pass --scope.',
+                });
+            }
+            throw e; // ambiguous / usage propagate with their own recovery guidance
+        }
+        if (doc.plugin !== undefined) {
+            throw usage(`${doc.name} belongs to the installed plugin "${doc.plugin}" — it is not a scope doc and cannot be moved here. Manage plugin docs with \`crtr pkg\`.`, { memory: doc.name, plugin: doc.plugin });
+        }
+        if (doc.scope === 'builtin') {
+            throw usage(`${doc.name} is a builtin document shipped with the package (read-only) — it cannot be moved. Override it with a same-named doc at a writable scope instead (\`crtr memory write ${doc.name} ...\`).`, { memory: doc.name, scope: 'builtin' });
+        }
+        // An explicit frontmatter `name` pins identity independent of the file's
+        // location, so a physical move would change nothing a reader can see.
+        const explicitName = doc.frontmatter?.['name'];
+        if (typeof explicitName === 'string' && explicitName.trim() !== '') {
+            throw usage(`${doc.name} pins its identity with an explicit \`name\` frontmatter field, so its name is not path-derived and a file move would not rename it. Edit the field with \`crtr memory edit ${doc.name}\` instead.`, { memory: doc.name, path: doc.path });
+        }
+        if (newName === '')
+            throw usage('--to requires the new canonical name');
+        if (!isDocLinkName(newName)) {
+            throw usage(`invalid new name: ${newName} — a canonical name is one or more [A-Za-z0-9_-] segments joined by \`/\``);
+        }
+        // Identity is derived from the path with `NN-` ordering prefixes stripped,
+        // so a prefixed target name would derive a different identity than asked.
+        if (normalizeDocName(newName) !== newName) {
+            throw usage(`invalid new name: ${newName} — a \`NN-\` ordering prefix is stripped from derived identity, so this doc would answer to ${normalizeDocName(newName)} instead. Name it that directly.`);
+        }
+        if (newName === doc.name)
+            throw usage(`${doc.name} already answers to that name — nothing to move`);
+        const newPath = memoryFilePath(doc.root, newName);
+        if (pathExists(newPath)) {
+            throw usage(`the target is occupied: ${newPath} already exists — pick a free name or delete the occupant first`, { memory: newName, path: newPath });
+        }
+        const corpus = listAllMemoryDocs(undefined, true, true);
+        const byName = docsByName(corpus);
+        const taken = byName.get(newName);
+        if (taken !== undefined) {
+            throw usage(`${newName} already answers to a document (${taken.scope} scope, ${taken.path}) — moving onto it would make every rewritten ref ambiguous. Pick a free name.`, { memory: newName, path: taken.path });
+        }
+        // Refs are rewritten only when this doc is what `[[<name>]]` actually
+        // resolves to. Moving a doc shadowed by a same-named nearer doc leaves
+        // every ref pointing at that surviving winner, so they are left alone.
+        const movedReal = realpathOrSelf(doc.path);
+        const winner = byName.get(doc.name);
+        const isWinner = winner !== undefined && realpathOrSelf(winner.path) === movedReal;
+        const referencing = [];
+        const blocked = [];
+        if (isWinner) {
+            const seenFiles = new Set([movedReal]);
+            for (const d of corpus) {
+                const real = realpathOrSelf(d.path);
+                if (seenFiles.has(real))
+                    continue;
+                seenFiles.add(real);
+                if (!findDocLinks(d.body).some((l) => l.name === doc.name))
+                    continue;
+                if (d.plugin !== undefined || d.scope === 'builtin')
+                    blocked.push(d);
+                else
+                    referencing.push(d);
+            }
+            if (blocked.length > 0) {
+                throw usage(`cannot move ${doc.name}: read-only docs link to it with [[${doc.name}]] and their refs cannot be rewritten — ` +
+                    blocked.map((d) => `${d.plugin !== undefined ? `plugin ${d.plugin}` : d.scope}: ${d.name} (${d.path})`).join('; ') +
+                    '. Nothing was changed.', { memory: doc.name });
+            }
+        }
+        // All checks passed — mutate. Inbound refs first, each an ordinary `edit`
+        // in that doc's own log; the mechanical splice touches only body bytes, so
+        // `last-updated` (recency of the knowledge itself) is deliberately not
+        // restamped.
+        const refsRewritten = [];
+        for (const d of referencing) {
+            const before = readText(d.path);
+            const { text: after, count } = rewriteRefs(before, doc.name, newName);
+            if (count === 0)
+                continue;
+            writeText(d.path, after);
+            appendHistoryRecord(historyLogPathFor(d.root, d.path), buildHistoryRecord({ op: 'edit', rationale: `\`crtr memory move\`: [[${doc.name}]] → [[${newName}]]`, before, after }));
+            refsRewritten.push({ name: d.name, scope: d.scope, path: d.path, refs: count });
+        }
+        // The doc itself: self-refs rewrite in the same motion as the move.
+        const before = readText(doc.path);
+        const after = isWinner ? rewriteRefs(before, doc.name, newName).text : before;
+        writeText(newPath, after);
+        rmSync(doc.path);
+        pruneEmptyParents(resolvePath(doc.path), doc.name.split('/').length);
+        // The revision log travels with the doc — history answers to the name the
+        // doc now answers to. A log already at the target (a prior, deleted life
+        // of that name) keeps its records; this doc's records append after them.
+        const oldLog = historyLogPathFor(doc.root, doc.path);
+        const newLog = historyLogPathFor(doc.root, newPath);
+        if (pathExists(oldLog)) {
+            ensureDir(dirname(newLog));
+            if (pathExists(newLog)) {
+                appendFileSync(newLog, readText(oldLog), 'utf8');
+                rmSync(oldLog);
+            }
+            else {
+                renameSync(oldLog, newLog);
+            }
+            pruneEmptyParents(resolvePath(oldLog), doc.name.split('/').length);
+        }
+        appendHistoryRecord(newLog, buildHistoryRecord({ op: 'move', from: doc.name, before, after }));
+        const refsNote = isWinner
+            ? refsRewritten.length > 0
+                ? ` Rewrote [[${doc.name}]] in ${refsRewritten.length} doc${refsRewritten.length === 1 ? '' : 's'}.`
+                : ' No inbound refs needed rewriting.'
+            : ` Inbound [[${doc.name}]] refs were left alone: a same-named doc at a nearer scope still answers to that name.`;
+        return {
+            name: newName,
+            previous_name: doc.name,
+            scope: doc.scope,
+            path: newPath,
+            moved: true,
+            log_path: newLog,
+            refs_rewritten: refsRewritten,
+            follow_up: `Moved.${refsNote} Read it back with \`crtr memory read ${newName}\`, and run \`crtr memory lint\` to verify no link dangles.`,
+        };
+    },
+});

package/dist/commands/memory/read.js

@@ -1,13 +1,16 @@
+import { CrtrClient } from '../../api/index.js';
+import { interpolateNodePaths } from '../../core/canvas/paths.js';
 import { defineLeaf } from '../../core/command.js';
 import { CrtrError, notFound } from '../../core/errors.js';
-import { createMemoryDocSnapshot, listAllMemoryDocs, resolveMemoryDoc, resolveMemoryDocs } from '../../core/memory-resolver.js';
-import { effectiveDocKind, parseSubstrateDoc, previewLine } from '../../core/substrate/schema.js';
-import { displayName, indexDirOf, isIndexName } from '../../core/substrate/ceiling.js';
-import { interpolateNodePaths } from '../../core/canvas/paths.js';
-import { readText } from '../../core/fs-utils.js';
+import { readText, realpathOrSelf } from '../../core/fs-utils.js';
 import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
 import { docLinkNames } from '../../core/memory/doc-link-grammar.js';
+import { createMemoryDocSnapshot, listAllMemoryDocs, resolveMemoryDoc, resolveMemoryDocs } from '../../core/memory-resolver.js';
 import { expandShellBlocks, hasShellBlocks, makeNodeShellRunner } from '../../core/runtime/shell-expansion.js';
+import { deliveredAtOrAbove, loadInjectedDocs, recordDelivery, saveInjectedDocs } from '../../core/substrate/injected-store.js';
+import { ancestorDirsOf, dirDedupKey, docsByName, isDirName, renderDirListing } from '../../core/substrate/listings.js';
+import { memoryReadDocBlocks } from '../../core/substrate/on-read.js';
+import { effectiveDocKind, normalizeDocName } from '../../core/substrate/schema.js';
 import { MEMORY_KINDS } from './shared.js';
 export { createMemoryDocSnapshot, resolveMemoryDocs };
 /** Load the body at an already-resolved memory path with the same frontmatter
@@ -20,117 +23,56 @@ export function readMemoryDocContent(path, includeFrontmatter = false) {
     const nodeId = process.env['CRTR_NODE_ID'];
     return nodeId ? interpolateNodePaths(content, nodeId) : content;
 }
-/** The routing list appended to a directory-INDEX read: one line per document
- * the INDEX gates, `[[name]]: <when-and-why-to-read>`. Membership is the
- * directory's docs unioned with the body's resolvable `[[links]]`, deduped —
- * a nested INDEX stands in for its whole subtree with a single line, while a
- * subdirectory without an INDEX is transparent and its leaves render directly
- * (mirroring how boot ceilings govern to the nearest INDEX). Every member
- * renders regardless of its own visibility rung: rungs price unsolicited
- * surfaces, and a read is a deliberate act. The root INDEX is excluded — the
- * top-level namespace merges across stores, so its "directory" would
- * enumerate the entire corpus. */
-function indexRoutes(doc) {
-    // A dir INDEX resolves two ways: the explicit `dir/INDEX` name, or the bare
-    // dir name (which carries the dir as its identity while the path is the
-    // INDEX.md). Detect from the path so both shapes route identically.
-    if (!doc.path.endsWith('/INDEX.md'))
-        return [];
-    const dir = isIndexName(doc.name) ? indexDirOf(doc.name) : doc.name;
-    if (dir === '')
-        return [];
-    const canonicalName = `${dir}/INDEX`;
-    let corpus;
+/** The node-config subject for memory-read-event gate evaluation. A CLI
+ * process cannot take it from canvas-db (V-1); one `/v1` request supplies it.
+ * With no node identity or no reachable daemon the answer is null — gated
+ * docs then skip while ungated docs still deliver. Never autostarts a daemon:
+ * a memory read must not boot the runtime as a side effect. */
+async function fetchSubject(nodeId) {
+    if (nodeId === undefined)
+        return null;
     try {
-        corpus = listAllMemoryDocs(undefined, true, true);
+        return await CrtrClient.forLocalSocket({ autostart: false }).nodeSubject(nodeId);
     }
     catch {
-        return [];
+        return null;
     }
-    // First occurrence wins: listAllMemoryDocs emits in resolver-precedence
-    // order, so the doc that renders a name's line is the doc a read of that
-    // name would actually return.
-    const byName = new Map();
-    for (const d of corpus)
-        if (!byName.has(d.name))
-            byName.set(d.name, d);
-    const prefix = dir + '/';
-    // Keyed by RENDERED identity (`displayName`), not `.name`: one physical
-    // directory INDEX answers to two names — `listAllMemoryDocs` emits the
-    // path-derived `dir/INDEX`, while `resolveMemoryDoc('dir')` returns it
-    // carrying the bare dir as its identity. Keying on `.name` let a body link
-    // to a sub-INDEX (written the normal way, by bare dir name) miss the entry
-    // the directory scan already added, and the doc rendered twice.
-    const members = new Map();
-    for (const [name, d] of byName) {
-        if (!name.startsWith(prefix) || name === canonicalName)
-            continue;
-        // The shallowest INDEX between the gating dir and this doc stands in for
-        // it (an INDEX finds itself here, keeping its own single line).
-        const segs = name.slice(prefix.length).split('/');
-        let member = d;
-        for (let i = 1; i < segs.length; i++) {
-            const gate = byName.get(`${prefix}${segs.slice(0, i).join('/')}/INDEX`);
-            if (gate !== undefined) {
-                member = gate;
-                break;
-            }
-        }
-        if (!members.has(displayName(member.name)))
-            members.set(displayName(member.name), member);
+}
+function corpusDocs() {
+    try {
+        return listAllMemoryDocs(undefined, true, true);
     }
-    // No members means this INDEX gates no cluster in the corpus namespace — a
-    // store-root front door whose explicit frontmatter name dodges the root
-    // check above lands here. Fall back to the plain links field.
-    if (members.size === 0)
+    catch {
         return [];
-    // Union the body's authored links so one list carries everything this INDEX
-    // routes to — the routes list subsumes `links` on an INDEX read.
-    for (const linkName of docLinkNames(doc.body)) {
-        let linked;
-        try {
-            linked = resolveMemoryDoc(linkName, { includeDescendants: true });
-        }
-        catch {
-            continue; // dangling link — lint's finding, not read's
-        }
-        if (displayName(linked.name) !== linkName)
-            continue;
-        if (linkName === displayName(canonicalName) || linkName === displayName(doc.name))
-            continue;
-        if (!members.has(linkName))
-            members.set(linkName, linked);
     }
-    return [...members.values()]
-        .map((m) => {
-        const label = displayName(m.name);
-        const sub = parseSubstrateDoc(m);
-        const line = sub === null ? '' : previewLine(sub);
-        return { label, line: line === '' ? `[[${label}]]` : `[[${label}]]: ${line}` };
-    })
-        .sort((a, b) => a.label.localeCompare(b.label))
-        .map((e) => e.line);
+}
+function attr(s) {
+    return s
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
 }
 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. Exact identity and direct-path matches resolve by scope precedence (node > project stack > profile > user > builtin); bare leaf-name fallback is considered only when no such match exists. You name the document by its crtr identifier, never a file path — do not cat or find the markdown off disk. Reach for `crtr memory find` first when you do not yet know which document applies.',
+    whenToUse: 'a task in front of you matches a stored document and you already know its name — read it before improvising. Exact identity and direct-path matches resolve by scope precedence (node > project stack > profile > user > builtin); bare leaf-name fallback is considered only when no such match exists. A directory name is also a valid target: it returns the neighborhood listing, and walking directories is the sanctioned browse move. 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',
+        summary: 'resolve a path-derived name to its document body (frontmatter stripped unless --frontmatter), or a directory name to its listing',
         params: [
-            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`). Exact identity and direct-path matches resolve by scope precedence: node > project stack > profile > user > builtin. A bare leaf falls back only when no exact/direct match exists.' },
+            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`). Exact identity and direct-path matches resolve by scope precedence: node > project stack > profile > user > builtin. A bare leaf falls back only when no exact/direct match exists. A directory name returns that directory\u2019s listing instead of a document.' },
             { 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. Revise it with `crtr memory edit`, never by editing this file — an edit records why the change happened and lands in the doc’s revision history.' },
-            { name: 'content', type: 'string', required: true, constraint: 'Document body. Frontmatter stripped unless --frontmatter is set. A document may embed shell as `!`cmd`` or a ```! fenced block; each runs once per read, in the current working directory, and is replaced by its output. Read `path` off disk when you need the literal unexecuted text.' },
-            { name: 'links', type: 'string[]', required: false, constraint: 'Canonical names this document links to via `[[name]]` that resolve in the current corpus — further reading, loaded only on demand with `crtr memory read <name>`. Omitted when the body carries no resolvable links, and subsumed by `routes` on a directory-INDEX read.' },
-            { name: 'routes', type: 'string[]', required: false, constraint: 'Present only when the document is a directory INDEX: one routing line per document the INDEX gates — the directory’s members plus the body’s resolvable links, a nested INDEX standing in for its subtree with a single line. Follow one with `crtr memory read <name>` when the task in front of you matches its line.' },
+            { name: 'name', type: 'string', required: true, constraint: 'Resolved document name, or the directory name on a directory read.' },
+            { name: 'kind', type: 'string', required: false, constraint: 'Resolved kind: knowledge or preference. Absent on a directory read.' },
+            { name: 'scope', type: 'string', required: false, constraint: 'Scope the document was resolved from: node, project, profile, user, or builtin. Absent on a directory read.' },
+            { name: 'path', type: 'string', required: false, constraint: 'Absolute path to the document on disk. Revise it with `crtr memory edit`, never by editing this file — an edit records why the change happened and lands in the doc’s revision history. Absent on a directory read.' },
+            { name: 'content', type: 'string', required: false, constraint: 'Document body. Frontmatter stripped unless --frontmatter is set. A document may embed shell as `!`cmd`` or a ```! fenced block; each runs once per read, in the current working directory, and is replaced by its output. Read `path` off disk when you need the literal unexecuted text. May be preceded by one `<auto-loaded-context>` block carrying the doc\u2019s neighborhood listings and any docs routed to this read. Absent on a directory read.' },
+            { name: 'listing', type: 'string[]', required: false, constraint: 'Present only on a directory read: one `[[name]]: <when-and-why>` line per member doc, one bare `[[name]]` per subdirectory. Follow any line with `crtr memory read <name>`.' },
+            { name: 'links', type: 'string[]', required: false, constraint: 'Canonical names this document links to via `[[name]]` that resolve in the current corpus — further reading, loaded only on demand with `crtr memory read <name>`. A directory link returns that directory\u2019s listing. Omitted when the body carries no resolvable links.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Hints at variant flags or next commands.' },
         ],
         outputKind: 'object',
@@ -156,52 +98,104 @@ export const readLeaf = defineLeaf({
             if (!(e instanceof CrtrError && e.code === 'not_found'))
                 throw e;
         }
-        if (doc !== undefined) {
-            const kind = effectiveDocKind(doc);
-            const raw = readMemoryDocContent(doc.path, includeFrontmatter);
-            // A read is an explicit act by an agent that can already run shell, so a
-            // document's embedded commands run here and their output lands inline —
-            // the same contract as invoking the document as a slash command. Nothing
-            // executes on the auto-load path, which never reaches this leaf.
-            const content = hasShellBlocks(raw)
-                ? await expandShellBlocks(raw, makeNodeShellRunner({ cwd: process.cwd() }))
-                : raw;
-            // `[[name]]` doc links are pointers, never transclusion: surface which
-            // linked names actually resolve so the reader can follow one when the
-            // task needs that depth, without ever auto-loading a linked body.
-            // A directory INDEX is a gate: its read appends one routing line per doc
-            // it gates, subsuming the links field. Non-INDEX reads keep plain links.
-            const routes = indexRoutes(doc);
-            const links = routes.length > 0 ? [] : docLinkNames(doc.body).filter((linkName) => {
-                try {
-                    // `resolveMemoryDoc` permits leaf-name fallback for interactive reads;
-                    // a stored graph edge does not. Compare the resolved canonical name
-                    // so an old shorthand never masquerades as a first-class doc link.
-                    return displayName(resolveMemoryDoc(linkName, { includeDescendants: true }).name) === linkName;
-                }
-                catch {
-                    return false;
+        const nodeId = process.env['CRTR_NODE_ID'] || undefined;
+        if (doc === undefined) {
+            // No doc answers for a directory — the bare listing does. An explicit
+            // dir read is a deliberate act, so every line renders (unlisted
+            // excluded), never dedup-filtered; rendered members still record at
+            // preview so unsolicited channels stay quiet about them later.
+            const dirName = normalizeDocName(nameRaw.replace(/\/+$/, ''));
+            const byName = docsByName(corpusDocs());
+            if (dirName !== '' && isDirName(byName, dirName)) {
+                const seen = nodeId !== undefined ? loadInjectedDocs(nodeId) : null;
+                const listing = renderDirListing(byName, dirName, seen, false);
+                if (nodeId !== undefined && seen !== null) {
+                    recordDelivery(seen, dirDedupKey(dirName), 'preview');
+                    saveInjectedDocs(nodeId, seen);
                 }
+                return {
+                    name: dirName,
+                    listing,
+                    follow_up: 'Each line is readable with `crtr memory read <name>` — a `[[name]]: <line>` entry is a doc, a bare `[[name]]` is a subdirectory whose read browses deeper. Browse the whole 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.',
             });
-            return {
-                name: doc.name,
-                kind,
-                scope: doc.scope,
-                path: doc.path,
-                content,
-                ...(routes.length > 0 ? { routes } : {}),
-                ...(links.length > 0 ? { links } : {}),
-                follow_up: (routes.length > 0
-                    ? 'This INDEX gates the docs listed in `routes` — follow one with `crtr memory read <name>` when the task in front of you matches its line. '
-                    : links.length > 0
-                        ? 'The `[[name]]` links in the body are further reading — follow one with `crtr memory read <name>` only when the task needs that depth. '
-                        : '') +
-                    'Use --frontmatter on this same command to inspect the YAML frontmatter, or revise the doc with `crtr memory edit` (recorded, with a rationale). 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.',
+        const kind = effectiveDocKind(doc);
+        const raw = readMemoryDocContent(doc.path, includeFrontmatter);
+        // A read is an explicit act by an agent that can already run shell, so a
+        // document's embedded commands run here and their output lands inline —
+        // the same contract as invoking the document as a slash command. Nothing
+        // executes on the auto-load path, which never reaches this leaf.
+        const content = hasShellBlocks(raw)
+            ? await expandShellBlocks(raw, makeNodeShellRunner({ cwd: process.cwd() }))
+            : raw;
+        const byName = docsByName(corpusDocs());
+        // `[[name]]` doc links are pointers, never transclusion: surface which
+        // linked names actually resolve so the reader can follow one when the
+        // task needs that depth, without ever auto-loading a linked body. A link
+        // may also name a directory — a browse link to its listing.
+        const links = docLinkNames(doc.body).filter((linkName) => {
+            if (isDirName(byName, linkName))
+                return true;
+            try {
+                // `resolveMemoryDoc` permits leaf-name fallback for interactive reads;
+                // a stored graph edge does not. Compare the resolved canonical name
+                // so an old shorthand never masquerades as a first-class doc link.
+                return resolveMemoryDoc(linkName, { includeDescendants: true }).name === linkName;
+            }
+            catch {
+                return false;
+            }
         });
+        // Reading a doc discloses where it sits (its directory's listing and each
+        // ancestor's, once per transcript) and fires the memory-read event
+        // (corpus docs whose `memory-read` entries match the resolved name).
+        // Both prepend in one <auto-loaded-context> block. Without a node
+        // identity the call is stateless: listings render undeduped and nothing
+        // records.
+        const seen = nodeId !== undefined ? loadInjectedDocs(nodeId) : null;
+        const subject = await fetchSubject(nodeId);
+        const excludeReal = realpathOrSelf(doc.path);
+        // The explicit read IS a content delivery: record it first so unsolicited
+        // channels (including this doc's own line in its directory listing) stay
+        // quiet about a doc whose full body is already in the transcript.
+        if (seen !== null)
+            recordDelivery(seen, excludeReal, 'content');
+        const blocks = [];
+        for (const dir of ancestorDirsOf(doc.name)) {
+            if (seen !== null && deliveredAtOrAbove(seen, dirDedupKey(dir), 'preview'))
+                continue;
+            const lines = renderDirListing(byName, dir, seen, true);
+            if (seen !== null)
+                recordDelivery(seen, dirDedupKey(dir), 'preview');
+            if (lines.length > 0)
+                blocks.push(`<memory-listing dir="${attr(dir)}">\n${lines.join('\n')}\n</memory-listing>`);
+        }
+        const targetNames = [doc.name];
+        if (doc.plugin !== undefined) {
+            const slash = doc.name.indexOf('/');
+            if (slash > 0)
+                targetNames.push(doc.name.slice(slash + 1));
+        }
+        blocks.push(...memoryReadDocBlocks(subject, excludeReal, targetNames, seen ?? new Map()));
+        if (nodeId !== undefined && seen !== null)
+            saveInjectedDocs(nodeId, seen);
+        const finalContent = blocks.length === 0 ? content : `<auto-loaded-context>\n${blocks.join('\n')}\n</auto-loaded-context>\n\n${content}`;
+        return {
+            name: doc.name,
+            kind,
+            scope: doc.scope,
+            path: doc.path,
+            content: finalContent,
+            ...(links.length > 0 ? { links } : {}),
+            follow_up: (links.length > 0
+                ? 'The `[[name]]` links in the body are further reading — follow one with `crtr memory read <name>` only when the task needs that depth. '
+                : '') +
+                'Use --frontmatter on this same command to inspect the YAML frontmatter, or revise the doc with `crtr memory edit` (recorded, with a rationale). Browse the inventory with `crtr memory list`.',
+        };
     },
 });

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

@@ -1,7 +1,6 @@
 import type { FlagParam } from '../../core/help.js';
 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
@@ -25,21 +24,23 @@ export declare function resolveWriteTarget(scopeArg: string | undefined, profile
     scope: MemoryScope;
     memoryDir: string;
 };
+/** Remove a just-removed file's now-empty parent directories up to (never
+ *  including) its tree root, so removing the last entry under an `area/`
+ *  prefix does not orphan an empty directory. The root is derived by walking
+ *  up one dirname per name segment: a doc named `a/b` sits at `<root>/a/b.md`,
+ *  so its root is two dirnames above — the same arithmetic holds for a
+ *  `.history/<name>.jsonl` sidecar. Stops at the first non-empty ancestor. */
+export declare function pruneEmptyParents(filePath: string, nameSegments: number): void;
 /** 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;
+/** Coerce one `--surface` value into a validated surfaces entry. Strict where
+ *  the runtime parser is tolerant: a flag that would be silently dropped or
+ *  trimmed at render time is an authoring mistake and fails HERE. The entry is
+ *  returned in canonical key order with a single glob kept as a bare string,
+ *  so the stored YAML stays as compact as the flag that authored it. */
+export declare function coerceSurface(raw: string): Record<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
@@ -50,8 +51,8 @@ export declare function coerceAppliesTo(values: string[]): unknown;
 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. */
+ *  package — the same one the parser uses — so nested gate maps and surfaces
+ *  entry lists round-trip), in canonical field order with preserved extras last. */
 export declare function serializeMemoryDoc(frontmatter: Record<string, unknown>, body: string): string;
 /** Everything after the closing frontmatter fence, byte for byte — leading blank
  *  lines and indentation intact. Source without a fence is all body. */
@@ -75,7 +76,7 @@ export declare function overlayParam(name: string, overrides?: Partial<FlagParam
  *  `--doc-rationale`, because `--rationale` there means why THIS REVISION is
  *  happening. Same field, same prose, two flag names that cannot be confused. */
 export declare const DOC_RATIONALE_CONSTRAINT = "Frontmatter rationale \u2014 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 the flag preserves an existing rationale unchanged.";
-export declare const GUIDE_VISIBILITY_RUNGS = "The visibility rungs `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 fits in a single sentence \u2014 a one-line preference or a one-sentence knowledge fact \u2014 skip `preview` and use `name` or `content` directly: the routing line would run longer than the doc itself. Sentence-length `content` docs are correct; never pad a memory to be more verbose than the rule or fact it carries.";
+export declare const GUIDE_SURFACES = "Every doc appears in its directory\u2019s listing by default (suppress with --unlisted); everything beyond the listing is explicit `surfaces` routing \u2014 entries declaring WHEN the doc delivers and how much. Events: `boot` delivers in the boot catalog every agent sees; `workspace-open` delivers in first-message context when cwd/profile mounts the doc\u2019s project store (project stores only); `read` fires when the agent reads a matching file (globs vs the file\u2019s absolute path and basename, `./`-anchored globs vs its path relative to the store\u2019s owning repo dir, `match-frontmatter` predicates over the read file\u2019s own YAML frontmatter); `memory-read` fires when another memory doc is read (globs vs that doc\u2019s canonical name, `./` anchored to this doc\u2019s own name directory); `command` fires when a matching shell command runs (globs vs the whole command string, `*` crossing `/`). `at` sets how much delivers: `name` the bare tag, `preview` the routing line, `content` the whole body. Each entry is paid by every future agent it fires on, so default down: no surfaces at all is correct for reference depth reached through listings and [[links]], and when a doc fits in a single sentence, deliver `content` directly \u2014 a `preview` routing line would run longer than the doc itself. Sentence-length `content` docs are correct; never pad a memory to be more verbose than the rule or fact it carries.";
 export declare const GUIDE_ROUTING_LINE = "The routing line (--when-and-why-to-read) is the only text an agent reads before deciding to load the doc. The test for its because-clause: if it can be derived by paraphrasing the doc\u2019s advice, it is a restatement, not a payoff \u2014 a real payoff names a consequence in the reader\u2019s world that the document itself never asserts. Bad: \"because only genuine first principles belong in taste memory.\" Bad: \"because keeping the test loop fast and free of speculative tests protects the development pace\" \u2014 the doc\u2019s rule as an outcome, derivable straight from its advice. Good: \"because identifying throughlines in user taste lets future decisions be made faster and with less re-litigation.\" Someone mid-task who has not read the doc must be able to decide from this 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 \u2014 ask the user one sharp question instead of improvising.";
-export declare const GUIDE_PREDICATE_VOCABULARY = "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.";
-export declare const GUIDE_DOC_LINKS = "Link related docs with `[[canonical/name]]`. A doc link in any body is a first-class cross-reference to another memory document by its exact canonical name \u2014 the same identifier `crtr memory read` takes (a directory INDEX is linked by its bare directory name). Links are pointers, never transclusion: the linked body is loaded only when a reader follows it, so a link costs nothing until needed. `crtr memory lint` fails on a link that resolves to no document, and `crtr memory read` lists a doc\u2019s resolvable links alongside its body. There is no alias or label form.";
+export declare const GUIDE_PREDICATE_VOCABULARY = "Gate and match-frontmatter 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.";
+export declare const GUIDE_DOC_LINKS = "Link related docs with `[[canonical/name]]`. A doc link in any body is a first-class cross-reference to another memory document by its exact canonical name \u2014 the same identifier `crtr memory read` takes. A bare directory name is a valid link too: following it returns that directory\u2019s listing, a browse entrance rather than a doc. Links are pointers, never transclusion: the linked body is loaded only when a reader follows it, so a link costs nothing until needed. `crtr memory lint` fails on a link that resolves to no document or directory, and `crtr memory read` lists a doc\u2019s resolvable links alongside its body. There is no alias or label form.";