@north-light/crouter 0.3.161 → 0.3.163

package/dist/commands/memory/write.js

@@ -18,10 +18,12 @@ export const writeLeaf = defineLeaf({
             'Store reusable current truth, not session notes. Useful memories are non-obvious procedures, gotchas, durable preferences, cross-repo conventions, and amendments to plans/specs that future agents must honor. Put plan/spec amendments under path names like `projects/<topic>/...`; add `projects/<topic>/INDEX.md` with `name` visibility so the topic is discoverable without loading the whole body. Do not store chat summaries, implementation history, or facts already recorded in the repo.\n\n' +
             'Set both visibility rungs explicitly on create. There is no kind default. `none`, `name`, `preview`, and `content` move from least to most loaded: `none` keeps the doc out of auto-load and on-read surfaces, `name` is the bare doc tag only, `preview` is the name + envelope + routing line (`when-and-why-to-read`), and `content` inlines the whole body when the body is short enough to justify it. Each axis is independent; usually one carries a real rung and the other is `none`. When a doc is short enough to state in a single sentence — a one-line preference, or a knowledge fact that fits in a sentence — skip `preview` and use `name` or `content` directly: the routing line would run longer than the doc itself, so a `preview` rung just adds words. Sentence-length `content` docs are not just acceptable, they are correct. Never pad a memory to be more verbose than the rule or fact it carries.\n\n' +
             'Choose the scope. `project` is for facts any agent in one repo needs. `user` is for person-wide facts and preferences that should follow the user everywhere. `profile` is for the profile’s bundle of dirs: cross-repo conventions, how the pieces relate, or the user’s stance toward that body of work. `node` is the narrowest — the this-node store (`nodes/<CRTR_NODE_ID>/context/memory/`), scratch memory only this running node sees; it rides straight into this node’s knowledge block and dies with the node. When unsure, choose the narrowest scope that will still reach the next agent who needs it.\n\n' +
-            'AGENTS.md is the one special doc: a store’s always-loaded operating guide, and every dir a profile manages should carry one (`crtr memory lint` flags the gaps). Name the doc AGENTS, target the exact dir with --dir, and set system-prompt-visibility to `content` so every agent working there boots with it. It is a front door, not a manual — constraints and gotchas, the key commands, a few sentences of architecture orientation, and only the conventions that differ from defaults. Every line is paid by every session in that dir forever: prefer a pointer (“when X, run Y -h / read Z, because W”) over inlined how-to, and cut any line that would not change an agent’s behavior.\n\n' +
-            'Choose the hook — boot vs file-read. Behavior and how-to procedure surface at boot. Knowledge about code belongs next to the code: put the file in that directory’s .crouter/memory/ (`--dir <project-dir>` targets it exactly, from anywhere) and it fires positionally when files there are read, costing nothing at boot. A knowledge doc about a person or process has no code directory to anchor to, so on-read triggering is meaningless — route it through boot instead and set the boot rung to `preview` when you want the routing line to surface.\n\n' +
+            'A project root INDEX is the workspace front door. Name the physical doc INDEX, target the exact project with --dir, and use kind knowledge, system-prompt-visibility none, file-read-visibility content, and applies-to ".". The `.` route surfaces the full operating guide in first-message context whenever cwd or a selected profile mounts that project store; its envelope name comes from the owning project directory unless the document already carries an explicit name. It is a front door, not a manual — keep only the project constraints, key commands, architecture orientation, and conventions that differ from defaults. `crtr memory lint` validates this exact contract for every project managed by the selected profile.\n\n' +
+            'Choose the hook — boot vs file context. System-prompt visibility is the boot catalog. Every non-none file-read rung also requires at least one explicit applies-to route: `.` means project workspace/profile mount and is evaluated during first-message assembly; every other value is a glob evaluated only after a matching file is actually read. There is no positional fallback from where the memory file lives. Put code-specific knowledge in the owning project store, give it the narrowest real file glob, and keep it out of boot when the file read is the useful trigger. Knowledge about a person or process usually has no file boundary, so set file-read-visibility none and route it through boot instead.\n\n' +
             'Write the routing line (--when-and-why-to-read) first, before storing anything: "When <circumstance>, this <kind> should be read because <broader downstream payoff>." WHY is the READER’s payoff — the consequence they secure for the task in front of them by spending the read — never what the document says, its rule, or why it should be obeyed. The trap most authors fall into is the DISGUISED restatement: a because-clause that reads like a benefit but is just the doc’s own thesis reworded as an outcome. It still fails. The test: if you could derive the because-clause by paraphrasing the doc’s advice, it is a restatement, not a payoff — a real payoff names a consequence in the reader’s world that the document itself never asserts. Bad (naked restatement): "because only genuine first principles belong in taste memory." Bad (restatement in benefit’s clothing): "because keeping the test loop fast and free of speculative tests protects the development pace" — that is the doc’s rule in outcome costume, derivable straight from its advice. Good: "because identifying throughlines in user taste lets future decisions be made faster and with less re-litigation." The stranger test: someone mid-task who has NOT read the doc must be able to decide from this one line alone whether the read is worth it. If you cannot name the concrete situation that triggers it, you do not yet understand the memory — ask the user one sharp question instead of improvising.\n\n' +
             'Gate and read-when share the same predicate language: a field map is AND-ed across fields; dotted fields resolve nested values; field matchers may be scalar, array, or object. Scalar matchers do exact equality, with arrays matching any element. Array matchers do membership or intersection. Object matchers accept `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, and `lte`. Combinators are `all`, `any`, and `not`; sibling field matchers next to them are AND-ed in. An empty condition is inert. An unknown op never matches.\n\n' +
+            'Link related docs with `[[canonical/name]]`. A doc link in any body is a first-class cross-reference to another memory document by its exact canonical name — the same identifier `crtr memory read` takes (a directory INDEX is linked by its bare directory name). Links are pointers, never transclusion: the linked body is loaded only when a reader follows it, so a link costs nothing until needed. `crtr memory lint` fails on a link that resolves to no document, and `crtr memory read` lists a doc’s resolvable links alongside its body. There is no alias or label form.\n\n' +
+            'When a doc grows long or information-rich, nest it into a graph instead of letting it become a scroll. The main doc at the topic’s path keeps the high-level, most load-bearing information, most important first; depth splits into reference docs under the topic’s directory (`area/topic/...`), each pointed at with a `[[link]]` as further reading. The main doc is the entry point a reader can act from alone; a reference leaf is loaded only when the task needs that depth. Save reference leaves at `none` visibility on both axes — the link from the main doc is how they are found, so any higher rung just double-charges every boot or read for depth the graph already routes. This is the same layering the visibility rungs apply to boot cost, applied to the body itself. Keep every doc as short as its job allows; `crtr memory lint` caps body length by rung and its findings carry the split guidance.\n\n' +
             'Find before write. Prefer slightly expanding an existing document, nesting genuinely separate depth under its topic, and updating the existing `when-and-why-to-read` (plus its INDEX router when present) over creating another similar memory. A new document earns its own identity only when it has a distinct read trigger and a coherent body that would make the existing document harder to route or use. Group related docs with path names (area/topic). Do not store what is already recorded or what only matters to this conversation. Body is for current truth, not history. Provenance is automatic on create and preserved on update. Run `crtr memory lint` — the frontmatter validator — after authoring.\n\n' +
             '--rationale is the gap this doc exists to close — the observed agent failure that prompted it, captured from user signal (a correction, a mistake you watched happen) rather than inferred from the doc’s own content. The bar: if the rationale is guessable from reading the doc, it is not the real one — a guessable gap is one agents do not actually fall into, so a merely-plausible-sounding reason is not worth recording. It is maintainer-facing only and NEVER ships in a delivered surface (boot render, on-read injection, `memory read` content) — it lives in frontmatter, visible only via `memory read --frontmatter`. Omit it when you have no such gap to record; omitting the flag on an update always preserves whatever rationale already exists.',
         params: [
@@ -30,9 +32,9 @@ export const writeLeaf = defineLeaf({
             { 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’s payoff — the consequence they secure for their task by reading — NEVER the doc summary, its rule, or that rule reworded as an outcome (a benefit-shaped restatement still fails). Rendered verbatim as the preview; required when creating.' },
             { kind: 'flag', name: 'short-form', type: 'string', required: false, constraint: 'Frontmatter short-form — a very abbreviated version of the content, the hook shown in `crtr memory list`.' },
             { kind: 'flag', name: 'system-prompt-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much of this document auto-loads into the system prompt / CLI help. Required when creating — there is no kind default; pick a rung explicitly.' },
-            { kind: 'flag', name: 'file-read-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much of this document surfaces when it is read off disk. Required when creating — there is no kind default; pick a rung explicitly.' },
+            { kind: 'flag', name: 'file-read-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much surfaces through file context. Required when creating — there is no kind default. Every value except none also requires at least one applies-to route in the resulting document.' },
             { kind: 'flag', name: 'gate', type: 'string', required: false, constraint: 'Frontmatter gate — YAML/JSON object predicate over node config using the same field/matcher vocabulary described in the guide.' },
-            { kind: 'flag', name: 'applies-to', type: 'string', required: false, repeatable: true, constraint: 'Frontmatter applies-to — one glob/path scope per flag occurrence. Repeat --applies-to for multiple globs (e.g. --applies-to "src/**" --applies-to "docs/**").' },
+            { kind: 'flag', name: 'applies-to', type: 'string', required: false, repeatable: true, constraint: 'One explicit file-context route per occurrence. In a project store, `.` fires when cwd/profile mounts that workspace during first-message assembly. Any other value is a glob matched after an actual file read against the absolute path, basename, and path relative to the owning project root. Required whenever file-read-visibility is not none.' },
             { kind: 'flag', name: 'read-when', type: 'string', required: false, constraint: 'Frontmatter read-when — YAML/JSON object predicate over a read file’s own frontmatter using the same field/matcher vocabulary described in the guide.' },
             { 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 `:`) — the doc body becomes the command’s injected prompt. Default false: most docs are consulted, not invoked.' },
             { kind: 'flag', name: 'rationale', type: 'string', required: false, constraint: 'Frontmatter rationale — the observed agent failure that made this doc necessary. Maintainer-facing only: never ships in any delivered surface (boot render, on-read injection, `memory read` content), visible only via `memory read --frontmatter`. Omitting this flag on an update PRESERVES an existing rationale unchanged.' },
@@ -112,6 +114,18 @@ export const writeLeaf = defineLeaf({
         if (input['slash'] === true)
             frontmatter['slash'] = true;
         setIf('rationale', input['rationale']);
+        const applies = frontmatter['applies-to'];
+        const routes = typeof applies === 'string'
+            ? [applies]
+            : Array.isArray(applies) && applies.every((value) => typeof value === 'string')
+                ? applies
+                : [];
+        if (frontmatter['file-read-visibility'] !== 'none' && routes.length === 0) {
+            throw usage(`file-read-visibility ${String(frontmatter['file-read-visibility'])} requires --applies-to: use "." for project workspace/profile-open context, a real file glob for matching reads, or choose file-read-visibility none`);
+        }
+        if (scope !== 'project' && routes.some((route) => route.trim() === '.')) {
+            throw usage('applies-to "." is a project-store workspace mount route; use a real file glob or choose file-read-visibility none for user, profile, and node memory');
+        }
         writeText(path, serializeMemoryDoc(frontmatter, body));
         // Confirm exactly the frontmatter choices made by this invocation. On an
         // update, inherited fields stay in the file but do not masquerade as newly

package/dist/commands/memory.js

@@ -19,7 +19,7 @@ export function registerMemory() {
         help: {
             name: 'memory',
             summary: 'list, read, search, and write memory documents — knowledge and preferences',
-            model: 'Documents have path-derived identities and resolve across layered scopes in precedence order: node > project stack > profile > user > builtin. Discover a document with `find` when its name is unknown; address it directly with `read`/`write` when known. A directory may carry an `INDEX.md` with the same frontmatter schema as any doc — it then renders as one entry at the INDEX\'s rung, and that rung is a ceiling for its whole subtree (`none` hides the dir): when a doc mysteriously is not surfacing, check its ancestors\' INDEX rungs and its gate.',
+            model: 'Documents have path-derived identities and resolve across layered scopes in precedence order: node > project stack > profile > user > builtin. Discover a document with `find` when its name is unknown; address it directly with `read`/`write` when known. A directory may carry an `INDEX.md` with the same frontmatter schema as any doc — it renders as one boot-catalog entry whose system-prompt rung caps that subtree. File context is separate and explicit: `applies-to: "."` opens project context with the workspace; other globs fire after matching reads.',
         },
         children: [listLeaf, readLeaf, findLeaf, writeLeaf, deleteLeaf, originLeaf, lintLeaf],
     });

package/dist/commands/search/contents.js

@@ -10,7 +10,7 @@ export const contentsLeaf = defineLeaf({
         name: 'search contents',
         summary: 'content extraction via Exa — cleaned highlights or full text for URLs you already have',
         params: [
-            { kind: 'positional', name: 'urls', required: true, constraint: 'One or more URLs to extract, separated by commas or whitespace.' },
+            { kind: 'positional', name: 'urls', repeatable: true, required: true, constraint: 'One or more URL tokens to extract. Each token may contain URLs separated by commas or whitespace.' },
             { kind: 'flag', name: 'text', type: 'bool', required: false, constraint: `Return cleaned full page text (capped at ${TEXT_MAX_CHARACTERS} characters per URL) instead of highlight excerpts. Off by default.` },
             { kind: 'flag', name: 'max-age-hours', type: 'int', required: false, constraint: 'Maximum acceptable age of cached content, in hours; content older than this is freshly crawled. 0 forces a fresh crawl every time. Omit to use cache when available and crawl as fallback.' },
         ],
@@ -23,7 +23,7 @@ export const contentsLeaf = defineLeaf({
         effects: ['Sends one contents request to the Exa API (network). URLs Exa fails to fetch are retried through the pure.md markdown service. No local state changes.'],
     },
     run: async (input) => {
-        const urls = parseUrls(input['urls']);
+        const urls = input['urls'].flatMap(parseUrls);
         if (urls.length === 0)
             throw usage('no URLs provided', { next: 'Pass one or more URLs separated by commas or whitespace.' });
         const wantText = input['text'];

package/dist/commands/sys/__tests__/sync-deps.test.js

@@ -9,7 +9,6 @@ import { closeDb } from '../../../core/canvas/db.js';
 import { resetScopeCache } from '../../../core/scope.js';
 import { spawnNode } from '../../../core/runtime/nodes.js';
 import { renderKnowledgeBlock } from '../../../core/substrate/render-node.js';
-import { renderOnReadDocs } from '../../../core/substrate/on-read.js';
 import { clearSessionCache } from '../../../core/substrate/session-cache.js';
 import { runDepsSync, sysSyncDepsLeaf } from '../sync-deps.js';
 const projects = [];
@@ -26,7 +25,7 @@ function assertVisibility(path, system, fileRead) {
     assert.match(doc, new RegExp(`^system-prompt-visibility: ${system}$`, 'm'));
     assert.match(doc, new RegExp(`^file-read-visibility: ${fileRead}$`, 'm'));
 }
-test('renders the dependency catalog preview and generated bundle names without leaf prose', () => {
+test('renders the dependency boot catalog preview and generated bundle names without leaf prose', () => {
     const originalHome = process.env.HOME;
     const originalCrtrHome = process.env.CRTR_HOME;
     const originalCwd = process.cwd();
@@ -52,21 +51,13 @@ test('renders the dependency catalog preview and generated bundle names without
         clearSessionCache();
         const node = spawnNode({ kind: 'general', cwd: project, parent: null }).node_id;
         const boot = renderKnowledgeBlock(node);
-        const readFile = join(project, 'src', 'app.ts');
-        write(readFile, 'export {};\n');
-        const onRead = renderOnReadDocs(node, readFile, new Set());
-        for (const rendered of [boot, onRead]) {
-            assert.match(rendered, /When writing code against this project's dependencies/, 'the top catalog stays preview-visible');
-            assert.doesNotMatch(rendered, /Dependency-shipped agent docs \(generated\)/, 'the top catalog body stays hidden');
-            for (const name of ['flat', 'reference', 'nested', 'child', 'notes']) {
-                assert.ok(rendered.includes(name), `expected generated name ${name} in rendered output`);
-            }
-            for (const leaked of ['FLAT_BUNDLE_BODY', 'FLAT_SIDECAR_BODY', 'NESTED_BUNDLE_BODY', 'NESTED_SIDECAR_BODY', 'Flat bundle routing prose.', 'Nested bundle routing prose.']) {
-                assert.ok(!rendered.includes(leaked), `generated leaf prose must not render: ${leaked}`);
-            }
+        assert.match(boot, /When writing code against this project's dependencies/, 'the top catalog stays preview-visible');
+        assert.doesNotMatch(boot, /Dependency-shipped agent docs \(generated\)/, 'the top catalog body stays hidden');
+        for (const name of ['flat', 'reference', 'nested', 'child', 'notes']) {
+            assert.ok(boot.includes(name), `expected generated name ${name} in boot output`);
         }
-        for (const name of ['deps/flat', 'deps/flat/reference', 'deps/nested/child', 'deps/nested/child/notes']) {
-            assert.match(onRead, new RegExp(`name="${name}"`), `on-read output exposes bare ${name}`);
+        for (const leaked of ['FLAT_BUNDLE_BODY', 'FLAT_SIDECAR_BODY', 'NESTED_BUNDLE_BODY', 'NESTED_SIDECAR_BODY', 'Flat bundle routing prose.', 'Nested bundle routing prose.']) {
+            assert.ok(!boot.includes(leaked), `generated leaf prose must not render: ${leaked}`);
         }
     }
     finally {
@@ -115,10 +106,10 @@ test('excludes one exact dependency bundle before vendoring while retaining safe
     assert.equal(existsSync(join(deps, 'safe', 'INDEX.md')), true);
     assert.equal(existsSync(join(deps, 'unsafe', 'INDEX.md')), false);
     assert.equal(existsSync(join(deps, 'unsafe', 'reference.md')), false);
-    assertVisibility(join(deps, 'safe', 'INDEX.md'), 'name', 'name');
-    assertVisibility(join(deps, 'safe', 'reference.md'), 'name', 'name');
+    assertVisibility(join(deps, 'safe', 'INDEX.md'), 'name', 'none');
+    assertVisibility(join(deps, 'safe', 'reference.md'), 'name', 'none');
     const catalog = join(deps, 'INDEX.md');
-    assertVisibility(catalog, 'preview', 'preview');
+    assertVisibility(catalog, 'preview', 'none');
     const catalogBody = readFileSync(catalog, 'utf8');
     assert.match(catalogBody, /deps\/safe/);
     assert.doesNotMatch(catalogBody, /unsafe/);
@@ -147,8 +138,8 @@ test('excludes a parent bundle without deleting its included nested bundle', ()
     assert.equal(existsSync(join(deps, 'reference.md')), false);
     assert.equal(existsSync(join(deps, 'child', 'INDEX.md')), true);
     assert.equal(existsSync(join(deps, 'child', 'reference.md')), true);
-    assertVisibility(join(deps, 'child', 'INDEX.md'), 'name', 'name');
-    assertVisibility(join(deps, 'child', 'reference.md'), 'name', 'name');
+    assertVisibility(join(deps, 'child', 'INDEX.md'), 'name', 'none');
+    assertVisibility(join(deps, 'child', 'reference.md'), 'name', 'none');
 });
 test('writes a truthful empty catalog when exclusions remove every bundle', () => {
     const project = mkdtempSync(join(tmpdir(), 'crtr-sync-deps-empty-'));

package/dist/commands/sys/__tests__/sync-import.test.js

@@ -17,7 +17,7 @@ import { closeDb } from '../../../core/canvas/db.js';
 import { resolveMemoryDoc } from '../../../core/memory-resolver.js';
 import { parseFrontmatterGeneric } from '../../../core/frontmatter.js';
 import { gitSync } from '../../../core/git.js';
-import { renderKnowledgeBlock } from '../../../core/substrate/render-node.js';
+import { renderWorkspaceOpenDocs } from '../../../core/substrate/on-read.js';
 import { clearSessionCache } from '../../../core/substrate/session-cache.js';
 import { sysSyncSkillsLeaf } from '../sync-skills.js';
 import { sysSyncProjectGuidanceLeaf } from '../sync-project-guidance.js';
@@ -124,24 +124,25 @@ test('migrates CLAUDE.md and a .claude/rules file into that dir\'s own .crouter/
     writeFileSync(join(source, '.claude', 'rules', 'foo.md'), '---\nname: foo\ndescription: Applies when touching src files.\npaths:\n  - "src/**/*.ts"\n---\n\nDo the foo thing.\n', 'utf8');
     const dry = await sysSyncProjectGuidanceLeaf.run({ source, dryRun: true });
     const dryRows = dry?.results;
-    assert.equal(dryRows.length, 2, 'both the AGENTS.md and the rule dry-run as candidates');
+    assert.equal(dryRows.length, 2, 'both the project guide and the rule dry-run as candidates');
     assert.ok(dryRows.every((r) => r.status === 'would-import'));
-    assert.equal(existsSync(join(source, '.crouter', 'memory', 'AGENTS.md')), false, 'dry-run writes nothing');
+    assert.equal(existsSync(join(source, '.crouter', 'memory', 'INDEX.md')), false, 'dry-run writes nothing');
     await sysSyncProjectGuidanceLeaf.run({ source });
-    const agentsTarget = join(source, '.crouter', 'memory', 'AGENTS.md');
+    const projectIndexTarget = join(source, '.crouter', 'memory', 'INDEX.md');
     const ruleTarget = join(source, '.crouter', 'memory', 'foo.md');
-    assert.equal(existsSync(agentsTarget), true);
+    assert.equal(existsSync(projectIndexTarget), true);
     assert.equal(existsSync(ruleTarget), true);
-    const agentsDoc = parseFrontmatterGeneric(readFileSync(agentsTarget, 'utf8'));
-    assert.equal(agentsDoc.data?.kind, 'knowledge');
-    assert.equal(agentsDoc.data?.name, 'demo-project');
-    assert.equal(agentsDoc.data?.['system-prompt-visibility'], 'content');
-    assert.equal(agentsDoc.data?.['file-read-visibility'], 'content');
-    assert.match(agentsDoc.body, /Build then commit\./);
+    const projectIndex = parseFrontmatterGeneric(readFileSync(projectIndexTarget, 'utf8'));
+    assert.equal(projectIndex.data?.kind, 'knowledge');
+    assert.equal(projectIndex.data?.name, 'demo-project');
+    assert.equal(projectIndex.data?.['system-prompt-visibility'], 'none');
+    assert.equal(projectIndex.data?.['file-read-visibility'], 'content');
+    assert.deepEqual(projectIndex.data?.['applies-to'], ['.']);
+    assert.match(projectIndex.body, /Build then commit\./);
     const prevCwd = process.cwd();
     process.chdir(source);
     try {
-        assert.equal(resolveMemoryDoc('demo-project').path, realpathSync(agentsTarget));
+        assert.equal(resolveMemoryDoc('demo-project').path, realpathSync(projectIndexTarget));
         assert.equal(resolveMemoryDoc('demo-project').name, 'demo-project');
     }
     finally {
@@ -165,8 +166,8 @@ test('migrates CLAUDE.md and a .claude/rules file into that dir\'s own .crouter/
     const overwritten = await sysSyncProjectGuidanceLeaf.run({ source, overwrite: true });
     const overwriteRows = overwritten?.results;
     assert.ok(overwriteRows.some((r) => r.status === 'imported'));
-    const agentsDoc2 = parseFrontmatterGeneric(readFileSync(agentsTarget, 'utf8'));
-    assert.match(agentsDoc2.body, /Build, THEN commit\./);
+    const projectIndex2 = parseFrontmatterGeneric(readFileSync(projectIndexTarget, 'utf8'));
+    assert.match(projectIndex2.body, /Build, THEN commit\./);
     rmSync(source, { recursive: true, force: true });
 });
 test('routes the walk-root AGENTS.md doc by the real git repo name, not a worktree\'s own basename', async () => {
@@ -189,13 +190,13 @@ test('routes the walk-root AGENTS.md doc by the real git repo name, not a worktr
     writeFileSync(join(linkedWorktree, 'CLAUDE.md'), '# Fallback Title\n\nRepo guidance.\n', 'utf8');
     const result = await sysSyncProjectGuidanceLeaf.run({ source: linkedWorktree });
     assert.equal(result?.imported, 1);
-    const target = join(linkedWorktree, '.crouter', 'memory', 'AGENTS.md');
+    const target = join(linkedWorktree, '.crouter', 'memory', 'INDEX.md');
     const doc = parseFrontmatterGeneric(readFileSync(target, 'utf8'));
     assert.equal(doc.data?.['when-and-why-to-read'], 'When working in demo-repo, this knowledge should be read because it is the project\'s operating guide.');
     git(['worktree', 'remove', '--force', linkedWorktree], mainRepo);
     rmSync(base, { recursive: true, force: true });
 });
-test('sibling purview roots keep distinct AGENTS names so boot render does not dedupe them away', async () => {
+test('sibling purview roots keep distinct INDEX identities so workspace-open render does not dedupe them away', async () => {
     const base = mkdtempSync(join(tmpdir(), 'crtr-sys-sync-purview-'));
     const rootA = join(base, 'alpha-root');
     const rootB = join(base, 'beta-root');
@@ -218,15 +219,15 @@ test('sibling purview roots keep distinct AGENTS names so boot render does not d
         process.chdir(runDir);
         clearSessionCache();
         const alphaDoc = resolveMemoryDoc('alpha-root');
-        assert.equal(alphaDoc.path, join(rootA, '.crouter', 'memory', 'AGENTS.md'));
+        assert.equal(alphaDoc.path, join(rootA, '.crouter', 'memory', 'INDEX.md'));
         assert.equal(alphaDoc.name, 'alpha-root');
         const betaDoc = resolveMemoryDoc('beta-root');
-        assert.equal(betaDoc.path, join(rootB, '.crouter', 'memory', 'AGENTS.md'));
+        assert.equal(betaDoc.path, join(rootB, '.crouter', 'memory', 'INDEX.md'));
         assert.equal(betaDoc.name, 'beta-root');
-        createNode(node('bootcheck', runDir));
-        const block = renderKnowledgeBlock('bootcheck');
-        assert.match(block, /Alpha body\./, 'first purview root survives the boot render');
-        assert.match(block, /Beta body\./, 'second purview root survives the boot render');
+        createNode({ ...node('bootcheck', runDir), profile_id: profileId });
+        const block = renderWorkspaceOpenDocs('bootcheck');
+        assert.match(block, /Alpha body\./, 'first purview root survives workspace-open rendering');
+        assert.match(block, /Beta body\./, 'second purview root survives workspace-open rendering');
     }
     finally {
         process.chdir(prevCwd);
@@ -237,7 +238,7 @@ test('sibling purview roots keep distinct AGENTS names so boot render does not d
     }
     rmSync(base, { recursive: true, force: true });
 });
-test('a nested project-subdir AGENTS/CLAUDE doc migrates to its OWN <nested>/.crouter/memory/AGENTS.md with a deterministic, non-colliding explicit name', async () => {
+test('a nested project-subdir guide migrates to its OWN <nested>/.crouter/memory/INDEX.md with a deterministic, non-colliding explicit name', async () => {
     const source = mkdtempSync(join(tmpdir(), 'crtr-sys-sync-nested-'));
     writeFileSync(join(source, 'CLAUDE.md'), '# Nested Demo\n\nRoot guidance.\n', 'utf8');
     const nestedDir = join(source, 'packages', 'widgets');
@@ -247,10 +248,10 @@ test('a nested project-subdir AGENTS/CLAUDE doc migrates to its OWN <nested>/.cr
     const projectRows = result?.results;
     assert.equal(projectRows.length, 2, 'both the root and nested docs are candidates');
     assert.ok(projectRows.every((r) => r.status === 'imported'));
-    const rootTarget = join(source, '.crouter', 'memory', 'AGENTS.md');
-    const nestedTarget = join(nestedDir, '.crouter', 'memory', 'AGENTS.md');
-    assert.equal(existsSync(rootTarget), true, 'root doc writes to the root\'s OWN .crouter/memory/AGENTS.md');
-    assert.equal(existsSync(nestedTarget), true, 'nested doc writes to the NESTED dir\'s OWN .crouter/memory/AGENTS.md, not the root store');
+    const rootTarget = join(source, '.crouter', 'memory', 'INDEX.md');
+    const nestedTarget = join(nestedDir, '.crouter', 'memory', 'INDEX.md');
+    assert.equal(existsSync(rootTarget), true, 'root guide writes to the root\'s OWN .crouter/memory/INDEX.md');
+    assert.equal(existsSync(nestedTarget), true, 'nested guide writes to the NESTED dir\'s OWN .crouter/memory/INDEX.md, not the root store');
     const rootDoc = parseFrontmatterGeneric(readFileSync(rootTarget, 'utf8'));
     const nestedDoc = parseFrontmatterGeneric(readFileSync(nestedTarget, 'utf8'));
     assert.equal(rootDoc.data?.name, 'nested-demo');
@@ -292,7 +293,7 @@ test('a nested project-subdir doc migrated when --source POINTS AT THE NESTED DI
     // unmigrated, so the nested doc's name must stay qualified on its own.
     const nestedResult = await sysSyncProjectGuidanceLeaf.run({ source: nestedDir });
     assert.equal(nestedResult?.imported, 1);
-    const nestedTarget = join(nestedDir, '.crouter', 'memory', 'AGENTS.md');
+    const nestedTarget = join(nestedDir, '.crouter', 'memory', 'INDEX.md');
     assert.equal(existsSync(nestedTarget), true);
     const nestedDoc = parseFrontmatterGeneric(readFileSync(nestedTarget, 'utf8'));
     assert.equal(nestedDoc.data?.name, 'demo-repo/packages/widgets', 'nested doc name is suffix-qualified even though --source pinned the nested dir directly');
@@ -307,7 +308,7 @@ test('falls back to the doc H1 title when the walk root is not inside a git repo
     writeFileSync(join(source, 'CLAUDE.md'), '# Standalone Docs Project\n\nDo the thing.\n', 'utf8');
     const result = await sysSyncProjectGuidanceLeaf.run({ source });
     assert.equal(result?.imported, 1);
-    const target = join(source, '.crouter', 'memory', 'AGENTS.md');
+    const target = join(source, '.crouter', 'memory', 'INDEX.md');
     const doc = parseFrontmatterGeneric(readFileSync(target, 'utf8'));
     assert.equal(doc.data?.['when-and-why-to-read'], 'When working in standalone-docs-project, this knowledge should be read because it is the project\'s operating guide.');
     rmSync(source, { recursive: true, force: true });

package/dist/commands/sys/setup-wizard.d.ts

@@ -52,6 +52,7 @@ export declare class SetupWizard implements Component, Focusable {
     private expandedPluginId;
     private confirming;
     private keyIndex;
+    private keyFieldIndex;
     private keyScroll;
     private keyFilter;
     private filteringKeys;
@@ -106,8 +107,10 @@ export declare class SetupWizard implements Component, Focusable {
     private buildSubmission;
     private finalize;
     private filteredKeybindings;
+    private selectedKeyRow;
     private selectedKeybinding;
     private moveKey;
+    private moveKeyField;
     private keyViewportLines;
     private keyPageSize;
     private beginKeyEdit;
@@ -129,7 +132,11 @@ export declare class SetupWizard implements Component, Focusable {
     private renderSystems;
     private renderExa;
     private renderConfirm;
-    private keyRowHasMessage;
+    private keyRowMessage;
+    /** Number of lines needed to keep the active paired field legible. A narrow
+     *  row stacks the action and field instead of sacrificing the action name,
+     *  selected-field identity, or value to fixed columns. */
+    private keyRowBodyLineCount;
     private keyLineCost;
     private renderKeybindings;
     private renderModels;