@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/commands/sys/sync.js

@@ -1,187 +1,339 @@
-// `crtr sys sync` — the SOLE entry point for bidirectional crtr ↔ Claude skill
-// sync (R-U1). Loads the layered manifest (P2), reconciles each enrolled pair
-// once via the direction-agnostic engine (P6), summarizes the outcome, and
-// sets the exit code: non-zero IFF any pair conflicted (R-E7). A malformed
-// manifest (R-U7) or an unknown `--pair` id (OD-3) aborts hard before any
-// reconcile runs — no lenient fallback, no partial write.
+// `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 { 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 { emit, isJsonOutput } from '../../core/io.js';
-import { ExitCode } from '../../types.js';
-import { readLayeredManifest } from '../../core/skill-sync/manifest.js';
-import { resolveProfile } from '../../core/skill-sync/profile.js';
-import { reconcilePair } from '../../core/skill-sync/engine.js';
-/** Render the per-pair status table + summary line as agent-ready markdown.
- *  Shown for both the clean and the conflict exit so the caller always sees the
- *  full partition. */
-function renderSync(results, summary, dryRun) {
-    const parts = [];
-    parts.push(dryRun
-        ? 'crtr ↔ Claude skill sync — DRY RUN (nothing written):'
-        : 'crtr ↔ Claude skill sync:');
-    if (results.length === 0) {
-        parts.push('No enrolled pairs.');
+import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
+import { pathExists, readJsonIfExists, readText, walkFiles, writeJson, writeText } from '../../core/fs-utils.js';
+import { findProjectScopeRoot, scopeMemoryDir } from '../../core/scope.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';
+function projectDir() {
+    const root = findProjectScopeRoot();
+    return root ? dirname(root) : null;
+}
+function ignoreFilePath() {
+    return join(homedir(), '.crouter', IGNORE_FILE);
+}
+function defaultSourceRoots() {
+    const roots = [
+        { label: 'claude-user', root: join(homedir(), '.claude', 'skills'), defaultScope: 'user' },
+        { label: 'pi-user', root: join(homedir(), '.pi', 'agent', 'skills'), defaultScope: 'user' },
+    ];
+    const proj = projectDir();
+    if (proj) {
+        roots.push({ label: 'claude-project', root: join(proj, '.claude', 'skills'), defaultScope: 'project' });
+        roots.push({ label: 'pi-project', root: join(proj, '.pi', 'agent', 'skills'), defaultScope: 'project' });
+    }
+    return roots;
+}
+function sourceRootsFromArg(sourceArg, scopeArg) {
+    if (sourceArg === undefined)
+        return defaultSourceRoots();
+    const root = resolve(sourceArg);
+    if (scopeArg !== undefined && scopeArg !== 'user' && scopeArg !== 'project') {
+        resolveWriteTarget(scopeArg);
+    }
+    return [{ label: 'source', root, defaultScope: scopeArg ?? 'user' }];
+}
+function collectCandidates(rootDef) {
+    const root = rootDef.root;
+    if (!existsSync(root))
+        return [];
+    const statRoot = resolve(root);
+    const candidates = [];
+    if (basename(statRoot) === HOST_SKILL_FILE) {
+        candidates.push({ path: statRoot, root: dirname(statRoot), source: rootDef.label, defaultScope: rootDef.defaultScope });
+        return candidates;
+    }
+    const directSkill = join(statRoot, HOST_SKILL_FILE);
+    if (existsSync(directSkill)) {
+        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)) {
+        candidates.push({ path: file, root: statRoot, source: rootDef.label, defaultScope: rootDef.defaultScope });
+    }
+    return candidates;
+}
+function scalarString(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return undefined;
+}
+function cleanClause(s) {
+    let out = s.replace(/\s+/g, ' ').trim();
+    out = out.replace(/^[,;:.\s]+/, '').replace(/[,;:.\s]+$/, '');
+    if (/^[A-Z][a-z]/.test(out))
+        out = out.charAt(0).toLowerCase() + out.slice(1);
+    return out;
+}
+const USE_WHEN_RE = /\b(?:use\s+this\s+skill\s+when|use\s+this\s+when|this\s+skill\s+should\s+be\s+used\s+when|used\s+when|use\s+when)\b\s*/i;
+function routeFromDescription(description, kind) {
+    const desc = description.replace(/\s+/g, ' ').trim();
+    if (desc === '')
+        return `When this migrated ${kind} applies, this ${kind} should be read.`;
+    const m = desc.match(USE_WHEN_RE);
+    if (m && m.index !== undefined) {
+        const gist = cleanClause(desc.slice(0, m.index));
+        const situation = cleanClause(desc.slice(m.index + m[0].length));
+        if (situation !== '') {
+            let out = `When ${situation}, this ${kind} should be read`;
+            if (gist !== '')
+                out += ` because ${gist}`;
+            return `${out}.`;
+        }
+    }
+    return `When ${cleanClause(desc)}, this ${kind} should be read.`;
+}
+function normalizedName(raw) {
+    const segments = raw
+        .replace(/\\/g, '/')
+        .replace(/\.md$/i, '')
+        .split('/')
+        .map((s) => s.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, ''))
+        .filter(Boolean);
+    return segments.join('/');
+}
+function nameForCandidate(candidate, fm) {
+    const fmName = scalarString(fm?.name);
+    if (fmName && fmName.trim() !== '')
+        return normalizedName(fmName);
+    const relDir = relative(candidate.root, dirname(candidate.path)).split(sep).join('/');
+    return normalizedName(relDir || basename(dirname(candidate.path)));
+}
+function targetMemoryDir(scope) {
+    const dir = scopeMemoryDir(scope);
+    if (!dir)
+        return resolveWriteTarget(scope).memoryDir;
+    return dir;
+}
+function readIgnoreState() {
+    let doc;
+    try {
+        doc = readJsonIfExists(ignoreFilePath());
     }
-    else {
-        const rows = results
-            .map((r) => `| ${r.id} | ${r.status} | ${r.wrote} |`)
-            .join('\n');
-        parts.push(`| pair | status | wrote |\n| --- | --- | --- |\n${rows}`);
+    catch (e) {
+        throw usage(`invalid JSON in ${ignoreFilePath()}: ${e instanceof Error ? e.message : String(e)}`);
     }
-    parts.push(`synced: ${summary.synced.length} · conflicts: ${summary.conflicts.length} · ` +
-        `noop: ${summary.noop.length} · files written: ${summary.wrote}`);
-    if (summary.conflicts.length > 0) {
-        parts.push(`Conflicts (NOT written): ${summary.conflicts.join(', ')}. ` +
-            'Each conflicting pair has a git-style report under ' +
-            '`~/.crouter/skill-sync/conflicts/<id>.md` — resolve the endpoints by hand, then re-run.');
+    if (doc === null)
+        return { version: 1, ignored: [] };
+    if (typeof doc !== 'object' ||
+        doc === null ||
+        doc.version !== 1 ||
+        !Array.isArray(doc.ignored)) {
+        throw usage(`malformed ${ignoreFilePath()}: expected {"version":1,"ignored":[...]}`);
     }
-    return parts.join('\n\n');
-}
-/** Drift label for the read-only `--status` view, derived from a dry-run
- *  reconcile: `noop` = already in agreement, `synced` = a clean merge the engine
- *  WOULD write, `conflict` = diverged and blocked. These are the only three
- *  statuses `reconcilePair` returns. */
-const DRIFT = {
-    noop: 'in-sync',
-    synced: 'would-write',
-    conflict: 'conflict',
-};
-/** Render one endpoint as `scope/name` (or `<scope>:<plugin>/<name>` for a
- *  plugin-scoped side) so a reader sees where each half of the pair lives. */
-function endpointLabel(ep) {
-    return ep.scope === 'plugin' || ep.scope === 'claude-plugin'
-        ? `${ep.scope}:${ep.plugin}/${ep.name}`
-        : `${ep.scope}/${ep.name}`;
-}
-/** Render the read-only `--status` inventory: every selected pair with its
- *  crtr↔Claude endpoints and drift state, computed via a dry-run reconcile so
- *  nothing is written. `results` is keyed back to `pairs` by id. */
-function renderStatus(pairs, results) {
-    const parts = [];
-    parts.push('crtr ↔ Claude skill-sync pairs (read-only; nothing written):');
-    if (pairs.length === 0) {
-        parts.push('No enrolled pairs.');
-        return parts.join('\n\n');
+    const ignored = [];
+    for (const entry of doc.ignored) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const e = entry;
+        if (typeof e.source === 'string' &&
+            typeof e.name === 'string' &&
+            (e.scope === 'user' || e.scope === 'project') &&
+            typeof e.ignoredAt === 'string') {
+            ignored.push({ source: resolve(e.source), name: e.name, scope: e.scope, ignoredAt: e.ignoredAt });
+        }
     }
-    const byId = new Map(results.map((r) => [r.id, r]));
-    const rows = pairs
-        .map((p) => {
-        const drift = DRIFT[byId.get(p.id).status];
-        return `| ${p.id} | ${endpointLabel(p.crtr)} | ${endpointLabel(p.claude)} | ${drift} |`;
-    })
-        .join('\n');
-    parts.push(`| pair | crtr | claude | drift |\n| --- | --- | --- | --- |\n${rows}`);
-    const inSync = results.filter((r) => r.status === 'noop').length;
-    const wouldWrite = results.filter((r) => r.status === 'synced').length;
-    const conflict = results.filter((r) => r.status === 'conflict').length;
-    parts.push(`in-sync: ${inSync} · would-write: ${wouldWrite} · conflict: ${conflict}`);
-    return parts.join('\n\n');
+    return { version: 1, ignored };
+}
+function writeIgnoreState(state) {
+    writeJson(ignoreFilePath(), state);
+}
+function isIgnored(prepared, state) {
+    const source = resolve(prepared.candidate.path);
+    return state.ignored.some((entry) => entry.source === source ||
+        (entry.scope === prepared.scope && entry.name === prepared.name));
+}
+function rememberIgnored(prepared, state) {
+    if (isIgnored(prepared, state))
+        return false;
+    state.ignored.push({
+        source: resolve(prepared.candidate.path),
+        name: prepared.name,
+        scope: prepared.scope,
+        ignoredAt: new Date().toISOString(),
+    });
+    state.ignored.sort((a, b) => `${a.scope}/${a.name}`.localeCompare(`${b.scope}/${b.name}`));
+    return true;
+}
+function skipResult(candidate, scope, reason) {
+    return { source: candidate.path, target: '', name: '', scope, status: 'skipped', reason };
+}
+function prepareCandidate(candidate, scopeOverride) {
+    const raw = readText(candidate.path);
+    const scope = scopeOverride ?? candidate.defaultScope;
+    if (raw.includes(LEGACY_BOOT_SKILL_MARKER_PREFIX)) {
+        return skipResult(candidate, scope, 'legacy generated crtr boot skill is pruned by host exports, not imported');
+    }
+    const parsed = parseFrontmatterGeneric(raw);
+    const sourceFm = parsed.data ?? {};
+    const kind = sourceFm.kind === 'preference' ? 'preference' : 'knowledge';
+    const name = nameForCandidate(candidate, sourceFm);
+    if (name === '')
+        return skipResult(candidate, scope, 'could not derive memory document name');
+    const memoryDir = targetMemoryDir(scope);
+    const target = memoryFilePath(memoryDir, name);
+    return { candidate, raw, parsed, sourceFm, kind, name, scope, target };
+}
+function convertPrepared(prepared, opts) {
+    if (pathExists(prepared.target) && !opts.overwrite) {
+        return {
+            source: prepared.candidate.path,
+            target: prepared.target,
+            name: prepared.name,
+            scope: prepared.scope,
+            status: 'skipped',
+            reason: 'target memory doc already exists; re-run with --overwrite to replace it',
+        };
+    }
+    const description = scalarString(prepared.sourceFm.description) ?? '';
+    const frontmatter = { ...prepared.sourceFm };
+    delete frontmatter.name;
+    delete frontmatter.description;
+    delete frontmatter.type;
+    delete frontmatter.keywords;
+    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);
+    }
+    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 (!opts.dryRun)
+        writeText(prepared.target, serializeMemoryDoc(frontmatter, prepared.parsed.body));
+    return {
+        source: prepared.candidate.path,
+        target: prepared.target,
+        name: prepared.name,
+        scope: prepared.scope,
+        status: opts.dryRun ? 'would-import' : 'imported',
+    };
+}
+function ignoreResult(prepared, reason, dryRun) {
+    return {
+        source: prepared.candidate.path,
+        target: prepared.target,
+        name: prepared.name,
+        scope: prepared.scope,
+        status: dryRun ? 'would-ignore' : 'ignored',
+        reason,
+    };
+}
+function renderSummary(results, ignoreMode) {
+    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;
+    const ignored = results.filter((r) => r.status === 'ignored').length;
+    const wouldIgnore = results.filter((r) => r.status === 'would-ignore').length;
+    let header;
+    if (ignoreMode)
+        header = `crtr sys sync — ${wouldIgnore > 0 ? `${wouldIgnore} would ignore` : `${ignored} ignored`}, ${skipped} skipped`;
+    else if (wouldImport > 0)
+        header = `crtr sys sync — dry run: ${wouldImport} would import, ${skipped} skipped, ${ignored} ignored`;
+    else
+        header = `crtr sys sync — ${imported} imported, ${skipped} skipped, ${ignored} ignored`;
+    const rows = results.map((r) => {
+        const target = r.target || '—';
+        const reason = r.reason ? ` (${r.reason})` : '';
+        return `| ${r.status} | ${r.scope}/${r.name || '—'} | ${target} | ${r.source}${reason} |`;
+    });
+    const body = rows.length === 0
+        ? ['No sync candidates.']
+        : ['| status | memory doc | target | source |', '| --- | --- | --- | --- |', ...rows];
+    return [header, '', ...body].join('\n');
 }
 export const sysSyncLeaf = defineLeaf({
     name: 'sync',
-    description: 'reconcile crtr ↔ Claude skill pairs (bidirectional)',
-    whenToUse: 'you want enrolled crtr skills and their Claude SKILL.md counterparts brought back into agreement. Performs the single, direction-agnostic 3-way reconcile over every pair in the skill-sync manifest (or just one via --pair), writing both sides + the merge base when clean and a conflict report when not.',
+    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.',
     help: {
         name: 'sys sync',
-        summary: 'reconcile enrolled crtr ↔ Claude skill pairs (bidirectional 3-way merge)',
+        summary: 'one-way import: SKILL.md bundles → crouter memory docs',
         params: [
-            {
-                kind: 'flag',
-                name: 'pair',
-                type: 'string',
-                required: false,
-                constraint: 'Reconcile only the pair with this id. Unknown id → hard error naming it + the valid ids, nothing written. Default: every enrolled pair.',
-            },
-            {
-                kind: 'flag',
-                name: 'dry-run',
-                type: 'bool',
-                required: false,
-                constraint: 'Compute every merge and report the would-be status, but write nothing — no endpoint, snapshot, or conflict report touched.',
-            },
-            {
-                kind: 'flag',
-                name: 'status',
-                type: 'bool',
-                required: false,
-                constraint: 'Read-only inventory mode: instead of reconciling, list every enrolled pair (honoring --pair) with its crtr↔Claude endpoints and drift state (in-sync / would-write / conflict), computed via a dry-run reconcile. Writes nothing and never exits non-zero on drift; a malformed manifest or unknown --pair id still aborts hard.',
-            },
+            { 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: '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.' },
         ],
         output: [
-            { name: 'synced', type: 'string[]', required: true, constraint: 'Pair ids written through cleanly to both endpoints + the merge base.' },
-            { name: 'conflicts', type: 'string[]', required: true, constraint: 'Pair ids that diverged and were NOT written; each has a report under ~/.crouter/skill-sync/conflicts/<id>.md. Non-empty → exit non-zero.' },
-            { name: 'noop', type: 'string[]', required: true, constraint: 'Pair ids already in agreement — nothing to do.' },
-            { name: 'wrote', type: 'number', required: true, constraint: 'Total endpoint files created/updated across all pairs (0 under --dry-run).' },
+            { 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: '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.' },
         ],
         outputKind: 'object',
         effects: [
-            'For each clean pair: writes the merged SKILL.md + assets to BOTH the crtr and Claude endpoints and updates the per-pair merge snapshot under ~/.crouter/skill-sync/snapshots/<id>/.',
-            'For each conflicting pair: writes NOTHING to the endpoints; writes a git-style conflict report to ~/.crouter/skill-sync/conflicts/<id>.md.',
-            'Exits non-zero iff any pair conflicted. A malformed manifest or an unknown --pair id aborts hard (non-zero) before any reconcile and writes nothing.',
-            'With --dry-run: read-only — computes every merge and the would-be summary, touches no endpoint, snapshot, or report.',
-            'With --status: read-only — emits the pair inventory + drift table (in-sync / would-write / conflict) instead of reconciling; writes nothing and exits zero regardless of drift.',
+            'Writes memory/<name>.md in the selected crouter scope with substrate frontmatter and the SKILL.md body.',
+            '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 --dry-run: read-only; writes nothing.',
         ],
     },
     run: async (input) => {
-        const pairFilter = input['pair'];
+        const sourceArg = input['source'];
+        const scopeArg = input['scope'];
         const dryRun = input['dryRun'] ?? false;
-        const statusMode = input['status'] ?? false;
-        // Malformed manifest throws here (R-U7) → dispatcher's handle() → non-zero.
-        const { pairs } = readLayeredManifest();
-        let selected = pairs;
-        if (pairFilter !== undefined) {
-            selected = pairs.filter((p) => p.id === pairFilter);
-            if (selected.length === 0) {
-                // OD-3 / R-O2 — unknown id aborts hard, naming the bad id + valid ids,
-                // nothing written.
-                const valid = pairs.map((p) => p.id);
-                throw usage(`unknown pair id: ${pairFilter}`, {
-                    received: pairFilter,
-                    next: `Valid pair ids: ${valid.length > 0 ? valid.join(', ') : '(none)'}. Run \`crtr sys sync -h\`.`,
-                });
+        const overwrite = input['overwrite'] ?? false;
+        const ignoreMode = input['ignore'] ?? false;
+        const includeIgnored = input['includeIgnored'] ?? false;
+        const roots = sourceRootsFromArg(sourceArg, scopeArg);
+        const seen = new Set();
+        const candidates = [];
+        for (const root of roots) {
+            for (const c of collectCandidates(root)) {
+                if (seen.has(c.path))
+                    continue;
+                seen.add(c.path);
+                candidates.push(c);
             }
         }
-        // --status: read-only inventory. Run the same engine in dry-run mode and
-        // render endpoints + drift; never write, never exit non-zero on drift.
-        if (statusMode) {
-            const results = selected.map((p) => reconcilePair(p, resolveProfile(p.frontmatter), { dryRun: true }));
-            if (isJsonOutput()) {
-                emit({
-                    pairs: selected.map((p, i) => ({
-                        id: p.id,
-                        crtr: p.crtr,
-                        claude: p.claude,
-                        drift: DRIFT[results[i].status],
-                    })),
-                });
+        const ignoreState = readIgnoreState();
+        const results = [];
+        let changedIgnoreState = false;
+        for (const candidate of candidates) {
+            const prepared = prepareCandidate(candidate, scopeArg);
+            if ('status' in prepared) {
+                results.push(prepared);
+                continue;
             }
-            else {
-                process.stdout.write(renderStatus(selected, results) + '\n');
+            if (ignoreMode) {
+                if (!dryRun)
+                    changedIgnoreState = rememberIgnored(prepared, ignoreState) || changedIgnoreState;
+                results.push(ignoreResult(prepared, dryRun ? 'would record permanent ignore' : `recorded in ~/.crouter/${IGNORE_FILE}`, dryRun));
+                continue;
             }
-            process.exit(ExitCode.SUCCESS);
-        }
-        // One conflict must NOT abort the loop (R-X3): collect every pair's result,
-        // partition, then decide the exit code once. A structural error (an
-        // unresolvable endpoint, both sides missing) is a hard config fault and is
-        // allowed to propagate — only content conflicts are a collected outcome.
-        const results = [];
-        for (const pair of selected) {
-            const profile = resolveProfile(pair.frontmatter);
-            results.push(reconcilePair(pair, profile, { dryRun }));
-        }
-        const summary = {
-            synced: results.filter((r) => r.status === 'synced').map((r) => r.id),
-            conflicts: results.filter((r) => r.status === 'conflict').map((r) => r.id),
-            noop: results.filter((r) => r.status === 'noop').map((r) => r.id),
-            wrote: results.reduce((n, r) => n + r.wrote, 0),
-        };
-        if (isJsonOutput()) {
-            emit(summary);
-        }
-        else {
-            process.stdout.write(renderSync(results, summary, dryRun) + '\n');
+            if (isIgnored(prepared, ignoreState)) {
+                if (includeIgnored)
+                    results.push(ignoreResult(prepared, `matched ~/.crouter/${IGNORE_FILE}`, false));
+                continue;
+            }
+            results.push(convertPrepared(prepared, { dryRun, overwrite }));
         }
-        // R-E7 — exit non-zero IFF a conflict was surfaced.
-        process.exit(summary.conflicts.length > 0 ? ExitCode.GENERAL : ExitCode.SUCCESS);
+        if (changedIgnoreState)
+            writeIgnoreState(ignoreState);
+        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;
+        const ignored = results.filter((r) => r.status === 'ignored').length;
+        const wouldIgnore = results.filter((r) => r.status === 'would-ignore').length;
+        return { imported, wouldImport, skipped, ignored, wouldIgnore, results, ignoreFile: ignoreFilePath(), ignoreMode };
     },
+    render: (result) => renderSummary(result.results, result.ignoreMode === true),
 });

package/dist/commands/sys/sysprompt.d.ts

@@ -0,0 +1 @@
+export declare const sysSyspromptLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/sys/sysprompt.js

@@ -0,0 +1,89 @@
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { getNode, jobDir } from '../../core/canvas/index.js';
+import { focusOf, openNodeWindow } from '../../core/runtime/placement.js';
+function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+export const sysSyspromptLeaf = defineLeaf({
+    name: 'sysprompt',
+    description: 'print a node\'s assembled system prompt',
+    whenToUse: 'you want to inspect a node\'s assembled system prompt headlessly, without paying conversation/context cost — the broker writes it to disk while live, and this command reads that artifact back as markdown.',
+    help: {
+        name: 'sys sysprompt',
+        summary: 'print a node\'s assembled system prompt',
+        params: [
+            { kind: 'positional', name: 'node', required: false, constraint: 'Node id. Defaults to the calling node (CRTR_NODE_ID).' },
+            { kind: 'flag', name: 'window', type: 'bool', required: false, constraint: 'Open the assembled prompt in a NEW tmux window in the session currently showing that node instead of printing to stdout.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The node whose prompt was read.' },
+            { name: 'captured_at', type: 'string', required: true, constraint: 'File mtime in ISO-8601 UTC.' },
+            { name: 'chars', type: 'number', required: true, constraint: 'Character count of the stored prompt.' },
+            { name: 'prompt', type: 'string', required: true, constraint: 'The assembled system prompt, exactly as pi built it.' },
+            { name: 'session', type: 'string', required: false, constraint: 'tmux session showing the node (only when --window is used).' },
+            { name: 'window', type: 'string', required: false, constraint: 'tmux window opened for the prompt (only when --window is used).' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only: reads the node\'s job/system-prompt.md artifact, or opens it in a tmux window.'],
+        // Giant prompt dump / machine payload for an agent to inspect deliberately,
+        // not to glance at inline — collapse it in the attach viewer by default.
+        preview: { suppressOutput: true },
+    },
+    run: async (input) => {
+        const nodeId = input['node']?.trim() || process.env['CRTR_NODE_ID'];
+        if (nodeId === undefined || nodeId === '') {
+            throw new InputError({ error: 'empty_node', message: 'a node id is required', field: 'node', next: 'Pass a node id or run from inside a node.' });
+        }
+        if (getNode(nodeId) === null) {
+            throw new InputError({ error: 'not_found', message: `no node: ${nodeId}`, field: 'node', next: 'List nodes with `crtr node inspect list`.' });
+        }
+        const path = join(jobDir(nodeId), 'system-prompt.md');
+        if (!existsSync(path)) {
+            throw new InputError({
+                error: 'not_found',
+                message: `system prompt not captured yet for ${nodeId}`,
+                field: 'node',
+                next: 'Focus or revive the node once while its broker is live, then rerun `crtr sys sysprompt <node>`.',
+            });
+        }
+        const prompt = readFileSync(path, 'utf8');
+        const capturedAt = statSync(path).mtime.toISOString();
+        if (input['window'] === true) {
+            const focus = focusOf(nodeId);
+            if (focus === null || focus.session === null || focus.session === '') {
+                throw new InputError({
+                    error: 'not_focused',
+                    message: `node ${nodeId} is not currently shown in tmux`,
+                    field: 'node',
+                    next: `Focus the node first with \`crtr node focus ${nodeId}\`, then rerun \`crtr sys sysprompt --window ${nodeId}\`.`,
+                });
+            }
+            const tmpPath = join(tmpdir(), `crtr-sysprompt-${nodeId}.md`);
+            writeFileSync(tmpPath, prompt, 'utf8');
+            const q = shellQuote(tmpPath);
+            // Syntax-highlight the prompt (markdown + its structural XML tags both stay visible).
+            // bat pages by default; markdown RENDERERS (termrender, glow) are wrong here — they
+            // silently swallow block-level XML tags, dropping most of the assembled prompt.
+            // Fall back to `less -R` when bat is not installed.
+            const command = `if command -v bat >/dev/null 2>&1; then bat --language=markdown --color=always --paging=always --style=plain ${q}; else less -R ${q}; fi`;
+            const opened = openNodeWindow({ session: focus.session, name: `sysprompt:${nodeId}`, cwd: process.cwd(), env: {}, command });
+            if (opened === null) {
+                throw new InputError({
+                    error: 'window_open_failed',
+                    message: `tmux could not open a window for node ${nodeId}`,
+                    field: 'node',
+                    next: 'Check the tmux server is reachable, then retry.',
+                });
+            }
+            return { node_id: nodeId, session: focus.session, window: opened.window };
+        }
+        return { node_id: nodeId, captured_at: capturedAt, chars: prompt.length, prompt };
+    },
+    render: (r) => ('window' in r)
+        ? `Opened system prompt for node ${r['node_id']} in tmux session ${r['session']} — window ${r['window']}.`
+        : `- node_id: ${r['node_id']}\n- captured_at: ${r['captured_at']}\n- chars: ${r['chars']}\n\n${r['prompt']}`,
+});

package/dist/commands/sys.js

@@ -1,9 +1,14 @@
-// `crtr sys` subtree: config {get,set,path}, doctor, update, version.
+// `crtr sys` subtree: config {get,set,path}, doctor, sync, update, version.
 // Replaces old config.ts + doctor.ts + update.ts command files.
 import { defineBranch } from '../core/command.js';
 import { configBranch } from './sys/config.js';
 import { sysDoctorLeaf } from './sys/doctor.js';
 import { sysFeedbackLeaf } from './sys/feedback.js';
+import { sysSettingsLeaf } from './sys/settings.js';
+import { sysSetupLeaf } from './sys/setup.js';
+import { sysSyspromptLeaf } from './sys/sysprompt.js';
+import { promptReviewLeaf } from './sys/prompt-review.js';
+import { sysPromptStudioLeaf } from './sys/promptstudio.js';
 import { sysSyncLeaf } from './sys/sync.js';
 import { sysUpdateLeaf, sysVersionLeaf } from './sys/update.js';
 export function registerSys() {
@@ -11,13 +16,13 @@ export function registerSys() {
         name: 'sys',
         rootEntry: {
             concept: 'crtr configuration, diagnostics, and self-management',
-            desc: 'config, doctor, sync, update, version, feedback',
-            useWhen: 'managing the crtr installation',
+            desc: 'config, settings, setup, doctor, sysprompt, prompt-review, promptstudio, sync, update, version, feedback',
+            useWhen: 'managing the crtr installation or opening built-in system views',
         },
         help: {
             name: 'sys',
-            summary: 'crtr system configuration, diagnostics, and self-management',
+            summary: 'crtr system configuration, settings, diagnostics, and self-management',
         },
-        children: [configBranch, sysDoctorLeaf, sysFeedbackLeaf, sysSyncLeaf, sysUpdateLeaf, sysVersionLeaf],
+        children: [configBranch, sysSettingsLeaf, sysSetupLeaf, sysDoctorLeaf, sysSyspromptLeaf, promptReviewLeaf, sysPromptStudioLeaf, sysFeedbackLeaf, sysUpdateLeaf, sysVersionLeaf, sysSyncLeaf],
     });
 }