@crouton-kit/crouter 0.3.49 → 0.3.51

package/dist/commands/human/prompts.js

@@ -36,7 +36,7 @@ export const humanAsk = defineLeaf({
     help: {
         name: 'human ask',
         summary: 'put a humanloop decision deck in front of a person; returns a job handle immediately. This is the default, expected channel for posing ANY question or decision to the user — reach for it instead of writing the question as prose in your reply.',
-        guide: 'Use exactly one of these forms: `crtr human ask "<question>"` for a simple open-text prompt (the CLI builds a one-item humanloop deck internally), or `crtr human ask --context-file deck.json` for a fully structured deck. The kickoff is instant and NEVER blocks — "never block on the result" refers only to not busy-waiting on the job; the human answering on their own time is not a reason to avoid asking or to fall back to inline prose. The deck body is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one.',
+        guide: 'Use exactly one of these forms: `crtr human ask "<question>"` for a simple open-text prompt (the CLI builds a one-item humanloop deck internally), or `crtr human ask --context-file deck.json` for a fully structured deck. The kickoff is instant and NEVER blocks — "never block on the result" refers only to not busy-waiting on the job; the human answering on their own time is not a reason to avoid asking or to fall back to inline prose. The deck body is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one. Author a GOOD deck: ask only what materially changes your next step (each question spends the human\'s attention), offer genuine alternatives as `options` (not one real pick plus filler), and layer content by progressive disclosure — `title` a short topic, `subtitle` the one-sentence TL;DR, `body` the plain-language detail with denser material under a `## Details` heading the reader can skip.',
         params: [
             { kind: 'positional', name: 'question', type: 'string', required: false, constraint: 'Bare-question shorthand for a simple open-text ask. Mutually exclusive with `--context-file`.' },
             { kind: 'context-file', name: 'deck', required: false, constraint: 'Strict complex-ask deck JSON. Use this when you need multiple interactions, options, or other deck structure. Mutually exclusive with the question shorthand.', shape: DECK_SCHEMA_HINT },

package/dist/commands/memory/write.js

@@ -12,7 +12,9 @@ export const writeLeaf = defineLeaf({
         summary: 'create or update memory/<name>.md at the resolved scope from frontmatter flags + a stdin body',
         guide: 'The body is the easy part; the craft is routing — every frontmatter flag decides who sees this doc, when, and at what context cost. Each rung up is paid by every future agent at every boot or read, forever, so default each rung down.\n\n' +
             'Pick the kind. knowledge is consulted for facts or procedures; preference directs behavior. The kind choice is about how the doc is used, not about how long it is.\n\n' +
+            '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. When unsure, choose the narrowest scope that will still reach the next agent who needs it.\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' +
             'Write the routing line (--when-and-why-to-read) first, before storing anything: "When <circumstance>, this <kind> should be read because <payoff>." The test is whether a stranger mid-task can decide from that one line alone whether to spend the read. 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. Never paraphrase the advice in the routing line; keep it about when to read and why the read is worth it.\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' +

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

@@ -8,25 +8,46 @@
 // Run: node --import tsx/esm --test src/commands/sys/__tests__/sync-import.test.ts
 import { afterEach, beforeEach, test } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync, existsSync, realpathSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { sysSyncLeaf } from '../sync.js';
+import { createNode } from '../../../core/canvas/canvas.js';
+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.js';
+import { clearSessionCache } from '../../../core/substrate/session-cache.js';
+import { sysSyncLeaf } from '../sync.js';
 function git(args, cwd) {
     const res = gitSync(args, cwd);
     if (res.status !== 0)
         throw new Error(`git ${args.join(' ')} failed in ${cwd}: ${res.stderr || res.stdout}`);
 }
+function node(id, cwd) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd,
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+    };
+}
 let home;
 let prevHome;
 beforeEach(() => {
+    closeDb();
+    clearSessionCache();
     prevHome = process.env.HOME;
     home = mkdtempSync(join(tmpdir(), 'crtr-sys-sync-'));
     process.env.HOME = home;
 });
 afterEach(() => {
+    closeDb();
+    clearSessionCache();
     if (prevHome === undefined)
         delete process.env.HOME;
     else
@@ -49,6 +70,21 @@ test('imports a SKILL.md bundle as a plain crouter memory doc', async () => {
     assert.equal(parsed.data?.['when-and-why-to-read'], 'When demo work appears, this knowledge should be read because handles demos.');
     assert.match(parsed.body, /Do the demo\./);
 });
+test('skips SKILL.md files vendored under node_modules while still importing a top-level authored SKILL.md', async () => {
+    const sourceRoot = join(home, 'repo');
+    const vendored = join(sourceRoot, 'node_modules', '@tanstack', 'some-pkg');
+    mkdirSync(vendored, { recursive: true });
+    writeFileSync(join(vendored, 'SKILL.md'), '---\nname: Vendored Skill\ndescription: Should never be imported.\n---\n\n# Vendored\n', 'utf8');
+    const authored = join(sourceRoot, 'my-skill');
+    mkdirSync(authored, { recursive: true });
+    writeFileSync(join(authored, 'SKILL.md'), '---\nname: My Skill\ndescription: Handles the real thing. Use when real work appears.\n---\n\n# Real\n\nDo the real thing.\n', 'utf8');
+    const result = await sysSyncLeaf.run({ source: sourceRoot, scope: 'user' });
+    assert.equal(result?.imported, 1);
+    assert.equal(existsSync(join(home, '.crouter', 'memory', 'vendored-skill.md')), false);
+    assert.equal(existsSync(join(home, '.crouter', 'memory', 'my-skill.md')), true);
+    const rows = (result?.results).map((r) => r.source);
+    assert.ok(!rows.some((s) => s.includes('node_modules')));
+});
 test('skips generated crtr boot skills instead of importing them', async () => {
     const bundle = join(home, '.pi', 'agent', 'skills', 'crtr-skills');
     mkdirSync(bundle, { recursive: true });
@@ -97,9 +133,19 @@ test('migrates CLAUDE.md and a .claude/rules file into that dir\'s own .crouter/
     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 prevCwd = process.cwd();
+    process.chdir(source);
+    try {
+        assert.equal(resolveMemoryDoc('demo-project').path, realpathSync(agentsTarget));
+        assert.equal(resolveMemoryDoc('demo-project').name, 'demo-project');
+    }
+    finally {
+        process.chdir(prevCwd);
+    }
     const ruleDoc = parseFrontmatterGeneric(readFileSync(ruleTarget, 'utf8'));
     assert.equal(ruleDoc.data?.kind, 'knowledge');
     assert.equal(ruleDoc.data?.['system-prompt-visibility'], 'none');
@@ -148,6 +194,113 @@ test('routes the walk-root AGENTS.md doc by the real git repo name, not a worktr
     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 () => {
+    const base = mkdtempSync(join(tmpdir(), 'crtr-sys-sync-purview-'));
+    const rootA = join(base, 'alpha-root');
+    const rootB = join(base, 'beta-root');
+    mkdirSync(rootA, { recursive: true });
+    mkdirSync(rootB, { recursive: true });
+    writeFileSync(join(rootA, 'CLAUDE.md'), '# Alpha Root\n\nAlpha body.\n', 'utf8');
+    writeFileSync(join(rootB, 'CLAUDE.md'), '# Beta Root\n\nBeta body.\n', 'utf8');
+    await sysSyncLeaf.run({ source: rootA });
+    await sysSyncLeaf.run({ source: rootB });
+    const profileId = 'purview-b7a4d1f0';
+    const profileDir = join(home, '.crouter', 'profiles', profileId);
+    mkdirSync(profileDir, { recursive: true });
+    writeFileSync(join(profileDir, 'profile.json'), JSON.stringify({ name: 'purview-pair', projects: [rootA, rootB], created_at: new Date().toISOString() }, null, 2) + '\n', 'utf8');
+    const runDir = join(base, 'run');
+    mkdirSync(runDir, { recursive: true });
+    const prevCwd = process.cwd();
+    const prevProfileId = process.env.CRTR_PROFILE_ID;
+    try {
+        process.env.CRTR_PROFILE_ID = profileId;
+        process.chdir(runDir);
+        clearSessionCache();
+        const alphaDoc = resolveMemoryDoc('alpha-root');
+        assert.equal(alphaDoc.path, join(rootA, '.crouter', 'memory', 'AGENTS.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.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');
+    }
+    finally {
+        process.chdir(prevCwd);
+        if (prevProfileId === undefined)
+            delete process.env.CRTR_PROFILE_ID;
+        else
+            process.env.CRTR_PROFILE_ID = prevProfileId;
+    }
+    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 () => {
+    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');
+    mkdirSync(nestedDir, { recursive: true });
+    writeFileSync(join(nestedDir, 'AGENTS.md'), '# Widgets Package\n\nNested guidance.\n', 'utf8');
+    const result = await sysSyncLeaf.run({ source });
+    const projectRows = (result?.results).filter((row) => row.target.includes('.crouter/memory'));
+    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 rootDoc = parseFrontmatterGeneric(readFileSync(rootTarget, 'utf8'));
+    const nestedDoc = parseFrontmatterGeneric(readFileSync(nestedTarget, 'utf8'));
+    assert.equal(rootDoc.data?.name, 'nested-demo');
+    assert.equal(nestedDoc.data?.name, 'nested-demo/packages/widgets');
+    assert.notEqual(rootDoc.data?.name, nestedDoc.data?.name, 'root and nested identities never collide');
+    assert.match(rootDoc.body, /Root guidance\./);
+    assert.match(nestedDoc.body, /Nested guidance\./);
+    const prevCwd = process.cwd();
+    try {
+        process.chdir(nestedDir);
+        clearSessionCache();
+        const resolved = resolveMemoryDoc('nested-demo/packages/widgets');
+        assert.equal(resolved.path, realpathSync(nestedTarget), 'resolveMemoryDoc finds a migrated nested doc by its explicit slashed identity');
+        assert.equal(resolved.name, 'nested-demo/packages/widgets');
+        assert.match(resolved.body, /Nested guidance\./);
+    }
+    finally {
+        process.chdir(prevCwd);
+    }
+    rmSync(source, { recursive: true, force: true });
+});
+test('a nested project-subdir doc migrated when --source POINTS AT THE NESTED DIR ITSELF still gets a suffix-qualified, non-colliding name', async () => {
+    // A nested doc's name suffix is computed against the git worktree top-level,
+    // not the supplied walk root, so `--source <nested-dir>` still yields a
+    // qualified, non-colliding name even when the walk starts at the nested dir.
+    const base = mkdtempSync(join(tmpdir(), 'crtr-sys-sync-nested-source-'));
+    const repoRoot = join(base, 'demo-repo');
+    mkdirSync(repoRoot, { recursive: true });
+    git(['init', '-b', 'main'], repoRoot);
+    git(['config', 'user.email', 'test@example.com'], repoRoot);
+    git(['config', 'user.name', 'Test'], repoRoot);
+    writeFileSync(join(repoRoot, 'CLAUDE.md'), '# Demo Repo\n\nRoot guidance.\n', 'utf8');
+    const nestedDir = join(repoRoot, 'packages', 'widgets');
+    mkdirSync(nestedDir, { recursive: true });
+    writeFileSync(join(nestedDir, 'AGENTS.md'), '# Widgets Package\n\nNested guidance.\n', 'utf8');
+    git(['add', '.'], repoRoot);
+    git(['commit', '-m', 'init'], repoRoot);
+    // --source pinned directly at the nested dir, with the root project doc left
+    // unmigrated, so the nested doc's name must stay qualified on its own.
+    const nestedResult = await sysSyncLeaf.run({ source: nestedDir });
+    assert.equal(nestedResult?.imported, 1);
+    const nestedTarget = join(nestedDir, '.crouter', 'memory', 'AGENTS.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');
+    assert.notEqual(nestedDoc.data?.name, 'demo-repo', 'nested identity never collapses to the bare root project label it would collide with');
+    assert.match(nestedDoc.body, /Nested guidance\./);
+    const projectRows = (nestedResult?.results).filter((row) => row.target.includes('.crouter/memory'));
+    assert.ok(projectRows.some((r) => r.status === 'imported' && r.target === nestedTarget));
+    rmSync(base, { recursive: true, force: true });
+});
 test('falls back to the doc H1 title when the walk root is not inside a git repo', async () => {
     const source = mkdtempSync(join(tmpdir(), 'crtr-sys-sync-nogit-'));
     writeFileSync(join(source, 'CLAUDE.md'), '# Standalone Docs Project\n\nDo the thing.\n', 'utf8');
@@ -155,6 +308,6 @@ test('falls back to the doc H1 title when the walk root is not inside a git repo
     assert.equal(result?.imported, 1);
     const target = join(source, '.crouter', 'memory', 'AGENTS.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.');
+    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/sync.js

@@ -1,7 +1,7 @@
 // `crtr sys sync` — explicit migration from legacy host Agent Skill bundles into
 // crouter memory documents. It is NOT a bidirectional SKILL.md sync surface: the
 // crouter side after a sync is a plain memory/<name>.md document.
-import { existsSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { defineLeaf } from '../../core/command.js';
@@ -17,8 +17,7 @@ const LEGACY_BOOT_SKILL_MARKER_PREFIX = '<!-- crtr-boot-skill v';
 const HOST_SKILL_FILE = 'SKILL.md';
 const IGNORE_FILE = 'skill-import-ignore.json';
 // Directories a project-doc walk never descends into — build/dependency trees
-// plus crouter's own state dir (mirrors nested-context's JUNK_DIRS, the
-// now-deleted extension this migration replaces).
+// plus crouter's own state dir.
 const PROJECT_DOC_JUNK_DIRS = new Set([
     'node_modules', '.git', '.venv', 'venv', 'dist', 'build', '.next', '.cache', '.yalc', '.sisyphus', CRTR_DIR_NAME,
 ]);
@@ -67,7 +66,7 @@ function collectCandidates(rootDef) {
         candidates.push({ path: directSkill, root: dirname(statRoot), source: rootDef.label, defaultScope: rootDef.defaultScope });
         return candidates;
     }
-    for (const file of walkFiles(statRoot, (name) => name === HOST_SKILL_FILE)) {
+    for (const file of walkFiles(statRoot, (name) => name === HOST_SKILL_FILE, (name) => PROJECT_DOC_JUNK_DIRS.has(name))) {
         candidates.push({ path: file, root: statRoot, source: rootDef.label, defaultScope: rootDef.defaultScope });
     }
     return candidates;
@@ -163,18 +162,17 @@ function collectProjectDocCandidates(root) {
     const stack = [rootResolved];
     while (stack.length > 0) {
         const dir = stack.pop();
-        const isWalkRoot = dir === rootResolved;
         for (const name of PROJECT_DOC_FILENAMES) {
             const p = join(dir, name);
             if (existsSync(p) && statSync(p).isFile()) {
-                out.push({ kind: 'agents', path: p, sourceDir: dir, isWalkRoot });
+                out.push({ kind: 'agents', path: p, sourceDir: dir, walkRoot: rootResolved });
                 break;
             }
         }
         const rulesDir = join(dir, '.claude', 'rules');
         if (existsSync(rulesDir)) {
             for (const file of walkFiles(rulesDir, (n) => n.endsWith('.md'))) {
-                out.push({ kind: 'rule', path: file, sourceDir: dir, isWalkRoot });
+                out.push({ kind: 'rule', path: file, sourceDir: dir, walkRoot: rootResolved });
             }
         }
         let entries;
@@ -226,6 +224,33 @@ function gitRepoRootName(dir) {
         return undefined;
     return basename(dirname(gitCommonDir));
 }
+/** The current git worktree's OWN top-level directory (`git rev-parse
+ *  --show-toplevel`) — unlike `--git-common-dir` above, this does NOT resolve
+ *  through a linked worktree to the shared repo storage; it is the actual
+ *  checked-out tree containing `dir`. This is the stable root to compute a
+ *  doc's subdir suffix against, even when the discovery walk itself started
+ *  strictly inside that tree — e.g. `--source` pointed directly at a nested
+ *  package dir, so the walk root and the source dir are the same directory
+ *  and a walk-root-relative suffix would be empty. Returns undefined when
+ *  `dir` isn't inside a git working tree at all (the non-git fallback keeps
+ *  using the walk root itself). */
+function gitWorktreeRoot(dir) {
+    const res = gitSync(['rev-parse', '--path-format=absolute', '--show-toplevel'], dir);
+    if (res.status !== 0)
+        return undefined;
+    const top = res.stdout.trim();
+    return top === '' ? undefined : resolve(top);
+}
+/** `realpathSync`, tolerant of a path that doesn't exist or can't be resolved
+ *  (falls back to the path as given). */
+function realpathOrSelf(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
 /** First Markdown H1 heading in the doc body, heading marker stripped. */
 function h1Title(body) {
     for (const raw of body.split('\n')) {
@@ -238,35 +263,69 @@ function h1Title(body) {
     }
     return undefined;
 }
-/** Routing-text label for the WALK-ROOT project doc: the raw basename of that
- *  directory is unreliable (a worktree/canvas checkout's basename is a node
- *  id, not the project name), so prefer the actual git repo's root dirname,
- *  falling back to the doc's own H1 title, falling back to the raw basename
- *  only as a last resort. Nested-dir docs don't need this — their own
- *  subdirectory basename already names them correctly. */
-function projectRootLabel(dir, body) {
-    return gitRepoRootName(dir) ?? h1Title(body) ?? basename(dir) ?? dir;
+/** Namespace label for a walk root: the raw basename of that directory is
+ *  unreliable (a worktree/canvas checkout's basename is a node id, not the
+ *  project name), so prefer the actual git repo's root dirname, then the root
+ *  doc's own H1 title if one exists there, then the raw basename. */
+function projectRootLabel(root) {
+    const gitLabel = gitRepoRootName(root);
+    if (gitLabel !== undefined)
+        return normalizedName(gitLabel);
+    for (const name of PROJECT_DOC_FILENAMES) {
+        const p = join(root, name);
+        if (existsSync(p) && statSync(p).isFile()) {
+            const title = h1Title(parseFrontmatterGeneric(readText(p)).body);
+            if (title !== undefined)
+                return normalizedName(title);
+        }
+    }
+    return normalizedName(basename(root) || root);
+}
+/** Explicit substrate identity for one migrated project doc: the root label
+ *  from the walk root (repo name/H1/basename), plus any relative subdir under
+ *  the STABLE SUFFIX ROOT. That suffix root is the git worktree top-level
+ *  when the source is git-backed, NOT the supplied walk root — so a
+ *  `--source` pointed directly at a nested subdir (walk root === source dir,
+ *  a walk-root-relative suffix would be empty) still gets a suffix relative
+ *  to the real project root and cannot collide with that root's own doc
+ *  identity. Non-git sources have no stable project root to prefer, so they
+ *  keep the walk-root fallback unchanged. Root AGENTS.md docs become
+ *  `crouter`/`hearth`-shaped identities while nested AGENTS.md docs get a
+ *  deterministic `root/subdir` name — regardless of whether the walk started
+ *  at that root or at the nested dir itself. */
+function projectDocLabel(candidate) {
+    const rootLabel = projectRootLabel(candidate.walkRoot);
+    const suffixRoot = gitWorktreeRoot(candidate.walkRoot) ?? candidate.walkRoot;
+    // `git rev-parse --show-toplevel` resolves through symlinks (e.g. macOS's
+    // /tmp -> /private/tmp); realpath BOTH sides before diffing so a symlinked
+    // walk root doesn't produce a bogus `../../..` suffix against the git-
+    // resolved top-level.
+    const relDir = relative(realpathOrSelf(suffixRoot), realpathOrSelf(candidate.sourceDir))
+        .split(sep)
+        .join('/')
+        .replace(/^\.$/, '');
+    return relDir === '' ? rootLabel : normalizedName(`${rootLabel}/${relDir}`);
 }
 /** AGENTS.md/CLAUDE.md → `<sourceDir>/.crouter/memory/AGENTS.md` at
  *  content/content (the CTO's ruling, 2026-07-06: an AGENTS.md-style doc is
  *  always-relevant AND wholly-important, so full-body at `content` is
- *  sanctioned — see `taste/document-substrate`). Doc name is fixed `AGENTS`
- *  (never `INDEX`, which carries ceiling/subtree-capping semantics here). */
+ *  sanctioned — see `taste/document-substrate`). The on-disk filename stays
+ *  `AGENTS.md`, but the substrate identity is the explicit project label so
+ *  sibling roots do not collapse on a shared `AGENTS` leaf. */
 function prepareAgentsCandidate(candidate) {
     const body = parseFrontmatterGeneric(readText(candidate.path)).body;
-    const dirLabel = candidate.isWalkRoot
-        ? projectRootLabel(candidate.sourceDir, body)
-        : basename(candidate.sourceDir) || candidate.sourceDir;
+    const docLabel = projectDocLabel(candidate);
     const frontmatter = {
         kind: 'knowledge',
-        'when-and-why-to-read': `When working in ${dirLabel}, this knowledge should be read because it is the project's operating guide.`,
+        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': 'content',
         'file-read-visibility': 'content',
     };
     return {
         candidate,
-        name: 'AGENTS',
+        name: docLabel,
         target: memoryFilePath(join(candidate.sourceDir, CRTR_DIR_NAME, 'memory'), 'AGENTS'),
         frontmatter,
         body,
@@ -282,9 +341,7 @@ function prepareRuleCandidate(candidate) {
     const fm = parsed.data ?? {};
     const name = normalizedName(basename(candidate.path));
     const description = scalarString(fm['description']) ?? '';
-    const dirLabel = candidate.isWalkRoot
-        ? projectRootLabel(candidate.sourceDir, parsed.body)
-        : basename(candidate.sourceDir) || candidate.sourceDir;
+    const dirLabel = projectDocLabel(candidate);
     const frontmatter = {
         kind: 'knowledge',
         'when-and-why-to-read': description !== ''

package/dist/core/__tests__/broker-sdk-wiring.test.js

@@ -83,13 +83,10 @@ test('C3b — broker splits model thinking suffix before SDK registry lookup', a
         rmSync(cwd, { recursive: true, force: true });
     }
 });
-// (C4 — project AGENTS.md/CLAUDE.md injection — was removed: crouter sets
-// `noContextFiles: true` in buildBrokerSession unconditionally (broker.ts) and
-// no longer re-renders those files into the bearings either (hard cut,
-// 2026-07-06) — project guidance now comes from the document substrate
-// (`crtr sys sync` migrates CLAUDE.md/AGENTS.md into a memory doc). Covered by
-// context-intro.test.ts's "a CLAUDE.md in the node's cwd no longer rides the
-// bearings" test.)
+// (C4 — project guidance now comes from the document substrate: crouter keeps
+// `noContextFiles: true` in buildBrokerSession, and buildContextIntro's
+// `<project_context>` block is environment-only. Covered by
+// context-intro.test.ts's environment-only regression.)
 // ===========================================================================
 // C2 — zero-viewer dialogs resolve to deny/cancel IMMEDIATELY (noOp), never
 // hanging the turn and never waiting on a per-dialog timeout. Drives the REAL

package/dist/core/__tests__/context-intro.test.js

@@ -69,13 +69,21 @@ test('worker bearings: base framing + <knowledge> block, NO across-cycles framin
     assert.doesNotMatch(block, /refresh cycles/, 'no across-cycles framing for a terminal worker');
     assert.match(block, /<\/crtr-bearings>/);
 });
-test('a CLAUDE.md in the node\'s cwd no longer rides the bearings; only the <environment> snapshot does (hard cut, 2026-07-06)', () => {
-    // buildProjectContextBlock used to re-render the node's AGENTS.md/CLAUDE.md
-    // into a <project_instructions> block (pi's own copy stays suppressed via
-    // broker.ts noContextFiles). That machinery is gone: project guidance now
-    // comes from the document substrate (a migrated AGENTS.md doc rides the
-    // <memory kind="knowledge"> block instead — see `crtr sys sync`), so a bare
-    // on-disk CLAUDE.md is simply never read by crtr at boot any more.
+test('node-local doc identity honors explicit frontmatter `name`, not the physical filename', () => {
+    // node-local docs follow the one substrate identity rule (resolveDocName):
+    // an explicit `name:` renders and dedups under that name, not the filename.
+    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
+    const dir = memoryDir(meta.node_id);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'physical-filename.md'), '---\nkind: knowledge\nname: explicit-identity\nwhen-and-why-to-read: When testing, this reference should be read because it is a regression fixture\nsystem-prompt-visibility: preview\n---\nTest body.\n');
+    const block = buildContextIntro(meta.node_id);
+    assert.match(block, /\u2500 explicit-identity {2}# read when:/, 'tree entry renders under the explicit frontmatter name');
+    assert.ok(!block.includes('physical-filename'), 'the physical filename never surfaces once an explicit name is set');
+});
+test('a CLAUDE.md in the node\'s cwd does not enter the bearings; only the <environment> snapshot remains', () => {
+    // buildProjectContextBlock now emits only the cwd/git environment snapshot.
+    // Project guidance lives in the document substrate instead, so a bare on-disk
+    // CLAUDE.md stays out of the bearings entirely.
     const proj = mkdtempSync(join(tmpdir(), 'crtr-proj-'));
     writeFileSync(join(proj, 'CLAUDE.md'), 'PROJECT_MARKER: build then commit.\n');
     const meta = spawnNode({ kind: 'general', cwd: proj, parent: null });

package/dist/core/__tests__/memory-resolver-precedence.test.d.ts

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

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

@@ -0,0 +1,144 @@
+// Regression matrix for `resolveMemoryDoc`'s precedence rule: scopes/sources
+// are visited NEAREST-FIRST, and the first source with ANY hit — by identity,
+// direct physical path, or bare-leaf fallback — wins outright. A farther
+// source's match, even an EXACT identity match, must never be consulted once
+// a nearer source has answered by any means. This locks in the fix for the
+// regression where a global identity-first scan let a farther-scope doc named
+// exactly `AGENTS` shadow a nearer worktree's own `AGENTS.md` (whose explicit
+// frontmatter `name` had since diverged from the physical filename).
+//
+// Fixture shape: two nested project scopes on disk —
+//   root/.crouter/memory/...       (farther project scope)
+//   root/child/.crouter/memory/... (nearer project scope; cwd lives here)
+// `findProjectScopeRoots` walks every ancestor `.crouter/` from cwd upward, so
+// from `root/child` the resolved stack is exactly [child, root], nearest first
+// — no profile indirection needed to exercise multi-scope precedence.
+//
+// Run: node --import tsx/esm --test src/core/__tests__/memory-resolver-precedence.test.ts
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { resetScopeCache } from '../scope.js';
+import { resolveMemoryDoc } from '../memory-resolver.js';
+let home;
+let base;
+let root;
+let child;
+let grandchild;
+let prevCwd;
+let prevHome;
+function writeDoc(path, body, frontmatterName) {
+    mkdirSync(join(path, '..'), { recursive: true });
+    const fm = frontmatterName ? `---\nname: ${frontmatterName}\n---\n` : '';
+    writeFileSync(path, `${fm}${body}\n`, 'utf8');
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-resolver-precedence-home-'));
+    prevHome = process.env.HOME;
+    process.env.HOME = home;
+});
+beforeEach(() => {
+    resetScopeCache();
+    base = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-resolver-precedence-')));
+    root = join(base, 'root');
+    child = join(root, 'child');
+    grandchild = join(child, 'grandchild');
+    mkdirSync(root, { recursive: true });
+    mkdirSync(child, { recursive: true });
+    mkdirSync(grandchild, { recursive: true });
+    // --- root (FARTHER project scope) ---
+    writeDoc(join(root, '.crouter', 'memory', 'AGENTS.md'), 'ROOT AGENTS BODY'); // derived name "AGENTS"
+    writeDoc(join(root, '.crouter', 'memory', 'shared.md'), 'ROOT SHARED BODY'); // derived name "shared"
+    writeDoc(join(root, '.crouter', 'memory', 'taste', 'document-substrate.md'), 'ROOT TASTE BODY'); // derived "taste/document-substrate"
+    writeDoc(join(root, '.crouter', 'memory', 'taste', 'INDEX.md'), 'ROOT TASTE INDEX'); // derived "taste/INDEX"
+    // --- child (NEARER project scope; cwd resolves here) ---
+    writeDoc(join(child, '.crouter', 'memory', 'AGENTS.md'), 'CHILD AGENTS BODY', 'crouter'); // physical AGENTS.md, identity diverged to "crouter"
+    writeDoc(join(child, '.crouter', 'memory', 'sub', 'shared.md'), 'CHILD SUB SHARED BODY'); // derived "sub/shared" — leaf "shared"
+    writeDoc(join(child, '.crouter', 'memory', 'taste', 'document-substrate.md'), 'CHILD TASTE BODY'); // derived "taste/document-substrate"
+    writeDoc(join(child, '.crouter', 'memory', 'taste', 'INDEX.md'), 'CHILD TASTE INDEX'); // derived "taste/INDEX"
+    // --- grandchild (nearest still; own migrated slashed identity) ---
+    writeDoc(join(grandchild, '.crouter', 'memory', 'AGENTS.md'), 'GRANDCHILD SUBDIR BODY', 'root/subdir');
+    prevCwd = process.cwd();
+});
+after(() => {
+    process.chdir(prevCwd);
+    resetScopeCache();
+    rmSync(base, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+    if (prevHome === undefined)
+        delete process.env.HOME;
+    else
+        process.env.HOME = prevHome;
+});
+test('a physical-path query whose nearest match diverged in identity from a farther same-derived-name doc resolves to the NEAREST physical file (the AGENTS shadowing case)', () => {
+    process.chdir(child);
+    resetScopeCache();
+    try {
+        const byPhysicalName = resolveMemoryDoc('AGENTS');
+        assert.equal(byPhysicalName.path, join(child, '.crouter', 'memory', 'AGENTS.md'));
+        assert.match(byPhysicalName.body, /CHILD AGENTS BODY/);
+        const byExplicitIdentity = resolveMemoryDoc('crouter');
+        assert.equal(byExplicitIdentity.path, join(child, '.crouter', 'memory', 'AGENTS.md'));
+        assert.match(byExplicitIdentity.body, /CHILD AGENTS BODY/);
+    }
+    finally {
+        process.chdir(prevCwd);
+    }
+});
+test('a migrated nested doc resolves by its explicit slashed identity', () => {
+    process.chdir(grandchild);
+    resetScopeCache();
+    try {
+        const doc = resolveMemoryDoc('root/subdir');
+        assert.equal(doc.path, join(grandchild, '.crouter', 'memory', 'AGENTS.md'));
+        assert.equal(doc.name, 'root/subdir');
+        assert.match(doc.body, /GRANDCHILD SUBDIR BODY/);
+    }
+    finally {
+        process.chdir(prevCwd);
+    }
+});
+test('a plain path-named doc with no explicit name resolves to the nearest copy', () => {
+    process.chdir(child);
+    resetScopeCache();
+    try {
+        const doc = resolveMemoryDoc('taste/document-substrate');
+        assert.equal(doc.path, join(child, '.crouter', 'memory', 'taste', 'document-substrate.md'));
+        assert.match(doc.body, /CHILD TASTE BODY/);
+    }
+    finally {
+        process.chdir(prevCwd);
+    }
+});
+test('a bare-directory query resolves to that dir\'s INDEX.md, nearest copy first', () => {
+    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/);
+    }
+    finally {
+        process.chdir(prevCwd);
+    }
+});
+test('two docs sharing a path-derived leaf name across scopes: nearest wins even over a farther EXACT identity match', () => {
+    process.chdir(child);
+    resetScopeCache();
+    try {
+        // Nearest scope's doc lives at "sub/shared.md" (derived name "sub/shared",
+        // leaf "shared"); the farther scope's doc lives at top-level "shared.md"
+        // (derived name "shared", an EXACT identity match for the bare query).
+        // Precedence-as-outer-loop means the nearer source's mere leaf-fallback
+        // hit must still beat the farther source's exact identity hit.
+        const doc = resolveMemoryDoc('shared');
+        assert.equal(doc.path, join(child, '.crouter', 'memory', 'sub', 'shared.md'));
+        assert.equal(doc.name, 'sub/shared');
+        assert.match(doc.body, /CHILD SUB SHARED BODY/);
+    }
+    finally {
+        process.chdir(prevCwd);
+    }
+});

package/dist/core/__tests__/on-read-identity.test.d.ts

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