@north-light/crouter 0.3.162 → 0.3.163

package/dist/commands/__tests__/api-canvas-source.test.d.ts

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

package/dist/commands/__tests__/api-canvas-source.test.js

@@ -0,0 +1,37 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { ApiCanvasSource } from '../api-client.js';
+const detail = {
+    node_id: 'node-1',
+    name: 'test',
+    kind: 'general',
+    mode: 'base',
+    lifecycle: 'resident',
+    status: 'active',
+    cwd: '/tmp/project',
+    host_kind: 'broker',
+    profile_id: null,
+    parent: null,
+    created: '2026-07-31T00:00:00.000Z',
+    intent: null,
+    waiting_for: null,
+    pi_pid: null,
+    final_report: null,
+    finalized_at: null,
+    description: 'generated-description',
+    icon: '\uf1fc',
+    edges: { parent: null, spawned_by: null, subscribes_to: [], subscribers: [], children: [] },
+    paths: {
+        node_dir: '/tmp/node',
+        context_dir: '/tmp/node/context',
+        reports_dir: '/tmp/node/reports',
+        meta_path: '/tmp/node/meta.json',
+        inbox_path: '/tmp/node/inbox.jsonl',
+        transcript_path: '/tmp/node/transcript.jsonl',
+        view_socket: '/tmp/node/view.sock',
+    },
+};
+test('the API canvas source retains the node icon needed by a reloaded viewer', async () => {
+    const source = new ApiCanvasSource({ getNode: async () => detail });
+    assert.equal((await source.getNode(detail.node_id))?.icon, '\uf1fc');
+});

package/dist/commands/__tests__/human.test.js

@@ -167,6 +167,8 @@ describe('human ask: stdin question + strict deck', () => {
         assert.match(out, /^  stdin\s+optional\. Simple open-text ask body\./m);
         assert.match(out, /single-quoted heredoc/);
         assert.match(out, /--context-file PATH/);
+        assert.match(out, /bodyPath is a relative path to the body file, resolved from the directory containing the deck JSON/);
+        assert.match(out, /paths escaping with \.\. or symlinks are rejected; absolute paths are unsupported/);
         assert.doesNotMatch(out, /crtr human ask "<question>"/);
     });
     test('reads an explicit title and literal question bytes', async () => {

package/dist/commands/__tests__/search-contents.test.d.ts

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

package/dist/commands/__tests__/search-contents.test.js

@@ -0,0 +1,52 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { parseArgv } from '../../core/command.js';
+import { contentsLeaf } from '../search/contents.js';
+async function requestBody(argv) {
+    const previousKey = process.env['EXA_API_KEY'];
+    const previousFetch = globalThis.fetch;
+    let body;
+    let requestCount = 0;
+    process.env['EXA_API_KEY'] = 'test-key';
+    globalThis.fetch = (async (_input, init) => {
+        requestCount++;
+        body = JSON.parse(String(init?.body));
+        return new Response(JSON.stringify({ results: [], statuses: [] }), {
+            status: 200,
+            headers: { 'content-type': 'application/json' },
+        });
+    });
+    try {
+        const input = await parseArgv(contentsLeaf.help.params ?? [], argv);
+        await contentsLeaf.run(input);
+        assert.equal(requestCount, 1);
+        assert.ok(body !== undefined);
+        return body;
+    }
+    finally {
+        globalThis.fetch = previousFetch;
+        if (previousKey === undefined)
+            delete process.env['EXA_API_KEY'];
+        else
+            process.env['EXA_API_KEY'] = previousKey;
+    }
+}
+test('search contents accepts separate URL positional argv tokens in one request', async () => {
+    const body = await requestBody(['https://example.com/one', 'https://example.com/two']);
+    assert.deepEqual(body['urls'], ['https://example.com/one', 'https://example.com/two']);
+});
+test('search contents flattens comma and whitespace-separated URLs across positional tokens', async () => {
+    const body = await requestBody([
+        'https://example.com/one,https://example.com/two',
+        'https://example.com/three https://example.com/four',
+    ]);
+    assert.deepEqual(body['urls'], [
+        'https://example.com/one',
+        'https://example.com/two',
+        'https://example.com/three',
+        'https://example.com/four',
+    ]);
+});
+test('search contents still rejects zero URL positional tokens', async () => {
+    await assert.rejects(() => parseArgv(contentsLeaf.help.params ?? [], []), (error) => error instanceof Error && error.message.includes('required parameter is missing'));
+});

package/dist/commands/api-client.js

@@ -195,6 +195,7 @@ function detailToMeta(d) {
         node_id: d.node_id,
         name: d.name,
         description: d.description,
+        icon: d.icon,
         cycles: d.cycles,
         created: d.created,
         cwd: d.cwd,

package/dist/commands/human/prompts.js

@@ -14,7 +14,7 @@ import { tmuxServerReachable } from '../../core/spawn.js';
 import { BrokerClient, BrokerUnavailableError } from '../../core/broker-client/index.js';
 import { markStopSignal } from '../../core/runtime/stop-signals.js';
 import { validateDeck, notifyDeck, atomicWriteJson, submitDeck, submitReview, display, } from '@crouton-kit/humanloop';
-import { DECK_SCHEMA_HINT, registerCrouterRoot, resolveMaxPanes } from './shared.js';
+import { BODY_PATH_CONTRACT, DECK_SCHEMA_HINT, registerCrouterRoot, resolveMaxPanes } from './shared.js';
 import { inboxOpenInstruction, inboxPopupHint } from '../../core/keybindings/index.js';
 /** The asking node's id, or null when run from a bare shell (no parent to route to). */
 function askingNode() {
@@ -159,7 +159,7 @@ export const humanAsk = defineLeaf({
             { kind: 'flag', name: 'title', type: 'string', required: false, constraint: 'Required with stdin: a short ≤~4-word inbox topic. Mutually exclusive with --context-file, whose JSON carries its own required title.' },
             { kind: 'flag', name: 'subtitle', type: 'string', required: false, constraint: 'Required with stdin: one plain-English sentence stating the decision, recommendation, and stakes. Mutually exclusive with --context-file, whose JSON requires every interaction subtitle.' },
             { kind: 'stdin', name: 'question', required: false, constraint: "Simple open-text ask body. Pipe markdown from a single-quoted heredoc (`<<'EOF'`) to preserve literal bytes. Requires --title and --subtitle; mutually exclusive with --context-file." },
-            { kind: 'context-file', name: 'deck', required: false, constraint: 'Strict structured deck JSON with a required deck title and non-empty subtitle on every interaction. Use this for multiple interactions, options, or other deck structure. Mutually exclusive with --title, --subtitle, and the question shorthand.', shape: DECK_SCHEMA_HINT },
+            { kind: 'context-file', name: 'deck', required: false, constraint: `Strict structured deck JSON with a required deck title and non-empty subtitle on every interaction. ${BODY_PATH_CONTRACT}. Use this for multiple interactions, options, or other deck structure. Mutually exclusive with --title, --subtitle, and the question shorthand.`, shape: DECK_SCHEMA_HINT },
         ],
         output: [
             { name: 'job_id', type: 'string', required: true, constraint: 'Node id of this human interaction. Its answer is pushed to your inbox when the human responds.' },

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

@@ -1,4 +1,5 @@
 import type { CompletionHandler } from '@crouton-kit/humanloop';
+export declare const BODY_PATH_CONTRACT: string;
 export declare const DECK_SCHEMA_HINT: string;
 /**
  * Crouter's private per-interaction record. Reduced to the delivery essentials:

package/dist/commands/human/shared.js

@@ -5,14 +5,17 @@ import { existsSync, mkdirSync, readdirSync, renameSync, rmdirSync, statSync } f
 import { readConfig } from '../../core/config.js';
 import { nodesRoot } from '../../core/canvas/paths.js';
 import { interactionState, listInboxRoots, registerInboxRoot, unregisterInboxRoot } from '@crouton-kit/humanloop';
+export const BODY_PATH_CONTRACT = 'bodyPath is a relative path to the body file, resolved from the directory containing the deck JSON; ' +
+    'it must stay inside that directory, and paths escaping with .. or symlinks are rejected; absolute paths are unsupported';
 export const DECK_SCHEMA_HINT = 'Deck must match the humanloop deck schema: {title (required short inbox topic), ' +
     'source?:{sessionName?,askedBy?,blockedSince?}, interactions:[{id, ' +
     'title (short ≤~4-word inbox topic that identifies the decision for a cold reader), ' +
     'subtitle (required ONE plain-English sentence stating the decision, your recommendation, and its stakes), ' +
-    '(body?|bodyPath?) (a self-contained decision brief: give the minimum plain-language ' +
-    'context and tradeoffs needed to decide, then place supporting evidence, chronology, and ' +
-    'technical detail under ## Details; the ONLY place for long or rich prose — directive-flavored ' +
-    'markdown rendered by termrender), options:[{id,label,description?}], multiSelect?, ' +
+    `(body?|bodyPath?) (a self-contained decision brief: give the minimum plain-language ` +
+    `context and tradeoffs needed to decide, then place supporting evidence, chronology, and ` +
+    `technical detail under ## Details; the ONLY place for long or rich prose — directive-flavored ` +
+    `markdown rendered by termrender). ${BODY_PATH_CONTRACT}. ` +
+    'body and bodyPath are mutually exclusive, options:[{id,label,description?}], multiSelect?, ' +
     'allowFreetext?, freetextLabel?, ' +
     "kind?:'notify'|'decision'|'context'|'error'}]}.";
 export function resolveMaxPanes() {

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

@@ -1,3 +1,9 @@
+/** The length rule. Caps are computed from the RAW rung strings — an invalid
+ *  rung already fails the schema check, so it simply matches no cap here.
+ *  `docName` is the doc's canonical resolver identity (explicit frontmatter
+ *  `name`, else the normalized path-derived name) — persona layers under
+ *  `kinds/` are recognized by it and never capped. */
+export declare function lintBodyLength(fm: Record<string, unknown>, body: string, docName: string): string | null;
 /** Schema checks for a doc living in a substrate memory dir: a memory store
  *  holds ONLY substrate docs, so a missing/invalid `kind` is an authoring
  *  error here (elsewhere it just means "not a substrate doc"). Both rungs are

package/dist/commands/memory/lint.js

@@ -13,10 +13,75 @@ import { listInstalledPlugins, listInstalledPluginsInRoot } from '../../core/res
 import { pluginMemoryDir, projectScopeRoots, scopeMemoryDir } from '../../core/scope.js';
 import { loadProfileManifest, profileMemoryDir } from '../../core/profiles/manifest.js';
 import { getDefaultProfileId } from '../../core/profiles/default-binding.js';
-import { isDocKind, RUNGS } from '../../core/substrate/schema.js';
-/** The parser normalizes the `always` alias to `content`, so it lints valid. */
-const VALID_RUNGS = [...RUNGS, 'always'];
+import { isDocKind, normalizeDocName, resolveDocName, RUNGS } from '../../core/substrate/schema.js';
+import { displayName } from '../../core/substrate/ceiling.js';
+import { docLinkNames } from '../../core/memory/doc-link-grammar.js';
+import { listAllMemoryDocs } from '../../core/memory-resolver.js';
+const VALID_RUNGS = [...RUNGS];
 const RUNG_FIELDS = ['system-prompt-visibility', 'file-read-visibility'];
+/** Rung-scaled body-length caps, measured in WORDS (frontmatter excluded).
+ *  Words, not lines: house style writes each paragraph as ONE logical line
+ *  and lets the editor soft-wrap, so a line count measures wrapping style
+ *  rather than context cost — words track what the reader actually pays.
+ *
+ *  `content` on the system axis inlines the whole body into every agent's
+ *  system prompt at boot; `preview`/`content` on the file-read axis surface
+ *  the whole body through a workspace mount or a matching file read — both
+ *  cap at 1000 words. `preview` on the system axis routes a deliberate
+ *  reader into the whole body, so its cap is the longest doc worth reading
+ *  end-to-end (calibrated to the humanizer doc, 2936 words). `name`/`none`
+ *  rungs never cap: such a doc is only reached deliberately (browse or a
+ *  [[link]]), so its length is the reader's choice. The strictest
+ *  applicable cap wins.
+ *
+ *  Persona layers — canonical names under `kinds/`, the docs the prompt
+ *  render composes into an agent's persona — are structurally exempt: an
+ *  agent reads its whole persona by construction, so persona length is a
+ *  persona-design choice, not an authoring smell. Suppression elsewhere is
+ *  deliberate and per-doc: `lint-ignore: length` in the frontmatter,
+ *  surfaced ONLY by the finding itself — never advertised in authoring
+ *  help. */
+const SYSTEM_CONTENT_MAX_WORDS = 1000;
+const FILE_READ_MAX_WORDS = 1000;
+const SYSTEM_PREVIEW_MAX_WORDS = 3000;
+/** Rules a doc may suppress via frontmatter `lint-ignore`. */
+const SUPPRESSIBLE_RULES = ['length'];
+function ignoresRule(fm, rule) {
+    const v = fm['lint-ignore'];
+    return v === rule || (Array.isArray(v) && v.includes(rule));
+}
+function countBodyWords(body) {
+    const trimmed = body.trim();
+    return trimmed === '' ? 0 : trimmed.split(/\s+/).length;
+}
+/** The length rule. Caps are computed from the RAW rung strings — an invalid
+ *  rung already fails the schema check, so it simply matches no cap here.
+ *  `docName` is the doc's canonical resolver identity (explicit frontmatter
+ *  `name`, else the normalized path-derived name) — persona layers under
+ *  `kinds/` are recognized by it and never capped. */
+export function lintBodyLength(fm, body, docName) {
+    if (ignoresRule(fm, 'length'))
+        return null;
+    // Persona exemption: render composes an agent's persona from the docs
+    // resolving under `kinds/...`, and an agent reads its whole persona by
+    // construction — persona length is persona design, never an authoring smell.
+    if (docName === 'kinds' || docName.startsWith('kinds/'))
+        return null;
+    const sys = fm['system-prompt-visibility'];
+    const file = fm['file-read-visibility'];
+    const words = countBodyWords(body);
+    const remedy = 'Keep the load-bearing core here and split the depth into [[linked]] reference docs saved at `none` visibility on both axes (the link is how they are found, so they cost nothing until followed). Keep it whole — `lint-ignore: length` in the frontmatter — only when every reader who surfaces this doc genuinely benefits from reading 100% of it, or it is one indivisible body of knowledge; then splitting just adds hops.';
+    if (sys === 'content' && words > SYSTEM_CONTENT_MAX_WORDS) {
+        return `body is ${words} words but system-prompt-visibility: content inlines every word into every agent's system prompt at boot — capped at ${SYSTEM_CONTENT_MAX_WORDS} words (system-prompt preview gets ${SYSTEM_PREVIEW_MAX_WORDS}; name/none are never capped on that axis). ${remedy}`;
+    }
+    if ((file === 'content' || file === 'preview') && words > FILE_READ_MAX_WORDS) {
+        return `body is ${words} words, over the ${FILE_READ_MAX_WORDS}-word cap for file-read routed rungs (file-read-visibility: preview|content surfaces the whole body through a workspace mount or a matching file read; name/none are never capped on that axis). ${remedy}`;
+    }
+    if (sys === 'preview' && words > SYSTEM_PREVIEW_MAX_WORDS) {
+        return `body is ${words} words, over the ${SYSTEM_PREVIEW_MAX_WORDS}-word cap for system-prompt preview (the routing line invites every reader into the whole body, so the cap is the longest doc worth reading end-to-end; system-prompt content is capped at ${SYSTEM_CONTENT_MAX_WORDS} words; name/none are never capped on that axis). ${remedy}`;
+    }
+    return null;
+}
 /** Schema checks for a doc living in a substrate memory dir: a memory store
  *  holds ONLY substrate docs, so a missing/invalid `kind` is an authoring
  *  error here (elsewhere it just means "not a substrate doc"). Both rungs are
@@ -53,10 +118,20 @@ export function lintSubstrateSchema(fm) {
         return `invalid gate: ${JSON.stringify(gate)} (expected a field→matcher object)`;
     }
     const appliesTo = fm['applies-to'];
-    if (appliesTo !== undefined &&
-        typeof appliesTo !== 'string' &&
-        !(Array.isArray(appliesTo) && appliesTo.every((g) => typeof g === 'string'))) {
-        return `invalid applies-to: ${JSON.stringify(appliesTo)} (expected a glob or glob list)`;
+    let appliesToGlobs;
+    if (appliesTo !== undefined) {
+        if (typeof appliesTo === 'string') {
+            appliesToGlobs = [appliesTo];
+        }
+        else if (Array.isArray(appliesTo) && appliesTo.every((g) => typeof g === 'string')) {
+            appliesToGlobs = appliesTo;
+        }
+        else {
+            return `invalid applies-to: ${JSON.stringify(appliesTo)} (expected one non-empty file glob or a non-empty list of file globs)`;
+        }
+        if (appliesToGlobs.length === 0 || appliesToGlobs.some((glob) => glob.trim() === '')) {
+            return `invalid applies-to: ${JSON.stringify(appliesTo)} (expected one non-empty file glob or a non-empty list of file globs)`;
+        }
     }
     // read-when (Stream A on-read frontmatter trigger): same well-formed-object
     // contract as gate — a non-object is inert (never fires), so catch it here.
@@ -64,6 +139,11 @@ export function lintSubstrateSchema(fm) {
     if (readWhen !== undefined && (readWhen === null || typeof readWhen !== 'object' || Array.isArray(readWhen))) {
         return `invalid read-when: ${JSON.stringify(readWhen)} (expected a field→matcher object)`;
     }
+    // Every authored file-read surface needs an explicit event boundary. Runtime
+    // parsing stays tolerant so one bad doc cannot break an agent's context.
+    if (fm['file-read-visibility'] !== 'none' && appliesToGlobs === undefined) {
+        return `missing applies-to: file-read-visibility is \`${fm['file-read-visibility']}\`, so this memory must declare when it surfaces. Use \`applies-to: "."\` for context loaded when cwd or a selected profile mounts this project store, use a non-empty file glob (or YAML list) for context loaded only after a matching file is read, or set \`file-read-visibility: none\` when this memory has no file-context route. File globs match the read file's absolute path, basename, or path relative to the memory's owning project root. \`read-when\` matches file metadata but does not replace the required workspace/file boundary. Run \`crtr memory write -h\` before changing routing frontmatter.`;
+    }
     // A dead on-read trigger: an explicit applies-to/read-when with nothing to
     // surface (file-read-visibility none) can never fire — flag it loudly rather
     // than store a silent no-op.
@@ -80,14 +160,26 @@ export function lintSubstrateSchema(fm) {
     if (rationale !== undefined && typeof rationale !== 'string') {
         return `invalid rationale: ${JSON.stringify(rationale)} (expected a string)`;
     }
+    const lintIgnore = fm['lint-ignore'];
+    if (lintIgnore !== undefined) {
+        const rules = Array.isArray(lintIgnore) ? lintIgnore : [lintIgnore];
+        if (rules.length === 0 || !rules.every((r) => typeof r === 'string' && SUPPRESSIBLE_RULES.includes(r))) {
+            return `invalid lint-ignore: ${JSON.stringify(lintIgnore)} (the only suppressible rule is \`length\`)`;
+        }
+    }
     return null;
 }
 /** Strict-parse one file; push a finding on a YAML error, then run the
- *  schema check when the file lives in a substrate store. */
-function lintFile(file, substrateStore, findings) {
+ *  schema check when the file lives in a substrate store, then validate every
+ *  `[[canonical/name]]` doc link in the body against the exact resolvable
+ *  corpus. A dangling link is an authoring error caught HERE, never silently
+ *  carried; leaf-name fallback is deliberately excluded so links stay stable
+ *  as the graph grows and another document acquires the same leaf name. */
+function lintFile(file, substrateStore, findings, corpusNames, fallbackName) {
     let fm;
+    let body;
     try {
-        fm = parseFrontmatterGeneric(readText(file)).data;
+        ({ data: fm, body } = parseFrontmatterGeneric(readText(file)));
     }
     catch (e) {
         const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
@@ -99,18 +191,31 @@ function lintFile(file, substrateStore, findings) {
     const schemaError = lintSubstrateSchema(fm);
     if (schemaError !== null)
         findings.push({ path: file, error: schemaError });
+    if (fm !== null) {
+        const lengthError = lintBodyLength(fm, body, resolveDocName(fm, fallbackName));
+        if (lengthError !== null)
+            findings.push({ path: file, error: lengthError });
+    }
+    for (const name of docLinkNames(body)) {
+        if (!corpusNames.has(name)) {
+            findings.push({
+                path: file,
+                error: `dangling doc link [[${name}]]: no memory document has that exact canonical name — retarget the link (\`crtr memory find ${name.split('/').pop()}\`) or drop it`,
+            });
+        }
+    }
 }
 export const lintLeaf = defineLeaf({
     name: 'lint',
-    description: 'validate frontmatter across the whole bounded document corpus',
-    whenToUse: 'you authored or migrated documents and want the authoring-time gate: strict-parse every doc in the bounded corpus (the substrate memory stores) and fail loudly on any invalid YAML or substrate schema violation; also flags any dir the selected profile manages that lacks an AGENTS.md operating guide and warns when the directory where lint runs lacks a routed INDEX.md front door. Run it before shipping doc changes; CI-friendly (non-zero exit on findings, warnings remain non-fatal).',
+    description: 'validate frontmatter and body length across the whole bounded document corpus',
+    whenToUse: 'you authored or migrated documents and want the authoring-time gate: strict-parse every doc in the bounded corpus (the substrate memory stores) and fail loudly on any invalid YAML, substrate schema violation, body longer than its visibility rung earns, or dangling `[[canonical/name]]` doc link; also validates the root INDEX.md front door of every project managed by the selected profile and warns when an unprofiled working directory has no front door. Run it before shipping doc changes; CI-friendly (non-zero exit on findings, warnings remain non-fatal).',
     help: {
         name: 'memory lint',
-        summary: 'strict-parse frontmatter across the bounded corpus; warn when the working directory lacks an INDEX',
+        summary: 'strict-parse the bounded memory corpus and validate project root INDEX front doors',
         params: [],
         output: [
             { name: 'checked', type: 'number', required: true, constraint: 'Files linted across all corpora.' },
-            { name: 'corpora', type: 'object', required: true, constraint: 'Per-corpus counts: {memory_stores (files), profile_projects (managed dirs checked for AGENTS.md)}.' },
+            { name: 'corpora', type: 'object', required: true, constraint: 'Per-corpus counts: {memory_stores (files), profile_projects (managed dirs checked for a root INDEX.md front door)}.' },
             { name: 'findings', type: 'object[]', required: true, constraint: 'One row per failure: {path, error}. Empty when green.' },
             { name: 'warnings', type: 'string[]', required: true, constraint: 'Non-fatal authoring gaps detected for the directory where lint ran.' },
         ],
@@ -121,14 +226,7 @@ export const lintLeaf = defineLeaf({
         const findings = [];
         const warnings = [];
         let memoryCount = 0;
-        // An INDEX gives the directory a discoverable, routed front door. It is
-        // intentionally advisory: lint still validates every available store when
-        // invoked from a directory that has not adopted project memory yet.
         const workingDirectory = process.cwd();
-        const workingDirectoryIndex = join(workingDirectory, '.crouter', 'memory', 'INDEX.md');
-        if (!pathExists(workingDirectoryIndex)) {
-            warnings.push(`${workingDirectory}: no .crouter/memory/INDEX.md — create the directory's routed front door with \`crtr memory write INDEX -h\``);
-        }
         // Substrate memory stores (ancestor projects/user/builtin), schema-aware.
         // A source's corpus is its NATIVE memory dir plus each enabled plugin's memory dir —
         // plugin docs are substrate docs and lint through the same schema gate.
@@ -137,14 +235,24 @@ export const lintLeaf = defineLeaf({
         //    path never yields a doc name, so e.g. the maintainer store shipped
         //    at builtin-memory/.crouter can never register) — lint must not
         //    flag files the substrate can never load.
+        // Exact canonical names in the current resolvable corpus. INDEX docs also
+        // expose their folded bare-directory name (`taste`, not `taste/INDEX`).
+        const corpusNames = new Set();
+        for (const doc of listAllMemoryDocs(undefined, true)) {
+            const canonical = displayName(doc.name);
+            if (canonical !== '')
+                corpusNames.add(canonical);
+        }
         const lintDir = (dir) => {
             if (!dir || !pathExists(dir))
                 return;
             for (const file of walkFiles(dir, (n) => n.endsWith('.md'), (d) => d.startsWith('.'))) {
-                if (!relative(dir, file).split(sep).join('/'))
+                const relPath = relative(dir, file).split(sep).join('/');
+                if (!relPath)
                     continue;
                 memoryCount += 1;
-                lintFile(file, basename(file) !== 'MEMORY.md', findings);
+                const fallbackName = normalizeDocName(relPath.replace(/\.md$/, ''));
+                lintFile(file, basename(file) !== 'MEMORY.md', findings, corpusNames, fallbackName);
             }
         };
         for (const root of projectScopeRoots()) {
@@ -161,32 +269,66 @@ export const lintLeaf = defineLeaf({
                     lintDir(pluginMemoryDir(plugin));
             }
         }
-        // Profile coverage: the selected profile's manifest names the dirs the
-        // operator manages. Lint the profile's own store, and require every
-        // managed project dir to carry an always-loaded operating guide
-        // (.crouter/memory/AGENTS.md) — a managed dir without one boots every
-        // agent there blind, so its absence is an authoring finding like any
-        // schema violation. (The managed dirs' stores themselves already lint
-        // above: projectScopeRoots folds the profile's project pointers in.)
+        // Profile coverage: each managed project has one direct root INDEX front
+        // door. It enters first-message context through the workspace-open `.`
+        // route, so its exact contract is knowledge + system none/file content +
+        // applies-to containing `.`.
         let profileProjects = 0;
+        let profileResolved = false;
         const profileIdOrName = process.env['CRTR_PROFILE_ID'] || getDefaultProfileId(process.cwd());
         if (profileIdOrName) {
             try {
                 const { profileId, manifest } = loadProfileManifest(profileIdOrName);
+                profileResolved = true;
                 lintDir(profileMemoryDir(profileId));
                 for (const dir of manifest.projects) {
                     profileProjects += 1;
-                    if (!pathExists(join(dir, '.crouter', 'memory', 'AGENTS.md'))) {
+                    const indexPath = join(dir, '.crouter', 'memory', 'INDEX.md');
+                    if (!pathExists(indexPath)) {
                         findings.push({
                             path: dir,
-                            error: `profile "${manifest.name}" manages this dir but it has no .crouter/memory/AGENTS.md — author its always-loaded operating guide (name the doc AGENTS, target the dir with --dir; run \`crtr memory write -h\` first)`,
+                            error: `profile "${manifest.name}" manages this dir but it has no .crouter/memory/INDEX.md root front door — author INDEX in that exact project with kind knowledge, system-prompt-visibility none, file-read-visibility content, and applies-to "."; run \`crtr memory write -h\` first`,
                         });
+                        continue;
+                    }
+                    try {
+                        const fm = parseFrontmatterGeneric(readText(indexPath)).data;
+                        const problems = [];
+                        if (fm?.kind !== 'knowledge')
+                            problems.push('kind must be `knowledge`');
+                        if (fm?.['system-prompt-visibility'] !== 'none')
+                            problems.push('system-prompt-visibility must be `none`');
+                        if (fm?.['file-read-visibility'] !== 'content')
+                            problems.push('file-read-visibility must be `content`');
+                        const applies = fm?.['applies-to'];
+                        const globs = typeof applies === 'string'
+                            ? [applies]
+                            : Array.isArray(applies) && applies.every((value) => typeof value === 'string')
+                                ? applies
+                                : [];
+                        if (!globs.some((glob) => glob.trim() === '.'))
+                            problems.push('applies-to must include `.`');
+                        if (problems.length > 0) {
+                            findings.push({ path: indexPath, error: `invalid project root front door: ${problems.join('; ')}` });
+                        }
+                    }
+                    catch (e) {
+                        const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
+                        findings.push({ path: indexPath, error: `invalid project root front door YAML: ${msg}` });
                     }
                 }
             }
             catch {
-                // Unresolvable profile (deleted/corrupt manifest): profile coverage
-                // just doesn't apply — the file corpus above already linted fully.
+                // Unresolvable profile: profile coverage does not apply. Treat cwd as
+                // unprofiled for the advisory front-door warning below.
+            }
+        }
+        // Without a selected, resolvable profile there is no managed-project
+        // finding to carry this signal, so keep a non-fatal cwd adoption warning.
+        if (!profileResolved) {
+            const workingDirectoryIndex = join(workingDirectory, '.crouter', 'memory', 'INDEX.md');
+            if (!pathExists(workingDirectoryIndex)) {
+                warnings.push(`${workingDirectory}: no .crouter/memory/INDEX.md root front door — author INDEX for this project with kind knowledge, system-prompt-visibility none, file-read-visibility content, and applies-to "."; run \`crtr memory write -h\` first`);
             }
         }
         const checked = memoryCount;
@@ -203,7 +345,7 @@ export const lintLeaf = defineLeaf({
                 checked,
                 findings: findings.map((f) => ({ path: f.path, error: f.error })),
                 warnings,
-                next: 'Fix each doc (quote YAML values containing `: `; use a valid kind/rung/gate); for a profile-managed dir missing AGENTS.md, author one — run `crtr memory write -h` — then re-run `crtr memory lint`.',
+                next: 'Fix each doc (quote YAML values containing `: `; use a valid kind/rung/gate; route every non-`none` file-read rung with `applies-to: "."` for workspace-open context or a non-empty file glob for matching reads; otherwise use file-read-visibility `none`; retarget or drop dangling [[links]]; split an over-length body into [[linked]] `none`-visibility reference docs); make every profile-managed project root INDEX match the front-door contract; then re-run `crtr memory lint`.',
             });
         }
         return {

package/dist/commands/memory/read.js

@@ -2,8 +2,10 @@ import { defineLeaf } from '../../core/command.js';
 import { CrtrError, notFound } from '../../core/errors.js';
 import { resolveMemoryDoc } from '../../core/memory-resolver.js';
 import { effectiveDocKind } from '../../core/substrate/schema.js';
+import { displayName } from '../../core/substrate/ceiling.js';
 import { interpolateNodePaths } from '../../core/canvas/paths.js';
 import { readText } from '../../core/fs-utils.js';
+import { docLinkNames } from '../../core/memory/doc-link-grammar.js';
 import { MEMORY_KINDS } from './shared.js';
 export const readLeaf = defineLeaf({
     name: 'read',
@@ -23,6 +25,7 @@ export const readLeaf = defineLeaf({
             { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was resolved from: node, project, profile, user, or builtin.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the document on disk — direct edits here are for a small body-only tweak; any routing/frontmatter/visibility change goes through `crtr memory write`.' },
             { name: 'content', type: 'string', required: true, constraint: 'Document body. Frontmatter stripped unless --frontmatter is set.' },
+            { name: '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.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Hints at variant flags or next commands.' },
         ],
         outputKind: 'object',
@@ -55,13 +58,31 @@ export const readLeaf = defineLeaf({
             // reading generically (env unset) keeps the token literal.
             const nodeId = process.env['CRTR_NODE_ID'];
             const content = nodeId ? interpolateNodePaths(raw, nodeId) : raw;
+            // `[[name]]` doc links are pointers, never transclusion: surface which
+            // linked names actually resolve so the reader can follow one when the
+            // task needs that depth, without ever auto-loading a linked body.
+            const links = docLinkNames(doc.body).filter((linkName) => {
+                try {
+                    // `resolveMemoryDoc` permits leaf-name fallback for interactive reads;
+                    // a stored graph edge does not. Compare the resolved canonical name
+                    // so an old shorthand never masquerades as a first-class doc link.
+                    return displayName(resolveMemoryDoc(linkName).name) === linkName;
+                }
+                catch {
+                    return false;
+                }
+            });
             return {
                 name: doc.name,
                 kind,
                 scope: doc.scope,
                 path: doc.path,
                 content,
-                follow_up: 'Use --frontmatter on this same command to inspect the YAML frontmatter, or edit `path` directly for a body-only tweak. Browse the inventory with `crtr memory list`.',
+                ...(links.length > 0 ? { links } : {}),
+                follow_up: (links.length > 0
+                    ? 'The `[[name]]` links in the body are further reading — follow one with `crtr memory read <name>` only when the task needs that depth. '
+                    : '') +
+                    'Use --frontmatter on this same command to inspect the YAML frontmatter, or edit `path` directly for a body-only tweak. Browse the inventory with `crtr memory list`.',
             };
         }
         throw notFound(`memory document not found: ${nameRaw}`, {