@crouton-kit/crouter 0.3.46 → 0.3.48

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

@@ -1,6 +1,9 @@
 // Regression: `crtr sys sync` is the one-shot migration path from legacy
 // Agent Skill bundles into crouter memory docs. The hard cut removes SKILL.md as
-// an active guidance surface, but must keep the converter.
+// an active guidance surface, but must keep the converter. It is ALSO the
+// migration path for CLAUDE.md/AGENTS.md/.claude/rules — the hard cut that
+// removes crtr's own bolted-on project-context loader (bearings.ts,
+// nested-context.ts) in favor of the document substrate.
 //
 // Run: node --import tsx/esm --test src/commands/sys/__tests__/sync-import.test.ts
 import { afterEach, beforeEach, test } from 'node:test';
@@ -10,6 +13,12 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { sysSyncLeaf } from '../sync.js';
 import { parseFrontmatterGeneric } from '../../../core/frontmatter.js';
+import { gitSync } from '../../../core/git.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}`);
+}
 let home;
 let prevHome;
 beforeEach(() => {
@@ -70,3 +79,82 @@ test('permanently ignores selected SKILL.md bundles', async () => {
     assert.notEqual(rendered, undefined);
     assert.match(rendered, /would ignore/);
 });
+test('migrates CLAUDE.md and a .claude/rules file into that dir\'s own .crouter/memory/, copy-not-move, skip-existing, --overwrite replaces', async () => {
+    const source = mkdtempSync(join(tmpdir(), 'crtr-sys-sync-projectdocs-'));
+    writeFileSync(join(source, 'CLAUDE.md'), '# Demo Project\n\nBuild then commit.\n', 'utf8');
+    mkdirSync(join(source, '.claude', 'rules'), { recursive: true });
+    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 projectRows = (r) => r.results.filter((row) => row.target.includes('.crouter/memory'));
+    const dry = await sysSyncLeaf.run({ source, dryRun: true });
+    const dryRows = projectRows(dry);
+    assert.equal(dryRows.length, 2, 'both the AGENTS.md 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');
+    await sysSyncLeaf.run({ source });
+    const agentsTarget = join(source, '.crouter', 'memory', 'AGENTS.md');
+    const ruleTarget = join(source, '.crouter', 'memory', 'foo.md');
+    assert.equal(existsSync(agentsTarget), true);
+    assert.equal(existsSync(ruleTarget), true);
+    const agentsDoc = parseFrontmatterGeneric(readFileSync(agentsTarget, 'utf8'));
+    assert.equal(agentsDoc.data?.kind, 'knowledge');
+    assert.equal(agentsDoc.data?.['system-prompt-visibility'], 'content');
+    assert.equal(agentsDoc.data?.['file-read-visibility'], 'content');
+    assert.match(agentsDoc.body, /Build then commit\./);
+    const ruleDoc = parseFrontmatterGeneric(readFileSync(ruleTarget, 'utf8'));
+    assert.equal(ruleDoc.data?.kind, 'knowledge');
+    assert.equal(ruleDoc.data?.['system-prompt-visibility'], 'none');
+    assert.equal(ruleDoc.data?.['file-read-visibility'], 'content');
+    assert.deepEqual(ruleDoc.data?.['applies-to'], ['src/**/*.ts']);
+    assert.match(ruleDoc.body, /Do the foo thing\./);
+    // Originals untouched — copy, not move.
+    assert.equal(existsSync(join(source, 'CLAUDE.md')), true);
+    assert.equal(existsSync(join(source, '.claude', 'rules', 'foo.md')), true);
+    // Re-run skips existing targets.
+    const rerun = await sysSyncLeaf.run({ source });
+    const rerunRows = projectRows(rerun);
+    assert.ok(rerunRows.every((r) => r.status === 'skipped'));
+    // --overwrite replaces.
+    writeFileSync(join(source, 'CLAUDE.md'), '# Demo Project v2\n\nBuild, THEN commit.\n', 'utf8');
+    const overwritten = await sysSyncLeaf.run({ source, overwrite: true });
+    const overwriteRows = projectRows(overwritten);
+    assert.ok(overwriteRows.some((r) => r.status === 'imported'));
+    const agentsDoc2 = parseFrontmatterGeneric(readFileSync(agentsTarget, 'utf8'));
+    assert.match(agentsDoc2.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 () => {
+    // Regression: running the migration from a linked git worktree (e.g. a
+    // canvas node's checkout, whose directory is named after a node id) must
+    // not bake that node id into the migrated doc's routing text — it should
+    // resolve through to the actual repo name shared by every worktree.
+    const base = mkdtempSync(join(tmpdir(), 'crtr-sys-sync-worktree-'));
+    const mainRepo = join(base, 'demo-repo');
+    mkdirSync(mainRepo, { recursive: true });
+    git(['init', '-b', 'main'], mainRepo);
+    git(['config', 'user.email', 'test@example.com'], mainRepo);
+    git(['config', 'user.name', 'Test'], mainRepo);
+    writeFileSync(join(mainRepo, 'README.md'), 'hello\n', 'utf8');
+    git(['add', '.'], mainRepo);
+    git(['commit', '-m', 'init'], mainRepo);
+    // A linked worktree whose basename looks nothing like the repo name.
+    const linkedWorktree = join(base, 'mr9xyz12-abcd3456');
+    git(['worktree', 'add', linkedWorktree, '-b', 'feature'], mainRepo);
+    writeFileSync(join(linkedWorktree, 'CLAUDE.md'), '# Fallback Title\n\nRepo guidance.\n', 'utf8');
+    const result = await sysSyncLeaf.run({ source: linkedWorktree });
+    assert.equal(result?.imported, 1);
+    const target = join(linkedWorktree, '.crouter', 'memory', 'AGENTS.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('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');
+    const result = await sysSyncLeaf.run({ source });
+    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.');
+    rmSync(source, { recursive: true, force: true });
+});

package/dist/commands/sys/sync.js

@@ -1,18 +1,29 @@
 // `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 } from 'node:fs';
+import { existsSync, readdirSync, 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';
 import { usage } from '../../core/errors.js';
 import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
+import { gitSync } from '../../core/git.js';
 import { pathExists, readJsonIfExists, readText, walkFiles, writeJson, writeText } from '../../core/fs-utils.js';
+import { loadProfileManifest } from '../../core/profiles/manifest.js';
 import { findProjectScopeRoot, scopeMemoryDir } from '../../core/scope.js';
+import { CRTR_DIR_NAME } from '../../types.js';
 import { memoryFilePath, resolveWriteTarget, serializeMemoryDoc } from '../memory/shared.js';
 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).
+const PROJECT_DOC_JUNK_DIRS = new Set([
+    'node_modules', '.git', '.venv', 'venv', 'dist', 'build', '.next', '.cache', '.yalc', '.sisyphus', CRTR_DIR_NAME,
+]);
+// First-match-per-dir order mirrors pi's own loader (AGENTS.md wins over CLAUDE.md).
+const PROJECT_DOC_FILENAMES = ['AGENTS.md', 'CLAUDE.md'];
 function projectDir() {
     const root = findProjectScopeRoot();
     return root ? dirname(root) : null;
@@ -115,6 +126,208 @@ function targetMemoryDir(scope) {
         return resolveWriteTarget(scope).memoryDir;
     return dir;
 }
+/** Discovery roots for the project-doc walk: an explicit `--source` pins a
+ *  single dir; otherwise cwd plus (when a profile is selected) every project
+ *  in its purview — the same profile-widened idea `findProjectScopeRoots`
+ *  applies to the boot render, so one invocation can migrate a whole
+ *  workspace instead of one repo at a time. Deduped, cwd first; never throws
+ *  on a missing/unreadable profile (cwd-only fallback). */
+function projectDocRoots(sourceArg) {
+    if (sourceArg !== undefined)
+        return [resolve(sourceArg)];
+    const roots = [resolve(process.cwd())];
+    const profileId = process.env['CRTR_PROFILE_ID'];
+    if (profileId !== undefined && profileId !== '') {
+        try {
+            const { manifest } = loadProfileManifest(profileId);
+            for (const p of manifest.projects) {
+                const r = resolve(p);
+                if (!roots.includes(r))
+                    roots.push(r);
+            }
+        }
+        catch {
+            // No/unreadable profile — cwd-only root.
+        }
+    }
+    return roots;
+}
+/** Walk `root` (skipping PROJECT_DOC_JUNK_DIRS) collecting every dir's
+ *  CLAUDE.md/AGENTS.md (first match per dir) plus every `.claude/rules/*.md`.
+ *  Each result names the directory whose OWN `.crouter/memory/` it targets. */
+function collectProjectDocCandidates(root) {
+    const out = [];
+    if (!existsSync(root) || !statSync(root).isDirectory())
+        return out;
+    const rootResolved = resolve(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 });
+                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 });
+            }
+        }
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (e.isDirectory() && !PROJECT_DOC_JUNK_DIRS.has(e.name))
+                stack.push(join(dir, e.name));
+        }
+    }
+    return out;
+}
+/** First non-empty line, heading markers stripped, truncated — the `short-form`
+ *  gist synthesized from a body with no frontmatter description to draw from. */
+function synthesizeShortForm(body) {
+    for (const raw of body.split('\n')) {
+        const cleaned = raw.replace(/^#+\s*/, '').replace(/\s+/g, ' ').trim();
+        if (cleaned !== '')
+            return cleaned.length > 200 ? `${cleaned.slice(0, 197)}...` : cleaned;
+    }
+    return 'Migrated project guidance.';
+}
+/** `.claude/rules` frontmatter `paths:` normalizes to a glob list — a single
+ *  string, an array, or absent (positional, unconditional rule). */
+function normalizeRulePaths(v) {
+    if (typeof v === 'string')
+        return v.trim() === '' ? [] : [v.trim()];
+    if (Array.isArray(v))
+        return v.filter((g) => typeof g === 'string' && g.trim() !== '');
+    return [];
+}
+/** The main repo root's directory name, found via `git rev-parse
+ *  --git-common-dir` — unlike `--show-toplevel`, this resolves through a
+ *  LINKED WORKTREE to the shared `.git` of the repo it belongs to, so a
+ *  canvas worktree checked out under a node-id path (e.g.
+ *  `.../worktrees/mr9vsbtn-ecd74d1b`) still resolves to the real project
+ *  name (`crouter`), not the worktree's own basename. Returns undefined when
+ *  `dir` isn't inside a git repo at all. */
+function gitRepoRootName(dir) {
+    const res = gitSync(['rev-parse', '--path-format=absolute', '--git-common-dir'], dir);
+    if (res.status !== 0)
+        return undefined;
+    const gitCommonDir = res.stdout.trim();
+    if (gitCommonDir === '')
+        return undefined;
+    return basename(dirname(gitCommonDir));
+}
+/** First Markdown H1 heading in the doc body, heading marker stripped. */
+function h1Title(body) {
+    for (const raw of body.split('\n')) {
+        const m = raw.match(/^#\s+(.+)$/);
+        if (m) {
+            const title = m[1].replace(/\s+/g, ' ').trim();
+            if (title !== '')
+                return title;
+        }
+    }
+    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;
+}
+/** 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). */
+function prepareAgentsCandidate(candidate) {
+    const body = parseFrontmatterGeneric(readText(candidate.path)).body;
+    const dirLabel = candidate.isWalkRoot
+        ? projectRootLabel(candidate.sourceDir, body)
+        : basename(candidate.sourceDir) || candidate.sourceDir;
+    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.`,
+        'short-form': synthesizeShortForm(body),
+        'system-prompt-visibility': 'content',
+        'file-read-visibility': 'content',
+    };
+    return {
+        candidate,
+        name: 'AGENTS',
+        target: memoryFilePath(join(candidate.sourceDir, CRTR_DIR_NAME, 'memory'), 'AGENTS'),
+        frontmatter,
+        body,
+    };
+}
+/** `.claude/rules/<name>.md` → `<sourceDir>/.crouter/memory/<name>.md`. A
+ *  `paths:` rule becomes an `applies-to` glob trigger at none/content; a
+ *  pathless rule is positional (surfaces like AGENTS.md on any read under its
+ *  own project scope) at the same none/content rungs. */
+function prepareRuleCandidate(candidate) {
+    const raw = readText(candidate.path);
+    const parsed = parseFrontmatterGeneric(raw);
+    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 frontmatter = {
+        kind: 'knowledge',
+        'when-and-why-to-read': description !== ''
+            ? 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']);
+    if (globs.length > 0)
+        frontmatter['applies-to'] = globs;
+    return {
+        candidate,
+        name,
+        target: memoryFilePath(join(candidate.sourceDir, CRTR_DIR_NAME, 'memory'), name),
+        frontmatter,
+        body: parsed.body,
+    };
+}
+/** Write (or dry-run report) a prepared project doc — copy-not-move,
+ *  skip-existing unless `--overwrite`, mirroring `convertPrepared` above. */
+function convertProjectDoc(prepared, opts) {
+    if (pathExists(prepared.target) && !opts.overwrite) {
+        return {
+            source: prepared.candidate.path,
+            target: prepared.target,
+            name: prepared.name,
+            scope: 'project',
+            status: 'skipped',
+            reason: 'target memory doc already exists; re-run with --overwrite to replace it',
+        };
+    }
+    if (!opts.dryRun)
+        writeText(prepared.target, serializeMemoryDoc(prepared.frontmatter, prepared.body));
+    return {
+        source: prepared.candidate.path,
+        target: prepared.target,
+        name: prepared.name,
+        scope: 'project',
+        status: opts.dryRun ? 'would-import' : 'imported',
+    };
+}
 function readIgnoreState() {
     let doc;
     try {
@@ -257,32 +470,33 @@ function renderSummary(results, ignoreMode) {
 }
 export const sysSyncLeaf = defineLeaf({
     name: 'sync',
-    description: 'convert legacy SKILL.md bundles into crouter memory docs',
-    whenToUse: 'migrating host-native Agent Skill bundles into the crouter memory-doc model. This is a one-way import from SKILL.md to memory/<name>.md; it never exports memory docs back to SKILL.md and never treats SKILL.md as an active crouter guidance surface.',
+    description: 'convert legacy SKILL.md bundles and CLAUDE.md/AGENTS.md/.claude/rules into crouter memory docs',
+    whenToUse: 'migrating legacy guidance surfaces into the crouter memory-doc model: host-native Agent Skill bundles (SKILL.md, one-way import into a scope-root memory dir) AND per-project CLAUDE.md/AGENTS.md/.claude/rules (one-way copy into that same directory\'s OWN .crouter/memory/, so the doc travels with the repo and gets positional on-read for free). Both are one-way; sync never exports memory docs back to any of these files and never treats them as an active crouter guidance surface once migrated — crouter stops reading the originals unconditionally.',
     help: {
         name: 'sys sync',
-        summary: 'one-way import: SKILL.md bundles → crouter memory docs',
+        summary: 'one-way import: SKILL.md bundles + CLAUDE.md/AGENTS.md/.claude/rules → crouter memory docs',
         params: [
-            { kind: 'flag', name: 'source', type: 'string', required: false, constraint: 'A SKILL.md file, a single skill bundle dir containing SKILL.md, or a skills root to scan recursively. Default: user/project Claude and pi skill roots that exist.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Target memory scope. Default: user for user host roots and project for project host roots; explicit value applies to every imported source.' },
+            { kind: 'flag', name: 'source', type: 'string', required: false, constraint: 'For SKILL.md: a SKILL.md file, a single skill bundle dir containing SKILL.md, or a skills root to scan recursively; default is the user/project Claude and pi skill roots that exist. For CLAUDE.md/AGENTS.md/.claude/rules: the root to walk recursively for those files; default is cwd plus every project in the current profile\'s purview (when one is selected). One value drives both discoveries.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Target memory scope for imported SKILL.md sources only. Default: user for user host roots and project for project host roots; explicit value applies to every imported SKILL.md source. Does not affect CLAUDE.md/AGENTS.md/.claude/rules migration — those always target their own source directory\'s .crouter/memory/, never a scope root.' },
             { kind: 'flag', name: 'dry-run', type: 'bool', required: false, constraint: 'Show what would be imported without writing memory docs.' },
             { kind: 'flag', name: 'overwrite', type: 'bool', required: false, constraint: 'Replace an existing target memory doc. Default: skip existing docs to avoid clobbering user-authored memory.' },
-            { kind: 'flag', name: 'ignore', type: 'bool', required: false, constraint: `Permanently ignore every selected source by recording it in ~/.crouter/${IGNORE_FILE}. Honors --source/--scope; with no --source, ignores every currently discovered default host skill candidate.` },
-            { kind: 'flag', name: 'include-ignored', type: 'bool', required: false, constraint: 'Include ignored candidates in the report without making sync read-only. Pair with --dry-run to audit the full candidate set without importing non-ignored skills.' },
+            { kind: 'flag', name: 'ignore', type: 'bool', required: false, constraint: `Permanently ignore every selected SKILL.md source by recording it in ~/.crouter/${IGNORE_FILE}. Honors --source/--scope; with no --source, ignores every currently discovered default host skill candidate. Does not apply to CLAUDE.md/AGENTS.md/.claude/rules — that migration is skipped entirely when --ignore is present.` },
+            { kind: 'flag', name: 'include-ignored', type: 'bool', required: false, constraint: 'Include ignored SKILL.md candidates in the report without making sync read-only. Pair with --dry-run to audit the full candidate set without importing non-ignored skills.' },
         ],
         output: [
-            { name: 'imported', type: 'number', required: true, constraint: 'Count of memory docs written.' },
-            { name: 'skipped', type: 'number', required: true, constraint: 'Count of SKILL.md files skipped.' },
+            { name: 'imported', type: 'number', required: true, constraint: 'Count of memory docs written, across both SKILL.md and CLAUDE.md/AGENTS.md/.claude/rules sources.' },
+            { name: 'skipped', type: 'number', required: true, constraint: 'Count of source files skipped (existing target without --overwrite, or an unimportable SKILL.md).' },
             { name: 'ignored', type: 'number', required: true, constraint: 'Count of selected SKILL.md files that are permanently ignored.' },
             { name: 'wouldIgnore', type: 'number', required: true, constraint: 'Count of selected SKILL.md files that would be ignored under --dry-run.' },
-            { name: 'results', type: 'object[]', required: true, constraint: 'Each: {source,target,name,scope,status,reason?}; status may be imported, skipped, would-import, ignored, or would-ignore.' },
+            { name: 'results', type: 'object[]', required: true, constraint: 'Each: {source,target,name,scope,status,reason?}; status may be imported, skipped, would-import, ignored, or would-ignore. A CLAUDE.md/AGENTS.md/.claude/rules row never carries ignored/would-ignore.' },
         ],
         outputKind: 'object',
         effects: [
             'Writes memory/<name>.md in the selected crouter scope with substrate frontmatter and the SKILL.md body.',
+            'Copies each discovered CLAUDE.md/AGENTS.md into <dir>/.crouter/memory/AGENTS.md at system-prompt-visibility/file-read-visibility content/content, and each .claude/rules/*.md into <dir>/.crouter/memory/<name>.md at none/content (applies-to set from the rule\'s paths: globs when present) — copy, not move; original files are left untouched.',
             'Skips existing memory docs unless --overwrite is present.',
             'Skips marker-bearing generated crtr boot skills; host exports prune those legacy artifacts instead.',
-            `With --ignore: writes ~/.crouter/${IGNORE_FILE} and does not import the selected sources.`,
+            `With --ignore: writes ~/.crouter/${IGNORE_FILE} and does not import the selected SKILL.md sources; the CLAUDE.md/AGENTS.md/.claude/rules migration does not run at all in this mode.`,
             'With --dry-run: read-only; writes nothing.',
         ],
     },
@@ -328,6 +542,22 @@ export const sysSyncLeaf = defineLeaf({
         }
         if (changedIgnoreState)
             writeIgnoreState(ignoreState);
+        // Project-doc migration (CLAUDE.md/AGENTS.md/.claude/rules) — independent
+        // of --ignore (a skill-only verb); an explicit --source pins its walk root
+        // too, so one invocation with --source drives both machineries over the
+        // same tree.
+        if (!ignoreMode) {
+            const docSeen = new Set();
+            for (const root of projectDocRoots(sourceArg)) {
+                for (const c of collectProjectDocCandidates(root)) {
+                    if (docSeen.has(c.path))
+                        continue;
+                    docSeen.add(c.path);
+                    const prepared = c.kind === 'agents' ? prepareAgentsCandidate(c) : prepareRuleCandidate(c);
+                    results.push(convertProjectDoc(prepared, { dryRun, overwrite }));
+                }
+            }
+        }
         const imported = results.filter((r) => r.status === 'imported').length;
         const wouldImport = results.filter((r) => r.status === 'would-import').length;
         const skipped = results.filter((r) => r.status === 'skipped').length;

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

@@ -83,11 +83,13 @@ 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 now sets
-// `noContextFiles: true` in buildBrokerSession and re-renders project context
-// into the first-message <crtr-context> bearings instead of pi's system prompt
-// (broker.ts). That behavior is covered by context-intro.test.ts's "project
-// instructions ride the bearings, not the system prompt" test.)
+// (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.)
 // ===========================================================================
 // 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

@@ -20,14 +20,9 @@ import { personaDrift } from '../runtime/persona.js';
 import { memoryDir } from '../runtime/memory.js';
 import registerCanvasContextIntro, { buildContextIntro, renderContextMessage, CONTEXT_INTRO_CUSTOM_TYPE, } from '../../pi-extensions/canvas-context-intro.js';
 let home;
-let prevAgentDir;
 before(() => {
     home = mkdtempSync(join(tmpdir(), 'crtr-ctxintro-'));
     process.env['CRTR_HOME'] = home;
-    // Isolate pi's global agent dir to an empty path so buildProjectContextBlock
-    // can't pick up the dev machine's real ~/.pi/agent/AGENTS.md (hermeticity).
-    prevAgentDir = process.env['PI_CODING_AGENT_DIR'];
-    process.env['PI_CODING_AGENT_DIR'] = join(home, 'no-agent-dir');
 });
 beforeEach(() => {
     closeDb();
@@ -38,10 +33,6 @@ after(() => {
     rmSync(home, { recursive: true, force: true });
     delete process.env['CRTR_HOME'];
     delete process.env['CRTR_NODE_ID'];
-    if (prevAgentDir === undefined)
-        delete process.env['PI_CODING_AGENT_DIR'];
-    else
-        process.env['PI_CODING_AGENT_DIR'] = prevAgentDir;
 });
 test('worker bearings: base framing + <knowledge> block, NO across-cycles framing', () => {
     // Bug-regression: review finding M1 — buildContextBearings renders the
@@ -78,20 +69,22 @@ 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('project instructions (AGENTS.md/CLAUDE.md) ride the bearings, not the system prompt', () => {
-    // pi's <project_context> is suppressed in the system prompt (broker.ts
-    // noContextFiles) and re-rendered into the first-message bearings here. The
-    // discovery walks the node cwd ancestry, so a CLAUDE.md in the node's cwd must
-    // surface inside a <project_context> block AFTER the <crtr-bearings> block.
+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.
     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 });
     const block = buildContextIntro(meta.node_id);
-    assert.match(block, /<project_context>/, 'project_context block present in the bearings');
-    assert.match(block, new RegExp(`<project_instructions path="${join(proj, 'CLAUDE.md')}">`), 'the project CLAUDE.md is rendered with its path');
-    assert.match(block, /PROJECT_MARKER: build then commit\./, 'project file content rides the message');
-    assert.match(block, /<environment cwd=".*crtr-proj-.*">/, 'environment block is appended inside project_context');
-    assert.match(block, /Directory:\n  CLAUDE\.md\n/, 'environment block includes an ls-style listing');
+    assert.doesNotMatch(block, /<project_instructions/, 'no <project_instructions> block is ever emitted');
+    assert.doesNotMatch(block, /PROJECT_MARKER: build then commit\./, 'the CLAUDE.md body never rides the bearings');
+    assert.match(block, /<project_context>/, 'project_context wrapper still present');
+    assert.match(block, /<environment cwd=".*crtr-proj-.*">/, 'environment block still rides inside project_context');
+    assert.match(block, /Directory:\n  CLAUDE\.md\n/, 'environment block still includes an ls-style listing');
     assert.match(block, /Git: not a git repository\./, 'git snapshot degrades cleanly for a non-repo');
     assert.match(block, /<environment[\s\S]*<\/environment>\n<\/project_context>$/, 'environment block closes project_context');
     assert.ok(block.indexOf('</crtr-bearings>') < block.indexOf('<project_context>'), 'project_context follows the crtr-bearings block');

package/dist/core/runtime/bearings.d.ts

@@ -1,8 +1,13 @@
 import { type Trigger } from '../canvas/index.js';
-/** The `<project_context>` block for the files discovered from `cwd`, plus the
- *  cwd/git environment snapshot that now rides at the end of the wrapper.
- *  Always emits the wrapper because the environment snapshot is always present
- *  even when no project instructions exist. Exported for testing. */
+/** The `<project_context>` block — now just the cwd/git `<environment>`
+ *  snapshot (dir listing + git status/worktrees). This USED to also carry a
+ *  `<project_instructions>` block re-rendering the node's AGENTS.md/CLAUDE.md;
+ *  that machinery is gone (hard cut, 2026-07-06) — project guidance now lives
+ *  in the document substrate (`crtr sys sync` migrates each CLAUDE.md/AGENTS.md
+ *  into that dir's own `.crouter/memory/AGENTS.md` at content/content, so it
+ *  surfaces via the `<memory kind="knowledge">` block instead). Always emits
+ *  the wrapper because the environment snapshot is always present. Exported
+ *  for testing. */
 export declare function buildProjectContextBlock(cwd: string): string;
 /** The context-directory note — names the path INLINE (no XML attribute, so it
  *  never scopes a sibling block) and frames the dir as durable, shared scratch.
@@ -85,7 +90,10 @@ export declare function buildWakeBearings(origin: WakeOrigin): string;
  *      from.
  *   2. `<memory kind="knowledge">` — the consultable catalog, a SIBLING of the
  *      bearings (never nested under the context dir). Dropped when empty.
- *   3. `<project_context>` — the AGENTS.md/CLAUDE.md instructions + the cwd/git
- *      environment snapshot, moved OUT of the system prompt (pi's copy is
- *      suppressed via noContextFiles in broker.ts) so it rides this message. */
+ *   3. `<project_context>` — the cwd/git environment snapshot. pi's own
+ *      AGENTS.md/CLAUDE.md system-prompt injection stays suppressed
+ *      (noContextFiles in broker.ts); project guidance instead rides the
+ *      `<memory kind="knowledge">` block above via the document substrate
+ *      (`crtr sys sync` migrates each CLAUDE.md/AGENTS.md into that dir's own
+ *      `.crouter/memory/AGENTS.md`). */
 export declare function buildContextBearings(nodeId: string): string;