@crouton-kit/crouter 0.3.31 → 0.3.33

package/dist/commands/search/puremd.js

@@ -0,0 +1,53 @@
+// Fallback content fetcher: when Exa cannot fetch a URL, we re-fetch it through
+// pure.md (https://pure.md), which renders any page to clean markdown. This is
+// the ONLY module that talks to pure.md. API-key resolution is optional — the
+// service works keyless (rate-limited); a key raises limits.
+import { join } from 'node:path';
+import { readFileSync, existsSync } from 'node:fs';
+import { userScopeRoot } from '../../core/scope.js';
+const PUREMD_BASE = 'https://pure.md';
+/** Resolve an optional pure.md API token: PUREMD_API_KEY env first, then
+ *  ~/.crouter/puremd.key. Returns undefined when neither is set — pure.md is
+ *  usable keyless, so a missing token is not an error. */
+function getApiKey() {
+    const env = process.env['PUREMD_API_KEY'];
+    if (env !== undefined && env.trim() !== '')
+        return env.trim();
+    const keyFile = join(userScopeRoot(), 'puremd.key');
+    if (existsSync(keyFile)) {
+        const fromFile = readFileSync(keyFile, 'utf8').trim();
+        if (fromFile !== '')
+            return fromFile;
+    }
+    return undefined;
+}
+/** Fetch a single URL's content as markdown via pure.md, capped at maxChars.
+ *  Never throws — any transport or HTTP failure becomes { ok: false, reason }
+ *  so the caller can keep the URL in its failures list. */
+export async function puremdFetch(url, maxChars) {
+    const headers = {};
+    const key = getApiKey();
+    if (key !== undefined)
+        headers['x-puremd-api-token'] = key;
+    let res;
+    try {
+        res = await fetch(`${PUREMD_BASE}/${url}`, { headers });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, reason: `pure.md request failed: ${msg}` };
+    }
+    if (!res.ok) {
+        return { ok: false, reason: `pure.md returned ${res.status} ${res.statusText}` };
+    }
+    let text;
+    try {
+        text = (await res.text()).trim();
+    }
+    catch {
+        return { ok: false, reason: 'pure.md response body unreadable' };
+    }
+    if (text === '')
+        return { ok: false, reason: 'pure.md returned empty content' };
+    return { ok: true, text: text.slice(0, maxChars) };
+}

package/dist/commands/search/web.d.ts

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

package/dist/commands/search/web.js

@@ -0,0 +1,65 @@
+import { defineLeaf } from '../../core/command.js';
+import { exaSearch, parseDomains, renderResult, TEXT_MAX_CHARACTERS, } from './exa.js';
+const SEARCH_TYPES = ['auto', 'fast', 'instant', 'deep-lite', 'deep', 'deep-reasoning'];
+export const webLeaf = defineLeaf({
+    name: 'web',
+    description: 'find web pages relevant to a query, with highlight excerpts',
+    whenToUse: 'you need to discover web pages relevant to a query and read query-matched excerpts from them — the default web search. Use this for open-ended research, finding sources, or gathering current information. Reach for `answer` instead when you want one synthesized, cited answer to a specific question rather than a ranked list of pages; reach for `contents` when you already hold the URLs and only need their content.',
+    help: {
+        name: 'search web',
+        summary: 'web search via Exa — ranked results with query-relevant highlight excerpts (or full text)',
+        params: [
+            { kind: 'positional', name: 'query', required: true, constraint: 'The search query. Natural language; be specific.' },
+            { kind: 'flag', name: 'type', type: 'enum', choices: [...SEARCH_TYPES], required: false, default: 'auto', constraint: 'Search depth. auto balances relevance and speed; fast/instant trade depth for latency; deep-lite/deep/deep-reasoning run multi-query expansion and rank the combined set for harder synthesis.' },
+            { kind: 'flag', name: 'num', type: 'int', required: false, default: 10, constraint: 'Number of results to return.' },
+            { kind: 'flag', name: 'text', type: 'bool', required: false, constraint: `Return cleaned full page text (capped at ${TEXT_MAX_CHARACTERS} characters per result) instead of highlight excerpts. Off by default; highlights keep token usage predictable.` },
+            { kind: 'flag', name: 'include-domains', type: 'string', required: false, constraint: 'Comma-separated domain allowlist — restrict results to these domains.' },
+            { kind: 'flag', name: 'exclude-domains', type: 'string', required: false, constraint: 'Comma-separated domain blocklist — drop results from these domains.' },
+        ],
+        output: [
+            { name: 'query', type: 'string', required: true, constraint: 'Echo of the query searched.' },
+            { name: 'results', type: 'object[]', required: true, constraint: 'Ranked best-first, each: title, url, published date and author when present, and either highlight excerpts (default) or capped full text (--text).' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next command — fetch full content of a result with `crtr search contents`, or refine the query.' },
+        ],
+        outputKind: 'object',
+        effects: ['Sends one search request to the Exa API (network). No local state changes.'],
+    },
+    run: async (input) => {
+        const query = input['query'];
+        const type = input['type'];
+        const num = input['num'];
+        const wantText = input['text'];
+        const contents = wantText
+            ? { text: { maxCharacters: TEXT_MAX_CHARACTERS } }
+            : { highlights: true };
+        const body = { query, type, numResults: num, contents };
+        const include = parseDomains(input['includeDomains']);
+        const exclude = parseDomains(input['excludeDomains']);
+        if (include !== undefined)
+            body['includeDomains'] = include;
+        if (exclude !== undefined)
+            body['excludeDomains'] = exclude;
+        const res = await exaSearch(body);
+        const results = res.results ?? [];
+        return {
+            query,
+            results,
+            follow_up: 'Fetch the full content of any result with `crtr search contents <url>`. No good hits? Broaden the query, drop domain filters, or try --type deep.',
+        };
+    },
+    render: (result) => {
+        const query = result['query'];
+        const results = result['results'];
+        const followUp = result['follow_up'];
+        if (results.length === 0) {
+            return `No results for "${query}".\n\n${followUp}`;
+        }
+        const lines = [`${results.length} results for "${query}":`, ''];
+        results.forEach((r, i) => {
+            lines.push(renderResult(r, i + 1));
+            lines.push('');
+        });
+        lines.push(followUp);
+        return lines.join('\n');
+    },
+});

package/dist/commands/search.d.ts

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

package/dist/commands/search.js

@@ -0,0 +1,24 @@
+// `crtr search` subtree — web search for agents, backed by the Exa API. Three
+// leaves: web (find pages), answer (one grounded cited answer), contents
+// (extract from URLs you already have). API key resolves from EXA_API_KEY or
+// ~/.crouter/exa.key (see ./search/exa.ts).
+import { defineBranch } from '../core/command.js';
+import { webLeaf } from './search/web.js';
+import { answerLeaf } from './search/answer.js';
+import { contentsLeaf } from './search/contents.js';
+export function registerSearch() {
+    return defineBranch({
+        name: 'search',
+        rootEntry: {
+            concept: 'web search for agents — find pages, get grounded answers, extract page content (Exa)',
+            desc: 'search the web, answer a question with citations, or extract content from known URLs',
+            useWhen: 'you need information from the live web — current events, documentation, sources, facts beyond your training. `crtr search web "<query>"` finds relevant pages with excerpts; `crtr search answer "<question>"` returns one synthesized, cited answer; `crtr search contents <url>` extracts clean content from URLs you already hold. Needs an Exa API key (EXA_API_KEY or ~/.crouter/exa.key).',
+        },
+        help: {
+            name: 'search',
+            summary: 'web search via the Exa API — find pages, answer questions with citations, extract page content',
+            model: 'Three leaves split by what you have and what you want. `web` is the default: a query in, ranked pages out with query-relevant highlight excerpts (or full text with --text) — use it for discovery and research. `answer` collapses a question into one synthesized, source-cited answer — use it when you want the conclusion, not a reading list. `contents` does no searching; it extracts cleaned content from URLs you already hold. Highlights are the default content mode everywhere (token-predictable); full text is opt-in and length-capped. Every leaf needs an Exa API key from EXA_API_KEY or ~/.crouter/exa.key.',
+        },
+        children: [webLeaf, answerLeaf, contentsLeaf],
+    });
+}

package/dist/commands/sys/__tests__/sync-import.test.d.ts

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

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

@@ -0,0 +1,72 @@
+// 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.
+//
+// Run: node --import tsx/esm --test src/commands/sys/__tests__/sync-import.test.ts
+import { afterEach, beforeEach, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { sysSyncLeaf } from '../sync.js';
+import { parseFrontmatterGeneric } from '../../../core/frontmatter.js';
+let home;
+let prevHome;
+beforeEach(() => {
+    prevHome = process.env.HOME;
+    home = mkdtempSync(join(tmpdir(), 'crtr-sys-sync-'));
+    process.env.HOME = home;
+});
+afterEach(() => {
+    if (prevHome === undefined)
+        delete process.env.HOME;
+    else
+        process.env.HOME = prevHome;
+    rmSync(home, { recursive: true, force: true });
+});
+test('imports a SKILL.md bundle as a plain crouter memory doc', async () => {
+    const sourceRoot = join(home, '.claude', 'skills');
+    const bundle = join(sourceRoot, 'demo-skill');
+    mkdirSync(bundle, { recursive: true });
+    writeFileSync(join(bundle, 'SKILL.md'), '---\nname: Demo Skill\ndescription: Handles demos. Use when demo work appears.\n---\n\n# Demo\n\nDo the demo.\n', 'utf8');
+    const result = await sysSyncLeaf.run({ source: sourceRoot, scope: 'user' });
+    assert.equal(result?.imported, 1);
+    const target = join(home, '.crouter', 'memory', 'demo-skill.md');
+    assert.equal(existsSync(target), true);
+    const parsed = parseFrontmatterGeneric(readFileSync(target, 'utf8'));
+    assert.equal(parsed.data?.kind, 'knowledge');
+    assert.equal(parsed.data?.['system-prompt-visibility'], 'preview');
+    assert.equal(parsed.data?.['file-read-visibility'], 'none');
+    assert.equal(parsed.data?.['when-and-why-to-read'], 'When demo work appears, this knowledge should be read because handles demos.');
+    assert.match(parsed.body, /Do the demo\./);
+});
+test('skips generated crtr boot skills instead of importing them', async () => {
+    const bundle = join(home, '.pi', 'agent', 'skills', 'crtr-skills');
+    mkdirSync(bundle, { recursive: true });
+    writeFileSync(join(bundle, 'SKILL.md'), '---\nname: crtr-skills\n---\n\n<!-- crtr-boot-skill v2 -->\n', 'utf8');
+    const result = await sysSyncLeaf.run({ source: bundle, scope: 'user' });
+    assert.equal(result?.imported, 0);
+    assert.equal(result?.skipped, 1);
+    assert.equal(existsSync(join(home, '.crouter', 'memory', 'crtr-skills.md')), false);
+});
+test('permanently ignores selected SKILL.md bundles', async () => {
+    const sourceRoot = join(home, '.claude', 'skills');
+    const bundle = join(sourceRoot, 'ignored-skill');
+    mkdirSync(bundle, { recursive: true });
+    writeFileSync(join(bundle, 'SKILL.md'), '---\nname: Ignored Skill\ndescription: Ignore me. Use when testing ignores.\n---\n\n# Ignore\n', 'utf8');
+    const ignored = await sysSyncLeaf.run({ source: sourceRoot, scope: 'user', ignore: true });
+    assert.equal(ignored?.ignored, 1);
+    assert.equal(existsSync(join(home, '.crouter', 'skill-import-ignore.json')), true);
+    const dry = await sysSyncLeaf.run({ source: sourceRoot, scope: 'user', dryRun: true });
+    assert.equal(dry?.wouldImport, 0);
+    assert.equal((dry?.results).length, 0);
+    const shown = await sysSyncLeaf.run({ source: sourceRoot, scope: 'user', dryRun: true, includeIgnored: true });
+    assert.equal(shown?.ignored, 1);
+    assert.equal((shown?.results)[0].status, 'ignored');
+    const wouldIgnore = await sysSyncLeaf.run({ source: sourceRoot, scope: 'user', dryRun: true, ignore: true });
+    assert.equal(wouldIgnore?.wouldIgnore, 1);
+    assert.equal((wouldIgnore?.results)[0].status, 'would-ignore');
+    const rendered = sysSyncLeaf.render?.(wouldIgnore);
+    assert.notEqual(rendered, undefined);
+    assert.match(rendered, /would ignore/);
+});

package/dist/commands/sys/config.js

@@ -12,7 +12,17 @@ const TOP_LEVEL_KEYS = new Set([
     'plugins',
     'max_panes_per_window',
     'canvasNav',
+    'modelLadders',
+    'personaStrengths',
 ]);
+const MODEL_PROVIDERS = new Set(['anthropic', 'openai']);
+const MODEL_STRENGTHS = new Set(['ultra', 'strong', 'medium', 'light']);
+function isModelProvider(value) {
+    return MODEL_PROVIDERS.has(value);
+}
+function isModelStrength(value) {
+    return MODEL_STRENGTHS.has(value);
+}
 function getNestedValue(obj, key) {
     const parts = key.split('.');
     let current = obj;
@@ -32,7 +42,7 @@ function parseConfigValue(raw) {
         return parseInt(raw, 10);
     return raw;
 }
-function setNestedValue(cfg, key, value) {
+function setNestedValue(cfg, key, rawValue, value) {
     const parts = key.split('.');
     const topKey = parts[0];
     if (!TOP_LEVEL_KEYS.has(topKey)) {
@@ -65,11 +75,50 @@ function setNestedValue(cfg, key, value) {
         // record tables are edited directly in config.json (run `crtr sys config
         // path` to locate it).
         if (key === 'canvasNav.prefixKey') {
-            cfg.canvasNav.prefixKey = String(value);
+            cfg.canvasNav.prefixKey = rawValue;
             return;
         }
         throw usage(`canvasNav.${parts.slice(1).join('.') || '*'} is a record table — edit config.json directly (run \`crtr sys config path\`). Only canvasNav.prefixKey is settable via this command.`);
     }
+    if (topKey === 'modelLadders') {
+        if (parts.length === 2 && parts[1] === 'defaultProvider') {
+            if (!isModelProvider(rawValue)) {
+                throw usage(`modelLadders.defaultProvider must be anthropic or openai`);
+            }
+            cfg.modelLadders.defaultProvider = rawValue;
+            return;
+        }
+        if (parts.length === 3) {
+            const provider = parts[1];
+            const strength = parts[2];
+            if (!isModelProvider(provider)) {
+                throw usage(`modelLadders provider must be anthropic or openai`);
+            }
+            if (!isModelStrength(strength)) {
+                throw usage(`modelLadders strength must be ultra, strong, medium, or light`);
+            }
+            if (rawValue.trim() === '') {
+                throw usage(`modelLadders.${provider}.${strength} cannot be empty`);
+            }
+            cfg.modelLadders[provider][strength] = rawValue;
+            return;
+        }
+        throw usage(`unsupported key path for set: ${key}`);
+    }
+    if (topKey === 'personaStrengths') {
+        if (parts.length !== 2) {
+            throw usage(`unsupported key path for set: ${key}`);
+        }
+        const persona = parts[1];
+        if (persona.trim() === '' || persona !== persona.trim()) {
+            throw usage(`personaStrengths.<persona-kind> must be a non-empty persona kind without leading or trailing whitespace`);
+        }
+        if (!isModelStrength(rawValue)) {
+            throw usage(`personaStrengths.<persona-kind> must be ultra, strong, medium, or light`);
+        }
+        cfg.personaStrengths[persona] = rawValue;
+        return;
+    }
     if (parts.length === 1) {
         cfg[topKey] = value;
         return;
@@ -87,13 +136,13 @@ function setNestedValue(cfg, key, value) {
 const configGet = defineLeaf({
     name: 'get',
     description: 'read a config value by key',
-    whenToUse: 'you want to read a single config value by its dotted key — the current auto_update policy, max_panes_per_window, the canvasNav prefix key — optionally from a specific scope. Use sys config set instead to change a value, sys config path to locate the file for hand-editing.',
+    whenToUse: 'you want to read a single config value by its dotted key — the current auto_update policy, max_panes_per_window, the canvasNav prefix key, model ladders, or persona strengths — optionally from a specific scope. Use sys config set instead to change a value, sys config path to locate the file for hand-editing.',
     help: {
         name: 'sys config get',
         summary: 'read a config value by dotted key',
         params: [
-            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: 'Dotted key path. Top-level keys: auto_update, marketplaces, plugins, max_panes_per_window, canvasNav (read whole; edit canvasNav.prefixBinds/graphBinds in config.json directly).' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project', 'all'], required: false, constraint: 'Scope to read from. Default: user.' },
+            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: 'Dotted key path. Top-level keys: auto_update, marketplaces, plugins, max_panes_per_window, canvasNav, modelLadders, personaStrengths (read whole; edit canvasNav.prefixBinds/graphBinds in config.json directly).' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Scope to read from. Default: user.' },
         ],
         output: [
             { name: 'key', type: 'string', required: true, constraint: 'Echo of input key.' },
@@ -117,12 +166,12 @@ const configGet = defineLeaf({
 const configSet = defineLeaf({
     name: 'set',
     description: 'write a config value by key',
-    whenToUse: 'you want to change a crtr setting — flip auto_update.crtr or auto_update.content to notify, apply, or off, raise max_panes_per_window, rebind canvasNav.prefixKey — written to the user or project scope. Use sys config get instead to read a value; the canvasNav record tables are not settable here, so edit config.json directly (sys config path) for those.',
+    whenToUse: 'you want to change a crtr setting — flip auto_update.crtr or auto_update.content to notify, apply, or off, raise max_panes_per_window, rebind canvasNav.prefixKey, set model ladders, or map persona strengths — written to the user or project scope. Use sys config get instead to read a value; the canvasNav record tables are not settable here, so edit config.json directly (sys config path) for those.',
     help: {
         name: 'sys config set',
         summary: 'write a config value by dotted key',
         params: [
-            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: 'Dotted key path. Supported: auto_update.crtr, auto_update.content, auto_update.interval_hours, max_panes_per_window, canvasNav.prefixKey. The canvasNav.prefixBinds/graphBinds record tables are not settable here — edit config.json directly (`crtr sys config path`).' },
+            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: 'Dotted key path. Supported: auto_update.crtr, auto_update.content, auto_update.interval_hours, max_panes_per_window, canvasNav.prefixKey, modelLadders.defaultProvider, modelLadders.<anthropic|openai>.<ultra|strong|medium|light>, personaStrengths.<persona-kind>. The canvasNav.prefixBinds/graphBinds record tables are not settable here — edit config.json directly (`crtr sys config path`).' },
             { kind: 'flag', name: 'value', type: 'string', required: true, constraint: 'value VALUE — string, required. Stored as-is if quoted; coerced to number or boolean when unambiguous.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Scope to write to. Default: user.' },
         ],
@@ -141,7 +190,7 @@ const configSet = defineLeaf({
         // Flags are stringly-typed; coerce to number or boolean when unambiguous
         const parsed = parseConfigValue(rawValue);
         const cfg = readConfig(scope);
-        setNestedValue(cfg, key, parsed);
+        setNestedValue(cfg, key, rawValue, parsed);
         writeConfig(scope, cfg);
         // Read back the written value for echo
         const written = getNestedValue(cfg, key);
@@ -191,10 +240,10 @@ const configPath = defineLeaf({
 export const configBranch = defineBranch({
     name: 'config',
     description: 'read and write configuration',
-    whenToUse: 'inspecting or changing crtr settings — read a value with sys config get, change one with sys config set (auto_update policy, max_panes_per_window, canvasNav.prefixKey), or locate config.json with sys config path to hand-edit the record tables set cannot reach.',
+    whenToUse: 'inspecting or changing crtr settings — read a value with sys config get, change one with sys config set (auto_update policy, max_panes_per_window, canvasNav.prefixKey, model ladders, persona strengths), or locate config.json with sys config path to hand-edit the record tables set cannot reach.',
     help: {
         name: 'sys config',
-        summary: 'read and write crtr configuration',
+        summary: 'read and write crtr configuration, including model ladders and persona strengths',
     },
     children: [configGet, configSet, configPath],
 });

package/dist/commands/sys/doctor.js

@@ -5,6 +5,9 @@ import { scopeRoot, listScopes, marketplacesDir, pluginsDir } from '../../core/s
 import { readMarketplaceManifest, readPluginManifest } from '../../core/manifest.js';
 import { pathExists, listDirs, removePath } from '../../core/fs-utils.js';
 import { lsRemote } from '../../core/git.js';
+import { listNodes } from '../../core/canvas/index.js';
+import { activeFaultForDisplay } from '../../core/canvas/render.js';
+import { readFault } from '../../core/runtime/fault.js';
 function pass(scope, name, message) {
     return { scope, name, status: 'pass', message };
 }
@@ -41,6 +44,8 @@ function applyRemediation(rem) {
                 removePath(rem.path);
                 return true;
             }
+            case 'human_action':
+                return false;
             default:
                 return false;
         }
@@ -49,6 +54,51 @@ function applyRemediation(rem) {
         return false;
     }
 }
+function faultMessage(fault) {
+    const parts = [
+        `${fault.link} ${fault.kind}`,
+        `disposition=${fault.retry.disposition}`,
+        typeof fault.retry.attempt === 'number' && typeof fault.retry.max === 'number' ? `attempt=${fault.retry.attempt}/${fault.retry.max}` : undefined,
+        typeof fault.retry.nextAt === 'string' ? `nextAt=${fault.retry.nextAt}` : undefined,
+    ].filter((part) => part !== undefined);
+    return parts.join(' · ');
+}
+function faultRemediation(fault) {
+    const actionByKind = {
+        connection: 'restore connectivity',
+        'rate-limit': 'wait for the rate limit to clear',
+        overloaded: 'wait for load to drop',
+        auth: 're-authenticate',
+        protocol: 'fix the protocol mismatch',
+        other: 'fix the underlying issue',
+    };
+    const progress = fault.retry.disposition === 'auto'
+        ? fault.retry.by === 'client'
+            ? 'client redialing'
+            : typeof fault.retry.attempt === 'number' && typeof fault.retry.max === 'number'
+                ? `auto-retrying, attempt ${fault.retry.attempt}/${fault.retry.max}`
+                : 'auto-retrying'
+        : fault.retry.disposition === 'fatal'
+            ? 'parked fatal'
+            : 'manual';
+    return {
+        kind: 'human_action',
+        description: `${actionByKind[fault.kind]}; ${progress}; inspect ${fault.logPath}`,
+        logPath: fault.logPath,
+    };
+}
+function runFaultChecks() {
+    const results = [];
+    for (const node of listNodes()) {
+        const fault = activeFaultForDisplay(node, readFault(node.node_id));
+        if (fault === null)
+            continue;
+        const name = `fault:${node.node_id}:${fault.link}`;
+        const remediation = faultRemediation(fault);
+        results.push(failCheck('canvas', name, faultMessage(fault), remediation));
+    }
+    return results;
+}
 function runChecksForScope(scope, opts) {
     const results = [];
     const root = scopeRoot(scope);
@@ -198,14 +248,14 @@ export const sysDoctorLeaf = defineLeaf({
             { kind: 'flag', name: 'remote', type: 'bool', required: false, constraint: 'Check git remotes with ls-remote (slow — makes network calls).' },
         ],
         output: [
-            { name: 'checks', type: 'object[]', required: true, constraint: 'Each: {scope, name, status, message, fixed?, remediation?}. status: pass | fail. remediation (when present) is {kind, description, ...payload} where kind is remove_config_key | rm_path. Sorted by scope then name.' },
+            { name: 'checks', type: 'object[]', required: true, constraint: 'Each: {scope, name, status, message, fixed?, remediation?}. status: pass | fail. scope may be user | project | canvas. remediation (when present) is {kind, description, ...payload} where kind is remove_config_key | rm_path | human_action. Sorted by scope then name.' },
             { name: 'ok', type: 'boolean', required: true, constraint: 'True when no unresolved fail checks remain.' },
         ],
         outputKind: 'object',
         effects: [
             'Read-only unless --fix is passed.',
-            'With --fix: applies each non-pass check\'s `remediation` — removes stale config entries and deletes dangling plugin/marketplace directories.',
-            'Each non-pass result carries a structured `remediation` describing the fix action (absolute paths, exact config keys) so callers can apply it directly without --fix.',
+            'With --fix: applies each non-pass check\'s `remediation` — removes stale config entries and deletes dangling plugin/marketplace directories; canvas fault findings stay read-only.',
+            'Each non-pass result carries a structured `remediation` describing the fix action (absolute paths, exact config keys, or a human_action with logPath) so callers can apply it directly without --fix.',
         ],
     },
     run: async (input) => {
@@ -218,10 +268,12 @@ export const sysDoctorLeaf = defineLeaf({
             const results = runChecksForScope(scope, { fix, remote });
             allResults.push(...results);
         }
+        allResults.push(...runFaultChecks());
         // Sort by scope then name (mirrors old printResults grouping)
+        const scopeOrder = { user: 0, project: 1, builtin: 2, canvas: 3 };
         allResults.sort((a, b) => {
             if (a.scope !== b.scope)
-                return a.scope.localeCompare(b.scope);
+                return scopeOrder[a.scope] - scopeOrder[b.scope];
             return a.name.localeCompare(b.name);
         });
         const ok = !allResults.some((r) => r.status === 'fail' && r.fixed !== true);

package/dist/commands/sys/prompt-review.d.ts

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

package/dist/commands/sys/prompt-review.js

@@ -0,0 +1,178 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { defineLeaf } from '../../core/command.js';
+import { InputError, readStdinRaw } from '../../core/io.js';
+import { workspaceRoot } from '../../core/artifact.js';
+import { availableKinds, kindWhenToUse, subPersonasFor } from '../../core/personas/index.js';
+import { resolvePromptReview } from '../../core/personas/resolve.js';
+function resolveLifecycle(mode, lifecycle) {
+    if (lifecycle !== undefined)
+        return lifecycle;
+    return mode === 'orchestrator' ? 'resident' : 'terminal';
+}
+function readJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new InputError({
+            error: 'invalid_json',
+            message: `stdin is not valid JSON: ${String(err)}`,
+            field: 'stdin',
+            next: 'Pass the comments deck JSON on stdin.',
+        });
+    }
+}
+function parseBool(value, field, defaultValue) {
+    if (value === undefined)
+        return defaultValue;
+    if (value === true || value === false)
+        return value;
+    if (typeof value !== 'string') {
+        throw new InputError({ error: 'invalid_field', message: `${field} must be true or false`, field, next: `Use true or false for ${field}.` });
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'true')
+        return true;
+    if (normalized === 'false')
+        return false;
+    throw new InputError({ error: 'invalid_field', message: `${field} must be true or false`, field, next: `Use true or false for ${field}.` });
+}
+function optionalString(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value : null;
+}
+function normaliseKindList() {
+    return availableKinds().map((kind) => ({ kind, whenToUse: kindWhenToUse(kind) }));
+}
+function normaliseSubPersonaList(kind) {
+    return subPersonasFor(kind).map((sub) => ({ kind: sub.kind, whenToUse: sub.whenToUse }));
+}
+function reviewList() {
+    const kinds = normaliseKindList();
+    const subPersonas = {};
+    for (const { kind } of kinds)
+        subPersonas[kind] = normaliseSubPersonaList(kind);
+    return {
+        kinds,
+        modes: ['base', 'orchestrator'],
+        lifecycles: ['terminal', 'resident'],
+        subPersonas,
+    };
+}
+function promptReviewPath() {
+    const dir = workspaceRoot();
+    const reviewsDir = join(dir, 'prompt-reviews');
+    mkdirSync(reviewsDir, { recursive: true });
+    return join(reviewsDir, `${new Date().toISOString()}.md`);
+}
+function renderExportDeck(deck) {
+    const lines = [];
+    lines.push(`# Prompt review — ${deck.config.kind}/${deck.config.mode}`);
+    lines.push('');
+    lines.push('## Config');
+    lines.push(`- timestamp: ${new Date().toISOString()}`);
+    lines.push(`- kind: ${deck.config.kind}`);
+    lines.push(`- mode: ${deck.config.mode}`);
+    lines.push(`- lifecycle: ${deck.config.lifecycle}`);
+    lines.push(`- hasManager: ${String(deck.config.hasManager)}`);
+    lines.push(`- node: ${deck.config.node ?? '(none)'}`);
+    lines.push('');
+    lines.push('## Comments');
+    if (deck.comments.length === 0) {
+        lines.push('- none');
+    }
+    else {
+        for (const comment of deck.comments) {
+            lines.push(`### ${comment.label} (${comment.layerId})`);
+            lines.push(`- source: \`${comment.sourcePath ?? '(generated)'}\` (${comment.scope})`);
+            if (comment.anchor !== null) {
+                lines.push('> ' + comment.anchor.split('\n').join('\n> '));
+            }
+            lines.push(comment.body);
+            lines.push('');
+        }
+        if (lines[lines.length - 1] === '')
+            lines.pop();
+    }
+    lines.push('');
+    lines.push('## Prompt sources (edit these)');
+    const seen = new Set();
+    for (const source of deck.sources) {
+        const key = `${source.scope}:${source.path}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        lines.push(`- ${source.label} — \`${source.path}\` (${source.scope})`);
+    }
+    lines.push('');
+    lines.push('These are review comments on an assembled system prompt; edit the listed source files to address them.');
+    return lines.join('\n') + '\n';
+}
+function exportReview(deck) {
+    const path = promptReviewPath();
+    writeFileSync(path, renderExportDeck(deck), 'utf8');
+    return { path };
+}
+function resolveDeck(input) {
+    const kind = input['kind'];
+    const mode = input['mode'] ?? 'base';
+    const lifecycle = resolveLifecycle(mode, input['lifecycle']);
+    const hasManager = parseBool(input['hasManager'], 'hasManager', true);
+    const node = optionalString(input['node']);
+    if (kind === undefined || kind.trim() === '') {
+        throw new InputError({ error: 'missing_parameter', message: 'kind is required', field: 'kind', next: 'Pass --kind <kind> or use --list.' });
+    }
+    return resolvePromptReview(kind, mode, {
+        lifecycle,
+        hasManager,
+    }, node ?? undefined);
+}
+export const promptReviewLeaf = defineLeaf({
+    name: 'prompt-review',
+    description: 'inspect an assembled prompt and export review notes',
+    whenToUse: 'you want to inspect a composed persona prompt for a kind/mode combo, compare the space around it, or export review notes back to source files',
+    help: {
+        name: 'sys prompt-review',
+        summary: 'inspect an assembled prompt and export review notes',
+        params: [
+            { kind: 'positional', name: 'action', type: 'string', required: false, constraint: 'Optional subcommand: export. Omit for the assembled prompt contract.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Persona kind to inspect. Required unless --list or export.' },
+            { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, default: 'base', constraint: 'Persona mode. Default: base.' },
+            { kind: 'flag', name: 'lifecycle', type: 'enum', choices: ['terminal', 'resident'], required: false, constraint: 'Lifecycle axis. Default: base -> terminal, orchestrator -> resident.' },
+            { kind: 'flag', name: 'has-manager', type: 'string', required: false, default: 'true', constraint: 'Whether the node reports to a manager. Use true or false. Default: true.' },
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Optional node id. When the node exists, runtime substrate layers are appended.' },
+            { kind: 'flag', name: 'list', type: 'bool', required: false, constraint: 'List the available kinds, modes, lifecycles, and sub-personas.' },
+        ],
+        output: [
+            { name: 'config', type: 'object', required: false, constraint: 'Resolved config: {kind, mode, lifecycle, hasManager, node}.' },
+            { name: 'layers', type: 'object[]', required: false, constraint: 'Ordered prompt layers, including excluded alternatives and provenance.' },
+            { name: 'assembled', type: 'string', required: false, constraint: 'The assembled prompt string.' },
+            { name: 'total', type: 'object', required: false, constraint: 'Approximate token/char totals for included layers.' },
+            { name: 'sources', type: 'object[]', required: false, constraint: 'De-duplicated source files referenced by the prompt.' },
+            { name: 'kinds', type: 'object[]', required: false, constraint: 'Available kinds for --list.' },
+            { name: 'modes', type: 'string[]', required: false, constraint: 'Mode choices for --list.' },
+            { name: 'lifecycles', type: 'string[]', required: false, constraint: 'Lifecycle choices for --list.' },
+            { name: 'subPersonas', type: 'object', required: false, constraint: 'Available sub-personas keyed by kind for --list.' },
+            { name: 'path', type: 'string', required: false, constraint: 'Written markdown path for export.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only inspection, or writes a review markdown file under the per-cwd crouter root.'],
+    },
+    run: async (input) => {
+        const action = input['action'];
+        const isList = input['list'] === true;
+        const hasManager = parseBool(input['hasManager'], 'hasManager', true);
+        if (action !== undefined && action !== 'export') {
+            throw new InputError({ error: 'unknown_action', message: `unknown action: ${action}`, field: 'action', next: 'Use `export` or omit the positional action.' });
+        }
+        if (action === 'export') {
+            const raw = await readStdinRaw();
+            const deck = readJson(raw);
+            return exportReview(deck);
+        }
+        if (isList)
+            return reviewList();
+        const deck = resolveDeck({ ...input, hasManager });
+        return deck;
+    },
+});

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

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