@north-light/crouter 0.3.201 → 0.3.202

package/dist/commands/memory/delete.js

@@ -2,7 +2,9 @@ import { existsSync, readdirSync, rmSync, rmdirSync } 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 { readText } from '../../core/fs-utils.js';
 import { resolveMemoryDoc } from '../../core/memory-resolver.js';
+import { appendHistoryRecord, buildHistoryRecord, historyLogPathFor } from '../../core/memory/history.js';
 import { MEMORY_SCOPES } from './shared.js';
 /** Remove the file's now-empty parent directories up to (never including) the
  *  scope's `memory/` root, so deleting the last doc under an `area/` prefix
@@ -35,12 +37,14 @@ export const deleteLeaf = defineLeaf({
             { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was deleted from: node, user, project, or profile.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path of the file that was removed.' },
             { name: 'deleted', type: 'boolean', required: true, constraint: 'Always true on success — the file was removed. A missing document fails with not_found instead.' },
-            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next command — browse what remains.' },
+            { name: 'log_path', type: 'string', required: true, constraint: 'Absolute path to the document’s revision log, which OUTLIVES the document — the delete is appended to it as a tombstone carrying the full final text, still readable with `crtr memory history`.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands — read the life of the removed doc, or browse what remains.' },
         ],
         outputKind: 'object',
         effects: [
             'Permanently removes memory/<name>.md from the resolved scope store, and prunes any parent directories it leaves empty. Irreversible.',
-        ],
+            'Appends a `delete` record carrying the document’s full final text to memory/.history/<name>.jsonl. The log itself is never removed.',
+        ]
     },
     run: async (input) => {
         const nameRaw = input['name'];
@@ -64,14 +68,21 @@ export const deleteLeaf = defineLeaf({
         if (doc.scope === 'builtin') {
             throw usage(`${doc.name} is a builtin document shipped with the package (read-only) — it cannot be deleted. Override it with a same-named doc at a writable scope instead (\`crtr memory write ${doc.name} ...\`).`, { memory: doc.name, scope: 'builtin' });
         }
+        const before = readText(doc.path);
+        const logPath = historyLogPathFor(doc.root, doc.path);
         rmSync(doc.path);
         pruneEmptyParents(resolvePath(doc.path), doc.name.split('/').length);
+        // The log is the audit trail and outlives the doc: the tombstone carries the
+        // full final text, and a later `write` of the same name keeps appending to
+        // this same log — one log per name over its whole life.
+        appendHistoryRecord(logPath, buildHistoryRecord({ op: 'delete', before, after: '' }));
         return {
             name: doc.name,
             scope: doc.scope,
             path: doc.path,
             deleted: true,
-            follow_up: `Removed. Browse what remains with \`crtr memory list\`.`,
+            log_path: logPath,
+            follow_up: `Removed. Its revision history survives — read it with \`crtr memory history ${doc.name}\`, or browse what remains with \`crtr memory list\`.`,
         };
     },
 });

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

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

package/dist/commands/memory/edit.js

@@ -0,0 +1,166 @@
+import { defineLeaf } from '../../core/command.js';
+import { CrtrError, notFound, usage } from '../../core/errors.js';
+import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
+import { readText, writeText } from '../../core/fs-utils.js';
+import { resolveMemoryDoc } from '../../core/memory-resolver.js';
+import { appendHistoryRecord, buildHistoryRecord, historyLogPathFor, readHistoryRecords, } from '../../core/memory/history.js';
+import { DOC_RATIONALE_CONSTRAINT, GUIDE_DOC_LINKS, GUIDE_PREDICATE_VOCABULARY, GUIDE_ROUTING_LINE, GUIDE_VISIBILITY_RUNGS, MEMORY_SCOPES, coerceAppliesTo, coerceGate, coerceReadWhen, overlayParam, literalBodySegment, serializeMemoryDocLiteral, } from './shared.js';
+/** Frontmatter fields an overlay flag cannot express removing. `kind`, the
+ *  routing line, and the two visibility rungs are the document's contract (a
+ *  doc without them is malformed); `origin` and `last-updated` are runtime
+ *  provenance. */
+const CLEARABLE_FIELDS = ['short-form', 'gate', 'applies-to', 'read-when', 'slash', 'rationale'];
+export const editLeaf = defineLeaf({
+    name: 'edit',
+    description: 'revise an existing memory document, recording why',
+    whenToUse: 'a document that already exists needs to change — its body, its frontmatter, or both. Every revision carries a --rationale and is appended to the doc\u2019s revision history, so the corpus keeps a record of why it reached its current state. Resolves the name exactly as `read` does and revises the doc where it lives; use `crtr memory write` only to create one that does not exist yet.',
+    help: {
+        name: 'memory edit',
+        summary: 'resolve an existing document and revise its body and/or frontmatter, appending a history record',
+        guide: 'The body you pipe is saved byte for byte. Nothing between stdin and disk parses, normalizes, summarizes, or rewrites it \u2014 the frontmatter fence is prepended and the text is otherwise untouched. Relaying a person\u2019s own words is therefore safe: pass them through unchanged and mark them with --verbatim.\n\n' +
+            'Two different rationales exist and they never share a flag. --rationale is why THIS REVISION is happening; it is required, it lands in the revision history, and it never touches the document text. --doc-rationale replaces the document\u2019s standing `rationale` frontmatter field \u2014 the observed gap the doc exists to close.\n\n' +
+            'Omitting stdin leaves the body exactly as it stands, which is how a frontmatter-only revision is made. Piping a body REPLACES the whole body; there is no partial or append mode. Emptying a document is not an edit \u2014 that intent is `crtr memory delete`.\n\n' +
+            'Omitted frontmatter flags preserve their fields. --unset is the only way to REMOVE one, and it is limited to fields a doc can legitimately live without (short-form, gate, applies-to, read-when, slash, rationale). --applies-to replaces the whole route set rather than adding to it.\n\n' +
+            'An edit that changes nothing fails. A rationale attached to zero change is noise in the trail the history exists to build \u2014 if the doc already says what you meant, there is nothing to record.\n\n' +
+            '`last-updated` is stamped on every successful edit; `origin` is preserved, so it keeps pointing at the conversation that created the doc rather than the last one to touch it.\n\n' +
+            GUIDE_ROUTING_LINE + '\n\n' +
+            GUIDE_VISIBILITY_RUNGS + '\n\n' +
+            GUIDE_PREDICATE_VOCABULARY + '\n\n' +
+            GUIDE_DOC_LINKS + '\n\n' +
+            'Create a document that does not exist yet with `crtr memory write`. Read the revisions back with `crtr memory history`.',
+        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. A leaf matching multiple documents in one source is rejected as ambiguous \u2014 pass the full name or --scope. Builtin and installed-plugin docs are read-only corpora and are refused.' },
+            { kind: 'flag', name: 'rationale', type: 'string', required: true, constraint: 'Why THIS REVISION is happening \u2014 the audit-trail entry, required on every edit. Recorded in the document\u2019s revision history, NEVER written into the document. To change the doc\u2019s standing `rationale` frontmatter field instead, use --doc-rationale.' },
+            { kind: 'flag', name: 'verbatim', type: 'bool', required: false, constraint: 'Declares the piped body a verbatim payload from the principal \u2014 their own text, relayed unchanged \u2014 rather than agent-authored prose. Pure provenance recorded in the history record; the save path is identical either way, because there is only one save path and it never transforms.' },
+            overlayParam('kind'),
+            overlayParam('when-and-why-to-read'),
+            overlayParam('short-form'),
+            overlayParam('system-prompt-visibility'),
+            overlayParam('file-read-visibility'),
+            overlayParam('gate'),
+            overlayParam('applies-to'),
+            overlayParam('read-when'),
+            overlayParam('slash', {}, 'Presence SETS the field; remove it with `--unset slash`.'),
+            { kind: 'flag', name: 'doc-rationale', type: 'string', required: false, constraint: DOC_RATIONALE_CONSTRAINT },
+            { kind: 'flag', name: 'unset', type: 'enum', choices: [...CLEARABLE_FIELDS], required: false, repeatable: true, constraint: 'Remove a frontmatter field an overlay flag cannot express removing. One field per occurrence. `kind`, `when-and-why-to-read`, the two visibility rungs, `origin`, and `last-updated` are never clearable. Unsetting `applies-to` while file-read-visibility is not none fails on the same invariant `write` raises.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Restrict resolution to this scope before editing. A disambiguation filter only \u2014 never a creation target, and never a way to move a doc between stores.' },
+            { kind: 'stdin', name: 'body', required: false, constraint: 'Full replacement body (markdown, no frontmatter), saved byte for byte. Piped on stdin only \u2014 this leaf already claims the one positional for NAME. Absent or empty stdin leaves the existing body untouched, which is how a frontmatter-only revision is made.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'Resolved document name.' },
+            { name: 'kind', type: 'string', required: true, constraint: 'Kind recorded in frontmatter after the revision.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was revised in: node, project, profile, or user.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the revised document.' },
+            { name: 'revision', type: 'number', required: true, constraint: 'This document\u2019s record count after the append \u2014 the revision number to pass to `crtr memory history --revision`.' },
+            { name: 'changed', type: 'string[]', required: true, constraint: '`body` when the body text changed, plus the frontmatter field names whose values changed. `last-updated` is excluded \u2014 it is stamped on every edit, so naming it says nothing.' },
+            { name: 'log_path', type: 'string', required: true, constraint: 'Absolute path to the document\u2019s append-only revision log (JSONL, one self-contained record per line).' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands \u2014 read the revisions or read the doc back.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Rewrites memory/<name>.md at the resolved scope and appends one `edit` record to memory/.history/<name>.jsonl.',
+        ],
+    },
+    run: async (input) => {
+        const nameRaw = input['name'];
+        const scopeArg = input['scope'];
+        const rationale = input['rationale'];
+        const verbatim = input['verbatim'] === true;
+        const stdinBody = input['body'] ?? '';
+        let doc;
+        try {
+            doc = resolveMemoryDoc(nameRaw, {
+                includeDescendants: true,
+                ...(scopeArg !== undefined ? { scope: scopeArg } : {}),
+            });
+        }
+        catch (e) {
+            if (e instanceof CrtrError && e.code === 'not_found') {
+                throw notFound(`memory document not found: ${nameRaw}`, {
+                    memory: nameRaw,
+                    next: `\`edit\` revises a document that already exists. Create it with \`crtr memory write ${nameRaw} ...\`, or run \`crtr memory find <query>\` if it exists under another name.`,
+                });
+            }
+            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}" \u2014 a read-only corpus managed by \`crtr pkg\`, not editable here. To override just this doc, write a same-named doc at a writable scope (\`crtr memory write ${doc.name} ...\`).`, { memory: doc.name, plugin: doc.plugin });
+        }
+        if (doc.scope === 'builtin') {
+            throw usage(`${doc.name} is a builtin document shipped with the package (read-only) \u2014 it cannot be edited. Override it with a same-named doc at a writable scope instead (\`crtr memory write ${doc.name} ...\`).`, { memory: doc.name, scope: 'builtin' });
+        }
+        const before = readText(doc.path);
+        const parsed = parseFrontmatterGeneric(before);
+        const previous = { ...(parsed.data ?? {}) };
+        const frontmatter = { ...previous };
+        const setIf = (key, value) => {
+            if (value !== undefined)
+                frontmatter[key] = value;
+        };
+        setIf('kind', input['kind']);
+        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['docRationale']);
+        for (const field of input['unset'] ?? []) {
+            delete frontmatter[field];
+        }
+        const applies = frontmatter['applies-to'];
+        const routes = typeof applies === 'string'
+            ? [applies]
+            : Array.isArray(applies) && applies.every((value) => typeof value === 'string')
+                ? applies
+                : [];
+        if (frontmatter['file-read-visibility'] !== 'none' && routes.length === 0) {
+            throw usage(`file-read-visibility ${String(frontmatter['file-read-visibility'])} requires at least one applies-to route: pass --applies-to (use "." for project workspace/profile-open context, a real file glob for matching reads), or set --file-read-visibility none`);
+        }
+        if (doc.scope !== 'project' && routes.some((route) => route.trim() === '.')) {
+            throw usage('applies-to "." is a project-store workspace mount route; use a real file glob or choose file-read-visibility none for user, profile, and node memory');
+        }
+        // LITERAL SAVE: the piped bytes reach disk untransformed, one structural
+        // blank line after the fence. Omitting stdin re-emits the existing body
+        // sliced from the raw file — never the parser's body, which drops leading
+        // blank lines and indentation.
+        const existingBody = literalBodySegment(before);
+        const bodySegment = stdinBody === '' ? existingBody : `\n${stdinBody}`;
+        // The no-op check compares against the document as it would serialize
+        // WITHOUT a fresh timestamp — `last-updated` changes on every edit, so
+        // stamping first would make every no-op look like a change.
+        const candidate = serializeMemoryDocLiteral(frontmatter, bodySegment);
+        if (candidate === before) {
+            throw usage(`edit changed nothing \u2014 ${doc.name} already says exactly this, so there is nothing to record`, {
+                memory: doc.name,
+                next: 'Pipe a different body or pass a frontmatter flag that changes a value. To remove the doc entirely, use `crtr memory delete`.',
+            });
+        }
+        frontmatter['last-updated'] = new Date().toISOString();
+        const after = serializeMemoryDocLiteral(frontmatter, bodySegment);
+        writeText(doc.path, after);
+        const logPath = historyLogPathFor(doc.root, doc.path);
+        appendHistoryRecord(logPath, buildHistoryRecord({ op: 'edit', rationale, ...(verbatim ? { verbatim: true } : {}), before, after }));
+        const changedFields = [...new Set([...Object.keys(previous), ...Object.keys(frontmatter)])]
+            .filter((key) => key !== 'last-updated')
+            .filter((key) => JSON.stringify(previous[key]) !== JSON.stringify(frontmatter[key]))
+            .sort((a, b) => a.localeCompare(b));
+        const changed = [...(bodySegment !== existingBody ? ['body'] : []), ...changedFields];
+        return {
+            name: doc.name,
+            kind: String(frontmatter['kind'] ?? ''),
+            scope: doc.scope,
+            path: doc.path,
+            revision: readHistoryRecords(logPath).length,
+            changed,
+            log_path: logPath,
+            follow_up: `Recorded. Review the revisions with \`crtr memory history ${doc.name} --diff\`, or read the doc back with \`crtr memory read ${doc.name}\`.`,
+        };
+    },
+});

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

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

package/dist/commands/memory/history.js

@@ -0,0 +1,179 @@
+import { join } from 'node:path';
+import { defineLeaf } from '../../core/command.js';
+import { CrtrError, notFound, usage } from '../../core/errors.js';
+import { nativeMemoryStoresInPrecedence, resolveHistoryLogPath, resolveMemoryDoc } from '../../core/memory-resolver.js';
+import { renderResult } from '../../core/render.js';
+import { parseSkillQualifier } from '../../core/resolver.js';
+import { HISTORY_DIR, historyLogPathFor, readHistoryRecords, summarizeChange, unifiedDiff, } from '../../core/memory/history.js';
+import { MEMORY_SCOPES } from './shared.js';
+/** Locate a document's revision log. A live doc resolves through the normal
+ *  document precedence walk; a DELETED one has no file to resolve, so its log
+ *  is resolved by name against each native store's `.history` tree in the same
+ *  order, under the same normalization the doc had — history outlives the
+ *  document it describes, answering to the name that document answered to. */
+function resolveLog(nameRaw, scopeArg) {
+    let doc;
+    try {
+        doc = resolveMemoryDoc(nameRaw, {
+            includeDescendants: true,
+            ...(scopeArg !== undefined ? { scope: scopeArg } : {}),
+        });
+    }
+    catch (e) {
+        if (!(e instanceof CrtrError && e.code === 'not_found'))
+            throw e;
+    }
+    if (doc !== undefined) {
+        if (doc.plugin !== undefined) {
+            throw usage(`${doc.name} belongs to the installed plugin "${doc.plugin}" — a read-only corpus with no revision history.`, {
+                memory: doc.name,
+                plugin: doc.plugin,
+            });
+        }
+        if (doc.scope === 'builtin') {
+            throw usage(`${doc.name} is a builtin document shipped with the package — a read-only corpus with no revision history.`, {
+                memory: doc.name,
+                scope: 'builtin',
+            });
+        }
+        return { name: doc.name, scope: doc.scope, logPath: historyLogPathFor(doc.root, doc.path) };
+    }
+    const parsed = parseSkillQualifier(nameRaw);
+    const name = parsed.segments.join('/');
+    if (name === '')
+        throw usage('memory document name required');
+    const scope = scopeArg ?? parsed.scope;
+    for (const store of nativeMemoryStoresInPrecedence(scope, true)) {
+        const logPath = resolveHistoryLogPath(join(store.memoryDir, HISTORY_DIR), parsed.segments);
+        if (logPath !== null)
+            return { name, scope: store.scope, logPath };
+    }
+    throw notFound(`no memory document or revision history found: ${nameRaw}`, {
+        memory: nameRaw,
+        next: 'Run `crtr memory find <query>` to locate the document. A document that exists but has no history predates this surface or has never been mutated through it.',
+    });
+}
+export const historyLeaf = defineLeaf({
+    name: 'history',
+    description: 'read a memory document\u2019s revision history',
+    whenToUse: 'you want to know how a document reached its current state \u2014 who revised it, when, why, and what changed per revision. Works for a deleted document too: the log outlives the doc. A diagnostics read; it advances nothing and changes nothing.',
+    help: {
+        name: 'memory history',
+        summary: 'list a document\u2019s revisions newest-first, with diffs or one full record on demand',
+        guide: 'Every mutation through `crtr memory write`, `edit`, and `delete` appends one self-contained record \u2014 complete document text before and after, plus who, when, and (on an edit) why. Diffs and revision numbers are derived here at read time, never stored.\n\n' +
+            'A record whose `before` differs from the previous record\u2019s `after` is the evidence of an out-of-band direct file edit; nothing prevents those, and nothing detects them beyond this.\n\n' +
+            'The log is a plain JSONL file at `log_path`, one JSON object per line \u2014 an external consumer reads it directly rather than through this command.',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`), resolved as `read` resolves it. When no such document exists, the same resolution runs against each writable store\u2019s history tree in precedence order \u2014 which is how a deleted document\u2019s history still answers to the name that document answered to. Builtin and installed-plugin docs are read-only corpora and carry no history.' },
+            { kind: 'flag', name: 'limit', type: 'int', required: false, default: 10, constraint: 'How many revisions to return, newest first. Default 10.' },
+            { kind: 'flag', name: 'diff', type: 'bool', required: false, constraint: 'Include a unified diff per listed revision, computed from that record\u2019s own before/after texts.' },
+            { kind: 'flag', name: 'revision', type: 'int', required: false, constraint: 'Show ONE revision in full \u2014 its metadata plus the complete before and after document texts. 1-based position in the log: the number `crtr memory edit` reports. Overrides --limit and --diff.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Restrict resolution to this scope. A disambiguation filter for a name present at several scopes.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'Resolved document name.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'Scope whose store holds the log: node, project, profile, or user.' },
+            { name: 'log_path', type: 'string', required: true, constraint: 'Absolute path to the append-only JSONL log \u2014 the direct-consumption pointer, one self-contained record per line.' },
+            { name: 'total', type: 'number', required: true, constraint: 'Total revisions in the log.' },
+            { name: 'revisions', type: 'object[]', required: false, constraint: 'Newest-first, capped by --limit. Each: {revision, op, at, node, rationale, body_changed, frontmatter_changed, diff}. `node` and `rationale` are present only when recorded; `diff` only with --diff. Absent when --revision selects one record.' },
+            { name: 'record', type: 'object', required: false, constraint: 'Present only with --revision: {revision, op, at, node, cwd, rationale, verbatim, before, after} \u2014 the full record including both complete document texts.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands \u2014 the flag variants and the doc read.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    // A unified diff is multi-line, and the default object[] renderer flattens it
+    // into one table cell. With --diff each revision gets its own block instead;
+    // every other shape falls through to the default rendering.
+    render: (result) => {
+        const revisions = result['revisions'];
+        if (revisions === undefined || !revisions.some((r) => typeof r['diff'] === 'string')) {
+            return renderResult(result, historyLeaf.help);
+        }
+        const blocks = revisions.map((r) => {
+            const meta = [`op: ${String(r['op'])}`, `at: ${String(r['at'])}`];
+            if (r['node'] !== undefined)
+                meta.push(`node: ${String(r['node'])}`);
+            if (r['verbatim'] === true)
+                meta.push('verbatim');
+            const fields = r['frontmatter_changed'] ?? [];
+            const changed = [
+                ...(r['body_changed'] === true ? ['body'] : []),
+                ...(fields.length > 0 ? [`frontmatter: ${fields.join(', ')}`] : []),
+            ];
+            const diff = String(r['diff'] ?? '');
+            return [
+                `## revision ${String(r['revision'])} \u2014 ${meta.join('  \u00b7  ')}`,
+                ...(r['rationale'] !== undefined ? [`rationale: ${String(r['rationale'])}`] : []),
+                `changed: ${changed.length > 0 ? changed.join('; ') : 'nothing'}`,
+                ...(diff === '' ? [] : ['', '```diff', diff, '```']),
+            ].join('\n');
+        });
+        return [
+            `- name: ${String(result['name'])}`,
+            `- scope: ${String(result['scope'])}`,
+            `- log_path: ${String(result['log_path'])}`,
+            `- total: ${String(result['total'])}`,
+            '',
+            blocks.join('\n\n'),
+            '',
+            String(result['follow_up']),
+        ].join('\n');
+    },
+    run: async (input) => {
+        const nameRaw = input['name'];
+        const scopeArg = input['scope'];
+        const limit = input['limit'] ?? 10;
+        const wantDiff = input['diff'] === true;
+        const revisionArg = input['revision'];
+        const { name, scope, logPath } = resolveLog(nameRaw, scopeArg);
+        const records = readHistoryRecords(logPath);
+        if (records.length === 0) {
+            throw notFound(`no revision history recorded for ${name}`, {
+                memory: name,
+                next: 'The document predates this surface or has never been mutated through `crtr memory write`/`edit`/`delete`. Its first edit records the pre-existing content in full.',
+            });
+        }
+        if (revisionArg !== undefined) {
+            if (revisionArg < 1 || revisionArg > records.length) {
+                throw usage(`revision ${revisionArg} is out of range for ${name} (1..${records.length})`, {
+                    memory: name,
+                    next: `Run \`crtr memory history ${name}\` to see which revisions exist.`,
+                });
+            }
+            const r = records[revisionArg - 1];
+            return {
+                name,
+                scope,
+                log_path: logPath,
+                total: records.length,
+                record: { revision: revisionArg, ...r },
+                follow_up: `Read the document as it stands with \`crtr memory read ${name}\`, or list the revisions with \`crtr memory history ${name} --diff\`.`,
+            };
+        }
+        const revisions = records
+            .map((r, i) => {
+            const summary = summarizeChange(r.before, r.after);
+            return {
+                revision: i + 1,
+                op: r.op,
+                at: r.at,
+                ...(r.node !== undefined ? { node: r.node } : {}),
+                ...(r.rationale !== undefined ? { rationale: r.rationale } : {}),
+                ...(r.verbatim === true ? { verbatim: true } : {}),
+                ...summary,
+                ...(wantDiff ? { diff: unifiedDiff(r.before, r.after) } : {}),
+            };
+        })
+            .reverse()
+            .slice(0, Math.max(0, limit));
+        return {
+            name,
+            scope,
+            log_path: logPath,
+            total: records.length,
+            revisions,
+            follow_up: `Add --diff for per-revision unified diffs, --revision N for one record's full before/after text, or read the document as it stands with \`crtr memory read ${name}\`.`,
+        };
+    },
+});

package/dist/commands/memory/list.js

@@ -86,7 +86,7 @@ export const listLeaf = defineLeaf({
             })),
             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>`.',
+            follow_up: 'Read one in full with `crtr memory read <name>`, or revise one with `crtr memory edit <name> --rationale "<why>"` (body, routing, frontmatter, and visibility all go through that one verb, and it records the change). Narrow with --kind / --scope, page with --cursor, or search a topic with `crtr memory find <query>`.',
         };
     },
 });

package/dist/commands/memory/read.js

@@ -127,7 +127,7 @@ export const readLeaf = defineLeaf({
             { name: 'name', type: 'string', required: true, constraint: 'Resolved document name.' },
             { name: 'kind', type: 'string', required: true, constraint: 'Resolved kind: knowledge or preference.' },
             { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was resolved from: 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: '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.' },
@@ -196,7 +196,7 @@ export const readLeaf = defineLeaf({
                     : 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 edit `path` directly for a body-only tweak. Browse the inventory with `crtr memory list`.',
+                    '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}`, {

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

@@ -1,3 +1,4 @@
+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"];
@@ -52,3 +53,29 @@ export declare function buildOrigin(): Record<string, unknown>;
  *  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;
+/** Everything after the closing frontmatter fence, byte for byte — leading blank
+ *  lines and indentation intact. Source without a fence is all body. */
+export declare function literalBodySegment(source: string): string;
+/** Serialize a document WITHOUT touching the body. `bodySegment` is everything
+ *  after the closing frontmatter fence (leading blank line included), emitted
+ *  byte for byte. This is the revision path: `edit` saves what it was given, so
+ *  an unchanged doc round-trips identically and a supplied body reaches disk
+ *  untransformed. Creation uses `serializeMemoryDoc`, which normalizes a first
+ *  body into the canonical shape. */
+export declare function serializeMemoryDocLiteral(frontmatter: Record<string, unknown>, bodySegment: string): string;
+/** The frontmatter-overlay flags, keyed by flag name, carrying the prose true
+ *  on BOTH leaves. `write` appends its creation clauses with `withConstraint`;
+ *  neither leaf restates the other's rules. */
+export declare const FRONTMATTER_OVERLAY_PARAMS: Record<string, FlagParam>;
+/** One overlay flag, with leaf-specific prose appended to the shared
+ *  constraint and any leaf-specific schema override applied. */
+export declare function overlayParam(name: string, overrides?: Partial<FlagParam>, extraConstraint?: string): FlagParam;
+/** The doc's standing `rationale` frontmatter field \u2014 the observed gap the doc
+ *  exists to close. `write` takes it as `--rationale`; `edit` takes it as
+ *  `--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_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.";

package/dist/commands/memory/shared.js

@@ -185,6 +185,7 @@ const FRONTMATTER_ORDER = [
     'applies-to',
     'read-when',
     'rationale',
+    'last-updated',
     'origin',
 ];
 /** Provenance for a doc at the moment it is created: when, where, and which
@@ -223,3 +224,71 @@ export function serializeMemoryDoc(frontmatter, body) {
     const cleanBody = body.replace(/^\n+/, '').replace(/\s+$/, '');
     return `---\n${yamlText}\n---\n\n${cleanBody}\n`;
 }
+// Structure only: the closing fence tolerates trailing spaces/tabs but never
+// consumes the newlines or indentation that open the body. `parseFrontmatterGeneric`
+// closes on `\s*`, which eats them — fine for reading a doc, lossy for rewriting one.
+const LITERAL_FENCE_RE = /^---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/;
+/** Everything after the closing frontmatter fence, byte for byte — leading blank
+ *  lines and indentation intact. Source without a fence is all body. */
+export function literalBodySegment(source) {
+    const match = source.match(LITERAL_FENCE_RE);
+    return match ? source.slice(match[0].length) : source;
+}
+/** Serialize a document WITHOUT touching the body. `bodySegment` is everything
+ *  after the closing frontmatter fence (leading blank line included), emitted
+ *  byte for byte. This is the revision path: `edit` saves what it was given, so
+ *  an unchanged doc round-trips identically and a supplied body reaches disk
+ *  untransformed. Creation uses `serializeMemoryDoc`, which normalizes a first
+ *  body into the canonical shape. */
+export function serializeMemoryDocLiteral(frontmatter, bodySegment) {
+    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+$/, '');
+    return `---\n${yamlText}\n---\n${bodySegment}`;
+}
+// ---------------------------------------------------------------------------
+// Help material shared by `write` and `edit`
+//
+// Single-sourced: both leaves compose these, so a wording fix lands on both.
+// Anything exclusive to one leaf (creation rules on `write`, the rationale
+// contract on `edit`) stays owned by that leaf.
+// ---------------------------------------------------------------------------
+/** The frontmatter-overlay flags, keyed by flag name, carrying the prose true
+ *  on BOTH leaves. `write` appends its creation clauses with `withConstraint`;
+ *  neither leaf restates the other's rules. */
+export const FRONTMATTER_OVERLAY_PARAMS = {
+    'kind': { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: false, constraint: 'Document kind.' },
+    'when-and-why-to-read': { 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\u2019s payoff \u2014 the consequence they secure for their task by reading \u2014 NEVER the doc summary, its rule, or that rule reworded as an outcome (a benefit-shaped restatement still fails). Rendered verbatim as the preview.' },
+    'short-form': { kind: 'flag', name: 'short-form', type: 'string', required: false, constraint: 'Frontmatter short-form \u2014 a very abbreviated version of the content, the hook shown in `crtr memory list`.' },
+    'system-prompt-visibility': { 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.' },
+    'file-read-visibility': { kind: 'flag', name: 'file-read-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much surfaces through file context. Every value except none also requires at least one applies-to route in the resulting document.' },
+    'gate': { kind: 'flag', name: 'gate', type: 'string', required: false, constraint: 'Frontmatter gate \u2014 YAML/JSON object predicate over node config using the same field/matcher vocabulary described in the guide.' },
+    'applies-to': { kind: 'flag', name: 'applies-to', type: 'string', required: false, repeatable: true, constraint: 'One explicit file-context route per occurrence; the flag set replaces the document\u2019s whole route list. In a project store, `.` fires when cwd/profile mounts that workspace during first-message assembly AND on any file read beneath the store\u2019s owning dir. Any other value is a glob matched after an actual file read against the absolute path, basename, and path relative to the owning project root. There is no positional fallback from where the memory file lives. Required whenever file-read-visibility is not none.' },
+    'read-when': { kind: 'flag', name: 'read-when', type: 'string', required: false, constraint: 'Frontmatter read-when \u2014 YAML/JSON object predicate over a read file\u2019s own frontmatter using the same field/matcher vocabulary described in the guide.' },
+    'slash': { 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 `:`) \u2014 the doc body becomes the command\u2019s injected prompt. Default false: most docs are consulted, not invoked.' },
+};
+/** One overlay flag, with leaf-specific prose appended to the shared
+ *  constraint and any leaf-specific schema override applied. */
+export function overlayParam(name, overrides = {}, extraConstraint) {
+    const base = FRONTMATTER_OVERLAY_PARAMS[name];
+    if (base === undefined)
+        throw new Error(`unknown frontmatter overlay param: ${name}`);
+    const constraint = extraConstraint === undefined ? base.constraint : `${base.constraint} ${extraConstraint}`;
+    return { ...base, ...overrides, constraint };
+}
+/** The doc's standing `rationale` frontmatter field \u2014 the observed gap the doc
+ *  exists to close. `write` takes it as `--rationale`; `edit` takes it as
+ *  `--doc-rationale`, because `--rationale` there means why THIS REVISION is
+ *  happening. Same field, same prose, two flag names that cannot be confused. */
+export 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 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 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 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 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.';