@north-light/crouter 0.3.208 → 0.3.210

package/dist/commands/sys/sync-project-guidance.js

@@ -1,8 +1,8 @@
 // `crtr sys sync project-guidance` — one-way migration of a project's own
 // CLAUDE.md/AGENTS.md/.claude/rules into that SAME directory's OWN
-// `.crouter/memory/`. Each project guide becomes the root INDEX front door;
-// rules retain their explicit path routes, or use the `.` route (workspace
-// mount + any file read beneath the store's owning dir) when they are pathless.
+// `.crouter/memory/`. Each project guide becomes the workspace front door
+// (workspace-open + ./** read entries); rules keep their explicit path routes
+// as read entries, or take the front-door pair when they are pathless.
 import { existsSync, readdirSync, statSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { defineLeaf } from '../../core/command.js';
@@ -218,9 +218,30 @@ function projectDocLabel(candidate) {
         .replace(/^\.$/, '');
     return relDir === '' ? rootLabel : normalizedName(`${rootLabel}/${relDir}`);
 }
+/** The surfaces pair every workspace front door carries: whole-doc delivery
+ *  when cwd/profile mounts the store, plus on any file read beneath the
+ *  store's owning dir. */
+function frontDoorSurfaces() {
+    return [
+        { on: 'workspace-open', at: 'content' },
+        { on: 'read', match: './**', at: 'content' },
+    ];
+}
+/** `./`-anchor a rule glob that could only match repo-relatively: any glob
+ *  containing `/` that starts with neither `/`, `**`, nor `./`. Mirrors the
+ *  surfaces migration's anchoring rule — this leaf MINTS new read globs, so it
+ *  must anchor them the same way or the routes it writes silently never fire. */
+function anchorReadGlob(g) {
+    const t = g.trim();
+    if (!t.includes('/'))
+        return t;
+    if (t.startsWith('/') || t.startsWith('**') || t.startsWith('./'))
+        return t;
+    return `./${t}`;
+}
 /** AGENTS.md/CLAUDE.md → `<sourceDir>/.crouter/memory/INDEX.md`, the
  *  workspace front door. Its explicit project identity keeps sibling roots
- *  distinct; system none/file content plus `applies-to: "."` puts the wholly
+ *  distinct; the workspace-open + ./** read entry pair puts the wholly
  *  important guide in first-message context when cwd/profile mounts the store,
  *  and surfaces it on any file read beneath the store's owning dir. */
 function prepareAgentsCandidate(candidate) {
@@ -231,9 +252,7 @@ function prepareAgentsCandidate(candidate) {
         name: docLabel,
         'when-and-why-to-read': `When working in ${docLabel}, this knowledge should be read because it is the project's operating guide.`,
         'short-form': synthesizeShortForm(body),
-        'system-prompt-visibility': 'none',
-        'file-read-visibility': 'content',
-        'applies-to': ['.'],
+        surfaces: frontDoorSurfaces(),
     };
     return {
         candidate,
@@ -244,9 +263,10 @@ function prepareAgentsCandidate(candidate) {
     };
 }
 /** `.claude/rules/<name>.md` → `<sourceDir>/.crouter/memory/<name>.md`. A
- *  `paths:` rule keeps its `applies-to` file globs at none/content; a pathless
- *  rule receives `applies-to: "."` and surfaces when the workspace opens or a
- *  file beneath the store's owning dir is read. Like the INDEX docs, each rule
+ *  `paths:` rule keeps its file globs as a `content` read entry (`./`-anchored
+ *  when repo-relative); a pathless rule takes the front-door pair and surfaces
+ *  when the workspace opens or a file beneath the store's owning dir is read.
+ *  Like the INDEX docs, each rule
  *  carries an explicit namespaced substrate name (`<root>/<subdir>/<leaf>`):
  *  without it the resolver falls back to the store-relative leaf, and two
  *  nested stores sharing a rule filename (e.g. apps/core and apps/gateway both
@@ -266,11 +286,11 @@ function prepareRuleCandidate(candidate) {
             ? routeFromDescription(description, 'knowledge')
             : `When working under ${dirLabel}, this knowledge should be read because it is migrated project rule guidance.`,
         'short-form': description !== '' ? description.replace(/\s+/g, ' ').trim() : synthesizeShortForm(parsed.body),
-        'system-prompt-visibility': 'none',
-        'file-read-visibility': 'content',
     };
-    const globs = normalizeRulePaths(fm['paths']);
-    frontmatter['applies-to'] = globs.length > 0 ? globs : ['.'];
+    const globs = normalizeRulePaths(fm['paths']).map(anchorReadGlob);
+    frontmatter['surfaces'] = globs.length > 0
+        ? [{ on: 'read', match: globs.length === 1 ? globs[0] : globs, at: 'content' }]
+        : frontDoorSurfaces();
     return {
         candidate,
         name,
@@ -321,7 +341,7 @@ function renderSummary(results) {
 export const sysSyncProjectGuidanceLeaf = defineLeaf({
     name: 'project-guidance',
     description: "migrate CLAUDE.md/AGENTS.md/.claude/rules into that directory's own crouter memory docs",
-    whenToUse: "migrating per-project CLAUDE.md/AGENTS.md/.claude/rules into the crouter memory-doc model: one-way copy into that same directory's OWN .crouter/memory/. The project guide becomes its root INDEX front door; path-scoped rules keep their globs and pathless rules open with the workspace. Never exports memory docs back to these source files.",
+    whenToUse: "migrating per-project CLAUDE.md/AGENTS.md/.claude/rules into the crouter memory-doc model: one-way copy into that same directory's OWN .crouter/memory/. The project guide becomes its workspace front door; path-scoped rules keep their globs as read entries and pathless rules open with the workspace. Never exports memory docs back to these source files.",
     help: {
         name: 'sys sync project-guidance',
         summary: "one-way migration: CLAUDE.md/AGENTS.md/.claude/rules → that dir's own crouter memory docs",
@@ -338,7 +358,7 @@ export const sysSyncProjectGuidanceLeaf = defineLeaf({
         ],
         outputKind: 'object',
         effects: [
-            "Copies each discovered CLAUDE.md/AGENTS.md into <dir>/.crouter/memory/INDEX.md with an explicit project name at system-prompt-visibility none, file-read-visibility content, and applies-to `.`. Copies each .claude/rules/*.md into <dir>/.crouter/memory/<name>.md at none/content, using the source paths as applies-to globs or `.` (workspace mount + reads beneath the owning dir) when no paths are declared. Originals are left untouched.",
+            "Copies each discovered CLAUDE.md/AGENTS.md into <dir>/.crouter/memory/INDEX.md with an explicit project name and the workspace front-door surfaces pair ({on: workspace-open, at: content} + {on: read, match: './**', at: content}). Copies each .claude/rules/*.md into <dir>/.crouter/memory/<name>.md with a content read entry over the source paths (‘./’-anchored when repo-relative), or the same front-door pair when no paths are declared. Originals are left untouched.",
             'Skips existing memory docs unless --overwrite is present.',
             'With --dry-run: read-only; writes nothing.',
         ],

package/dist/commands/sys/sync-skills.js

@@ -167,6 +167,12 @@ function convertPrepared(prepared, opts) {
     delete frontmatter.description;
     delete frontmatter.type;
     delete frontmatter.keywords;
+    // Retired visibility-axis fields a stale source may still carry — they must
+    // never pass through into a substrate doc.
+    delete frontmatter['system-prompt-visibility'];
+    delete frontmatter['file-read-visibility'];
+    delete frontmatter['applies-to'];
+    delete frontmatter['read-when'];
     frontmatter.kind = prepared.kind;
     if (typeof frontmatter['when-and-why-to-read'] !== 'string' || frontmatter['when-and-why-to-read'].trim() === '') {
         frontmatter['when-and-why-to-read'] = routeFromDescription(description, prepared.kind);
@@ -174,10 +180,8 @@ function convertPrepared(prepared, opts) {
     if (typeof frontmatter['short-form'] !== 'string' || frontmatter['short-form'].trim() === '') {
         frontmatter['short-form'] = description.replace(/\s+/g, ' ').trim();
     }
-    if (typeof frontmatter['system-prompt-visibility'] !== 'string')
-        frontmatter['system-prompt-visibility'] = 'preview';
-    if (typeof frontmatter['file-read-visibility'] !== 'string')
-        frontmatter['file-read-visibility'] = 'none';
+    if (!Array.isArray(frontmatter['surfaces']))
+        frontmatter['surfaces'] = [{ on: 'boot', at: 'preview' }];
     if (!opts.dryRun)
         writeText(prepared.target, serializeMemoryDoc(frontmatter, prepared.parsed.body));
     return {

package/dist/commands/sys.js

@@ -11,19 +11,20 @@ import { supportBranch } from './sys/support.js';
 import { sysSyspromptLeaf } from './sys/sysprompt.js';
 import { promptReviewLeaf } from './sys/prompt-review.js';
 import { sysSyncBranch } from './sys/sync.js';
+import { sysMigrateLeaf } from './sys/migrate.js';
 import { sysUpdateLeaf, sysVersionLeaf } from './sys/update.js';
 export function registerSys() {
     return defineBranch({
         name: 'sys',
         rootEntry: {
             concept: 'crtr configuration, diagnostics, and self-management',
-            desc: 'settings, config, setup, doctor, sysprompt, prompt-review, sync, update, version, feedback, logs, support, daemon',
+            desc: 'settings, config, setup, doctor, sysprompt, prompt-review, sync, migrate, update, version, feedback, logs, support, daemon',
             useWhen: 'managing the crtr installation, inspecting diagnostics, or operating the crtrd supervisor process',
         },
         help: {
             name: 'sys',
             summary: 'crtr system configuration, settings, diagnostics, and self-management',
         },
-        children: [sysSettingsLeaf, configBranch, sysSetupLeaf, sysDoctorLeaf, sysSyspromptLeaf, promptReviewLeaf, sysFeedbackLeaf, sysLogsLeaf, supportBranch, sysUpdateLeaf, sysVersionLeaf, sysSyncBranch, daemonBranch],
+        children: [sysSettingsLeaf, configBranch, sysSetupLeaf, sysDoctorLeaf, sysSyspromptLeaf, promptReviewLeaf, sysFeedbackLeaf, sysLogsLeaf, supportBranch, sysUpdateLeaf, sysVersionLeaf, sysMigrateLeaf, sysSyncBranch, daemonBranch],
     });
 }

package/dist/core/__tests__/inline-memory-refs.test.js

@@ -3,7 +3,7 @@
 // Load-bearing corpus regression for `buildRefInventory` — the authoritative
 // inventory the broker and terminal attach viewer both resolve inline memory
 // references against. Covers scope precedence dedup, referenceability
-// (both kinds, gated and slash docs), INDEX folding, malformed-doc omission,
+// (both kinds, gated and slash docs), directory browse names, malformed-doc omission,
 // metadata-only rows, and stable ordering, all over real on-disk fixtures.
 import { test, describe, before, beforeEach, after } from 'node:test';
 import assert from 'node:assert/strict';
@@ -17,7 +17,7 @@ import { buildRefInventory } from '../memory/inline-ref-inventory.js';
 // ---------------------------------------------------------------------------
 // Wave C4 — buildRefInventory: the authoritative corpus builder. Fixture-
 // backed (node/project/user scope docs on disk), since precedence dedup,
-// referenceability-ignores-gate/slash, and INDEX folding are all corpus-shape
+// referenceability-ignores-gate/slash, and directory browse names are all corpus-shape
 // facts that a pure in-memory test can't exercise. Fixture names are prefixed
 // to avoid any collision with the real shipped builtin/user corpus that
 // listAllMemoryDocs() also picks up in this environment.
@@ -128,12 +128,15 @@ describe('buildRefInventory (fixture-backed corpus)', () => {
         assert.equal(refs.find((r) => r.name === 'crtr-inline-ref-fixture-knowledge')?.kind, 'knowledge');
         assert.equal(refs.find((r) => r.name === 'crtr-inline-ref-fixture-preference')?.kind, 'preference');
     });
-    test('an INDEX doc folds to its bare directory name, not "<dir>/INDEX"', () => {
+    test('an INDEX doc keeps its canonical name; the bare dir name is a browse link, not a ref row', () => {
         writeDoc(join(projectMemoryDir(), 'crtr-inline-ref-fixture-taste'), 'INDEX.md', "kind: knowledge\nshort-form: 'taste index'");
         const { refs, names } = buildRefInventory();
+        assert.ok(names.has('crtr-inline-ref-fixture-taste/INDEX'));
+        // The directory name resolves as a listing link — in `names` for linkify,
+        // never a RefMeta row (no doc answers for a directory).
         assert.ok(names.has('crtr-inline-ref-fixture-taste'));
-        assert.ok(!names.has('crtr-inline-ref-fixture-taste/INDEX'));
-        const winner = refs.find((r) => r.name === 'crtr-inline-ref-fixture-taste');
+        assert.ok(!refs.some((r) => r.name === 'crtr-inline-ref-fixture-taste'));
+        const winner = refs.find((r) => r.name === 'crtr-inline-ref-fixture-taste/INDEX');
         assert.equal(winner?.shortForm, 'taste index');
     });
     test('a root INDEX doc is omitted, never exposed as an empty ref name', () => {

package/dist/core/__tests__/memory-resolver-precedence.test.js

@@ -128,13 +128,14 @@ test('a plain path-named doc with no explicit name resolves to the nearest copy'
         process.chdir(prevCwd);
     }
 });
-test('a bare-directory query resolves to that dir\'s INDEX.md, nearest copy first', () => {
+test('a bare-directory query does not resolve to a doc — directories answer with listings, not INDEX.md', () => {
     process.chdir(child);
     resetScopeCache();
     try {
-        const doc = resolveMemoryDoc('taste');
-        assert.equal(doc.path, join(child, '.crouter', 'memory', 'taste', 'INDEX.md'));
-        assert.match(doc.body, /CHILD TASTE INDEX/);
+        assert.throws(() => resolveMemoryDoc('taste'), (err) => {
+            assert.equal(err.code, 'not_found');
+            return true;
+        });
     }
     finally {
         process.chdir(prevCwd);

package/dist/core/__tests__/nested-store-discovery.test.js

@@ -76,9 +76,7 @@ test('resolveMemoryDocForTarget resolves a nested doc only with includeDescendan
     mkdirSync(nestedMemory, { recursive: true });
     writeFileSync(join(nestedMemory, 'guide.md'), '---\nkind: knowledge\n' +
         'name: nested-guide\n' +
-        'when-and-why-to-read: When working in sub, this knowledge should be read because it carries the subsystem constraints.\n' +
-        'system-prompt-visibility: none\n' +
-        'file-read-visibility: none\n---\n' +
+        'when-and-why-to-read: When working in sub, this knowledge should be read because it carries the subsystem constraints.\n---\n' +
         'NESTED GUIDE BODY\n');
     const target = { cwd: proj, profileId: null, nodeId: null };
     assert.throws(() => resolveMemoryDocForTarget('nested-guide', target, {}), (e) => e instanceof CrtrError && e.code === 'not_found', 'without the opt-in the flat ancestor stack does not see the nested store');

package/dist/core/__tests__/on-read-crouter-home-fence.test.js

@@ -50,15 +50,15 @@ test('a store nested in the crouter home does not leak into a canvas-artifact re
     mkdirSync(leakedStore, { recursive: true });
     writeFileSync(join(leakedStore, 'private-thing.md'), '---\nkind: knowledge\n' +
         "when-and-why-to-read: When X, read this because Y.\n" +
-        'file-read-visibility: content\n' +
-        'applies-to: "**/*.md"\n---\n' +
+        'surfaces:\n' +
+        '  - {on: read, match: "**/*.md", at: content}\n---\n' +
         'PRIVATE ASSISTANT MEMORY MUST NOT LEAK\n');
     // A canvas runtime artifact under the crouter home — the shape of every node
     // report/context file the harness auto-reads.
     const reportFile = join(fakeHome, '.crouter', 'canvas', 'nodes', 'somenode', 'reports', 'r.md');
     mkdirSync(join(fakeHome, '.crouter', 'canvas', 'nodes', 'somenode', 'reports'), { recursive: true });
     writeFileSync(reportFile, '# a node report\n');
-    const rendered = renderOnReadDocs(node, reportFile, new Set());
+    const rendered = renderOnReadDocs(node, reportFile, new Map());
     assert.ok(!rendered.includes('PRIVATE ASSISTANT MEMORY MUST NOT LEAK'), `crouter-home-nested store must not surface on a canvas read; got: ${rendered}`);
     assert.ok(!rendered.includes('private-thing'), `crouter-home-nested store name must not surface on a canvas read; got: ${rendered}`);
 });

package/dist/core/__tests__/on-read-dedup-resume.test.js

@@ -45,7 +45,7 @@ after(() => {
     else
         process.env['HOME'] = prevHomeEnv;
 });
-test('project and user memory docs without applies-to do not fire on file reads', () => {
+test('project and user memory docs without read surfaces do not fire on file reads', () => {
     const fakeHome = mkdtempSync(join(tmpdir(), 'crtr-onread-user-home-'));
     process.env['HOME'] = fakeHome;
     resetScopeCache();
@@ -53,18 +53,16 @@ test('project and user memory docs without applies-to do not fire on file reads'
     const userMemDir = join(fakeHome, '.crouter', 'memory');
     mkdirSync(userMemDir, { recursive: true });
     writeFileSync(join(userMemDir, 'noisy-global.md'), '---\nkind: preference\n' +
-        'when-and-why-to-read: When reading any file, this preference should be read because this fixture must not fire without an explicit route\n' +
-        'file-read-visibility: content\n---\n' +
+        'when-and-why-to-read: When reading any file, this preference should be read because this fixture must not fire without an explicit route\n---\n' +
         'NOISY USER BODY\n');
     const projectMemDir = join(fakeHome, 'work', '.crouter', 'memory');
     mkdirSync(projectMemDir, { recursive: true });
     writeFileSync(join(projectMemDir, 'local.md'), '---\nkind: knowledge\n' +
-        'when-and-why-to-read: When reading project files, this reference should be read because this fixture proves explicit file routing\n' +
-        'file-read-visibility: content\n---\n' +
+        'when-and-why-to-read: When reading project files, this reference should be read because this fixture proves explicit file routing\n---\n' +
         'LOCAL PROJECT BODY\n');
     const readFile = join(fakeHome, 'work', 'ideas.md');
     writeFileSync(readFile, 'turn off xml closer\n');
-    const rendered = renderOnReadDocs(node, readFile, new Set());
+    const rendered = renderOnReadDocs(node, readFile, new Map());
     assert.ok(!rendered.includes('NOISY USER BODY'), 'user-global doc has no explicit file route');
     assert.ok(!rendered.includes('LOCAL PROJECT BODY'), 'project doc also has no implicit file route');
     assert.equal(rendered, '', 'no file context renders without an explicit trigger');
@@ -72,13 +70,15 @@ test('project and user memory docs without applies-to do not fire on file reads'
 });
 test('on-read doc surfaces once, stays deduped across a revive(resume), re-surfaces after a fresh launch', () => {
     const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
-    // A file-routed substrate doc in a `.crouter/memory/` ancestor.
+    // A file-routed substrate doc in a `.crouter/memory/` ancestor. The
+    // `./`-anchored glob pins the repo-relative anchor: `src/file.ts` matches
+    // only relative to the doc's owning repo dir, never absolutely.
     const memDir = join(work, '.crouter', 'memory');
     mkdirSync(memDir, { recursive: true });
     writeFileSync(join(memDir, 'onread-fixture.md'), '---\nkind: knowledge\n' +
         'when-and-why-to-read: When reading work files, this reference should be read because it is the on-read regression fixture\n' +
-        'file-read-visibility: content\n' +
-        'applies-to: "src/**"\n---\n' +
+        'surfaces:\n' +
+        '  - {on: read, match: "./src/**", at: content}\n---\n' +
         `${FIXTURE_BODY}\n`);
     const readFile = join(work, 'src', 'file.ts');
     mkdirSync(join(work, 'src'), { recursive: true });
@@ -106,13 +106,13 @@ test('an explicitly routed doc injects on-read under its frontmatter name, not t
     writeFileSync(join(memDir, 'physical-guide.md'), '---\nkind: knowledge\n' +
         'name: acme-project\n' +
         'when-and-why-to-read: When reading acme source, this knowledge should be read because it carries the project-specific implementation constraints.\n' +
-        'file-read-visibility: content\n' +
-        'applies-to: "src/**"\n---\n' +
+        'surfaces:\n' +
+        '  - {on: read, match: "./src/**", at: content}\n---\n' +
         'ACME PROJECT OPERATING GUIDE\n');
     const readFile = join(work, 'src', 'file.ts');
     mkdirSync(join(work, 'src'), { recursive: true });
     writeFileSync(readFile, 'export const x = 1;\n');
-    const rendered = renderOnReadDocs(node, readFile, new Set());
+    const rendered = renderOnReadDocs(node, readFile, new Map());
     assert.ok(rendered.includes('ACME PROJECT OPERATING GUIDE'), 'the matching explicit route fires');
     assert.ok(rendered.includes('<memory kind="knowledge" name="acme-project"'), `expected explicit frontmatter name "acme-project" in the injected envelope, got: ${rendered}`);
     assert.ok(!rendered.includes('name="physical-guide"'), 'must not fall back to the path-derived name when frontmatter sets one');

package/dist/core/__tests__/on-read-nested-store.test.js

@@ -1,9 +1,9 @@
 // A `.crouter/memory` store nested BELOW a mounted project root is delivered
-// by the read path, not by boot: its `.`-routed docs surface on the first read
-// beneath the store's owning dir, deduplicated against the workspace-open
-// render through the shared transcript dedup set. The `.` route stays fenced
-// to project-store docs — a hand-authored `.` in a user-scope doc must never
-// match a read.
+// by the read path, not by boot: its `./**`-routed docs surface on the first
+// read beneath the store's owning dir, deduplicated against the
+// workspace-open render through the shared transcript dedup set. The `./`
+// anchor stays fenced to project-store docs — a hand-authored `./` glob in a
+// user-scope doc must never match a read.
 //
 // Run: node --import tsx/esm --test src/core/__tests__/on-read-nested-store.test.ts
 import { test, before, beforeEach, after } from 'node:test';
@@ -45,22 +45,25 @@ after(() => {
         process.env['HOME'] = prevHomeEnv;
 });
 /** A work tree with a root front door and a nested store front door, both
- *  routed `.`. Returns the work dir. */
+ *  carrying the explicit front-door pair (workspace-open + `./**` read).
+ *  Returns the work dir. */
 function makeWorkTree() {
     const work = join(fakeHome, 'work');
     const rootStore = join(work, '.crouter', 'memory');
     mkdirSync(rootStore, { recursive: true });
     writeFileSync(join(rootStore, 'INDEX.md'), '---\nkind: knowledge\n' +
         'when-and-why-to-read: When working in this workspace, this knowledge should be read because it is the operating guide.\n' +
-        'file-read-visibility: content\n' +
-        'applies-to: "."\n---\n' +
+        'surfaces:\n' +
+        '  - {on: workspace-open, at: content}\n' +
+        '  - {on: read, match: "./**", at: content}\n---\n' +
         `${ROOT_BODY}\n`);
     const nestedStore = join(work, 'pkg', '.crouter', 'memory');
     mkdirSync(nestedStore, { recursive: true });
     writeFileSync(join(nestedStore, 'INDEX.md'), '---\nkind: knowledge\n' +
         'when-and-why-to-read: When working in pkg, this knowledge should be read because it carries the package constraints.\n' +
-        'file-read-visibility: content\n' +
-        'applies-to: "."\n---\n' +
+        'surfaces:\n' +
+        '  - {on: workspace-open, at: content}\n' +
+        '  - {on: read, match: "./**", at: content}\n---\n' +
         `${NESTED_BODY}\n`);
     return work;
 }
@@ -70,18 +73,18 @@ test('a nested store front door surfaces on a read beneath its owning dir, not o
     const inside = join(work, 'pkg', 'lib', 'file.ts');
     mkdirSync(join(work, 'pkg', 'lib'), { recursive: true });
     writeFileSync(inside, 'export const x = 1;\n');
-    const rendered = renderOnReadDocs(node, inside, new Set());
+    const rendered = renderOnReadDocs(node, inside, new Map());
     assert.ok(rendered.includes(NESTED_BODY), `read beneath pkg surfaces the nested front door; got: ${rendered}`);
     const outside = join(work, 'docs', 'notes.ts');
     mkdirSync(join(work, 'docs'), { recursive: true });
     writeFileSync(outside, 'export const y = 2;\n');
-    const renderedOutside = renderOnReadDocs(node, outside, new Set());
+    const renderedOutside = renderOnReadDocs(node, outside, new Map());
     assert.ok(!renderedOutside.includes(NESTED_BODY), `read outside pkg must not surface the nested front door; got: ${renderedOutside}`);
 });
 test('workspace-open and on-read share one dedup set: root front door once, nested store on first read beneath it', () => {
     const work = makeWorkTree();
     const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
-    const seen = new Set();
+    const seen = new Map();
     const opened = renderWorkspaceOpenDocs(node, seen);
     assert.ok(opened.includes(ROOT_BODY), 'workspace open delivers the mounted root front door');
     assert.ok(!opened.includes(NESTED_BODY), 'boot stays flat: the nested store is not in the mounted stack');
@@ -92,18 +95,18 @@ test('workspace-open and on-read share one dedup set: root front door once, nest
     assert.ok(onRead.includes(NESTED_BODY), 'the nested front door delivers on the first read beneath it');
     assert.ok(!onRead.includes(ROOT_BODY), 'the root front door already delivered at workspace open — never twice');
 });
-test('a hand-authored `.` route in a user-scope doc never matches a read', () => {
+test('a hand-authored `./`-anchored read glob in a user-scope doc never matches a read', () => {
     const userStore = join(fakeHome, '.crouter', 'memory');
     mkdirSync(userStore, { recursive: true });
     writeFileSync(join(userStore, 'control.md'), '---\nkind: knowledge\n' +
         'when-and-why-to-read: When reading markdown, this knowledge should be read because it is the corpus-loaded control fixture.\n' +
-        'file-read-visibility: content\n' +
-        'applies-to: "**/*.md"\n---\n' +
+        'surfaces:\n' +
+        '  - {on: read, match: "**/*.md", at: content}\n---\n' +
         'USER CONTROL BODY\n');
     writeFileSync(join(userStore, 'dot-routed.md'), '---\nkind: knowledge\n' +
         'when-and-why-to-read: When anything, this knowledge should be read because it must never fire.\n' +
-        'file-read-visibility: content\n' +
-        'applies-to: "."\n---\n' +
+        'surfaces:\n' +
+        '  - {on: read, match: "./**", at: content}\n---\n' +
         'USER DOT BODY MUST NOT FIRE\n');
     const work = join(fakeHome, 'work');
     mkdirSync(work, { recursive: true });
@@ -111,7 +114,7 @@ test('a hand-authored `.` route in a user-scope doc never matches a read', () =>
     const readFile = join(fakeHome, 'notes', 'thing.md');
     mkdirSync(join(fakeHome, 'notes'), { recursive: true });
     writeFileSync(readFile, '# a note\n');
-    const rendered = renderOnReadDocs(node, readFile, new Set());
+    const rendered = renderOnReadDocs(node, readFile, new Map());
     assert.ok(rendered.includes('USER CONTROL BODY'), 'the glob-routed user doc proves the user store is in the corpus');
-    assert.ok(!rendered.includes('USER DOT BODY MUST NOT FIRE'), `the \`.\` route is project-store only — a user doc's owning root is ~; got: ${rendered}`);
+    assert.ok(!rendered.includes('USER DOT BODY MUST NOT FIRE'), `the \`./\` anchor is project-store only — a user doc's owning root is ~; got: ${rendered}`);
 });

package/dist/core/canvas/db.d.ts

@@ -1,6 +1,8 @@
 import { DatabaseSync } from 'node:sqlite';
 /** The ordered migration list. Index `i` is migration version `i + 1`; the db's
- *  `user_version` tracks how many have been applied. Append only. */
+ *  `user_version` tracks how many have been applied. Append only. Journaled
+ *  entries from `src/migrations/registry.ts` follow the local steps, so a new
+ *  registry migration lands as the next version. */
 export declare const MIGRATIONS: ReadonlyArray<(db: DatabaseSync) => void>;
 /** Bring `db` up to the latest schema version. Reads `user_version`, runs each
  *  pending migration in order, and bumps `user_version` after each so the work

package/dist/core/canvas/db.js

@@ -7,7 +7,8 @@
 import { DatabaseSync } from 'node:sqlite';
 import { existsSync, readFileSync, readdirSync, appendFileSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
-import { canvasDbPath, ensureHome, isSafeNodeId, nodesRoot, nodeMetaPath } from './paths.js';
+import { canvasDbPath, crtrHome, ensureHome, isSafeNodeId, nodesRoot, nodeMetaPath } from './paths.js';
+import { STATE_MIGRATIONS } from '../../migrations/registry.js';
 import { customExtensionPaths } from './extensions.js';
 import { updateJsonFileDurably } from './meta-file.js';
 // --- Schema as a forward-only migration list ------------------------------
@@ -1152,8 +1153,16 @@ ALTER TABLE crons ADD COLUMN held INTEGER NOT NULL DEFAULT 0;
 ALTER TABLE crons ADD COLUMN last_poke_at TEXT;
 `);
 }
+/** The journaled lane of the state-migration registry, adapted to this chain's
+ *  step shape. Registry order is preserved, so these versions stay stable as
+ *  long as the registry is append-only (same contract as the local list). */
+const JOURNALED_STATE_MIGRATIONS = STATE_MIGRATIONS
+    .filter((m) => m.lane === 'journaled')
+    .map((m) => (db) => m.apply(db, crtrHome()));
 /** The ordered migration list. Index `i` is migration version `i + 1`; the db's
- *  `user_version` tracks how many have been applied. Append only. */
+ *  `user_version` tracks how many have been applied. Append only. Journaled
+ *  entries from `src/migrations/registry.ts` follow the local steps, so a new
+ *  registry migration lands as the next version. */
 export const MIGRATIONS = [
     /* v1 */ baselineSchema,
     /* v2 */ addRuntimeColumns,
@@ -1189,6 +1198,7 @@ export const MIGRATIONS = [
     /* v30 */ dropConsultOutbox,
     /* v31 */ addReviewSubmitRequested,
     /* v32 */ addCronHeldColumns,
+    ...JOURNALED_STATE_MIGRATIONS,
 ];
 /** Migration indexes that manage their OWN transaction and therefore must not
  *  be wrapped by `migrate()` — `node:sqlite` rejects a nested BEGIN. Index 3

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

@@ -4,13 +4,15 @@
  *  rule of its own. */
 export declare const HISTORY_DIR = ".history";
 /** File operations only — deliberately not a review lifecycle. */
-export type HistoryOp = 'create' | 'edit' | 'delete';
+export type HistoryOp = 'create' | 'edit' | 'delete' | 'move';
 export interface HistoryRecord {
     op: HistoryOp;
     at: string;
     /** Authoring node id; absent for a human at a bare CLI. */
     node?: string;
     cwd: string;
+    /** The canonical name this document answered to before a `move`; absent otherwise. */
+    from?: string;
     /** Why this revision happened. Required on `edit`, absent otherwise. */
     rationale?: string;
     /** True when the body was declared a verbatim payload from the principal. */
@@ -29,6 +31,7 @@ export declare function historyLogPathFor(memoryRoot: string, docPath: string):
  *  serialized key order — the on-disk shape consumers read. */
 export declare function buildHistoryRecord(input: {
     op: HistoryOp;
+    from?: string;
     rationale?: string;
     verbatim?: boolean;
     before: string;

package/dist/core/memory/history.js

@@ -40,6 +40,7 @@ export function buildHistoryRecord(input) {
         at: new Date().toISOString(),
         ...(env['CRTR_NODE_ID'] ? { node: env['CRTR_NODE_ID'] } : {}),
         cwd: env['CRTR_NODE_CWD'] ?? process.cwd(),
+        ...(input.from !== undefined ? { from: input.from } : {}),
         ...(input.rationale !== undefined ? { rationale: input.rationale } : {}),
         ...(input.verbatim === true ? { verbatim: true } : {}),
         before: input.before,

package/dist/core/memory/inline-ref-inventory.d.ts

@@ -2,10 +2,11 @@ import type { RefMeta } from '../runtime/broker-protocol.js';
 /**
  * Build the inline memory-reference inventory: every referenceable document
  * in this node's corpus, precedence-deduped first-wins by canonical name,
- * both kinds, no gate/rung/`slash` filtering, INDEX docs folded to their bare
- * directory name. Returns display metadata (`refs`, stably sorted by winning
- * scope then name) plus the resolution set (`names`) that both the broker's
- * per-submission resolver and `buildGuidance` test tokens against.
+ * both kinds, no gate/rung/`slash` filtering. Returns display metadata
+ * (`refs`, stably sorted by winning scope then name) plus the resolution set
+ * (`names` — doc names plus every proper directory prefix, because a bare-dir
+ * ref is a legal listing link) that both the broker's per-submission resolver
+ * and `buildGuidance` test tokens against.
  */
 export declare function buildRefInventory(): {
     refs: RefMeta[];

package/dist/core/memory/inline-ref-inventory.js

@@ -18,8 +18,10 @@
 //     automatic boot/on-read surfacing only (spec §7.1), and `slash` governs
 //     command registration only (spec §4.3). An explicit human reference
 //     outranks both.
-//   • A directory's INDEX doc folds to its bare directory name (`taste`, not
-//     `taste/INDEX`), matching what `crtr memory read taste` accepts.
+//   • Directory names are referenceable too: a bare-dir `[[ref]]` opens the
+//     directory's listing through `crtr memory read <dir>`, so every proper
+//     name-prefix of a winning doc joins the resolution set — resolution
+//     only, never a display row.
 //   • A malformed doc (no valid `kind`) is already dropped by
 //     `parseSubstrateDoc` returning null, so it never reaches the winners map.
 //
@@ -29,7 +31,6 @@
 // cache it reads through.
 import { listAllMemoryDocs } from '../memory-resolver.js';
 import { parseSubstrateDoc } from '../substrate/schema.js';
-import { displayName } from '../substrate/ceiling.js';
 import { cachedSubstrateDocsInclusive } from '../substrate/session-cache.js';
 // Display-sort weight matching resolution precedence (node > project >
 // profile > user > builtin) — display-only; resolution itself is
@@ -44,26 +45,21 @@ const SCOPE_SORT_RANK = {
 /**
  * Build the inline memory-reference inventory: every referenceable document
  * in this node's corpus, precedence-deduped first-wins by canonical name,
- * both kinds, no gate/rung/`slash` filtering, INDEX docs folded to their bare
- * directory name. Returns display metadata (`refs`, stably sorted by winning
- * scope then name) plus the resolution set (`names`) that both the broker's
- * per-submission resolver and `buildGuidance` test tokens against.
+ * both kinds, no gate/rung/`slash` filtering. Returns display metadata
+ * (`refs`, stably sorted by winning scope then name) plus the resolution set
+ * (`names` — doc names plus every proper directory prefix, because a bare-dir
+ * ref is a legal listing link) that both the broker's per-submission resolver
+ * and `buildGuidance` test tokens against.
  */
 export function buildRefInventory() {
     const docs = cachedSubstrateDocsInclusive(listAllMemoryDocs, parseSubstrateDoc);
-    // First-wins by canonical (INDEX-folded) name: docs arrive already in
-    // precedence order (listAllMemoryDocs' nearest-first source ordering), so
-    // the first doc seen for a name is the winner.
+    // First-wins by canonical name: docs arrive already in precedence order
+    // (listAllMemoryDocs' nearest-first source ordering), so the first doc seen
+    // for a name is the winner.
     const winners = new Map();
     for (const doc of docs) {
-        const name = displayName(doc.name);
-        // A root INDEX folds to '' (no bare-directory token exists for it) and
-        // has no other nonempty canonical identity in this corpus, so it has
-        // no inline token to offer — omit it rather than expose `name: ''`.
-        if (name === '')
-            continue;
-        if (!winners.has(name))
-            winners.set(name, doc);
+        if (!winners.has(doc.name))
+            winners.set(doc.name, doc);
     }
     const refs = [];
     for (const [name, doc] of winners) {
@@ -75,5 +71,13 @@ export function buildRefInventory() {
             return scopeDelta;
         return a.name.localeCompare(b.name);
     });
-    return { refs, names: new Set(refs.map((r) => r.name)) };
+    const names = new Set(refs.map((r) => r.name));
+    // Directory names resolve as listing links, so they join the set — but not
+    // the display rows: a dir has no kind/short-form to show.
+    for (const name of winners.keys()) {
+        const segs = name.split('/');
+        for (let i = 1; i < segs.length; i++)
+            names.add(segs.slice(0, i).join('/'));
+    }
+    return { refs, names };
 }

package/dist/core/memory-resolver.d.ts

@@ -5,8 +5,8 @@ import { type InstalledPlugin, type Scope } from '../types.js';
  * stack nearest > ... > profile > user > builtin) for strong matches: (1) exact
  * substrate identity (`doc.name === query` — the explicit frontmatter `name`,
  * or its path-derived fallback), then (2) direct `memory/<name>.md` physical
- * path (plus the bare-dir/bare-plugin-name → `INDEX.md` convenience neither
- * identity nor a literal path expresses). Only when no source has a strong
+ * path. A directory name resolves to NO doc — the read leaf answers it with
+ * the directory's listing. Only when no source has a strong
  * match does a second nearest-first pass try bare leaf-name fallback (final
  * path segment only). Thus scope precedence resolves competing strong matches,
  * while a nearer nested doc's coincidental leaf can never shadow a farther
@@ -123,8 +123,8 @@ export declare function listAllMemoryDocs(scope?: MemoryScope, quiet?: boolean,
  *  tree segment for segment with `.jsonl` in place of `.md`. Reuses the doc
  *  resolution rules so a log outlives its doc under the same name the doc had:
  *  numeric prefixes stay prefix-blind (`00-topic.md` logged at
- *  `.history/00-topic.jsonl` still answers to `topic`) and a bare directory
- *  name falls back to its INDEX log. Returns null when nothing resolves. */
+ *  `.history/00-topic.jsonl` still answers to `topic`). Returns null when
+ *  nothing resolves. */
 export declare function resolveHistoryLogPath(historyDir: string, segments: string[]): string | null;
 export interface MemoryDocSnapshot {
     /** Every document in default scope precedence order, loaded once. */