@north-light/crouter 0.3.234 → 0.3.235

package/dist/commands/attention.js

@@ -209,7 +209,7 @@ export const attentionBranch = defineBranch({
     help: {
         name: 'canvas attention',
         summary: 'aggregate pending human tickets across the canvas',
-        model: '`count` returns a single integer (stdout.count is machine-parseable); `list` returns itemised asking-node entries. Scope with --node (one node) or --view (sub-DAG) — default is canvas-wide. A ticket is any humanloop interaction awaiting the user: an ask, a review, or a notification.',
+        model: '`count` returns a single integer (stdout.count is machine-parseable) and accepts --node or --view; `list` returns itemised asking-node entries and accepts --view only. Both default to canvas-wide. A ticket is any humanloop interaction awaiting the user: an ask, a review, or a notification.',
     },
     children: [attentionCount, attentionList, attentionMap],
 });

package/dist/commands/cron.js

@@ -19,7 +19,7 @@ import { resolve as resolvePath } from 'node:path';
 import { defineBranch, defineLeaf } from '../core/command.js';
 import { InputError, readStdinRaw } from '../core/io.js';
 import { parseWhen, parseCadence, cadenceDisplay } from '../core/wake.js';
-import { resolveProfileOperand } from '../core/profiles/manifest.js';
+import { loadProfileManifest, resolveProfileOperand } from '../core/profiles/manifest.js';
 import { profilesStateBlock } from '../core/profiles/state-block.js';
 import { cliClient, rethrowAsCliError } from './api-client.js';
 /** Canonicalize a profile operand (id, manifest name, or nearest match) to its profile id so
@@ -69,7 +69,7 @@ function parseRunTimeout(raw) {
  *  caller sees the whole canvas home. */
 function scopeQuery() {
     const p = envProfileId();
-    return p !== undefined && p.trim() !== '' ? { profile: canonicalProfileId(p) } : undefined;
+    return p !== undefined && p.trim() !== '' ? { profile: p } : undefined;
 }
 /** Resolve the chosen-else-inherited cwd, and refuse one that is not a
  *  directory NOW — the row is a snapshot, so a bad cwd would fail at every
@@ -235,7 +235,7 @@ const addLeaf = defineLeaf({
         const profile = profileFlag !== undefined
             ? canonicalProfileId(profileFlag)
             : inherited !== undefined && inherited.trim() !== ''
-                ? canonicalProfileId(inherited)
+                ? loadProfileManifest(inherited).profileId
                 : undefined;
         const scopeFlag = input['scope'];
         const scope = scopeFlag ?? (profile !== undefined ? 'profile' : 'global');
@@ -286,7 +286,7 @@ const listLeaf = defineLeaf({
             { name: 'crons', type: 'object[]', required: true, constraint: 'One row per cron: cron_id, name, fire_at (next fire, UTC), recur (cadence display), state (active|paused), held (true while parked by an exit-75 gate — fires on daemon poke, else at fire_at), on_output, sink, expires_at, last_run (the most recent settled run: finished, exit_code, delivered — null if it never ran).' },
         ],
         outputKind: 'object',
-        effects: [],
+        effects: ['None. Read-only.'],
     },
     run: async () => {
         const crons = await cliClient().listCrons(scopeQuery()).catch(rethrowAsCliError);
@@ -349,7 +349,7 @@ const showLeaf = defineLeaf({
             { name: 'runs', type: 'object[]', required: true, constraint: 'The bounded run log, most recent first: started, exit_code (-1 = timeout kill), duration_ms, stdout/stderr heads, delivered (what the sink did, or why it did not).' },
         ],
         outputKind: 'object',
-        effects: [],
+        effects: ['None. Read-only.'],
     },
     run: async (input) => {
         const id = requireCronId(input);

package/dist/commands/human.js

@@ -41,7 +41,7 @@ export function registerHuman() {
                 pageHelp.brief,
                 pageHelp.authoring,
                 pageHelp.componentSelection.join('\n'),
-                'Props, response contracts, and the full component catalog: `crtr human components`.',
+                'Props, response contracts, and the full component catalog: `crtr human components`; select with `crtr human components list`, then read one with `crtr human components show <component>`.',
             ].join('\n\n'),
         },
         children: [

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/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/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

@@ -18,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
@@ -463,6 +464,7 @@ const FRONTMATTER_ORDER = [
     'gate',
     'slash',
     'rationale',
+    'lint-ignore',
     'last-updated',
     'origin',
 ];
@@ -734,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',
@@ -760,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.' },
@@ -767,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

@@ -11,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;
 }
@@ -60,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.' },
@@ -117,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;
@@ -141,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']);

package/dist/commands/node/inspect.js

@@ -82,10 +82,13 @@ const nodeList = defineLeaf({
                 return false;
             return true;
         });
-        const nodes = (await Promise.all(rows.map(async (row) => {
+        const nodes = [];
+        for (const row of rows) {
             const detail = await canvasSource.getNode(row.node_id).catch(rethrowAsCliError);
-            return { ...row, name: fullName(detail ?? row) };
-        }))).filter((row) => name === undefined || name === '' || fuzzyMatch(name, row.name));
+            const named = { ...row, name: fullName(detail ?? row) };
+            if (name === undefined || name === '' || fuzzyMatch(name, named.name))
+                nodes.push(named);
+        }
         return { nodes };
     },
 });
@@ -119,6 +122,7 @@ const nodeShow = defineLeaf({
         ],
         output: [
             { name: 'node', type: 'object', required: true, constraint: 'The full node meta (system prompt + every telemetry field). The render surfaces a glanceable slice; `--json` carries the complete dump.' },
+            { name: 'fault', type: 'object', required: true, constraint: 'The active runtime fault projection, or null: {link, kind, retry: {disposition}, since}.' },
             { name: 'reports', type: 'object[]', required: true, constraint: 'Who this node subscribes to (its reports/down), each enriched with {node_id, name, kind, status, active} — these are typically its spawned children.' },
             { name: 'managers', type: 'object[]', required: true, constraint: 'Who subscribes to this node (its managers/up), same enriched shape.' },
             { name: 'artifacts', type: 'object', required: true, constraint: 'Counts of what the node left on disk by corpus: {report, doc, roadmap}. Enumerate them with `node inspect artifacts <id>`.' },
@@ -186,7 +190,7 @@ const nodeShow = defineLeaf({
         if (reports.length > 0)
             hints.push(`Drill into a child/report: \`crtr node inspect show <node_id>\` (${reports.map((r) => r['node_id']).join(', ')}).`);
         hints.push(`Full machine dump (system prompt + all telemetry): \`crtr --json node inspect show ${id}\`.`);
-        return { node, reports, managers, artifacts, pending_crons, paths, follow_up: hints.join('\n') };
+        return { node, fault: node.fault ?? null, reports, managers, artifacts, pending_crons, paths, follow_up: hints.join('\n') };
     },
     render: (r) => {
         const node = r['node'];
@@ -195,12 +199,14 @@ const nodeShow = defineLeaf({
         const isRemoteShow = remoteShowResults.has(r);
         const alive = isRemoteShow ? 'remote (liveness not checked locally)' : (isPidAlive(pid) ? 'alive' : 'dead');
         const intent = node['intent'] ? `/${String(node['intent'])}` : '';
+        const fault = r['fault'];
         const parts = [];
         // 1) Glanceable meta slice — the debug-critical fields, not the full dump.
         parts.push(`# ${fullName(node)}  (${id})`);
         const meta = [
             `- kind/mode/lifecycle: ${node['kind']} / ${node['mode']} / ${node['lifecycle']}`,
             `- status: ${node['status']}${intent}`,
+            ...(fault === null || fault === undefined ? [] : [`- fault: ${String(fault['kind'])} / ${String(fault['retry']?.disposition)} since ${String(fault['since'])}`]),
             `- broker pid: ${pid ?? '(none)'} — ${alive}`,
             `- cwd: ${node['cwd']}`,
             `- host: ${node['host_kind']}` + (node['profile_id'] ? ` · profile ${node['profile_id']}` : ''),
@@ -291,6 +297,7 @@ export const nodeInspect = defineBranch({
     help: {
         name: 'node inspect',
         summary: 'read one node (or the roster) — topology, context dir, and artifacts',
+        model: 'Inspection is read-only and never revives a node. The roster is the selection surface; one-node metadata points to progressively heavier views: a parsed broker snapshot, rendered conversation, context browser, or artifact references.',
     },
     children: [nodeList, nodeShow, nodeSnapshotLeaf, nodeTranscriptLeaf, nodeContextLeaf, nodeArtifactsLeaf],
 });

package/dist/commands/node/lifecycle.js

@@ -355,6 +355,7 @@ export const nodeLifecycle = defineBranch({
     help: {
         name: 'node lifecycle',
         summary: 'end, transition, or revive a node — recycle the pane, close + cascade-cancel a subtree, demote to terminal in place, or revive a dormant node',
+        model: 'Lifecycle actions preserve or replace an existing node identity. Finishing is permanent, closing is revivable, demotion changes the completion obligation in place, and revival relaunches a dormant broker. Teardown cascades only through descendants exclusively managed by the affected subtree.',
     },
     children: [nodeRecycle, nodeClose, nodeDemote, nodeReviveLeaf],
 });

package/dist/commands/node/message.js

@@ -56,7 +56,7 @@ function messageRequestParams() {
         { kind: 'stdin', name: 'body', required: false, constraint: 'Visible message body. The schema alone is a complete request.' },
         { kind: 'flag', name: 'to', type: 'string', required: false, constraint: 'Target an existing node by id. Exactly one of --to or --self is required.' },
         { kind: 'flag', name: 'self', type: 'bool', required: false, constraint: 'Target the calling node. Exactly one of --to or --self is required.' },
-        { kind: 'flag', name: 'tier', type: 'enum', choices: ['critical', 'urgent', 'normal'], required: false, default: 'normal', constraint: 'Delivery urgency. Deferred never wakes an idle node.' },
+        { kind: 'flag', name: 'tier', type: 'enum', choices: ['critical', 'urgent', 'normal'], required: false, default: 'normal', constraint: 'Delivery urgency. Every accepted tier may revive a dormant target, because the request must be answered; deferred is rejected for that reason.' },
         { kind: 'flag', name: 'output-schema', type: 'string', required: true, constraint: `JSON Schema the result must satisfy. ${OUTPUT_SCHEMA_TRANSPORT} The target answers through a constrained submit tool, then keeps working. ${OUTPUT_SCHEMA_CONSTRAINTS}` },
         { kind: 'flag', name: 'situational-context', type: 'string', required: false, constraint: 'Non-empty hidden ambient context delivered beside the message, or alone.' },
         { kind: 'flag', name: 'reopen', type: 'bool', required: false, hidden: true, constraint: 'Clear a finalized target latch before delivery or fresh revive.' },
@@ -105,7 +105,7 @@ async function runMessageEngine(input) {
 const nodeMessageSend = defineLeaf({
     name: 'send',
     description: 'deliver an inbox message to an existing node immediately',
-    whenToUse: 'you need to steer or inform a node now without creating an ongoing subscription',
+    whenToUse: 'a node that already exists should have information or new direction now — steering a worker mid-task, handing over a finding it needs, correcting a wrong turn, or waking a dormant node with fresh work. The target reads it and decides what to do with it. Use `node message request` instead when you need an answer back in a shape you specify, and `node subscription add` when the target should keep receiving this node’s pushes rather than this one delivery',
     help: {
         name: 'node message send',
         summary: 'deliver an inbox message to an existing node immediately',
@@ -120,7 +120,7 @@ const nodeMessageSend = defineLeaf({
 const nodeMessageRequest = defineLeaf({
     name: 'request',
     description: 'deliver an immediate typed-output request to an existing node',
-    whenToUse: 'the target must answer once through a submit tool constrained by a JSON Schema',
+    whenToUse: 'a node that already exists must hand back one answer in a shape you fix — a choice among options, a structured extraction, a verdict your own logic will branch on — or must be held to answering at all before it goes quiet. Use `node message send` instead when prose in the target’s own judgment is enough, and `node new --output-schema` when no node holds the context yet and the work needs a fresh agent',
     help: {
         name: 'node message request',
         summary: 'deliver an immediate typed-output request to an existing node',
@@ -139,6 +139,10 @@ export const nodeMessage = defineBranch({
     name: 'message',
     description: 'deliver immediate inbox work to an existing node',
     whenToUse: 'you need one immediate delivery: send ordinary information, or request one schema-constrained result',
-    help: { name: 'node message', summary: 'deliver now; choose ordinary delivery or a typed-output obligation' },
+    help: {
+        name: 'node message',
+        summary: 'deliver one immediate inbox entry to an existing node',
+        model: 'Both children append one inbox entry to a node that already exists, targeted by id or --self, and may revive it if it is dormant. They differ in what the delivery obligates. An ordinary message obligates nothing: the target reads it and acts however it judges best. A request installs a one-off submit schema and holds the target awake and owing until it answers; the answer is validated against the schema, written to the target’s result file, and pushed as an update report to the TARGET’S subscribers, so subscribe to it first if the answer has to reach you. Neither child creates that standing relationship — a durable delivery edge is `node subscription`, and work that needs a fresh agent is `node new`.',
+    },
     children: [nodeMessageSend, nodeMessageRequest],
 });

package/dist/commands/node/subscription.js

@@ -69,6 +69,10 @@ export const nodeSubscription = defineBranch({
     name: 'subscription',
     description: 'manage push-delivery edges between nodes',
     whenToUse: 'you need an ongoing active or passive subscriber-to-publisher delivery edge that spawn did not create, or need to remove one',
-    help: { name: 'node subscription', summary: 'add or remove subscriber-to-publisher push-delivery edges' },
+    help: {
+        name: 'node subscription',
+        summary: 'add or remove subscriber-to-publisher push-delivery edges',
+        model: 'Subscriptions point from a subscriber to a publisher and control future push delivery. Active edges wake on each push; passive edges accumulate pushes for the subscriber’s next turn. Removing either edge stops subsequent delivery without changing messages already received.',
+    },
     children: [nodeSubscribe, nodeUnsubscribe],
 });

package/dist/commands/node/wait.js

@@ -154,6 +154,10 @@ export const nodeWaitBranch = defineBranch({
     name: 'wait',
     description: 'declare a durable controller or deadline wait',
     whenToUse: 'a terminal node must dorm for one named controller, or race its inbox against a self-scheduled deadline',
-    help: { name: 'node wait', summary: 'declare durable wait state; choose the event that settles it' },
+    help: {
+        name: 'node wait',
+        summary: 'declare durable wait state; choose the event that settles it',
+        model: 'Both waits belong to the calling terminal node and settle on one future event. A controller wait records an existing node as the wake source; a deadline wait arms an urgent one-shot cron that races any earlier inbox delivery and is canceled when that delivery wins.',
+    },
     children: [nodeWait, nodeWaitDeadline],
 });

package/dist/commands/pkg/plugin-manage.js

@@ -791,7 +791,7 @@ export const pluginRemove = defineLeaf({
         summary: 'remove a plugin and its directory from the given scope',
         params: [
             { kind: 'positional', name: 'name', type: 'string', required: true, constraint: 'Plugin name to remove.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: searches all scopes.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: searches every scope.' },
         ],
         output: [
             { name: 'scopes', type: 'string[]', required: true, constraint: 'Scopes the plugin was removed from.' },

package/dist/commands/pkg.js

@@ -14,6 +14,7 @@ export function registerPkg() {
         help: {
             name: 'pkg',
             summary: 'manage plugins and marketplace sources',
+            model: 'Marketplaces are configured source catalogs; plugins are installed extensions resolved from those catalogs or direct HTTP endpoints. Browsing searches the configured catalogs without changing source or install state.',
         },
         children: [pkgBrowseLeaf, pluginBranch, marketBranch],
     });

package/dist/commands/profile/rename.js

@@ -3,7 +3,7 @@ import { resolveProfileOperand, renameProfile } from '../../core/profiles/manife
 export const renameLeaf = defineLeaf({
     name: 'rename',
     description: "change a profile's display name",
-    whenToUse: "you want to change a profile's display name — the gateable `profile` subject value and the name shown in bearings/listings. The profile id (its directory) never changes.",
+    whenToUse: "you want the profile to appear under a new name in bearings, listings, and `profile` subject gates. The profile id (its directory) never changes.",
     help: {
         name: 'profile rename',
         summary: "change a profile's manifest `name` only — the profile_id is stable and never changes",

package/dist/commands/sys/config.js

@@ -257,6 +257,7 @@ export const configBranch = defineBranch({
     help: {
         name: 'sys config',
         summary: 'read and write crtr configuration, including model ladders; edit humanActions maps directly in ~/.crouter/config.json or <repo>/.crouter/config.json',
+        model: 'Configuration resolves through ordered scopes. Reads can resolve the effective value, writes target one writable scope, and path inspection reveals the backing files without reading values.',
     },
     children: [configGet, configSet, configPath],
 });

package/dist/commands/sys.js

@@ -24,6 +24,7 @@ export function registerSys() {
         help: {
             name: 'sys',
             summary: 'crtr system configuration, settings, diagnostics, and self-management',
+            model: 'Configuration and settings own durable behavior; diagnostics and support observe it. Setup, migration, sync, and update change installed or generated state, while daemon control owns the supervisor lifecycle.',
         },
         children: [sysSettingsLeaf, configBranch, sysSetupLeaf, sysDoctorLeaf, sysSyspromptLeaf, promptReviewLeaf, sysFeedbackLeaf, sysLogsLeaf, supportBranch, sysUpdateLeaf, sysVersionLeaf, sysMigrateLeaf, sysSyncBranch, daemonBranch],
     });

package/dist/core/__tests__/cli-help-contract.test.d.ts

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