@north-light/crouter 0.3.233 → 0.3.235

package/dist/commands/memory/__tests__/command-selector-and-mutation-guards.test.js

@@ -82,7 +82,7 @@ beforeEach(() => {
     mkdirSync(child, { recursive: true });
     mkdirSync(nestedWrite, { recursive: true });
     mkdirSync(nestedEmpty, { recursive: true });
-    // --- repository root, declaring the namespace for every nested store ---
+    // repository root, declaring the namespace for every nested store
     writeDoc(join(storeDir(root), 'INDEX.md'), 'kind: knowledge\nnamespace: acme\nwhen-and-why-to-read: "When the root acme store is addressed, this knowledge should be read because it names what the store holds."', 'ROOT STORE INDEX');
     writeDoc(join(storeDir(root), 'foo.md'), 'kind: knowledge', 'ROOT FOO BODY');
     writeDoc(join(storeDir(root), 'linker.md'), 'kind: knowledge', 'ROOT LINKER BODY linking [[acme/foo]] once.');
@@ -91,17 +91,17 @@ beforeEach(() => {
     // A `name:` pin on a file whose own path already derives a different identity.
     writeDoc(join(storeDir(root), 'x.md'), 'kind: knowledge\nname: y', 'ROOT PINNED BODY');
     appendHistoryRecord(join(storeDir(root), '.history', 'x.jsonl'), buildHistoryRecord({ op: 'create', before: '', after: 'ROOT PINNED BODY' }));
-    // --- child: a nested store deriving `acme/child`; cwd lives here ---
+    // child: a nested store deriving `acme/child`; cwd lives here
     writeDoc(join(storeDir(child), 'INDEX.md'), 'kind: knowledge\nwhen-and-why-to-read: "When the child guide is addressed, this knowledge should be read because it names what the nested store holds."', 'CHILD STORE INDEX');
     writeDoc(join(storeDir(child), 'foo.md'), 'kind: knowledge', 'CHILD FOO BODY');
     // This nested store has content but no guide, so a write at its exact prefix
     // must create metadata-free INDEX.md rather than a second declaration.
     writeDoc(join(storeDir(nestedWrite), 'topic.md'), 'kind: knowledge', 'NESTED WRITE TOPIC');
-    // --- lint fixtures ---
+    // lint fixtures
     writeDoc(join(storeDir(badns), 'INDEX.md'), 'kind: knowledge\nnamespace: 42', 'BADNS STORE INDEX');
     writeDoc(join(storeDir(dangling), 'INDEX.md'), 'kind: knowledge\nnamespace: dang\nwhen-and-why-to-read: "When the dang store is addressed, this knowledge should be read because it names what the store holds."', 'DANG STORE INDEX');
     writeDoc(join(storeDir(dangling), 'broken.md'), 'kind: knowledge', 'Links [[dang/nowhere]], which no document answers to.');
-    // --- two profiles, both holding the SAME canonical name ---
+    // two profiles, both holding the SAME canonical name
     const a = createProfile('memcmd-a');
     const b = createProfile('memcmd-b');
     profileB = profileMemoryDir(b.profileId);

package/dist/commands/memory/__tests__/memory-list-and-lint-ignore.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/memory/__tests__/memory-list-and-lint-ignore.test.js

@@ -0,0 +1,96 @@
+import { test, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { parseFrontmatterGeneric } from '../../../core/frontmatter.js';
+import { resetScopeCache } from '../../../core/scope.js';
+import { CrtrError } from '../../../core/errors.js';
+import { editLeaf } from '../edit.js';
+import { listLeaf } from '../list.js';
+import { writeLeaf } from '../write.js';
+const previousHome = process.env['HOME'];
+const previousCrtrHome = process.env['CRTR_HOME'];
+const home = mkdtempSync(join(tmpdir(), 'crtr-memory-list-'));
+const canvasHome = mkdtempSync(join(tmpdir(), 'crtr-memory-list-canvas-'));
+mkdirSync(join(home, '.crouter', 'memory'), { recursive: true });
+process.env['HOME'] = home;
+process.env['CRTR_HOME'] = canvasHome;
+function writeMemory(name, frontmatter = 'kind: knowledge') {
+    writeFileSync(join(home, '.crouter', 'memory', name), `---\n${frontmatter}\n---\n\nBODY\n`, 'utf8');
+}
+after(() => {
+    resetScopeCache();
+    if (previousHome === undefined)
+        delete process.env['HOME'];
+    else
+        process.env['HOME'] = previousHome;
+    if (previousCrtrHome === undefined)
+        delete process.env['CRTR_HOME'];
+    else
+        process.env['CRTR_HOME'] = previousCrtrHome;
+    rmSync(home, { recursive: true, force: true });
+    rmSync(canvasHome, { recursive: true, force: true });
+});
+test('memory list resumes locale-aware pages across case boundaries', async () => {
+    writeMemory('upper.md', 'kind: knowledge\nname: A');
+    writeMemory('lower.md', 'kind: knowledge\nname: a');
+    writeMemory('INDEXED.md');
+    const first = (await listLeaf.run({ scope: 'user', limit: 2, cursor: undefined, kind: undefined, dir: undefined, paths: false }));
+    assert.deepEqual(first.items.map((item) => item.name), ['a', 'A']);
+    assert.ok(first.next_cursor);
+    const second = (await listLeaf.run({ scope: 'user', limit: 1, cursor: first.next_cursor, kind: undefined, dir: undefined, paths: false }));
+    assert.deepEqual(second.items.map((item) => item.name), ['INDEXED']);
+    const edge = (await listLeaf.run({ scope: 'user', limit: 3, cursor: undefined, kind: undefined, dir: undefined, paths: false }));
+    assert.deepEqual(edge.items.map((item) => item.name), ['a', 'A', 'INDEXED']);
+    assert.equal(edge.next_cursor, null);
+});
+test('memory write and edit set, validate, and unset lint-ignore', async () => {
+    const scalar = (await writeLeaf.run({
+        name: 'lint-scalar',
+        scope: 'user',
+        kind: 'knowledge',
+        whenAndWhyToRead: 'When lint length is intentional, this knowledge should be read because the document remains available.',
+        lintIgnore: 'length',
+        body: 'SCALAR',
+    }));
+    assert.equal(parseFrontmatterGeneric(readFileSync(scalar.path, 'utf8')).data?.['lint-ignore'], 'length');
+    const list = (await writeLeaf.run({
+        name: 'lint-list',
+        scope: 'user',
+        kind: 'knowledge',
+        whenAndWhyToRead: 'When lint breadth is intentional, this knowledge should be read because the document remains available.',
+        lintIgnore: ['length', 'broad-memory-read'],
+        body: 'LIST',
+    }));
+    assert.deepEqual(parseFrontmatterGeneric(readFileSync(list.path, 'utf8')).data?.['lint-ignore'], ['length', 'broad-memory-read']);
+    await editLeaf.run({
+        name: 'lint-scalar',
+        scope: 'user',
+        rationale: 'set the second suppressible rule',
+        lintIgnore: ['length', 'broad-memory-read'],
+    });
+    await editLeaf.run({
+        name: 'lint-scalar',
+        scope: 'user',
+        rationale: 'remove lint suppression',
+        unset: ['lint-ignore'],
+    });
+    assert.equal(parseFrontmatterGeneric(readFileSync(scalar.path, 'utf8')).data?.['lint-ignore'], undefined);
+    let error;
+    try {
+        await writeLeaf.run({
+            name: 'lint-invalid',
+            scope: 'user',
+            kind: 'knowledge',
+            whenAndWhyToRead: 'When invalid lint metadata is supplied, this knowledge should be read because it must be rejected.',
+            lintIgnore: ['length', 'not-a-rule'],
+            body: 'INVALID',
+        });
+    }
+    catch (caught) {
+        error = caught;
+    }
+    assert.ok(error instanceof CrtrError);
+    assert.equal(error.code, 'usage');
+});

package/dist/commands/memory/delete.js

@@ -33,7 +33,7 @@ export const deleteLeaf = defineLeaf({
         summary: 'resolve an exact canonical name and remove that document from its store',
         params: [
             { kind: 'positional', name: 'name', required: true, constraint: 'Full canonical name of the document — a project document is `<namespace>/<local name>`. Resolution is exact, as `read` resolves it: a file path, a bare leaf, a `<scope>/<name>` spelling, and a trailing `/INDEX` all fail. A canonical directory’s own document is deleted at the directory name; its members are untouched and stay reachable. If two physical files in the selected store own the name, delete selects the first path in stable lexical order and reports it. Builtin and installed-plugin documents are read-only and refuse to delete, as does the repository-root document, which declares the immutable namespace for every document in the repository; a nested store’s root guide is ordinary and may be deleted.' },
-            selectorParam('scope-read', { choices: [...MEMORY_WRITE_SCOPES] }, 'builtin is not a choice — builtin documents ship with the package and cannot be deleted.'),
+            selectorParam('scope-read', { choices: [...MEMORY_WRITE_SCOPES] }, 'Package-shipped documents cannot be deleted through this writable-scope selector.'),
             selectorParam('dir', {}, 'Deletes from that one store, including a non-winning duplicate no target view resolves to.'),
         ],
         output: [

package/dist/commands/memory/edit.js

@@ -4,11 +4,11 @@ import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
 import { readText, writeText } from '../../core/fs-utils.js';
 import { loadMemoryStoreView, resolveMemoryCandidates, } from '../../core/memory-resolver.js';
 import { appendHistoryRecord, buildHistoryRecord, historyLogPathFor, readHistoryRecords, } from '../../core/memory/history.js';
-import { DOC_RATIONALE_CONSTRAINT, GUIDE_CANONICAL_NAMES, GUIDE_DOC_LINKS, GUIDE_PREDICATE_VOCABULARY, GUIDE_ROUTING_LINE, GUIDE_SURFACES, coerceGate, coerceSurface, memoryExtensionCatalogForDoc, memoryExtensionFieldCatalogHelp, overlayParam, parseRequestedExtensionChanges, applyExtensionChanges, literalBodySegment, serializeMemoryDocLiteral, selectorParam, requireLocalNameInStore, requireUnambiguousDoc, resolveReadSelector, } from './shared.js';
+import { DOC_RATIONALE_CONSTRAINT, GUIDE_CANONICAL_NAMES, GUIDE_DOC_LINKS, GUIDE_PREDICATE_VOCABULARY, GUIDE_ROUTING_LINE, GUIDE_SURFACES, coerceGate, coerceLintIgnore, coerceSurface, memoryExtensionCatalogForDoc, memoryExtensionFieldCatalogHelp, overlayParam, parseRequestedExtensionChanges, applyExtensionChanges, literalBodySegment, serializeMemoryDocLiteral, selectorParam, requireLocalNameInStore, requireUnambiguousDoc, resolveReadSelector, } from './shared.js';
 /** Frontmatter fields an overlay flag cannot express removing. `kind` and the
  *  routing line are the document's contract (a doc without them is malformed);
  *  `origin` and `last-updated` are runtime provenance. */
-const CLEARABLE_FIELDS = ['short-form', 'gate', 'surfaces', 'unlisted', 'slash', 'rationale'];
+const CLEARABLE_FIELDS = ['short-form', 'gate', 'surfaces', 'unlisted', 'slash', 'rationale', 'lint-ignore'];
 export const editLeaf = defineLeaf({
     name: 'edit',
     description: 'revise an existing memory document, recording why',
@@ -19,7 +19,7 @@ export const editLeaf = defineLeaf({
         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, surfaces, unlisted, slash, rationale). --surface replaces the whole surfaces list rather than adding to it.\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, surfaces, unlisted, slash, rationale, lint-ignore). --surface replaces the whole surfaces list 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' +
@@ -38,6 +38,7 @@ export const editLeaf = defineLeaf({
             overlayParam('unlisted', {}, 'Presence SETS the field; remove it with `--unset unlisted`.'),
             overlayParam('surface'),
             overlayParam('gate'),
+            overlayParam('lint-ignore'),
             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: 'extension', type: 'string', required: false, repeatable: true, constraint: 'Set one declared plugin field as `extensions.<plugin>.<field>=VALUE`. The path is required in full; booleans accept only true or false, numbers require finite numeric syntax, and strings/enums preserve the literal text after the first =. Every requested field validates before the document is revised.' },
@@ -105,6 +106,7 @@ export const editLeaf = defineLeaf({
         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 lintIgnore = coerceLintIgnore(input['lintIgnore']);
         const extensionChanges = parseRequestedExtensionChanges(input['extension'], input['unsetExtension'], memoryExtensionCatalogForDoc(doc));
         const before = readText(doc.path);
         const parsed = parseFrontmatterGeneric(before);
@@ -146,6 +148,7 @@ export const editLeaf = defineLeaf({
         }
         if (input['gate'] !== undefined)
             frontmatter['gate'] = coerceGate(input['gate']);
+        setIf('lint-ignore', lintIgnore);
         if (input['slash'] === true)
             frontmatter['slash'] = true;
         setIf('rationale', input['docRationale']);

package/dist/commands/memory/find.js

@@ -126,7 +126,7 @@ export const findLeaf = defineLeaf({
         const units = selector.store !== null
             ? searchUnits(kindFilter, loadMemoryStoreView(requireMountedStore(selector.store), false).docs, false)
             : searchUnits(kindFilter, listAllMemoryDocs(selector.scope, false, true), true);
-        // --- grep mode: regex over every unit's body, one row per matching line ---
+        // grep mode: regex over every unit's body, one row per matching line
         if (grep) {
             let regex;
             try {
@@ -167,7 +167,7 @@ export const findLeaf = defineLeaf({
             registerMemoryListingExposure(listingIdentity);
             return output;
         }
-        // --- ranked mode: weighted relevance over name/routing-line/short-form(+body) ---
+        // ranked mode: weighted relevance over name/routing-line/short-form(+body)
         const terms = query
             .toLowerCase()
             .split(/\s+/)

package/dist/commands/memory/lint.js

@@ -3,6 +3,7 @@
 // verification, the plugin candidate gate, and the build's builtin gate consume
 // too; this leaf only picks WHAT to lint (a target view, or one exact store
 // with --dir) and shapes the findings for the CLI.
+import { envProfileId } from '../../shared/env.js';
 import { defineLeaf } from '../../core/command.js';
 import { warn } from '../../core/output.js';
 import { ExitCode } from '../../types.js';
@@ -26,7 +27,7 @@ function findingRow(finding) {
 function resolvableNamesForStore(store) {
     const view = loadMemoryTargetView({
         cwd: store.ownerDir ?? store.storeRoot,
-        profileId: process.env['CRTR_PROFILE_ID'] || null,
+        profileId: envProfileId() || null,
         nodeId: null,
     }, { quiet: true, includeDescendants: true });
     return resolvableCanonicalNames(view.docs);

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

@@ -20,4 +20,8 @@ export interface ListedMemoryDoc {
  *  point of naming a store is to see what it physically holds, including a pair
  *  that shares one identity. */
 export declare function listMemoryDocs(kindFilter: string | undefined, docs: readonly MemoryDoc[], dedup: boolean): ListedMemoryDoc[];
+/** The stable key used by both inventory ordering and cursor resumption. */
+export declare function memoryListKey(doc: Pick<ListedMemoryDoc, 'scope' | 'kind' | 'name' | 'physicalRelativePath'>): string;
+/** Locale-aware total order for memory inventory keys. */
+export declare function compareMemoryListKeys(left: string, right: string): number;
 export declare const listLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/memory/list.js

@@ -46,20 +46,26 @@ export function listMemoryDocs(kindFilter, docs, dedup) {
             candidates: byName.get(doc.name) ?? [doc],
         });
     }
-    // Physical path is the final tiebreaker so two rows of one identity keep a
-    // stable order — the cursor key ends on the same component.
-    items.sort((a, b) => {
-        const sr = scopeRank(a.scope) - scopeRank(b.scope);
-        if (sr !== 0)
-            return sr;
-        const kc = a.kind.localeCompare(b.kind);
-        if (kc !== 0)
-            return kc;
-        const nc = a.name.localeCompare(b.name);
-        return nc !== 0 ? nc : a.physicalRelativePath.localeCompare(b.physicalRelativePath);
-    });
+    items.sort((a, b) => compareMemoryListKeys(memoryListKey(a), memoryListKey(b)));
     return items;
 }
+/** The stable key used by both inventory ordering and cursor resumption. */
+export function memoryListKey(doc) {
+    return `${String(scopeRank(doc.scope) + 10).padStart(2, '0')}:${doc.kind}:${doc.name}:${doc.physicalRelativePath}`;
+}
+/** Locale-aware total order for memory inventory keys. */
+export function compareMemoryListKeys(left, right) {
+    const [leftScope, leftKind, leftName, ...leftPath] = left.split(':');
+    const [rightScope, rightKind, rightName, ...rightPath] = right.split(':');
+    const scope = Number(leftScope) - Number(rightScope);
+    if (scope !== 0)
+        return scope;
+    const kind = leftKind.localeCompare(rightKind);
+    if (kind !== 0)
+        return kind;
+    const name = leftName.localeCompare(rightName);
+    return name !== 0 ? name : leftPath.join(':').localeCompare(rightPath.join(':'));
+}
 export const listLeaf = defineLeaf({
     name: 'list',
     description: 'inventory of stored memory documents',
@@ -95,8 +101,8 @@ export const listLeaf = defineLeaf({
         const items = selector.store !== null
             ? listMemoryDocs(kindFilter, loadMemoryStoreView(requireMountedStore(selector.store), false).docs, false)
             : listMemoryDocs(kindFilter, listAllMemoryDocs(selector.scope, false, true), true);
-        const keyOf = (d) => `${String(scopeRank(d.scope) + 10).padStart(2, '0')}:${d.kind}:${d.name}:${d.physicalRelativePath}`;
-        const result = paginate(items, { limit, cursor }, { defaultLimit: 50, maxLimit: 200, keyOf, total: 'count' });
+        const keyOf = memoryListKey;
+        const result = paginate(items, { limit, cursor }, { defaultLimit: 50, maxLimit: 200, keyOf, compareKeys: compareMemoryListKeys, total: 'count' });
         const output = {
             items: result.items.map((d) => ({
                 name: d.name,

package/dist/commands/memory/move.js

@@ -53,7 +53,7 @@ export const moveLeaf = defineLeaf({
         params: [
             { kind: 'positional', name: 'name', required: true, constraint: 'Full canonical name of the document to move — a project document is `<namespace>/<local name>`. Resolution is exact, as `read` resolves it: a file path, a bare leaf, a `<scope>/<name>` spelling, and a trailing `/INDEX` all fail. If two physical files in the selected store own the name, move selects the first path in stable lexical order and recovers the collision. Builtin and installed-plugin documents are read-only and refuse to move, as does the repository-root document, which declares the immutable namespace for every document in the repository; a nested store’s root guide is ordinary and may move.' },
             { kind: 'flag', name: 'to', type: 'string', required: true, constraint: 'The new full canonical name, in the SAME store — the repository namespace and store path included, since a move never crosses stores. `/`-joined segments of [A-Za-z0-9_-], no trailing `INDEX` (a directory’s document answers at the directory name). A nested store’s effective prefix is a legal destination for its optional root guide. Rejected when a document in that store already answers to it, or when either `<local name>.md` or `<local name>/INDEX.md` already exists there.' },
-            selectorParam('scope-read', { choices: [...MEMORY_WRITE_SCOPES] }, 'builtin is not a choice — builtin documents ship with the package and cannot move.'),
+            selectorParam('scope-read', { choices: [...MEMORY_WRITE_SCOPES] }, 'Package-shipped documents cannot move through this writable-scope selector.'),
             selectorParam('dir', {}, 'Source, destination, and inbound-link rewriting all stay inside that one store, so moving a non-winning duplicate leaves every other store untouched — and rewrites no link at all, because the name still resolves to the candidate that outranks it here.'),
         ],
         output: [

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

@@ -1,11 +1,6 @@
-import { createMemoryDocSnapshot, resolveMemoryDocs } from '../../core/memory-resolver.js';
+import { createMemoryDocSnapshot, readMemoryDocContent, resolveMemoryDocs } from '../../core/memory-resolver.js';
 import type { MemoryDoc } from '../../core/memory-resolver.js';
-export { createMemoryDocSnapshot, resolveMemoryDocs };
-/** Load the body at an already-resolved memory path with the same frontmatter
- * stripping and in-node path interpolation as `memory read`. Callers that
- * already have the resolved path (such as slash-command discovery) avoid
- * re-walking every memory store for each document. */
-export declare function readMemoryDocContent(path: string, includeFrontmatter?: boolean): string;
+export { createMemoryDocSnapshot, readMemoryDocContent, resolveMemoryDocs };
 /** One physical document sharing a canonical identity, as the path-aware
  *  surfaces report it. `--dir <its project>` is how a non-winner is reached. */
 export declare function candidateRow(doc: MemoryDoc, winner: MemoryDoc): Record<string, unknown>;

package/dist/commands/memory/read.js

@@ -1,12 +1,11 @@
+import { envNodeId } from '../../shared/env.js';
 import { CrtrClient } from '../../api/index.js';
-import { interpolateNodePaths } from '../../core/canvas/paths.js';
 import { defineLeaf } from '../../core/command.js';
 import { CrtrError } from '../../core/errors.js';
 import { memoryExtensionEffectiveCatalog, projectEffectiveMemoryExtensions } from '../../core/memory/extensions.js';
-import { readText, realpathOrSelf } from '../../core/fs-utils.js';
-import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
+import { realpathOrSelf } from '../../core/fs-utils.js';
 import { docLinkNames } from '../../core/memory/doc-link-grammar.js';
-import { createMemoryDocSnapshot, listAllMemoryDocs, loadMemoryStoreView, resolveMemoryCandidates, resolveMemoryDocs, } from '../../core/memory-resolver.js';
+import { createMemoryDocSnapshot, listAllMemoryDocs, loadMemoryStoreView, readMemoryDocContent, resolveMemoryCandidates, resolveMemoryDocs, } from '../../core/memory-resolver.js';
 import { expandShellBlocks, hasShellBlocks, makeNodeShellRunner } from '../../core/runtime/shell-expansion.js';
 import { emptyContextExposureState, exposedAtOrAbove, exposureTarget, loadContextExposureState, registerDocumentExposure, registerExposure, saveContextExposureState, } from '../../core/substrate/injected-store.js';
 import { dirDedupKey, docListingDirs, docsByName, isDirName, renderDirListing } from '../../core/substrate/listings.js';
@@ -15,17 +14,7 @@ import { renderResult } from '../../core/render.js';
 import { effectiveDocKind } from '../../core/substrate/schema.js';
 import { canonicalSegments } from '../../core/memory/identity.js';
 import { MEMORY_KINDS, requireMountedStore, resolveReadSelector, selectorParam } from './shared.js';
-export { createMemoryDocSnapshot, resolveMemoryDocs };
-/** Load the body at an already-resolved memory path with the same frontmatter
- * stripping and in-node path interpolation as `memory read`. Callers that
- * already have the resolved path (such as slash-command discovery) avoid
- * re-walking every memory store for each document. */
-export function readMemoryDocContent(path, includeFrontmatter = false) {
-    const raw = readText(path);
-    const content = includeFrontmatter ? raw : parseFrontmatterGeneric(raw).body;
-    const nodeId = process.env['CRTR_NODE_ID'];
-    return nodeId ? interpolateNodePaths(content, nodeId) : content;
-}
+export { createMemoryDocSnapshot, readMemoryDocContent, resolveMemoryDocs };
 /** 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
@@ -150,7 +139,7 @@ export const readLeaf = defineLeaf({
             }
             fail = () => resolveMemoryCandidates(nameRaw, resolveOpts);
         }
-        const nodeId = process.env['CRTR_NODE_ID'] || undefined;
+        const nodeId = envNodeId() || undefined;
         if (set === null) {
             // No document answers this name — a directory with no document of its own
             // still does, through its listing. An explicit dir read is a deliberate

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

@@ -185,6 +185,7 @@ export declare const SELECTOR_PARAMS: Record<string, FlagParam>;
 /** One selector flag, with leaf-specific prose appended to the shared
  *  constraint and any leaf-specific schema override applied. */
 export declare function selectorParam(name: string, overrides?: Partial<FlagParam>, extraConstraint?: string): FlagParam;
+export declare function coerceLintIgnore(raw: unknown): string | string[] | undefined;
 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. */

package/dist/commands/memory/shared.js

@@ -3,6 +3,7 @@
 // scope modules and build their documented output objects on top of the small
 // helpers here. Nothing in this file forks on kind or re-implements the
 // schema/gate/resolver — it only composes them.
+import { envNodeId, envProfileId } from '../../shared/env.js';
 import { existsSync, readdirSync, realpathSync, rmdirSync, statSync } from 'node:fs';
 import { dirname, join, resolve as resolvePath } from 'node:path';
 import { stringify as yamlStringify, parse as yamlParse } from 'yaml';
@@ -17,6 +18,7 @@ import { NEUTRAL_PROJECT_MEMORY, scopeMemoryDir, projectScopeRoot, ensureProject
 import { loadProfileManifest, resolveProfileOperand, profileMemoryDir } from '../../core/profiles/manifest.js';
 import { memoryDir as nodeMemoryDir } from '../../core/runtime/memory.js';
 import { SURFACE_EVENTS, SURFACE_RUNGS } from '../../core/substrate/schema.js';
+import { SUPPRESSIBLE_RULES } from '../../core/substrate/frontmatter-validation.js';
 import { exposureTarget, loadContextExposureState, registerExposure, saveContextExposureState, } from '../../core/substrate/injected-store.js';
 // The two memory kinds — knowledge (consult: procedural playbooks + factual
 // references merged) vs preference (behave: standing directives). Used as the
@@ -40,7 +42,7 @@ export function scopeRank(scope) {
     return scope === 'node' ? -1 : scope === 'project' ? 0 : scope === 'profile' ? 1 : scope === 'user' ? 2 : 3;
 }
 export function registerMemoryListingExposure(identity) {
-    const nodeId = process.env['CRTR_NODE_ID'];
+    const nodeId = envNodeId();
     if (nodeId === undefined || nodeId === '')
         return;
     const state = loadContextExposureState(nodeId);
@@ -151,7 +153,7 @@ export function resolveWriteSelector(input) {
     if (scope === 'node') {
         // The this-node store: the same dir render.ts's nodeLocalDocs loads at
         // boot, so a doc written here rides into this node's knowledge block.
-        const nodeId = process.env['CRTR_NODE_ID'] || '';
+        const nodeId = envNodeId() || '';
         if (nodeId === '') {
             throw usage('node scope requires a running node (CRTR_NODE_ID unset); rerun inside a node');
         }
@@ -163,7 +165,7 @@ export function resolveWriteSelector(input) {
         // is a durable id this process was launched under, so it resolves strictly
         // — a stale one must fail rather than write into a neighbouring store.
         const typed = input.profile !== undefined && input.profile !== '';
-        const profileIdOrName = typed ? input.profile : process.env['CRTR_PROFILE_ID'] || '';
+        const profileIdOrName = typed ? input.profile : envProfileId() || '';
         if (profileIdOrName === '') {
             throw usage('profile scope requires a selected profile; rerun inside a profiled node or pass --profile');
         }
@@ -209,14 +211,12 @@ export function requireMountedStore(store) {
         next: `Run \`crtr sys migrate --dir ${repositoryRoot}\`.`,
     });
 }
-// ---------------------------------------------------------------------------
 // Canonical name → physical placement
 //
 // Every surface takes the FULL canonical name. Placement strips the selected
 // store's namespace off it, checks that neither the identity nor either
 // physical representation of the local name is already taken, and picks the
 // form the new file takes.
-// ---------------------------------------------------------------------------
 /** Normalize and validate a full canonical name: ordering prefixes are
  *  physical-path-only, a trailing `INDEX` is never an address, and the segment
  *  charset is fixed. */
@@ -464,6 +464,7 @@ const FRONTMATTER_ORDER = [
     'gate',
     'slash',
     'rationale',
+    'lint-ignore',
     'last-updated',
     'origin',
 ];
@@ -709,13 +710,11 @@ export function applyExtensionChanges(frontmatter, sets, unsets) {
     else
         frontmatter['extensions'] = extensions;
 }
-// ---------------------------------------------------------------------------
 // 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. */
@@ -737,7 +736,7 @@ export const SELECTOR_PARAMS = {
         type: 'enum',
         choices: [...MEMORY_WRITE_SCOPES],
         required: false,
-        constraint: 'Store to write to (builtin documents ship with the package and installed-plugin documents are managed by `crtr pkg`, so neither is writable). Default: project when cwd sits in a project, else user. `project` resolves to the NEAREST ancestor `.crouter/` walking up from cwd — in a nested workspace that can be a parent’s store, not the dir you are standing in; pass --dir to pin the exact project. `profile` requires a selected profile (CRTR_PROFILE_ID) or an explicit --profile. `node` writes the this-node store (`nodes/<CRTR_NODE_ID>/context/memory/`), the nearest scope, seen only by this running node. Conflicts with --dir.',
+        constraint: 'Store to write to (package-shipped documents and installed-plugin documents are managed outside this command, so neither is writable). Default: project when cwd sits in a project, else user. `project` resolves to the NEAREST ancestor `.crouter/` walking up from cwd — in a nested workspace that can be a parent’s store, not the dir you are standing in; pass --dir to pin the exact project. `profile` requires a selected profile (CRTR_PROFILE_ID) or an explicit --profile. `node` writes the this-node store (`nodes/<CRTR_NODE_ID>/context/memory/`), the nearest scope, seen only by this running node. Conflicts with --dir.',
     },
     'dir': {
         kind: 'flag',
@@ -763,6 +762,15 @@ export function selectorParam(name, overrides = {}, extraConstraint) {
     const constraint = extraConstraint === undefined ? base.constraint : `${base.constraint} ${extraConstraint}`;
     return { ...base, ...overrides, constraint };
 }
+export function coerceLintIgnore(raw) {
+    if (raw === undefined)
+        return undefined;
+    const rules = Array.isArray(raw) ? raw : [raw];
+    if (rules.length === 0 || rules.some((rule) => typeof rule !== 'string' || !SUPPRESSIBLE_RULES.includes(rule))) {
+        throw usage(`invalid lint-ignore: ${JSON.stringify(raw)} (suppressible rules: ${SUPPRESSIBLE_RULES.map((rule) => `\`${rule}\``).join(', ')})`);
+    }
+    return rules.length === 1 ? rules[0] : 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.' },
@@ -770,6 +778,7 @@ export const FRONTMATTER_OVERLAY_PARAMS = {
     'unlisted': { kind: 'flag', name: 'unlisted', type: 'bool', required: false, default: false, constraint: 'Suppress this doc from directory listings. Suppression only — explicit reads, [[links]], and surfaces entries still work.' },
     'surface': { kind: 'flag', name: 'surface', type: 'string', required: false, repeatable: true, constraint: 'One routing entry per occurrence, as a YAML/JSON object `{on, at, match?, match-frontmatter?, gate?}`; the flag set replaces the document’s whole surfaces list. `on` is boot|workspace-open|read|memory-read|command|pre-command; `at` is name|preview|content. `match` holds the event’s globs — required on read/memory-read/command/pre-command (a read entry may carry `match-frontmatter`, a predicate over the read file’s own frontmatter, instead), meaningless on boot/workspace-open. Optional entry `gate` is a node-config predicate using the same vocabulary as the document gate; its event constraints and gate both match before it participates. A `./`-anchored glob is relative: for `read` to the store’s owning repo dir, for `memory-read` to this doc’s routing anchor — its own canonical name when the doc is its directory’s document (`<dir>/INDEX.md`), otherwise the canonical directory it sits in. Participating entries fold to their highest `at`; there is no cross-entry deny precedence.' },
     '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.' },
+    'lint-ignore': { kind: 'flag', name: 'lint-ignore', type: 'enum', choices: [...SUPPRESSIBLE_RULES], required: false, repeatable: true, constraint: 'Suppress one authoring lint rule for this document. Repeat for a list; valid rules: length, broad-memory-read.' },
     '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

package/dist/commands/memory/write.js

@@ -1,3 +1,4 @@
+import { envNodeId, envProfileId } from '../../shared/env.js';
 import { join } from 'node:path';
 import { defineLeaf } from '../../core/command.js';
 import { usage } from '../../core/errors.js';
@@ -10,7 +11,7 @@ import { parsedSubstrateSurfaces } from '../../core/substrate/frontmatter-valida
 import { ensureDir, realpathOrSelf, walkFiles, writeText } from '../../core/fs-utils.js';
 import { associateRepository } from '../../core/memory/repository-association.js';
 import { appendHistoryRecord, buildHistoryRecord, historyLogPathFor, } from '../../core/memory/history.js';
-import { DOC_RATIONALE_CONSTRAINT, GUIDE_CANONICAL_NAMES, GUIDE_DOC_LINKS, GUIDE_PREDICATE_VOCABULARY, GUIDE_ROUTING_LINE, GUIDE_SURFACES, planNewDocumentPlacement, resolveWriteSelector, requireMountedStore, buildOrigin, coerceGate, coerceSurface, memoryExtensionCatalogForDoc, memoryExtensionFieldCatalogHelp, overlayParam, requireCanonicalName, selectorParam, parseRequestedExtensionChanges, applyExtensionChanges, serializeMemoryDoc, } from './shared.js';
+import { DOC_RATIONALE_CONSTRAINT, GUIDE_CANONICAL_NAMES, GUIDE_DOC_LINKS, GUIDE_PREDICATE_VOCABULARY, GUIDE_ROUTING_LINE, GUIDE_SURFACES, planNewDocumentPlacement, resolveWriteSelector, requireMountedStore, buildOrigin, coerceGate, coerceLintIgnore, coerceSurface, memoryExtensionCatalogForDoc, memoryExtensionFieldCatalogHelp, overlayParam, requireCanonicalName, selectorParam, parseRequestedExtensionChanges, applyExtensionChanges, serializeMemoryDoc, } from './shared.js';
 function emptyMemoryStore(memoryDir) {
     return walkFiles(memoryDir, (name) => name.endsWith('.md') && name !== 'SKILL.md', (name) => name === '.crouter').length === 0;
 }
@@ -59,6 +60,7 @@ export const writeLeaf = defineLeaf({
             overlayParam('unlisted'),
             overlayParam('surface'),
             overlayParam('gate'),
+            overlayParam('lint-ignore'),
             overlayParam('slash'),
             { kind: 'flag', name: 'rationale', type: 'string', required: false, constraint: DOC_RATIONALE_CONSTRAINT },
             { kind: 'flag', name: 'extension', type: 'string', required: false, repeatable: true, constraint: 'Set one declared plugin field as `extensions.<plugin>.<field>=VALUE`. The path is required in full; booleans accept only true or false, numbers require finite numeric syntax, and strings/enums preserve the literal text after the first =. Every requested field validates before the document is written.' },
@@ -116,6 +118,7 @@ export const writeLeaf = defineLeaf({
             canonicalName = placement.canonicalName;
             path = placement.path;
         }
+        const lintIgnore = coerceLintIgnore(input['lintIgnore']);
         const extensionChanges = parseRequestedExtensionChanges(input['extension'], undefined, memoryExtensionCatalogForDoc({ scope, path }));
         const frontmatter = {};
         frontmatter['kind'] = kind;
@@ -140,6 +143,7 @@ export const writeLeaf = defineLeaf({
         }
         if (input['gate'] !== undefined)
             frontmatter['gate'] = coerceGate(input['gate']);
+        setIf('lint-ignore', lintIgnore);
         if (input['slash'] === true)
             frontmatter['slash'] = true;
         setIf('rationale', input['rationale']);
@@ -188,14 +192,14 @@ export const writeLeaf = defineLeaf({
                 ? {
                     resolvable: resolvableCanonicalNames(loadMemoryTargetView({
                         cwd: store.ownerDir ?? process.cwd(),
-                        profileId: process.env['CRTR_PROFILE_ID'] || null,
-                        nodeId: process.env['CRTR_NODE_ID'] || null,
+                        profileId: envProfileId() || null,
+                        nodeId: envNodeId() || null,
                     }, { quiet: true, includeDescendants: true }).docs),
                 }
                 : {}),
             ...(carriesBootEntry
                 ? {
-                    nestedStore: descendantStoreRoots(projectScopeRoots(process.cwd(), process.env['CRTR_PROFILE_ID'] || null))
+                    nestedStore: descendantStoreRoots(projectScopeRoots(process.cwd(), envProfileId() || null))
                         .map((root) => realpathOrSelf(join(root, 'memory')))
                         .includes(realpathOrSelf(memoryDir)),
                 }

package/dist/commands/node/bash.js

@@ -1,4 +1,5 @@
 // `crtr node bash` — file-backed background job controls.
+import { envNodeId } from '../../shared/env.js';
 import { defineBranch, defineLeaf } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
 import { displayMessage } from '../../core/runtime/tmux-chrome.js';
@@ -12,7 +13,7 @@ function resolveBashTarget(input, missingMessage) {
     if (id === undefined || id === '')
         id = nodeInPane(pane);
     if (id === undefined || id === '')
-        id = process.env['CRTR_NODE_ID'];
+        id = envNodeId();
     if (id === undefined || id === '') {
         throw new InputError({ error: 'no_node', message: missingMessage, next: 'Run from inside a node, pass --node <id>, or --pane <pane>.' });
     }

package/dist/commands/node/create.js

@@ -1,4 +1,5 @@
 // `crtr node new` — creation commands and persona-kind helpers.
+import { envNodeId } from '../../shared/env.js';
 import { defineLeaf } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
 import { mark } from '../../core/timing.js';
@@ -207,7 +208,7 @@ async function runNodeCreation(input) {
     if (noKickoff && mode === 'orchestrator') {
         throw new InputError({ error: 'no_kickoff_orchestrator_unsupported', message: '--no-kickoff cannot be combined with --mode orchestrator', field: 'no-kickoff', next: 'Drop --no-kickoff and provide a prompt, or spawn in base mode.' });
     }
-    const parentId = parent ?? process.env['CRTR_NODE_ID'];
+    const parentId = parent ?? envNodeId();
     mark('node_new.create_start', { root });
     const detail = await cliClient().createNode({
         ...(kind !== undefined ? { kind } : {}),