@crouton-kit/crouter 0.3.8 → 0.3.11

package/dist/core/__tests__/jobs.test.js

@@ -6,7 +6,7 @@ import assert from 'node:assert/strict';
 import { mkdirSync, rmSync, existsSync, readFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { createJob, writeResult, writeMarkdownResult, readResult, } from '../jobs.js';
+import { createJob, writeResult, writeMarkdownResult, readResult, recordJobPane, jobStatus, } from '../jobs.js';
 let stateDir;
 let origXdg;
 before(() => {
@@ -64,3 +64,35 @@ describe('writeMarkdownResult + readResult round-trip', () => {
         assert.equal(r.status, 'timeout');
     });
 });
+describe('closed-pane reaping (zombie prevention)', () => {
+    test('live job whose recorded pane is gone is reaped to closed on status read', () => {
+        const { jobId } = createJob('prompt', { cwd: '/tmp' });
+        // A pane id that cannot exist on any tmux server.
+        recordJobPane(jobId, '%999999999');
+        const status = jobStatus(jobId);
+        assert.equal(status.state, 'closed');
+    });
+    test('reaped job exposes a closed result explaining the closed pane', async () => {
+        const { jobId } = createJob('prompt', { cwd: '/tmp' });
+        recordJobPane(jobId, '%999999999');
+        // Trigger the reaper.
+        jobStatus(jobId);
+        const r = await readResult(jobId, { waitMs: 0 });
+        assert.equal(r.status, 'closed');
+        assert.match(r.reason ?? '', /pane closed/);
+    });
+    test('job with no recorded pane is NOT reaped (stays live)', () => {
+        const { jobId } = createJob('prompt', { cwd: '/tmp' });
+        const status = jobStatus(jobId);
+        assert.equal(status.state, 'live');
+    });
+    test('already-submitted job is never overwritten by the reaper', async () => {
+        const { jobId } = createJob('prompt', { cwd: '/tmp' });
+        recordJobPane(jobId, '%999999999');
+        writeMarkdownResult(jobId, '**done**\n', 'done');
+        jobStatus(jobId);
+        const r = await readResult(jobId, { waitMs: 0 });
+        assert.equal(r.status, 'done');
+        assert.equal(r.result_md, '**done**\n');
+    });
+});

package/dist/core/__tests__/resolver.test.js

@@ -6,7 +6,9 @@ import assert from 'node:assert/strict';
 import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { parseSkillQualifier } from '../resolver.js';
+import { parseSkillQualifier, resolveSkill } from '../resolver.js';
+import { resetScopeCache } from '../scope.js';
+import { CrtrError } from '../errors.js';
 import { InputError } from '../io.js';
 import { readConfig } from '../config.js';
 import { SCHEMA_VERSION } from '../../types.js';
@@ -111,3 +113,69 @@ describe('config migration: skill keys colon → slash', () => {
         assert.equal(cfg.schema_version, SCHEMA_VERSION, 'schema_version bumped to current');
     });
 });
+// ---------------------------------------------------------------------------
+// resolveSkill — leaf-name fallback
+// ---------------------------------------------------------------------------
+describe('resolveSkill leaf-name fallback', () => {
+    let testHomeDir;
+    let origHome;
+    function writePluginSkill(plugin, skillPath) {
+        const root = join(testHomeDir, '.crouter', 'plugins', plugin);
+        mkdirSync(join(root, '.crouter-plugin'), { recursive: true });
+        writeFileSync(join(root, '.crouter-plugin', 'plugin.json'), JSON.stringify({ name: plugin, version: '0.0.1' }), 'utf8');
+        const skillDir = join(root, 'skills', ...skillPath.split('/'));
+        mkdirSync(skillDir, { recursive: true });
+        writeFileSync(join(skillDir, 'SKILL.md'), `---\nname: ${skillPath.split('/').pop()}\n---\nbody`, 'utf8');
+    }
+    before(() => {
+        testHomeDir = join(tmpdir(), `crtr-leaf-test-${Date.now()}`);
+        mkdirSync(testHomeDir, { recursive: true });
+        origHome = process.env['HOME'];
+        process.env['HOME'] = testHomeDir;
+        resetScopeCache();
+        // Unique leaf: only one plugin has it, reached via nested path.
+        writePluginSkill('ai', 'interface/cli-design');
+        // Colliding leaf: two plugins both expose `dup` at different paths.
+        writePluginSkill('pa', 'x/dup');
+        writePluginSkill('pb', 'y/dup');
+    });
+    after(() => {
+        if (origHome === undefined)
+            delete process.env['HOME'];
+        else
+            process.env['HOME'] = origHome;
+        resetScopeCache();
+        rmSync(testHomeDir, { recursive: true, force: true });
+    });
+    test('bare leaf name resolves to the nested skill', () => {
+        const s = resolveSkill('cli-design');
+        assert.equal(s.name, 'interface/cli-design');
+        assert.equal(s.plugin, 'ai');
+    });
+    test('full path still resolves directly', () => {
+        const s = resolveSkill('ai/interface/cli-design');
+        assert.equal(s.name, 'interface/cli-design');
+        assert.equal(s.plugin, 'ai');
+    });
+    test('colliding leaf name throws ambiguous listing full paths', () => {
+        assert.throws(() => resolveSkill('dup'), (e) => {
+            assert.ok(e instanceof CrtrError, 'should be CrtrError');
+            assert.equal(e.code, 'ambiguous');
+            assert.match(e.message, /pa\/x\/dup/);
+            assert.match(e.message, /pb\/y\/dup/);
+            return true;
+        });
+    });
+    test('colliding leaf is resolvable via full path', () => {
+        const s = resolveSkill('pb/y/dup');
+        assert.equal(s.plugin, 'pb');
+        assert.equal(s.name, 'y/dup');
+    });
+    test('unknown leaf still throws not_found', () => {
+        assert.throws(() => resolveSkill('no-such-leaf-xyz'), (e) => {
+            assert.ok(e instanceof CrtrError);
+            assert.equal(e.code, 'not_found');
+            return true;
+        });
+    });
+});

package/dist/core/__tests__/spawn.test.d.ts

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

package/dist/core/__tests__/spawn.test.js

@@ -0,0 +1,138 @@
+// Tests for agent-CLI selection in spawn.ts (detectAgentKind + buildAgentCommand).
+//
+// Run with: node --import tsx/esm --test src/core/__tests__/spawn.test.ts
+import { test, describe, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { detectAgentKind, buildAgentCommand, buildAgentPrintArgv, buildAgentPrintCommand, normalizeModelForKind, subagentSessionName, } from '../spawn.js';
+const origPi = process.env['PI_CODING_AGENT'];
+afterEach(() => {
+    if (origPi === undefined)
+        delete process.env['PI_CODING_AGENT'];
+    else
+        process.env['PI_CODING_AGENT'] = origPi;
+});
+describe('subagentSessionName', () => {
+    test('derives a deterministic, tmux-safe name from a pane id', () => {
+        assert.equal(subagentSessionName('%5'), 'crtr-agents-5');
+        assert.equal(subagentSessionName('%23'), 'crtr-agents-23');
+    });
+    test('is stable for the same pane id and distinct across panes', () => {
+        assert.equal(subagentSessionName('%7'), subagentSessionName('%7'));
+        assert.notEqual(subagentSessionName('%7'), subagentSessionName('%8'));
+    });
+    test('strips characters tmux would treat specially', () => {
+        assert.equal(subagentSessionName('%1.2'), 'crtr-agents-12');
+        assert.match(subagentSessionName('%99'), /^crtr-agents-[a-zA-Z0-9]+$/);
+    });
+});
+describe('detectAgentKind', () => {
+    test('returns pi when PI_CODING_AGENT=true', () => {
+        process.env['PI_CODING_AGENT'] = 'true';
+        assert.equal(detectAgentKind(), 'pi');
+    });
+    test('defaults to claude when no signal is present', () => {
+        delete process.env['PI_CODING_AGENT'];
+        assert.equal(detectAgentKind(), 'claude');
+    });
+});
+describe('buildAgentCommand: claude', () => {
+    test('fresh prompt uses --dangerously-skip-permissions and quotes the prompt', () => {
+        const cmd = buildAgentCommand({ prompt: 'do the thing', name: 'worker-1' }, 'claude');
+        assert.equal(cmd, "claude -n 'worker-1' --dangerously-skip-permissions 'do the thing'");
+    });
+    test('fork uses --resume <id> --fork-session', () => {
+        const cmd = buildAgentCommand({ prompt: 'p', fork: { sessionId: 'abc-123' } }, 'claude');
+        assert.equal(cmd, "claude --resume 'abc-123' --fork-session --dangerously-skip-permissions 'p'");
+    });
+});
+describe('buildAgentCommand: pi', () => {
+    test('fresh prompt has no skip-permissions flag (pi has no permission popups)', () => {
+        const cmd = buildAgentCommand({ prompt: 'do the thing', name: 'worker-1' }, 'pi');
+        assert.equal(cmd, "pi -n 'worker-1' 'do the thing'");
+        assert.ok(!cmd.includes('--dangerously-skip-permissions'));
+    });
+    test('fork uses --fork <id>', () => {
+        const cmd = buildAgentCommand({ prompt: 'p', fork: { sessionId: 'abc-123' } }, 'pi');
+        assert.equal(cmd, "pi --fork 'abc-123' 'p'");
+    });
+    test('single-quotes in the prompt are escaped safely', () => {
+        const cmd = buildAgentCommand({ prompt: "it's fine" }, 'pi');
+        assert.equal(cmd, "pi 'it'\\''s fine'");
+    });
+});
+describe('buildAgentCommand: subagent persona (systemPrompt/model/tools)', () => {
+    test('pi emits --model, --tools, and --append-system-prompt before the prompt', () => {
+        const cmd = buildAgentCommand({ prompt: 'task', name: 'scout', systemPrompt: 'You are a scout.', model: 'haiku', tools: ['read', 'grep'] }, 'pi');
+        assert.equal(cmd, "pi -n 'scout' --model 'anthropic/haiku' --tools 'read,grep' --append-system-prompt 'You are a scout.' 'task'");
+    });
+    test('claude emits --model and --append-system-prompt but NOT --tools (different tool model)', () => {
+        const cmd = buildAgentCommand({ prompt: 'task', systemPrompt: 'persona', model: 'sonnet', tools: ['read', 'grep'] }, 'claude');
+        assert.ok(cmd.includes("--model 'sonnet'"));
+        assert.ok(cmd.includes("--append-system-prompt 'persona'"));
+        assert.ok(!cmd.includes('--tools'));
+    });
+    test('omitted persona fields add no flags', () => {
+        const cmd = buildAgentCommand({ prompt: 'task' }, 'pi');
+        assert.equal(cmd, "pi 'task'");
+    });
+});
+describe('buildAgentPrintArgv: subagent persona', () => {
+    test('pi threads model/tools/system prompt as discrete args', () => {
+        const { args } = buildAgentPrintArgv({ prompt: 'task', systemPrompt: 'persona', model: 'haiku', tools: ['read', 'bash'] }, 'pi');
+        assert.deepEqual(args, ['--model', 'anthropic/haiku', '--tools', 'read,bash', '--append-system-prompt', 'persona', '-p', 'task']);
+    });
+    test('claude threads model/system prompt but not tools', () => {
+        const { args } = buildAgentPrintArgv({ prompt: 'task', systemPrompt: 'persona', model: 'sonnet', tools: ['read'] }, 'claude');
+        assert.deepEqual(args, ['--model', 'sonnet', '--append-system-prompt', 'persona', '-p', '--dangerously-skip-permissions', 'task']);
+    });
+});
+describe('normalizeModelForKind: pi Claude-alias resolution', () => {
+    test('pins bare Claude aliases to the anthropic provider under pi', () => {
+        assert.equal(normalizeModelForKind('sonnet', 'pi'), 'anthropic/sonnet');
+        assert.equal(normalizeModelForKind('opus', 'pi'), 'anthropic/opus');
+        assert.equal(normalizeModelForKind('haiku', 'pi'), 'anthropic/haiku');
+    });
+    test('preserves a :thinking suffix when pinning the provider', () => {
+        assert.equal(normalizeModelForKind('sonnet:high', 'pi'), 'anthropic/sonnet:high');
+    });
+    test('leaves provider-prefixed and concrete ids untouched under pi', () => {
+        assert.equal(normalizeModelForKind('anthropic/sonnet', 'pi'), 'anthropic/sonnet');
+        assert.equal(normalizeModelForKind('openai/gpt-4o', 'pi'), 'openai/gpt-4o');
+        assert.equal(normalizeModelForKind('claude-sonnet-4-6', 'pi'), 'claude-sonnet-4-6');
+        assert.equal(normalizeModelForKind('gpt-4o-mini', 'pi'), 'gpt-4o-mini');
+    });
+    test('never rewrites for the claude CLI (native alias support)', () => {
+        assert.equal(normalizeModelForKind('sonnet', 'claude'), 'sonnet');
+        assert.equal(normalizeModelForKind('opus', 'claude'), 'opus');
+    });
+});
+describe('buildAgentCommand: defaults to detected kind', () => {
+    test('uses pi when PI_CODING_AGENT=true and no explicit kind passed', () => {
+        process.env['PI_CODING_AGENT'] = 'true';
+        const cmd = buildAgentCommand({ prompt: 'hi' });
+        assert.ok(cmd.startsWith('pi '));
+    });
+});
+describe('buildAgentPrintArgv (headless print mode)', () => {
+    test('pi uses -p and no skip-permissions flag', () => {
+        const { cmd, args } = buildAgentPrintArgv({ prompt: 'do it', name: 'w1' }, 'pi');
+        assert.equal(cmd, 'pi');
+        assert.deepEqual(args, ['-n', 'w1', '-p', 'do it']);
+        assert.ok(!args.includes('--dangerously-skip-permissions'));
+    });
+    test('claude uses -p plus --dangerously-skip-permissions', () => {
+        const { cmd, args } = buildAgentPrintArgv({ prompt: 'do it' }, 'claude');
+        assert.equal(cmd, 'claude');
+        assert.deepEqual(args, ['-p', '--dangerously-skip-permissions', 'do it']);
+    });
+    test('argv passes the prompt as a discrete arg (no shell quoting)', () => {
+        const { args } = buildAgentPrintArgv({ prompt: "it's $weird" }, 'pi');
+        assert.equal(args[args.length - 1], "it's $weird");
+    });
+});
+describe('buildAgentPrintCommand (shell string)', () => {
+    test('pi prints with -p and shell-quotes the prompt', () => {
+        const cmd = buildAgentPrintCommand({ prompt: "it's fine" }, 'pi');
+        assert.equal(cmd, "pi '-p' 'it'\\''s fine'");
+    });
+});

package/dist/core/__tests__/subagents.test.d.ts

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

package/dist/core/__tests__/subagents.test.js

@@ -0,0 +1,75 @@
+// Tests for subagent discovery, resolution, and frontmatter parsing.
+//
+// Run with: node --import tsx/esm --test src/core/__tests__/subagents.test.ts
+import { test, describe, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { listSubagents, resolveSubagent, subagentId } from '../subagents.js';
+import { resetScopeCache } from '../scope.js';
+import { parseFrontmatterGeneric } from '../frontmatter.js';
+describe('parseFrontmatterGeneric', () => {
+    test('returns raw record including tools/model fields skills ignore', () => {
+        const src = '---\nname: scout\ndescription: recon\nmodel: haiku\ntools: read, grep, bash\n---\nBody here.\n';
+        const { data, body } = parseFrontmatterGeneric(src);
+        assert.ok(data !== null);
+        assert.equal(data['name'], 'scout');
+        assert.equal(data['description'], 'recon');
+        assert.equal(data['model'], 'haiku');
+        assert.equal(data['tools'], 'read, grep, bash');
+        assert.equal(body, 'Body here.\n');
+    });
+    test('list-style tools parse to an array', () => {
+        const src = '---\nname: x\ndescription: d\ntools:\n  - read\n  - bash\n---\nb\n';
+        const { data } = parseFrontmatterGeneric(src);
+        assert.deepEqual(data['tools'], ['read', 'bash']);
+    });
+    test('no frontmatter yields null data', () => {
+        const { data, body } = parseFrontmatterGeneric('just a body');
+        assert.equal(data, null);
+        assert.equal(body, 'just a body');
+    });
+});
+describe('subagent discovery (project scope)', () => {
+    let dir;
+    const origCwd = process.cwd();
+    before(() => {
+        dir = mkdtempSync(join(tmpdir(), 'crtr-subagents-'));
+        const agents = join(dir, '.crouter', 'agents');
+        mkdirSync(agents, { recursive: true });
+        writeFileSync(join(dir, '.crouter', 'config.json'), '{}');
+        writeFileSync(join(agents, 'scout.md'), '---\nname: scout\ndescription: Fast recon\nmodel: haiku\ntools: read, grep\n---\nYou are a scout.\n');
+        writeFileSync(join(agents, 'reviewer.md'), '---\nname: reviewer\ndescription: Code review\n---\nYou review code.\n');
+        // Missing description → skipped from listings.
+        writeFileSync(join(agents, 'broken.md'), '---\nname: broken\n---\nno description\n');
+        // Name defaults to filename stem when frontmatter omits it.
+        writeFileSync(join(agents, 'stemmed.md'), '---\ndescription: named by file\n---\nbody\n');
+        process.chdir(dir);
+        resetScopeCache();
+    });
+    after(() => {
+        process.chdir(origCwd);
+        resetScopeCache();
+        rmSync(dir, { recursive: true, force: true });
+    });
+    test('listSubagents finds valid agents and skips description-less files', () => {
+        const ids = listSubagents('project').map(subagentId).sort();
+        assert.deepEqual(ids, ['reviewer', 'scout', 'stemmed']);
+    });
+    test('frontmatter tools comma-string coerces to array; model carried', () => {
+        const scout = resolveSubagent('scout', { scope: 'project' });
+        assert.deepEqual(scout.frontmatter.tools, ['read', 'grep']);
+        assert.equal(scout.frontmatter.model, 'haiku');
+        assert.equal(scout.systemPrompt.trim(), 'You are a scout.');
+        assert.equal(scout.plugin, '_');
+    });
+    test('name defaults to filename stem', () => {
+        const a = resolveSubagent('stemmed', { scope: 'project' });
+        assert.equal(a.name, 'stemmed');
+        assert.equal(a.frontmatter.description, 'named by file');
+    });
+    test('resolveSubagent throws notFound for unknown name', () => {
+        assert.throws(() => resolveSubagent('nope', { scope: 'project' }), /subagent not found/);
+    });
+});

package/dist/core/__tests__/unknown-path.test.d.ts

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

package/dist/core/__tests__/unknown-path.test.js

@@ -0,0 +1,52 @@
+// Regression tests for unknown-subcommand error recovery hints.
+// Run with: node --import tsx/esm --test src/core/__tests__/unknown-path.test.ts
+//
+// The `next` road sign must name a command that actually exists: the FULL path
+// to the deepest matched node, not just its local name. A prior bug emitted
+// `crtr find -h` (dropping the `skill` parent) when `crtr skill find bogus` was
+// invoked, sending the caller to a nonexistent top-level command.
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { defineRoot, defineBranch, defineLeaf, walk, unknownPathError } from '../command.js';
+const leaf = defineLeaf({
+    name: 'search',
+    help: { name: 'search', summary: 'search', output: [], outputKind: 'object', effects: ['None. Read-only.'] },
+    run: async () => ({}),
+});
+const findBranch = defineBranch({
+    name: 'find',
+    help: { name: 'find', summary: 'find', children: [{ name: 'search', desc: 'search', useWhen: 'x' }] },
+    children: [leaf],
+});
+const skillBranch = defineBranch({
+    name: 'skill',
+    help: { name: 'skill', summary: 'skill', children: [{ name: 'find', desc: 'find', useWhen: 'x' }] },
+    rootEntry: { concept: 'skill', desc: 'skill', useWhen: 'x' },
+    children: [findBranch],
+});
+const root = defineRoot({
+    tagline: 'test runtime',
+    globals: [],
+    subtrees: [skillBranch],
+});
+function nextHint(...tokens) {
+    const { node, path, remaining } = walk(root, tokens);
+    const err = unknownPathError(node, path, remaining[0]);
+    return err.details.next;
+}
+describe('unknown-path error: recovery hint names the full valid path', () => {
+    test('root-level unknown points at `crtr -h`', () => {
+        assert.match(nextHint('bogus'), /Run `crtr -h`/);
+    });
+    test('one-level unknown points at `crtr skill -h`', () => {
+        assert.match(nextHint('skill', 'bogus'), /Run `crtr skill -h`/);
+    });
+    test('two-level unknown points at `crtr skill find -h`, not `crtr find -h`', () => {
+        const hint = nextHint('skill', 'find', 'bogus');
+        assert.match(hint, /Run `crtr skill find -h`/);
+        assert.doesNotMatch(hint, /Run `crtr find -h`/);
+    });
+    test('valid children of the matched node are listed', () => {
+        assert.match(nextHint('skill', 'find', 'bogus'), /Valid children: search\./);
+    });
+});

package/dist/core/bootstrap.d.ts

@@ -1,6 +1,8 @@
+import type { RootDef } from './command.js';
 export declare const OFFICIAL_MARKETPLACE_NAME = "crouter-official-marketplace";
 export declare const OFFICIAL_MARKETPLACE_URL = "https://github.com/crouton-labs/crouter-official-marketplace.git";
 export declare const OFFICIAL_MARKETPLACE_REF = "main";
 export declare function ensureBootSkill(argv: string[]): void;
+export declare function ensureSlashCommands(root: RootDef, argv: string[]): void;
 export declare function ensureOfficialMarketplace(argv: string[]): void;
 export declare function ensureProjectScope(argv: string[]): void;

package/dist/core/bootstrap.js

@@ -6,6 +6,7 @@ import { ensureDir, pathExists, readText, removePath, nowIso } from './fs-utils.
 import { readConfig, readState, updateConfig, updateState, ensureScopeInitialized } from './config.js';
 import { clone } from './git.js';
 import { readMarketplaceManifest } from './manifest.js';
+import { collectSlashSpecs } from './command.js';
 import { CRTR_DIR_NAME } from '../types.js';
 export const OFFICIAL_MARKETPLACE_NAME = 'crouter-official-marketplace';
 export const OFFICIAL_MARKETPLACE_URL = 'https://github.com/crouton-labs/crouter-official-marketplace.git';
@@ -94,6 +95,71 @@ export function ensureBootSkill(argv) {
         }
     }
 }
+// ---------------------------------------------------------------------------
+// Slash commands (editor prompt templates) auto-installed for opted-in nodes.
+//
+// Any command that declares a `slash` SlashSpec is rendered to a markdown
+// template and dropped into the host's command dirs on each crtr run — pi reads
+// `~/.pi/agent/prompts/<name>.md`, Claude Code reads `~/.claude/commands/<name>.md`,
+// so `/name` becomes available. Marker-guarded (never clobbers a user-edited
+// file) and version-rolled like the boot skill. Kill switch: CRTR_NO_MODE_CMDS=1.
+// ---------------------------------------------------------------------------
+const SLASH_CMD_MARKER = '<!-- crtr-mode-cmd v1 -->';
+const SLASH_CMD_MARKER_PREFIX = '<!-- crtr-mode-cmd v';
+/** Render a SlashSpec to a full template file (frontmatter + marker + body). */
+function renderSlashTemplate(spec) {
+    const hint = spec.argumentHint !== undefined
+        ? `argument-hint: ${JSON.stringify(spec.argumentHint)}\n`
+        : '';
+    return `---\ndescription: ${spec.description}\n${hint}---\n\n${SLASH_CMD_MARKER}\n\n${spec.body}\n`;
+}
+/** Write `content` to `file` unless a user-customized file is already there.
+ *  Rolls forward our own (marker-bearing) versions; skips if identical. */
+function writeSlashFileIfOurs(dir, name, content) {
+    const file = join(dir, `${name}.md`);
+    if (pathExists(file)) {
+        const existing = readText(file);
+        if (!existing.includes(SLASH_CMD_MARKER_PREFIX))
+            return; // user's own file
+        if (existing === content)
+            return; // already current
+    }
+    ensureDir(dir);
+    writeFileSync(file, content, 'utf8');
+}
+export function ensureSlashCommands(root, argv) {
+    try {
+        if (process.env.CRTR_NO_MODE_CMDS === '1')
+            return;
+        if (shouldSkipForArgv(argv))
+            return;
+        const specs = collectSlashSpecs(root);
+        if (specs.length === 0)
+            return;
+        // Target each host's command dir, but only when that host is actually in use
+        // (its root dir exists). We never create ~/.pi or ~/.claude ourselves.
+        const targets = [];
+        if (pathExists(join(homedir(), '.pi', 'agent'))) {
+            targets.push(join(homedir(), '.pi', 'agent', 'prompts'));
+        }
+        if (pathExists(join(homedir(), '.claude'))) {
+            targets.push(join(homedir(), '.claude', 'commands'));
+        }
+        if (targets.length === 0)
+            return;
+        for (const spec of specs) {
+            const content = renderSlashTemplate(spec);
+            for (const dir of targets)
+                writeSlashFileIfOurs(dir, spec.name, content);
+        }
+    }
+    catch (e) {
+        if (process.env.CRTR_DEBUG === '1') {
+            const msg = e instanceof Error ? e.message : String(e);
+            process.stderr.write(`crtr: slash-command error: ${msg}\n`);
+        }
+    }
+}
 export function ensureOfficialMarketplace(argv) {
     try {
         if (process.env.CRTR_NO_BOOTSTRAP === '1')

package/dist/core/command.d.ts

@@ -1,14 +1,39 @@
-import type { RootHelp, BranchHelp, LeafHelp, InputParam } from './help.js';
+import type { RootHelp, RootEntry, BranchHelp, LeafHelp, InputParam } from './help.js';
+import { CrtrError } from './errors.js';
+/** Opt-in flag that surfaces a node as an editor slash command (a pi prompt
+ *  template / Claude Code command). When set, the bootstrap auto-writes a
+ *  markdown template named `<name>.md` to the host's command dirs on each crtr
+ *  run, so `/name` becomes available. The body is thin — it points the agent at
+ *  the live `crtr` workflow so the CLI stays the source of truth. */
+export interface SlashSpec {
+    /** Command name → `/<name>` and the template filename. */
+    name: string;
+    /** Frontmatter description shown in the autocomplete dropdown. */
+    description: string;
+    /** Optional autocomplete hint, e.g. `<url>` or `[topic]`. */
+    argumentHint?: string;
+    /** Markdown body (no frontmatter). Bootstrap wraps it with frontmatter + a
+     *  version marker. Use `$ARGUMENTS` for the invocation's free text. */
+    body: string;
+}
 export interface LeafDef {
     kind: 'leaf';
     name: string;
     help: LeafHelp;
+    /** Opt into editor slash-command exposure (see SlashSpec). */
+    slash?: SlashSpec;
     run: (input: Record<string, unknown>) => Promise<Record<string, unknown> | void>;
 }
 export interface BranchDef {
     kind: 'branch';
     name: string;
     help: BranchHelp;
+    /** How this subtree represents itself one level up. Present on top-level
+     *  subtrees (assembled into root -h by defineRoot); omitted on nested
+     *  branches, whose parent representation is the branch's own children list. */
+    rootEntry?: RootEntry;
+    /** Opt into editor slash-command exposure (see SlashSpec). */
+    slash?: SlashSpec;
     children: (LeafDef | BranchDef)[];
 }
 export interface RootDef {
@@ -19,18 +44,49 @@ export interface RootDef {
 export declare function defineLeaf(opts: {
     name: string;
     help: LeafHelp;
+    slash?: SlashSpec;
     run: (input: Record<string, unknown>) => Promise<Record<string, unknown> | void>;
 }): LeafDef;
 export declare function defineBranch(opts: {
     name: string;
     help: BranchHelp;
+    rootEntry?: RootEntry;
+    slash?: SlashSpec;
     children: (LeafDef | BranchDef)[];
 }): BranchDef;
+/** Walk the whole tree and collect every node's SlashSpec (depth-first). Used
+ *  by the bootstrap to discover which commands opted into slash exposure. */
+export declare function collectSlashSpecs(root: RootDef): SlashSpec[];
+/** Assemble root -h from the subtrees themselves. Root owns only the tagline
+ *  and globals; every subtree's concept line, selection rubric, and dynamic
+ *  block come from its own RootEntry. A subtree without a rootEntry does not
+ *  appear in root -h — declaring the parent-level representation is how a
+ *  subtree opts into being listed. */
 export declare function defineRoot(opts: {
-    help: RootHelp;
+    tagline: string;
+    globals: {
+        name: string;
+        desc: string;
+    }[];
     subtrees: BranchDef[];
 }): RootDef;
+type AnyNode = RootDef | BranchDef | LeafDef;
+/** Walk argv tokens to the deepest matched node.
+ *  Returns { node, path, remaining } where path is the sequence of matched node
+ *  names from root (excluding root itself) and remaining are unconsumed tokens.
+ *  -h / --help tokens are NOT consumed here — the caller checks for them. */
+export declare function walk(root: RootDef, tokens: string[]): {
+    node: AnyNode;
+    path: string[];
+    remaining: string[];
+};
+/** Build a structured unknown-path error. Names valid children of the deepest
+ *  matched node and names the entry command per the spec. The entry command is
+ *  the full path to the matched node (not just its local name), so the recovery
+ *  hint is a command that actually exists. No fuzzy matching. */
+export declare function unknownPathError(node: AnyNode, path: string[], bad: string): CrtrError;
 /** Parse remaining argv tokens against the leaf's InputParam schema.
  *  Returns a plain object whose keys are camelCase parameter names. */
 export declare function parseArgv(params: InputParam[], tokens: string[]): Promise<Record<string, unknown>>;
 export declare function runCli(root: RootDef, argv: string[]): Promise<void>;
+export {};