@north-light/crouter 0.3.154

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

@@ -0,0 +1,306 @@
+// `crtr sys sync skills` — one-way import of legacy host Agent Skill bundles
+// (SKILL.md) into crouter memory documents. 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 { 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 { CRTR_DIR_NAME } from '../../types.js';
+import { memoryFilePath, resolveWriteTarget, serializeMemoryDoc } from '../memory/shared.js';
+import { normalizedName, routeFromDescription, scalarString } from './sync-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 skill-root walk never descends into — build/dependency trees
+// plus crouter's own state dir.
+const SKILL_WALK_JUNK_DIRS = new Set([
+    'node_modules', '.git', '.venv', 'venv', 'dist', 'build', '.next', '.cache', '.yalc', '.sisyphus', CRTR_DIR_NAME,
+]);
+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, (name) => SKILL_WALK_JUNK_DIRS.has(name))) {
+        candidates.push({ path: file, root: statRoot, source: rootDef.label, defaultScope: rootDef.defaultScope });
+    }
+    return candidates;
+}
+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());
+    }
+    catch (e) {
+        throw usage(`invalid JSON in ${ignoreFilePath()}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    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":[...]}`);
+    }
+    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 });
+        }
+    }
+    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 skills — ${wouldIgnore > 0 ? `${wouldIgnore} would ignore` : `${ignored} ignored`}, ${skipped} skipped`;
+    else if (wouldImport > 0)
+        header = `crtr sys sync skills — dry run: ${wouldImport} would import, ${skipped} skipped, ${ignored} ignored`;
+    else
+        header = `crtr sys sync skills — ${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 sysSyncSkillsLeaf = defineLeaf({
+    name: 'skills',
+    description: 'import host Agent Skill (SKILL.md) bundles as crouter memory docs',
+    whenToUse: 'migrating legacy host-native Agent Skill bundles (SKILL.md — Claude/pi user or project skill roots, or an explicit bundle/root via --source) into the crouter memory-doc model. One-way: crouter never re-exports memory docs back to SKILL.md, and stops reading the originals unconditionally once migrated.',
+    help: {
+        name: 'sys sync skills',
+        summary: 'one-way import: host SKILL.md bundles → 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: the user/project Claude and pi skill roots that exist.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Target memory scope for the selected sources. Default: user for user host roots and project for project host roots; an explicit value applies to every selected 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 SKILL.md 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: 'imported', type: 'number', required: true, constraint: 'Count of memory docs written.' },
+            { name: 'wouldImport', type: 'number', required: true, constraint: 'Count of memory docs that would be written under --dry-run.' },
+            { 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 is one of imported, skipped, would-import, ignored, would-ignore.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            '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 sourceArg = input['source'];
+        const scopeArg = input['scope'];
+        const dryRun = input['dryRun'] ?? false;
+        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);
+            }
+        }
+        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;
+            }
+            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;
+            }
+            if (isIgnored(prepared, ignoreState)) {
+                if (includeIgnored)
+                    results.push(ignoreResult(prepared, `matched ~/.crouter/${IGNORE_FILE}`, false));
+                continue;
+            }
+            results.push(convertPrepared(prepared, { dryRun, overwrite }));
+        }
+        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/sync.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../../core/command.js';
+export declare const sysSyncBranch: BranchDef;

package/dist/commands/sys/sync.js

@@ -0,0 +1,18 @@
+// `crtr sys sync` — the migration branch: three independent, one-way
+// conversion lanes from non-crouter guidance surfaces into crouter memory
+// docs. See each child leaf for its exact source/target/effects contract.
+import { defineBranch } from '../../core/command.js';
+import { sysSyncSkillsLeaf } from './sync-skills.js';
+import { sysSyncProjectGuidanceLeaf } from './sync-project-guidance.js';
+import { sysSyncDepsLeaf } from './sync-deps.js';
+export const sysSyncBranch = defineBranch({
+    name: 'sync',
+    description: 'migrate non-crouter guidance surfaces into crouter memory docs',
+    whenToUse: 'importing or migrating an external guidance source — host Agent Skill bundles, project CLAUDE.md/AGENTS.md/.claude/rules, or npm-dependency-shipped Agent Skill bundles — into the crouter memory-doc model',
+    help: {
+        name: 'sys sync',
+        summary: 'migrate external guidance sources into crouter memory docs',
+        model: "Three independent one-way conversion lanes, none of which ever export memory docs back to their source: skills imports host-native SKILL.md bundles into a scope-root memory dir; project-guidance migrates a project's own CLAUDE.md/AGENTS.md/.claude/rules into that same directory's OWN .crouter/memory/; deps vendors Agent Skill bundles shipped inside installed npm dependencies into the owning project's .crouter/memory/deps/ as wholly derived, regenerated-per-run docs.",
+    },
+    children: [sysSyncSkillsLeaf, sysSyncProjectGuidanceLeaf, sysSyncDepsLeaf],
+});

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,97 @@
+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 { jobDir } from '../../core/canvas/paths.js';
+import { openNodeWindow } from '../../core/runtime/placement-tmux.js';
+import { ApiError } from '../../api/index.js';
+import { cliClient } from '../api-client.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.' });
+        }
+        try {
+            await cliClient().getNode(nodeId);
+        }
+        catch (err) {
+            if (err instanceof ApiError && err.status === 404) {
+                throw new InputError({ error: 'not_found', message: `no node: ${nodeId}`, field: 'node', next: 'List nodes with `crtr node inspect list`.' });
+            }
+            throw err;
+        }
+        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 = await cliClient().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 surface 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/update.d.ts

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

package/dist/commands/sys/update.js

@@ -0,0 +1,139 @@
+import { defineLeaf } from '../../core/command.js';
+import { updateState } from '../../core/config.js';
+import { projectScopeRoot } from '../../core/scope.js';
+import { selfCheck, selfUpdate, contentCheck, contentUpdate } from '../../core/self-update.js';
+import { nowIso } from '../../core/fs-utils.js';
+import { processLocatedGeneration, readPackageVersion, runtimeManifest, selectedGeneration } from './shared.js';
+export const sysUpdateLeaf = defineLeaf({
+    name: 'update',
+    description: 'update binary and content',
+    whenToUse: 'upgrading crtr or its installed plugins and marketplaces — pull the latest binary, refresh installed content, or both, or just check what is out of date without applying anything.',
+    help: {
+        name: 'sys update',
+        summary: 'update the crtr binary and/or installed plugins and marketplaces',
+        params: [
+            { kind: 'flag', name: 'target', type: 'enum', choices: ['self', 'content', 'all'], required: false, constraint: "What to update. Default: all." },
+            { kind: 'flag', name: 'check', type: 'bool', required: false, constraint: 'Check for updates without applying them (bounded, blocking).' },
+        ],
+        output: [
+            { name: 'target', type: 'string', required: false, constraint: 'Present when applying updates: self | content | all.' },
+            { name: 'status', type: 'string', required: false, constraint: 'done | failed when applying updates.' },
+            { name: 'error', type: 'string', required: false, constraint: 'Failure message when status is failed.' },
+            { name: 'updates', type: 'object[]', required: false, constraint: 'Present when --check. Each: {name, current, latest, up_to_date, unreachable, kind}.' },
+            { name: 'up_to_date', type: 'boolean', required: false, constraint: 'Present when --check. True when all items are up to date.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            '--check — read-only, bounded network calls.',
+            'Default (no --check) — launches a background job; returns job handle immediately.',
+        ],
+    },
+    run: async (input) => {
+        const target = input['target'];
+        const check = input['check'];
+        const resolvedTarget = target !== undefined ? target : 'all';
+        if (check) {
+            // Bounded blocking path: collect check results and return
+            const updates = [];
+            if (resolvedTarget === 'self' || resolvedTarget === 'all') {
+                const r = selfCheck();
+                if (r !== null) {
+                    updates.push({
+                        name: '@north-light/crouter',
+                        kind: 'self',
+                        current: r.current,
+                        latest: r.latest,
+                        up_to_date: r.current === r.latest,
+                        unreachable: false,
+                    });
+                }
+                else {
+                    updates.push({
+                        name: '@north-light/crouter',
+                        kind: 'self',
+                        current: null,
+                        latest: null,
+                        up_to_date: true,
+                        unreachable: true,
+                    });
+                }
+            }
+            if (resolvedTarget === 'content' || resolvedTarget === 'all') {
+                const entries = contentCheck();
+                for (const e of entries) {
+                    updates.push({
+                        name: e.name,
+                        kind: e.kind,
+                        current: e.current,
+                        latest: e.latest,
+                        up_to_date: e.up_to_date,
+                        unreachable: e.unreachable,
+                    });
+                }
+            }
+            const up_to_date = updates.every((u) => u.up_to_date || u.unreachable);
+            return { updates: updates, up_to_date };
+        }
+        // Apply path — run synchronously (selfUpdate/contentUpdate are sync spawns).
+        try {
+            if (resolvedTarget === 'self' || resolvedTarget === 'all') {
+                selfUpdate();
+                const scopes = ['user'];
+                if (projectScopeRoot())
+                    scopes.unshift('project');
+                for (const scope of scopes) {
+                    updateState(scope, (s) => {
+                        s.last_self_check = nowIso();
+                    });
+                }
+            }
+            if (resolvedTarget === 'content' || resolvedTarget === 'all') {
+                contentUpdate();
+            }
+            return { target: resolvedTarget, status: 'done' };
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return { target: resolvedTarget, status: 'failed', error: msg };
+        }
+    },
+});
+export const sysVersionLeaf = defineLeaf({
+    name: 'version',
+    description: 'print installed version',
+    whenToUse: 'you need the installed crtr version — to report it in a bug or confirm an upgrade landed.',
+    help: {
+        name: 'sys version',
+        summary: 'report selected and process runtime generations',
+        params: [],
+        output: [
+            { name: 'version', type: 'string', required: true, constraint: 'Version from this process generation manifest; package.json version in a development checkout.' },
+            { name: 'selected_generation', type: 'object', required: true, constraint: 'Selected runtime generation: {id, version, status}; id/version are null when no selection exists.' },
+            { name: 'process_generation', type: 'object', required: true, constraint: 'Generation containing this loaded module: {id, version, status}; id/version are null in a development checkout.' },
+            { name: 'drift', type: 'boolean', required: true, constraint: 'True when selected and process generation ids differ.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (_input) => {
+        const describe = (lookup) => {
+            if (lookup.generation === null)
+                return { id: null, version: null, status: lookup.error ?? 'no runtime generation' };
+            const { id, manifest } = lookup.generation;
+            const shape = runtimeManifest.validateManifestShape(manifest, { id, entryName: 'cli' });
+            return {
+                id,
+                version: typeof manifest.packageVersion === 'string' ? manifest.packageVersion : null,
+                status: shape.ok ? 'valid' : shape.error,
+            };
+        };
+        const selected = describe(selectedGeneration());
+        const process = describe(processLocatedGeneration());
+        return {
+            version: process.version ?? readPackageVersion(),
+            selected_generation: selected,
+            process_generation: process,
+            drift: selected.id !== null && process.id !== null && selected.id !== process.id,
+        };
+    },
+});

package/dist/commands/sys.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerSys(): BranchDef;

package/dist/commands/sys.js

@@ -0,0 +1,30 @@
+// `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 { daemonBranch } from './sys/daemon.js';
+import { sysDoctorLeaf } from './sys/doctor.js';
+import { sysFeedbackLeaf } from './sys/feedback.js';
+import { sysLogsLeaf } from './sys/logs.js';
+import { sysSetupLeaf } from './sys/setup.js';
+import { supportBranch } from './sys/support.js';
+import { sysSyspromptLeaf } from './sys/sysprompt.js';
+import { promptReviewLeaf } from './sys/prompt-review.js';
+import { sysPromptStudioLeaf } from './sys/promptstudio.js';
+import { sysSyncBranch } from './sys/sync.js';
+import { sysUpdateLeaf, sysVersionLeaf } from './sys/update.js';
+export function registerSys() {
+    return defineBranch({
+        name: 'sys',
+        rootEntry: {
+            concept: 'crtr configuration, diagnostics, and self-management',
+            desc: 'config, setup, doctor, sysprompt, prompt-review, promptstudio, sync, update, version, feedback, logs, support, daemon',
+            useWhen: 'managing the crtr installation, the crtrd supervisor process, or opening built-in system views',
+        },
+        help: {
+            name: 'sys',
+            summary: 'crtr system configuration, settings, diagnostics, and self-management',
+        },
+        children: [configBranch, sysSetupLeaf, sysDoctorLeaf, sysSyspromptLeaf, promptReviewLeaf, sysPromptStudioLeaf, sysFeedbackLeaf, sysLogsLeaf, supportBranch, sysUpdateLeaf, sysVersionLeaf, sysSyncBranch, daemonBranch],
+    });
+}

package/dist/commands/view-cycle.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const viewCycleLeaf: LeafDef;