@crouton-kit/crouter 0.3.11 → 0.3.13

package/dist/commands/push.d.ts

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

package/dist/commands/push.js

@@ -0,0 +1,159 @@
+// `crtr push` + `crtr feed` — the one verb up the graph, and its read side.
+//
+//   crtr push update [body]   — routine progress (also auto-emitted every stop)
+//   crtr push urgent [body]   — force-wake subscribers
+//   crtr push final  [body]   — finish: write result, mark node done, close window
+//   crtr feed read            — drain the caller's (or a named) inbox into a digest
+//
+// "push" is THE verb a node uses to talk to its managers; the tier is the
+// subcommand. The caller's node is resolved from CRTR_NODE_ID (injected by the
+// runtime into every node process). Absent ⇒ InputError — push is only
+// meaningful inside a live node.
+import { defineBranch, defineLeaf } from '../core/command.js';
+import { InputError, readStdinRaw } from '../core/io.js';
+import { push } from '../core/feed/feed.js';
+import { readInboxSince, readCursor, writeCursor, coalesce, } from '../core/feed/inbox.js';
+function requireCallerNode() {
+    const id = process.env['CRTR_NODE_ID'];
+    if (id === undefined || id.trim() === '') {
+        throw new InputError({
+            error: 'no_node_context',
+            message: 'CRTR_NODE_ID is not set — push runs inside a canvas node.',
+            next: 'Run push from a node process spawned by the runtime.',
+        });
+    }
+    return id.trim();
+}
+const TIER_BLURB = {
+    update: 'routine progress — fans a pointer to subscribers, no forced wake',
+    urgent: 'force-wake subscribers (inbox tier urgent)',
+    final: 'finish: write the canonical result, mark the node done, close its window',
+};
+function makeTierLeaf(tier) {
+    return defineLeaf({
+        name: tier,
+        help: {
+            name: `push ${tier}`,
+            summary: TIER_BLURB[tier],
+            params: [
+                { kind: 'stdin', name: 'body', required: true, constraint: 'Report body (markdown). Positional or stdin.' },
+            ],
+            output: [
+                { name: 'report_path', type: 'string', required: true, constraint: 'Path of the written report.' },
+                { name: 'delivered_to', type: 'string[]', required: true, constraint: 'Subscriber node ids that received a pointer.' },
+                { name: 'status', type: 'string', required: true, constraint: '"done" for final, else "active".' },
+            ],
+            outputKind: 'object',
+            effects: [
+                'Writes nodes/<nodeId>/reports/<ts>-<tier>.md.',
+                'Appends one inbox pointer per subscriber.',
+                ...(tier === 'final' ? ['Marks the node done (status + intent); its window closes on next stop.'] : []),
+            ],
+        },
+        run: async (input) => {
+            const nodeId = requireCallerNode();
+            let body = typeof input['body'] === 'string' ? input['body'].trim() : '';
+            if (body === '')
+                body = (await readStdinRaw()).trim();
+            if (body === '') {
+                throw new InputError({ error: 'missing_body', message: 'no report body', field: 'body', next: 'Pass the body as an argument or on stdin.' });
+            }
+            const result = await push(nodeId, { kind: tier, body });
+            return { report_path: result.reportPath, delivered_to: result.deliveredTo, status: tier === 'final' ? 'done' : 'active' };
+        },
+        render: (r) => {
+            const n = Array.isArray(r['delivered_to']) ? r['delivered_to'].length : 0;
+            const line = tier === 'final'
+                ? 'Result recorded — node finished; its window closes on next stop. Nothing more to do here.'
+                : tier === 'urgent'
+                    ? `Urgent report fanned to ${n} subscriber(s) — they are force-woken.`
+                    : `Progress report fanned to ${n} subscriber(s).`;
+            return `<pushed tier="${tier}" status="${r['status']}" delivered="${n}">\n${line}\nreport: ${r['report_path']}\n</pushed>`;
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// feed read — drain the inbox
+// ---------------------------------------------------------------------------
+const feedReadLeaf = defineLeaf({
+    name: 'read',
+    help: {
+        name: 'feed read',
+        summary: 'drain unread inbox pointers for the caller (or a named node) into a compact digest',
+        params: [
+            { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node whose inbox to read. Defaults to CRTR_NODE_ID. Use to inspect a worker\'s inbox as an orchestrator.' },
+            { kind: 'flag', name: 'all', type: 'bool', required: false, default: false, constraint: 'Ignore the cursor and return everything from the start.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'Node whose inbox was read.' },
+            { name: 'digest', type: 'string', required: true, constraint: 'Coalesced digest — paste directly into a prompt.' },
+            { name: 'entries', type: 'object[]', required: true, constraint: 'Raw InboxEntry objects.' },
+            { name: 'cursor', type: 'string', required: true, constraint: 'New cursor ISO written after draining.' },
+        ],
+        outputKind: 'object',
+        effects: ['Advances nodes/<nodeId>/inbox.jsonl.cursor.', 'Read-only on inbox.jsonl itself.'],
+    },
+    run: async (input) => {
+        const nodeId = typeof input['node'] === 'string' && input['node'].trim() !== ''
+            ? input['node'].trim()
+            : requireCallerNode();
+        const cursor = input['all'] === true ? undefined : readCursor(nodeId);
+        const entries = readInboxSince(nodeId, cursor);
+        const newCursor = entries.length > 0 ? entries[entries.length - 1].ts : cursor ?? new Date().toISOString();
+        writeCursor(nodeId, newCursor);
+        return {
+            node_id: nodeId,
+            digest: coalesce(entries),
+            entries: entries,
+            cursor: newCursor,
+        };
+    },
+    render: (r) => {
+        const n = Array.isArray(r['entries']) ? r['entries'].length : 0;
+        const digest = typeof r['digest'] === 'string' && r['digest'].trim() !== ''
+            ? r['digest']
+            : 'Inbox empty — nothing new from your subscriptions.';
+        return `<feed node="${r['node_id']}" unread="${n}">\n${digest}\n</feed>`;
+    },
+});
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+export function registerPush() {
+    return defineBranch({
+        name: 'push',
+        rootEntry: {
+            concept: 'the one verb up the graph — a node reports to whoever subscribes to it',
+            desc: 'push a report (update / urgent / final) to your subscribers',
+            useWhen: 'sharing progress, raising an alert, or finishing your work',
+        },
+        help: {
+            name: 'push',
+            summary: 'push a report to your subscribers',
+            model: 'A push writes a markdown report to the node\'s reports/ history and fans a lightweight pointer to every subscriber\'s inbox (not the content — they dereference lazily). The stophook auto-pushes an `update` every stop, so the feed is continuous; you push explicitly for intentional signals. `push final` is how ANY node finishes: write the canonical result, mark done, close the window.',
+            children: [
+                { name: 'update', desc: TIER_BLURB.update, useWhen: 'sharing routine progress explicitly' },
+                { name: 'urgent', desc: TIER_BLURB.urgent, useWhen: 'something your managers must see now' },
+                { name: 'final', desc: TIER_BLURB.final, useWhen: 'the work is done — this finishes the node' },
+            ],
+        },
+        children: [makeTierLeaf('update'), makeTierLeaf('urgent'), makeTierLeaf('final')],
+    });
+}
+export function registerFeed() {
+    return defineBranch({
+        name: 'feed',
+        rootEntry: {
+            concept: 'the read side of the spine — pointers your subscriptions have pushed',
+            desc: 'drain your inbox feed into a digest',
+            useWhen: 'catching up on what the nodes you subscribe to have reported',
+        },
+        help: {
+            name: 'feed',
+            summary: 'read the per-node inbox feed',
+            model: 'Each node has an inbox.jsonl that accumulates ~30-token pointers from publishers it subscribes to. `feed read` coalesces unread pointers into one digest; dereference the reports that matter by reading their ref paths.',
+            children: [{ name: 'read', desc: 'drain unread pointers into a digest', useWhen: 'checking what your subscriptions pushed' }],
+        },
+        children: [feedReadLeaf],
+    });
+}

package/dist/commands/revive.d.ts

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

package/dist/commands/revive.js

@@ -0,0 +1,64 @@
+// `crtr canvas revive` — explicit node revival.
+//
+// Bypasses the daemon: directly opens a fresh tmux window for a node that is
+// done, idle, or dead. Default behavior resumes the saved pi conversation
+// (--resume); pass --fresh to start a clean pi session against the context dir.
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { reviveNode } from '../core/runtime/revive.js';
+import { getNode } from '../core/canvas/index.js';
+// ---------------------------------------------------------------------------
+// revive node
+// ---------------------------------------------------------------------------
+export const reviveLeaf = defineLeaf({
+    name: 'revive',
+    help: {
+        name: 'canvas revive',
+        summary: 'open a fresh tmux window for a node, optionally resuming its saved pi conversation',
+        params: [
+            {
+                kind: 'positional',
+                name: 'node',
+                required: true,
+                constraint: 'Node id to revive.',
+            },
+            {
+                kind: 'flag',
+                name: 'fresh',
+                type: 'bool',
+                required: false,
+                default: false,
+                constraint: 'When set, start a clean pi session (no --resume). Default: resume the saved conversation.',
+            },
+        ],
+        output: [
+            { name: 'window', type: 'string', required: false, constraint: 'New tmux window id.' },
+            { name: 'session', type: 'string', required: true, constraint: 'Tmux session the node was placed in.' },
+            { name: 'resumed', type: 'boolean', required: true, constraint: 'True when pi was told to --resume the saved conversation.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Opens a background (non-focus-stealing) tmux window running pi.',
+            'Updates the node\'s canvas record: status=active, intent=null, window=<new>.',
+        ],
+    },
+    run: async (input) => {
+        const nodeId = input['node'];
+        const fresh = input['fresh'] ?? false;
+        // Validate the node exists before attempting revival.
+        const meta = getNode(nodeId);
+        if (meta === null) {
+            throw new InputError({
+                error: 'not_found',
+                message: `no node: ${nodeId}`,
+                next: 'List nodes with `crtr node inspect list`.',
+            });
+        }
+        const result = reviveNode(nodeId, { resume: !fresh });
+        return {
+            window: result.window ?? undefined,
+            session: result.session,
+            resumed: result.resumed,
+        };
+    },
+});

package/dist/commands/skill/author.d.ts

@@ -0,0 +1,3 @@
+export declare const authorGuide: import("../../core/command.js").LeafDef;
+export declare const authorScaffold: import("../../core/command.js").LeafDef;
+export declare const authorBranch: import("../../core/command.js").BranchDef;

package/dist/commands/skill/author.js

@@ -0,0 +1,147 @@
+import { join } from 'node:path';
+import { writeFileSync } from 'node:fs';
+import { defineLeaf, defineBranch } from '../../core/command.js';
+import { usage, general, notFound } from '../../core/errors.js';
+import { SCOPE_SKILL_PLUGIN, SKILL_ENTRY_FILE, SKILLS_DIR, SKILL_TYPES, isSkillType, } from '../../types.js';
+import { parseSkillQualifier, findPluginByName, } from '../../core/resolver.js';
+import { resolveScopeArg, requireScopeRoot, scopeSkillsDir, } from '../../core/scope.js';
+import { serializeFrontmatter } from '../../core/frontmatter.js';
+import { ensureScopeInitialized } from '../../core/config.js';
+import { ensureDir, pathExists } from '../../core/fs-utils.js';
+import { skillCreatePrompt, skillTemplatePrompt } from '../../prompts/skill.js';
+import { VALID_TYPES, resolveWriteScope } from './shared.js';
+export const authorGuide = defineLeaf({
+    name: 'guide',
+    help: {
+        name: 'skill author guide',
+        summary: 'load the skill authoring workflow — two stages: omit type to pick one, pass type for its full skeleton',
+        params: [
+            { kind: 'flag', name: 'type', type: 'enum', choices: [...VALID_TYPES], required: false, constraint: 'OMIT to receive the template-picker guide first; pass on the second call for that type\'s full workflow + skeleton.' },
+            { kind: 'flag', name: 'topic', type: 'string', required: false, constraint: 'Optional topic context injected into the guide.' },
+        ],
+        output: [
+            { name: 'guide', type: 'string', required: true, constraint: 'Stage 1 (no type): the template-picker workflow. Stage 2 (type given): that type\'s authoring workflow + skeleton.' },
+            { name: 'type', type: 'string | null', required: true, constraint: 'Echo of the requested type, or null on the picker stage.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const type = input['type'];
+        const topic = input['topic'];
+        const topicArg = topic !== undefined ? topic : '';
+        // Progressive disclosure: no type → template picker (stage 1);
+        // type given → that type's full workflow + skeleton (stage 2).
+        if (type === undefined) {
+            return { guide: skillCreatePrompt(topicArg), type: null };
+        }
+        return { guide: skillTemplatePrompt(type, topicArg), type };
+    },
+});
+export const authorScaffold = defineLeaf({
+    name: 'scaffold',
+    help: {
+        name: 'skill author scaffold',
+        summary: 'create an empty SKILL.md stub at the given qualifier',
+        params: [
+            { kind: 'positional', name: 'qualifier', required: true, constraint: 'Skill identifier in <plugin>/<skill> form.' },
+            { kind: 'flag', name: 'type', type: 'enum', choices: [...VALID_TYPES], required: false, constraint: 'One of: playbook, primer, reference, runbook, freeform.' },
+            { kind: 'flag', name: 'description', type: 'string', required: false, constraint: 'Short description written to frontmatter.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: project if available, else user.' },
+        ],
+        output: [
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the scaffolded SKILL.md.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Recommended next call to load the authoring guide.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Creates the skill directory and SKILL.md stub at the resolved location.',
+            'Writes frontmatter with name, description (if provided), and type (if provided).',
+        ],
+    },
+    run: async (input) => {
+        const qualifier = input['qualifier'];
+        const typeStr = input['type'];
+        const description = input['description'];
+        const scopeStr = input['scope'];
+        const parsed = parseSkillQualifier(qualifier);
+        if (parsed.segments.length === 0) {
+            throw usage('skill name required in qualifier');
+        }
+        // For scaffold, the qualifier is always <plugin>/<skill>. If it's a single segment,
+        // treat it as a scope-direct skill name. Otherwise first segment is the plugin.
+        const pluginName = parsed.segments.length > 1 ? parsed.segments[0] : undefined;
+        const skillName = parsed.segments.length > 1
+            ? parsed.segments.slice(1).join('/')
+            : parsed.segments[0];
+        if (typeStr !== undefined && !isSkillType(typeStr)) {
+            throw usage(`unknown skill type: ${typeStr} / valid: ${SKILL_TYPES.join(' | ')}`);
+        }
+        const skillType = typeStr !== undefined && isSkillType(typeStr) ? typeStr : undefined;
+        let skillFile;
+        // Scope-direct: no plugin qualifier, or explicit `_/` sentinel (internal only)
+        if (pluginName === undefined || pluginName === SCOPE_SKILL_PLUGIN) {
+            const scope = resolveWriteScope(scopeStr);
+            const scopeRootPath = requireScopeRoot(scope);
+            ensureScopeInitialized(scope, scopeRootPath);
+            const skillsRoot = scopeSkillsDir(scope);
+            if (!skillsRoot) {
+                throw general(`no skills dir for scope ${scope}`);
+            }
+            const skillDir = join(skillsRoot, ...skillName.split('/'));
+            skillFile = join(skillDir, SKILL_ENTRY_FILE);
+            if (pathExists(skillFile)) {
+                throw general(`skill already exists: ${skillFile}`);
+            }
+            ensureDir(skillDir);
+            const fm = serializeFrontmatter({
+                name: skillName,
+                description,
+                type: skillType,
+            });
+            writeFileSync(skillFile, fm, 'utf8');
+        }
+        else {
+            // Plugin-scoped scaffold
+            const scopeForLookup = scopeStr !== undefined
+                ? (() => {
+                    const r = resolveScopeArg(scopeStr);
+                    return r !== 'all' ? r : undefined;
+                })()
+                : undefined;
+            const plugin = scopeForLookup !== undefined
+                ? findPluginByName(pluginName, scopeForLookup)
+                : findPluginByName(pluginName);
+            if (!plugin) {
+                throw notFound(`plugin not found: ${pluginName}`);
+            }
+            const skillDir = join(plugin.root, SKILLS_DIR, ...skillName.split('/'));
+            skillFile = join(skillDir, SKILL_ENTRY_FILE);
+            if (pathExists(skillFile)) {
+                throw general(`skill already exists: ${skillFile}`);
+            }
+            ensureDir(skillDir);
+            const fm = serializeFrontmatter({
+                name: skillName,
+                description,
+                type: skillType,
+            });
+            writeFileSync(skillFile, fm, 'utf8');
+        }
+        const typeHint = skillType !== undefined ? `--type ${skillType} ` : '';
+        const follow_up = `crtr skill author guide ${typeHint}--topic "${skillName}"`;
+        return { path: skillFile, follow_up };
+    },
+});
+export const authorBranch = defineBranch({
+    name: 'author',
+    help: {
+        name: 'skill author',
+        summary: 'create and scaffold new skills',
+        children: [
+            { name: 'guide', desc: 'load authoring workflow + skeleton for a type', useWhen: 'writing a new skill and need the template and instructions' },
+            { name: 'scaffold', desc: 'create an empty SKILL.md stub', useWhen: 'initializing the file before writing content' },
+        ],
+    },
+    children: [authorGuide, authorScaffold],
+});

package/dist/commands/skill/find.d.ts

@@ -0,0 +1,4 @@
+export declare const findList: import("../../core/command.js").LeafDef;
+export declare const findSearch: import("../../core/command.js").LeafDef;
+export declare const findGrep: import("../../core/command.js").LeafDef;
+export declare const findBranch: import("../../core/command.js").BranchDef;

package/dist/commands/skill/find.js

@@ -0,0 +1,254 @@
+import { join } from 'node:path';
+import { defineLeaf, defineBranch } from '../../core/command.js';
+import { usage } from '../../core/errors.js';
+import { SCOPE_SKILL_PLUGIN, SKILLS_DIR } from '../../types.js';
+import { listScopes, scopeSkillsDir } from '../../core/scope.js';
+import { listAllSkills, listInstalledPlugins } from '../../core/resolver.js';
+import { paginate } from '../../core/pagination.js';
+import { walkFiles, readText } from '../../core/fs-utils.js';
+export const findList = defineLeaf({
+    name: 'list',
+    help: {
+        name: 'skill find list',
+        summary: 'paginated list of installed skills',
+        params: [
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project', 'all'], required: false, constraint: 'Default: all.' },
+            { kind: 'flag', name: 'plugin', type: 'string', required: false, constraint: 'Filter to a single plugin name.' },
+            { kind: 'flag', name: 'include-disabled', type: 'bool', required: false, constraint: 'When present, includes disabled skills.' },
+            { kind: 'flag', name: 'limit', type: 'int', required: false, default: 50, constraint: 'Max 200.' },
+            { kind: 'flag', name: 'cursor', type: 'string', required: false, constraint: 'Opaque token from next_cursor. Omit on first call.' },
+            { kind: 'flag', name: 'full', type: 'bool', required: false, constraint: 'When present, includes each skill\'s description in items. Off by default to keep enumerations cheap; pair with --plugin or --limit to bound cost.' },
+        ],
+        output: [
+            { name: 'items', type: 'object[]', required: true, constraint: 'Each: {name, plugin, scope, enabled, disabled_in?}. With --full, each item also includes description. Sorted by scope then plugin then name ascending.' },
+            { name: 'next_cursor', type: 'string | null', required: true, constraint: 'null means no more items.' },
+            { name: 'total', type: 'integer | null', required: true, constraint: 'Exact when cheap; null otherwise.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands for drilling into an item or refining the list.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const scopeStr = input['scope'];
+        const pluginFilter = input['plugin'];
+        const includeDisabled = input['includeDisabled'];
+        const limitRaw = input['limit'];
+        const limit = Math.min(Math.max(1, limitRaw), 200);
+        const cursor = input['cursor'];
+        const full = input['full'];
+        const scopes = listScopes(scopeStr);
+        const skills = scopes
+            .flatMap((s) => listAllSkills(s))
+            .filter((sk) => {
+            if (pluginFilter !== undefined && sk.plugin !== pluginFilter)
+                return false;
+            if (!includeDisabled && !sk.enabled)
+                return false;
+            return true;
+        });
+        // Sort by scope then plugin then name ascending
+        const scopeOrder = { project: 0, user: 1, builtin: 2 };
+        skills.sort((a, b) => {
+            const so = (scopeOrder[a.scope] !== undefined ? scopeOrder[a.scope] : 3) -
+                (scopeOrder[b.scope] !== undefined ? scopeOrder[b.scope] : 3);
+            if (so !== 0)
+                return so;
+            const po = a.plugin.localeCompare(b.plugin);
+            if (po !== 0)
+                return po;
+            return a.name.localeCompare(b.name);
+        });
+        const keyOf = (sk) => `${sk.scope}/${sk.plugin}/${sk.name}`;
+        const params = {};
+        if (limit !== undefined)
+            params.limit = limit;
+        if (cursor !== undefined)
+            params.cursor = cursor;
+        const result = paginate(skills, params, {
+            defaultLimit: 50,
+            maxLimit: 200,
+            keyOf,
+            total: 'count',
+        });
+        return {
+            items: result.items.map((sk) => {
+                const base = {
+                    name: sk.name,
+                    plugin: sk.plugin,
+                    scope: sk.scope,
+                    enabled: sk.enabled,
+                    disabled_in: sk.disabledIn !== undefined ? sk.disabledIn : null,
+                };
+                if (full) {
+                    base['description'] = sk.frontmatter.description !== undefined ? sk.frontmatter.description : null;
+                }
+                return base;
+            }),
+            next_cursor: result.next_cursor,
+            total: result.total,
+            follow_up: 'Use `crtr skill read <name>` for the full SKILL.md body. Run `crtr skill find list -h` for filters and verbosity.',
+        };
+    },
+});
+export const findSearch = defineLeaf({
+    name: 'search',
+    help: {
+        name: 'skill find search',
+        summary: 'search skills by name, description, and keywords',
+        params: [
+            { kind: 'positional', name: 'query', required: true, constraint: 'Whitespace-separated terms matched case-insensitively against name, description, and keywords; skills matching more terms rank higher.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project', 'all'], required: false, constraint: 'Default: all.' },
+            { kind: 'flag', name: 'plugin', type: 'string', required: false, constraint: 'Filter to a single plugin name.' },
+            { kind: 'flag', name: 'include-disabled', type: 'bool', required: false, constraint: 'When present, includes disabled skills.' },
+            { kind: 'flag', name: 'search-body', type: 'bool', required: false, constraint: 'When present, also searches inside SKILL.md body text.' },
+        ],
+        output: [
+            { name: 'query', type: 'string', required: true, constraint: 'Echo of the input query.' },
+            { name: 'hits', type: 'object[]', required: true, constraint: 'Each: {name, plugin, scope, score, description}. Sorted by score descending. description is the frontmatter line — the discriminator for picking which hit to read in full.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands for drilling into a hit or refining the search.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const query = input['query'];
+        const scopeStr = input['scope'];
+        const pluginFilter = input['plugin'];
+        const includeDisabled = input['includeDisabled'];
+        const searchBody = input['searchBody'];
+        const terms = query
+            .toLowerCase()
+            .split(/\s+/)
+            .filter((t) => t.length > 0);
+        if (terms.length === 0)
+            throw usage('query must contain at least one non-whitespace term');
+        const scopes = listScopes(scopeStr);
+        const candidates = scopes
+            .flatMap((s) => listAllSkills(s))
+            .filter((sk) => {
+            if (pluginFilter !== undefined && sk.plugin !== pluginFilter)
+                return false;
+            if (!includeDisabled && !sk.enabled)
+                return false;
+            return true;
+        });
+        const hits = [];
+        for (const sk of candidates) {
+            const matchedSet = new Set();
+            let score = 0;
+            const nameLc = sk.name.toLowerCase();
+            const descLc = sk.frontmatter.description !== undefined ? sk.frontmatter.description.toLowerCase() : null;
+            const kwsLc = sk.frontmatter.keywords !== undefined ? sk.frontmatter.keywords.map((k) => k.toLowerCase()) : null;
+            const bodyLc = searchBody ? readText(sk.path).toLowerCase() : null;
+            for (const term of terms) {
+                if (nameLc.includes(term)) {
+                    score += 10;
+                    matchedSet.add('name');
+                }
+                if (descLc !== null && descLc.includes(term)) {
+                    score += 4;
+                    matchedSet.add('description');
+                }
+                if (kwsLc !== null && kwsLc.some((k) => k.includes(term))) {
+                    score += 6;
+                    matchedSet.add('keywords');
+                }
+                if (bodyLc !== null && bodyLc.includes(term)) {
+                    score += 1;
+                    matchedSet.add('body');
+                }
+            }
+            if (score > 0)
+                hits.push({ skill: sk, score, matched: Array.from(matchedSet) });
+        }
+        hits.sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name));
+        return {
+            query,
+            hits: hits.map((h) => ({
+                name: h.skill.name,
+                plugin: h.skill.plugin,
+                scope: h.skill.scope,
+                score: h.score,
+                description: h.skill.frontmatter.description !== undefined ? h.skill.frontmatter.description : null,
+            })),
+            follow_up: 'Use `crtr skill read <name>` for the full SKILL.md body. Run `crtr skill find search -h` for filters.',
+        };
+    },
+});
+export const findGrep = defineLeaf({
+    name: 'grep',
+    help: {
+        name: 'skill find grep',
+        summary: 'search skill file contents for a regex pattern',
+        params: [
+            { kind: 'positional', name: 'pattern', required: true, constraint: 'ECMAScript regex. Applied to each line of every SKILL.md file.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project', 'all'], required: false, constraint: 'Default: all.' },
+            { kind: 'flag', name: 'plugin', type: 'string', required: false, constraint: 'Filter to a single plugin name.' },
+        ],
+        output: [
+            { name: 'matches', type: 'object[]', required: true, constraint: 'Each: {path, line, text}. path is absolute. Sorted by path then line ascending.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const pattern = input['pattern'];
+        const scopeStr = input['scope'];
+        const pluginFilter = input['plugin'];
+        let regex;
+        try {
+            regex = new RegExp(pattern);
+        }
+        catch {
+            throw usage(`invalid regex pattern: ${pattern}`);
+        }
+        const scopes = listScopes(scopeStr);
+        const skillsDirs = [];
+        for (const s of scopes) {
+            if (pluginFilter === undefined || pluginFilter === SCOPE_SKILL_PLUGIN) {
+                const root = scopeSkillsDir(s);
+                if (root)
+                    skillsDirs.push(root);
+            }
+            for (const plugin of listInstalledPlugins(s)) {
+                if (!plugin.enabled)
+                    continue;
+                if (pluginFilter !== undefined && plugin.name !== pluginFilter)
+                    continue;
+                skillsDirs.push(join(plugin.root, SKILLS_DIR));
+            }
+        }
+        const matchLines = [];
+        for (const skillsDir of skillsDirs) {
+            const files = walkFiles(skillsDir);
+            for (const file of files) {
+                const content = readText(file);
+                const lines = content.split('\n');
+                lines.forEach((lineText, idx) => {
+                    if (regex.test(lineText)) {
+                        matchLines.push({ path: file, line: idx + 1, text: lineText });
+                    }
+                });
+            }
+        }
+        // Sort by path then line ascending
+        matchLines.sort((a, b) => {
+            const pc = a.path.localeCompare(b.path);
+            return pc !== 0 ? pc : a.line - b.line;
+        });
+        return { matches: matchLines };
+    },
+});
+export const findBranch = defineBranch({
+    name: 'find',
+    help: {
+        name: 'skill find',
+        summary: 'discover skills by listing, keyword search, or body grep',
+        children: [
+            { name: 'list', desc: 'paginated list of installed skills', useWhen: 'enumerating all available skills' },
+            { name: 'search', desc: 'keyword search across name/description/keywords', useWhen: 'looking for skills matching a topic' },
+            { name: 'grep', desc: 'regex search across SKILL.md bodies', useWhen: 'finding skills containing specific text or patterns' },
+        ],
+    },
+    children: [findList, findSearch, findGrep],
+});

package/dist/commands/skill/read.d.ts

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