@crouton-kit/crouter 0.3.11 → 0.3.12

package/dist/core/personas/loader.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Persona file loader.
+ *
+ * Discovers and parses persona markdown files with YAML frontmatter.
+ * Resolution order (highest → lowest precedence): project > user > builtin.
+ *
+ * Layout on disk:
+ *   <root>/personas/<kind>/base.md
+ *   <root>/personas/<kind>/orchestrator.md
+ *   <root>/personas/orchestration-kernel.md
+ *
+ * The builtin root is src/builtin-personas (or dist/builtin-personas in the
+ * compiled build), resolved relative to this module — mirrors the pattern used
+ * for STOPHOOK_PATH in spawn.ts.
+ */
+export interface LoadedPersona {
+    /** Raw, uncoerced frontmatter key/value record (null when no frontmatter). */
+    frontmatter: Record<string, unknown> | null;
+    /** Body text with any @include directives inlined. */
+    body: string;
+}
+/**
+ * Load and parse a persona file for the given `kind` and `mode`.
+ *
+ * Returns `null` when no file is found in any scope (project/user/builtin).
+ * On success, `@include` directives in the body are resolved and inlined.
+ */
+export declare function loadPersona(kind: string, mode: 'base' | 'orchestrator'): LoadedPersona | null;
+/**
+ * Load the raw text of the orchestration kernel (no frontmatter, body only).
+ * Returns an empty string if the kernel file cannot be found.
+ */
+export declare function loadKernel(): string;
+/**
+ * Load the base runtime prompt — the node operating protocol prepended to
+ * EVERY persona (push/finish/delegate/feed/ask). Returns '' if not found.
+ */
+export declare function loadRuntimeBase(): string;
+/**
+ * Enumerate the kinds with at least one persona file (base.md or
+ * orchestrator.md) across all scope roots (project/user/builtin). Used to
+ * validate a requested `--kind` and to list the valid choices.
+ */
+export declare function availableKinds(): string[];

package/dist/core/personas/loader.js

@@ -0,0 +1,157 @@
+/**
+ * Persona file loader.
+ *
+ * Discovers and parses persona markdown files with YAML frontmatter.
+ * Resolution order (highest → lowest precedence): project > user > builtin.
+ *
+ * Layout on disk:
+ *   <root>/personas/<kind>/base.md
+ *   <root>/personas/<kind>/orchestrator.md
+ *   <root>/personas/orchestration-kernel.md
+ *
+ * The builtin root is src/builtin-personas (or dist/builtin-personas in the
+ * compiled build), resolved relative to this module — mirrors the pattern used
+ * for STOPHOOK_PATH in spawn.ts.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseFrontmatterGeneric } from '../frontmatter.js';
+import { userScopeRoot, findProjectScopeRoot } from '../scope.js';
+// ---------------------------------------------------------------------------
+// Builtin root resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the builtin-personas directory from the location of this compiled
+ * or source module. Works from both `dist/core/personas/loader.js` and
+ * `src/core/personas/loader.ts` (tsx dev runs).
+ */
+function builtinPersonasRoot() {
+    const here = dirname(fileURLToPath(import.meta.url)); // dist/core/personas or src/core/personas
+    const coreDir = dirname(here); // dist/core or src/core
+    const pkgDir = dirname(coreDir); // dist/ or src/
+    const distPath = join(pkgDir, 'builtin-personas');
+    const srcPath = join(dirname(pkgDir), 'src', 'builtin-personas');
+    // Prefer the path that exists; fall back to the dist-sibling (which may not
+    // exist yet if the package is being run pre-build, but that is the caller's
+    // problem).
+    if (existsSync(distPath))
+        return distPath;
+    if (existsSync(srcPath))
+        return srcPath;
+    return distPath;
+}
+// ---------------------------------------------------------------------------
+// Scope roots for personas
+// ---------------------------------------------------------------------------
+/** Returns the ordered list of roots to search, highest precedence first. */
+function personaSearchRoots() {
+    const roots = [];
+    const projectRoot = findProjectScopeRoot();
+    if (projectRoot)
+        roots.push(join(projectRoot, 'personas'));
+    roots.push(join(userScopeRoot(), 'personas'));
+    roots.push(builtinPersonasRoot());
+    return roots;
+}
+// ---------------------------------------------------------------------------
+// File resolution helpers
+// ---------------------------------------------------------------------------
+/**
+ * Find the first existing file across the scope roots.
+ * `relativePath` is relative to each root (e.g. 'general/base.md').
+ */
+function resolveFile(relativePath) {
+    for (const root of personaSearchRoots()) {
+        const candidate = join(root, relativePath);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// @include inlining
+// ---------------------------------------------------------------------------
+const INCLUDE_RE = /^@include\s+(\S+)\s*$/m;
+/**
+ * Inline any `@include <filename>` directive found in `body`.
+ * The included file is looked up via the same scope-resolution chain; if it
+ * cannot be found, the directive line is replaced with an empty string rather
+ * than throwing — callers that need the kernel should use `loadKernel()`
+ * directly and can assert it themselves.
+ */
+function inlineIncludes(body) {
+    return body.replace(INCLUDE_RE, (_match, filename) => {
+        const path = resolveFile(filename);
+        if (!path)
+            return '';
+        const src = readFileSync(path, 'utf8');
+        // The kernel file has no frontmatter, but run through the parser just in
+        // case someone added one in a user/project override.
+        const { body: kernelBody } = parseFrontmatterGeneric(src);
+        return kernelBody.trim();
+    });
+}
+/**
+ * Load and parse a persona file for the given `kind` and `mode`.
+ *
+ * Returns `null` when no file is found in any scope (project/user/builtin).
+ * On success, `@include` directives in the body are resolved and inlined.
+ */
+export function loadPersona(kind, mode) {
+    const relativePath = `${kind}/${mode}.md`;
+    const filePath = resolveFile(relativePath);
+    if (!filePath)
+        return null;
+    const src = readFileSync(filePath, 'utf8');
+    const { data, body } = parseFrontmatterGeneric(src);
+    return {
+        frontmatter: data,
+        body: inlineIncludes(body).trim(),
+    };
+}
+/**
+ * Load the raw text of the orchestration kernel (no frontmatter, body only).
+ * Returns an empty string if the kernel file cannot be found.
+ */
+export function loadKernel() {
+    const filePath = resolveFile('orchestration-kernel.md');
+    if (!filePath)
+        return '';
+    const src = readFileSync(filePath, 'utf8');
+    const { body } = parseFrontmatterGeneric(src);
+    return body.trim();
+}
+/**
+ * Load the base runtime prompt — the node operating protocol prepended to
+ * EVERY persona (push/finish/delegate/feed/ask). Returns '' if not found.
+ */
+export function loadRuntimeBase() {
+    const filePath = resolveFile('runtime-base.md');
+    if (!filePath)
+        return '';
+    const src = readFileSync(filePath, 'utf8');
+    const { body } = parseFrontmatterGeneric(src);
+    return body.trim();
+}
+/**
+ * Enumerate the kinds with at least one persona file (base.md or
+ * orchestrator.md) across all scope roots (project/user/builtin). Used to
+ * validate a requested `--kind` and to list the valid choices.
+ */
+export function availableKinds() {
+    const kinds = new Set();
+    for (const root of personaSearchRoots()) {
+        if (!existsSync(root))
+            continue;
+        for (const entry of readdirSync(root, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const dir = join(root, entry.name);
+            if (existsSync(join(dir, 'base.md')) || existsSync(join(dir, 'orchestrator.md'))) {
+                kinds.add(entry.name);
+            }
+        }
+    }
+    return [...kinds].sort();
+}

package/dist/core/personas/resolve.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Persona resolver — composes base + orchestrator personas into a
+ * ResolvedPersona ready for use when spawning a canvas node.
+ *
+ * Composition rules:
+ *   mode==='base'
+ *     → load <kind>/base.md; if missing fall back to general defaults.
+ *
+ *   mode==='orchestrator'
+ *     → prefer <kind>/orchestrator.md (which must embed the kernel via
+ *       @include orchestration-kernel.md — inlined by the loader).
+ *       If no orchestrator.md exists for this kind, compose:
+ *         <kind>/base.md body  +  '\n\n'  +  kernel body
+ *       If even the base is missing, fall back to general defaults + kernel.
+ *
+ * Frontmatter from whichever file is the primary source (orchestrator.md >
+ * base.md) supplies model/lifecycle/skills/extensions/tools.
+ *
+ * Lifecycle defaults:
+ *   base         → 'terminal'
+ *   orchestrator → 'resident'
+ */
+export interface ResolvedPersona {
+    systemPrompt: string;
+    extensions: string[];
+    skills: string[];
+    model?: string;
+    lifecycle: 'terminal' | 'resident';
+    tools?: string[];
+}
+/**
+ * Resolve a fully composed persona for the given `kind` and `mode`.
+ *
+ * Never throws for missing files — missing personas produce sensible defaults.
+ */
+export declare function resolve(kind: string, mode: 'base' | 'orchestrator'): ResolvedPersona;

package/dist/core/personas/resolve.js

@@ -0,0 +1,110 @@
+/**
+ * Persona resolver — composes base + orchestrator personas into a
+ * ResolvedPersona ready for use when spawning a canvas node.
+ *
+ * Composition rules:
+ *   mode==='base'
+ *     → load <kind>/base.md; if missing fall back to general defaults.
+ *
+ *   mode==='orchestrator'
+ *     → prefer <kind>/orchestrator.md (which must embed the kernel via
+ *       @include orchestration-kernel.md — inlined by the loader).
+ *       If no orchestrator.md exists for this kind, compose:
+ *         <kind>/base.md body  +  '\n\n'  +  kernel body
+ *       If even the base is missing, fall back to general defaults + kernel.
+ *
+ * Frontmatter from whichever file is the primary source (orchestrator.md >
+ * base.md) supplies model/lifecycle/skills/extensions/tools.
+ *
+ * Lifecycle defaults:
+ *   base         → 'terminal'
+ *   orchestrator → 'resident'
+ */
+import { loadPersona, loadKernel, loadRuntimeBase } from './loader.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function toStringArray(v) {
+    if (!Array.isArray(v))
+        return [];
+    return v.filter((x) => typeof x === 'string');
+}
+function toOptionalString(v) {
+    return typeof v === 'string' ? v : undefined;
+}
+function toLifecycle(v, defaultValue) {
+    if (v === 'terminal' || v === 'resident')
+        return v;
+    return defaultValue;
+}
+/** The bare-minimum system prompt used when no persona file is found at all. */
+function fallbackBasePrompt(kind) {
+    return `You are a ${kind} agent. Complete the task you have been given.`;
+}
+/** Prepend the base runtime protocol (push/finish/delegate/feed/ask) to a
+ *  persona's prompt — every node, every kind, every mode gets it first. */
+function withBase(personaPrompt) {
+    const base = loadRuntimeBase();
+    return base ? `${base}\n\n---\n\n${personaPrompt}` : personaPrompt;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a fully composed persona for the given `kind` and `mode`.
+ *
+ * Never throws for missing files — missing personas produce sensible defaults.
+ */
+export function resolve(kind, mode) {
+    if (mode === 'base') {
+        const persona = loadPersona(kind, 'base');
+        if (!persona) {
+            // No persona file for this kind — use minimal defaults.
+            return {
+                systemPrompt: withBase(fallbackBasePrompt(kind)),
+                extensions: [],
+                skills: [],
+                lifecycle: 'terminal',
+            };
+        }
+        const fm = persona.frontmatter ?? {};
+        return {
+            systemPrompt: withBase(persona.body || fallbackBasePrompt(kind)),
+            extensions: toStringArray(fm['extensions']),
+            skills: toStringArray(fm['skills']),
+            model: toOptionalString(fm['model']),
+            lifecycle: toLifecycle(fm['lifecycle'], 'terminal'),
+            tools: fm['tools'] !== undefined ? toStringArray(fm['tools']) : undefined,
+        };
+    }
+    // mode === 'orchestrator'
+    const orchestratorPersona = loadPersona(kind, 'orchestrator');
+    if (orchestratorPersona) {
+        // Orchestrator file exists; @include was already inlined by the loader.
+        const fm = orchestratorPersona.frontmatter ?? {};
+        return {
+            systemPrompt: withBase(orchestratorPersona.body || fallbackBasePrompt(kind)),
+            extensions: toStringArray(fm['extensions']),
+            skills: toStringArray(fm['skills']),
+            model: toOptionalString(fm['model']),
+            lifecycle: toLifecycle(fm['lifecycle'], 'resident'),
+            tools: fm['tools'] !== undefined ? toStringArray(fm['tools']) : undefined,
+        };
+    }
+    // No orchestrator.md for this kind — compose base + bare kernel.
+    const kernel = loadKernel();
+    const basePersona = loadPersona(kind, 'base');
+    const baseBody = basePersona?.body || fallbackBasePrompt(kind);
+    const fm = basePersona?.frontmatter ?? {};
+    // Append the kernel to the base body (with separator if kernel is non-empty).
+    const systemPrompt = kernel ? `${baseBody}\n\n${kernel}` : baseBody;
+    return {
+        systemPrompt: withBase(systemPrompt),
+        extensions: toStringArray(fm['extensions']),
+        skills: toStringArray(fm['skills']),
+        model: toOptionalString(fm['model']),
+        // Override lifecycle to 'resident' — this node is being used as an orchestrator.
+        lifecycle: 'resident',
+        tools: fm['tools'] !== undefined ? toStringArray(fm['tools']) : undefined,
+    };
+}

package/dist/core/render.d.ts

@@ -0,0 +1,11 @@
+import type { LeafHelp } from './help.js';
+import type { ErrorPayload } from './io.js';
+/** Schema-driven fallback: turn a result object into agent-ready XML+markdown.
+ *  Field order follows the leaf's declared output schema; any extra keys append
+ *  after. Scalars become attributes or a bullet list, prose and collections
+ *  become their own fenced blocks. */
+export declare function renderResult(result: Record<string, unknown>, help: LeafHelp): string;
+/** Render a structured failure as an instruction-shaped block: what broke, what
+ *  was received, and the recovery road sign — the same recovery info the JSON
+ *  payload carries, shaped for the model to act on. */
+export declare function renderError(p: ErrorPayload): string;

package/dist/core/render.js

@@ -0,0 +1,126 @@
+// Default stdout rendering: the result a leaf returns is written FOR the model
+// to act on, not as data to parse. Output is a continuation of the agent's
+// prompt — light XML fences around markdown, prose where prose belongs. The
+// raw JSON object is still available behind the `--json` global for tooling.
+//
+// A leaf may hand `defineLeaf` a bespoke `render(result)` for instruction-shaped
+// output (see `node new`, `push`, `feed read`). Everything else falls through to
+// the schema-driven generic renderer here, so every command obeys the paradigm
+// without a hand-written renderer.
+// Field names whose value is prose the agent reads, not a scalar it keys on —
+// these always render as their own fenced block, never as a tag attribute.
+const PROSE_FIELDS = new Set([
+    'follow_up', 'digest', 'message', 'next', 'result', 'content', 'body', 'guide',
+    'summary', 'note', 'reason', 'detail', 'details', 'hint', 'instruction',
+    'instructions', 'prompt', 'roadmap', 'report', 'answer', 'response', 'text',
+]);
+/** Minimal attribute-value sanitization: values here are controlled (ids,
+ *  statuses, counts), so collapse quotes rather than entity-escape. */
+function attrEsc(s) {
+    return String(s).replace(/"/g, "'").replace(/\n/g, ' ');
+}
+function scalarStr(v) {
+    if (v === null || v === undefined)
+        return '';
+    if (Array.isArray(v))
+        return v.map(scalarStr).join(', ');
+    if (typeof v === 'object')
+        return JSON.stringify(v);
+    return String(v);
+}
+/** A string field is prose when it is named as such, spans lines, or is long
+ *  enough that it reads as a sentence rather than an identifier. */
+function isProse(name, v) {
+    if (typeof v !== 'string')
+        return false;
+    if (PROSE_FIELDS.has(name))
+        return true;
+    return v.includes('\n') || v.length > 80;
+}
+/** Short, space-free scalars ride as attributes on the open tag (ids, statuses,
+ *  counts); everything else that isn't prose lists as a markdown bullet. */
+function isAttr(v) {
+    if (typeof v === 'number' || typeof v === 'boolean')
+        return true;
+    return typeof v === 'string' && v.length <= 40 && !v.includes(' ') && !v.includes('\n');
+}
+/** Root element name = the command path with spaces hyphenated. */
+function rootTag(help) {
+    return help.name.trim().split(/\s+/).join('-').replace(/[^a-zA-Z0-9_-]/g, '') || 'result';
+}
+function renderArray(name, arr) {
+    if (arr.length === 0)
+        return `<${name} count="0"></${name}>`;
+    const allObjects = arr.every((x) => x !== null && typeof x === 'object' && !Array.isArray(x));
+    if (allObjects) {
+        const rows = arr;
+        const cols = [];
+        for (const r of rows)
+            for (const k of Object.keys(r))
+                if (!cols.includes(k))
+                    cols.push(k);
+        const head = `| ${cols.join(' | ')} |`;
+        const sep = `| ${cols.map(() => '---').join(' | ')} |`;
+        const body = rows.map((r) => `| ${cols.map((c) => scalarStr(r[c])).join(' | ')} |`).join('\n');
+        return `<${name} count="${arr.length}">\n${head}\n${sep}\n${body}\n</${name}>`;
+    }
+    const items = arr.map((x) => `- ${scalarStr(x)}`).join('\n');
+    return `<${name} count="${arr.length}">\n${items}\n</${name}>`;
+}
+/** Schema-driven fallback: turn a result object into agent-ready XML+markdown.
+ *  Field order follows the leaf's declared output schema; any extra keys append
+ *  after. Scalars become attributes or a bullet list, prose and collections
+ *  become their own fenced blocks. */
+export function renderResult(result, help) {
+    const order = help.output.map((f) => f.name);
+    for (const k of Object.keys(result))
+        if (!order.includes(k))
+            order.push(k);
+    const attrs = [];
+    const bullets = [];
+    const blocks = [];
+    for (const name of order) {
+        const v = result[name];
+        if (v === undefined || v === null)
+            continue;
+        if (Array.isArray(v)) {
+            blocks.push(renderArray(name, v));
+            continue;
+        }
+        if (typeof v === 'object') {
+            blocks.push(`<${name}>\n${JSON.stringify(v, null, 2)}\n</${name}>`);
+            continue;
+        }
+        if (isProse(name, v)) {
+            blocks.push(`<${name}>\n${v}\n</${name}>`);
+            continue;
+        }
+        if (isAttr(v)) {
+            attrs.push(`${name}="${attrEsc(v)}"`);
+            continue;
+        }
+        bullets.push(`- ${name}: ${scalarStr(v)}`);
+    }
+    const tag = rootTag(help);
+    const open = attrs.length > 0 ? `<${tag} ${attrs.join(' ')}>` : `<${tag}>`;
+    const parts = [];
+    if (bullets.length > 0)
+        parts.push(bullets.join('\n'));
+    if (blocks.length > 0)
+        parts.push(blocks.join('\n\n'));
+    const inner = parts.join('\n\n');
+    return inner !== '' ? `${open}\n${inner}\n</${tag}>` : `${open}</${tag}>`;
+}
+/** Render a structured failure as an instruction-shaped block: what broke, what
+ *  was received, and the recovery road sign — the same recovery info the JSON
+ *  payload carries, shaped for the model to act on. */
+export function renderError(p) {
+    const lines = [p.message];
+    if (p.received !== undefined && p.received !== null && p.received !== '') {
+        lines.push(`received: ${scalarStr(p.received)}`);
+    }
+    if (p.field !== undefined)
+        lines.push(`field: ${p.field}`);
+    lines.push(`Next: ${p.next}`);
+    return `<error code="${attrEsc(p.error)}">\n${lines.join('\n')}\n</error>`;
+}

package/dist/core/resolver.d.ts

@@ -28,5 +28,15 @@ export declare function parseSkillQualifier(raw: string): ParsedSkillQualifier;
 export declare function listInstalledMarketplaces(scope: Scope): InstalledMarketplace[];
 export declare function listAllMarketplaces(): InstalledMarketplace[];
 export declare function findMarketplaceByName(name: string, scope?: Scope): InstalledMarketplace | null;
+export interface CategoryResolution {
+    id: string;
+    plugin: string | undefined;
+    scope: Scope | undefined;
+    dir: string;
+    indexPath: string | undefined;
+    skills: Skill[];
+}
+export declare function resolveCategory(name: string, opts?: SkillResolutionOpts): CategoryResolution | null;
+export declare function buildCategoryIndex(cat: CategoryResolution): string;
 export declare function scopeRootsLabel(): string;
 export {};

package/dist/core/resolver.js

@@ -1,7 +1,7 @@
 import { join, relative, sep, dirname } from 'node:path';
 import { SCOPE_SKILL_PLUGIN, SKILL_ENTRY_FILE, SKILLS_DIR, skillConfigKey, } from '../types.js';
 import { readConfig } from './config.js';
-import { listDirs, pathExists, readText, walkFiles, } from './fs-utils.js';
+import { listDirs, pathExists, readText, readTextIfExists, walkFiles, } from './fs-utils.js';
 import { readMarketplaceManifest, readPluginManifest } from './manifest.js';
 import { parseFrontmatter } from './frontmatter.js';
 import { ambiguous, notFound, usage } from './errors.js';
@@ -534,6 +534,114 @@ export function findMarketplaceByName(name, scope) {
     }
     return null;
 }
+export function resolveCategory(name, opts = {}) {
+    const parsed = parseSkillQualifier(name);
+    if (parsed.segments.length === 0)
+        return null;
+    const effectiveScope = opts.scope ?? parsed.scope;
+    let pluginQualifier;
+    let subpath;
+    if (opts.pluginFilter !== undefined) {
+        pluginQualifier = opts.pluginFilter;
+        const sub = parsed.segments.join('/');
+        subpath = sub || undefined;
+    }
+    else if (parsed.segments.length > 1) {
+        const maybePlugin = parsed.segments[0];
+        const pluginMatch = findPluginByName(maybePlugin, effectiveScope) ??
+            (effectiveScope === undefined ? null : findPluginByName(maybePlugin));
+        if (pluginMatch !== null) {
+            pluginQualifier = maybePlugin;
+            subpath = parsed.segments.slice(1).join('/');
+        }
+        else {
+            pluginQualifier = undefined;
+            subpath = parsed.segments.join('/');
+        }
+    }
+    else {
+        const maybePlugin = parsed.segments[0];
+        const pluginMatch = findPluginByName(maybePlugin, effectiveScope) ??
+            (effectiveScope === undefined ? null : findPluginByName(maybePlugin));
+        if (pluginMatch !== null) {
+            pluginQualifier = maybePlugin;
+            subpath = undefined;
+        }
+        else {
+            pluginQualifier = undefined;
+            subpath = maybePlugin;
+        }
+    }
+    let skills;
+    let dir;
+    let id;
+    let resolvedScope;
+    if (pluginQualifier !== undefined) {
+        const plugin = findPluginByName(pluginQualifier, effectiveScope) ??
+            (effectiveScope === undefined ? null : findPluginByName(pluginQualifier));
+        if (!plugin)
+            return null;
+        resolvedScope = plugin.scope;
+        const allPluginSkills = listSkillsInPlugin(plugin);
+        if (subpath === undefined) {
+            skills = allPluginSkills;
+            dir = join(plugin.root, SKILLS_DIR);
+            id = pluginQualifier;
+        }
+        else {
+            skills = allPluginSkills.filter((s) => s.name.startsWith(subpath + '/'));
+            dir = join(plugin.root, SKILLS_DIR, ...subpath.split('/'));
+            id = `${pluginQualifier}/${subpath}`;
+        }
+    }
+    else if (subpath !== undefined) {
+        const scope = effectiveScope ?? 'user';
+        resolvedScope = scope;
+        const skillsRoot = scopeSkillsDir(scope);
+        if (!skillsRoot)
+            return null;
+        const allScopeSkills = listScopeRootSkills(scope);
+        skills = allScopeSkills.filter((s) => s.name.startsWith(subpath + '/'));
+        dir = join(skillsRoot, ...subpath.split('/'));
+        id = `${scope}/${subpath}`;
+    }
+    else {
+        return null;
+    }
+    if (skills.length === 0)
+        return null;
+    const indexMd = join(dir, 'index.md');
+    const indexPath = pathExists(indexMd) ? indexMd : undefined;
+    return { id, plugin: pluginQualifier, scope: resolvedScope, dir, indexPath, skills };
+}
+export function buildCategoryIndex(cat) {
+    const lines = [];
+    lines.push(`# ${cat.id} — ${cat.skills.length} skills`);
+    lines.push('');
+    if (cat.indexPath !== undefined) {
+        const authored = readTextIfExists(cat.indexPath);
+        if (authored !== null) {
+            const { body } = parseFrontmatter(authored);
+            const trimmed = body.trim();
+            if (trimmed.length > 0) {
+                lines.push(trimmed);
+                lines.push('');
+            }
+        }
+    }
+    lines.push('## Skills');
+    const sorted = [...cat.skills].sort((a, b) => a.name.localeCompare(b.name));
+    for (const skill of sorted) {
+        const fullId = skill.plugin === SCOPE_SKILL_PLUGIN
+            ? `${skill.scope}/${skill.name}`
+            : `${skill.plugin}/${skill.name}`;
+        const desc = skill.frontmatter.description ?? '(no description)';
+        lines.push(`- \`${fullId}\` — ${desc}`);
+    }
+    lines.push('');
+    lines.push(`Read one with \`crtr skill read <full-id>\`. Narrow with \`crtr skill find list --plugin ${cat.plugin ?? cat.id}\`.`);
+    return lines.join('\n');
+}
 export function scopeRootsLabel() {
     const proj = projectScopeRoot();
     return proj ? `project=${proj}, user=${userScopeRoot()}` : `user=${userScopeRoot()}`;

package/dist/core/runtime/front-door.d.ts

@@ -0,0 +1,10 @@
+import type { RootDef } from './../command.js';
+/** Env marker set on every pi the front door boots. Its presence means we are
+ *  already inside a front-door-booted root, so a nested front-door launch must
+ *  be refused — otherwise a removed/renamed subcommand that a child pi re-runs
+ *  (e.g. `crtr node -h`) fork-bombs pi until the machine must be rebooted. */
+export declare const FRONT_DOOR_ENV = "CRTR_FRONT_DOOR";
+/** If this invocation is a front-door (root) launch, boot it and never return.
+ *  Returns false when it's a recognized subcommand / help / unknown token (let
+ *  the dispatcher handle it — for unknown tokens it errors cleanly). */
+export declare function maybeBootRoot(root: RootDef, argv: string[]): boolean;