@crouton-kit/crouter 0.3.3 → 0.3.11

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 {};

package/dist/core/command.js

@@ -17,14 +17,60 @@ export function defineLeaf(opts) {
         kind: 'leaf',
         name: opts.name,
         help: opts.help,
+        slash: opts.slash,
         run: opts.run,
     };
 }
 export function defineBranch(opts) {
-    return { kind: 'branch', name: opts.name, help: opts.help, children: opts.children };
+    return {
+        kind: 'branch',
+        name: opts.name,
+        help: opts.help,
+        rootEntry: opts.rootEntry,
+        slash: opts.slash,
+        children: opts.children,
+    };
 }
+/** 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 function collectSlashSpecs(root) {
+    const out = [];
+    const visit = (node) => {
+        if (node.slash !== undefined)
+            out.push(node.slash);
+        if (node.kind === 'branch')
+            for (const c of node.children)
+                visit(c);
+    };
+    for (const s of root.subtrees)
+        visit(s);
+    return out;
+}
+/** 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 function defineRoot(opts) {
-    return { kind: 'root', help: opts.help, subtrees: opts.subtrees };
+    // Each listed subtree becomes one <name> block at root, assembled straight
+    // from its RootEntry. Root composes nothing and hardcodes nothing: add a
+    // subtree with a rootEntry and it surfaces; its concept, rubric, state tag,
+    // and dynamic block all travel with it.
+    const commands = opts.subtrees
+        .filter((s) => s.rootEntry !== undefined)
+        .map((s) => ({
+        name: s.name,
+        concept: s.rootEntry.concept,
+        desc: s.rootEntry.desc,
+        useWhen: s.rootEntry.useWhen,
+        dynamicState: s.rootEntry.dynamicState,
+    }));
+    const help = {
+        tagline: opts.tagline,
+        commands,
+        globals: opts.globals,
+    };
+    return { kind: 'root', help, subtrees: opts.subtrees };
 }
 /** Validate and return child names for an unknown-path error. */
 function childNames(node) {
@@ -35,10 +81,12 @@ function childNames(node) {
     return [];
 }
 /** Walk argv tokens to the deepest matched node.
- *  Returns { node, remaining } where remaining are unconsumed tokens.
+ *  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. */
-function walk(root, tokens) {
+export function walk(root, tokens) {
     let current = root;
+    const path = [];
     let i = 0;
     while (i < tokens.length) {
         const token = tokens[i];
@@ -50,6 +98,7 @@ function walk(root, tokens) {
             if (nextNode === undefined)
                 break;
             current = nextNode;
+            path.push(nextNode.name);
             i++;
         }
         else if (current.kind === 'branch') {
@@ -57,6 +106,7 @@ function walk(root, tokens) {
             if (nextNode === undefined)
                 break;
             current = nextNode;
+            path.push(nextNode.name);
             i++;
         }
         else {
@@ -64,7 +114,7 @@ function walk(root, tokens) {
             break;
         }
     }
-    return { node: current, remaining: tokens.slice(i) };
+    return { node: current, path, remaining: tokens.slice(i) };
 }
 function renderNode(node) {
     if (node.kind === 'root')
@@ -77,15 +127,13 @@ function helpRequested(remaining) {
     return remaining.some((t) => t === '-h' || t === '--help');
 }
 /** Build a structured unknown-path error. Names valid children of the deepest
- *  matched node and names the entry command per the spec. No fuzzy matching. */
-function unknownPathError(node, bad) {
+ *  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 function unknownPathError(node, path, bad) {
     const valid = childNames(node);
     const validStr = valid.length > 0 ? valid.join(', ') : '(none)';
-    const entryCmd = node.kind === 'root'
-        ? 'crtr -h'
-        : node.kind === 'branch'
-            ? `crtr ${node.name} -h`
-            : 'crtr -h';
+    const entryCmd = path.length > 0 ? `crtr ${path.join(' ')} -h` : 'crtr -h';
     return new CrtrError('unknown_path', `unknown subcommand: ${bad}`, ExitCode.USAGE, {
         received: bad,
         next: `Valid children: ${validStr}. Run \`${entryCmd}\` for the full list.`,
@@ -257,7 +305,7 @@ export async function runCli(root, argv) {
         process.stdout.write(renderRoot(root.help) + '\n');
         process.exit(ExitCode.SUCCESS);
     }
-    const { node, remaining } = walk(root, tokens);
+    const { node, path, remaining } = walk(root, tokens);
     try {
         // Help anywhere in remaining tokens → print node help and exit
         if (helpRequested(remaining)) {
@@ -267,7 +315,7 @@ export async function runCli(root, argv) {
         // Bare branch or bare root (no -h, but no leaf selected) → help surface
         if (node.kind === 'root' || node.kind === 'branch') {
             if (remaining.length > 0) {
-                throw unknownPathError(node, remaining[0]);
+                throw unknownPathError(node, path, remaining[0]);
             }
             process.stdout.write(renderNode(node) + '\n');
             process.exit(ExitCode.SUCCESS);

package/dist/core/config.js

@@ -1,7 +1,8 @@
 import { join } from 'node:path';
-import { CONFIG_FILE, STATE_FILE, defaultScopeConfig, defaultScopeState } from '../types.js';
+import { CONFIG_FILE, STATE_FILE, SCHEMA_VERSION, defaultScopeConfig, defaultScopeState } from '../types.js';
 import { readJsonIfExists, writeJson, ensureDir } from './fs-utils.js';
 import { scopeRoot, requireScopeRoot } from './scope.js';
+import { diag } from './io.js';
 function configPathFor(root) {
     return join(root, CONFIG_FILE);
 }
@@ -23,7 +24,24 @@ export function readConfig(scope) {
     const existing = readJsonIfExists(configPathFor(root));
     if (!existing)
         return defaultScopeConfig();
-    return mergeConfig(existing);
+    const cfg = mergeConfig(existing);
+    if ((existing.schema_version ?? 0) < SCHEMA_VERSION) {
+        migrateSkillConfigKeys(cfg, scope, root);
+    }
+    return cfg;
+}
+function migrateSkillConfigKeys(cfg, scope, root) {
+    const colonKeys = Object.keys(cfg.skills).filter((k) => k.includes(':'));
+    if (colonKeys.length > 0) {
+        for (const key of colonKeys) {
+            const newKey = key.replace(/:/g, '/');
+            cfg.skills[newKey] = cfg.skills[key];
+            delete cfg.skills[key];
+        }
+        diag(`crtr: migrated ${colonKeys.length} skill config keys to slash form in ${scope}`);
+    }
+    cfg.schema_version = SCHEMA_VERSION;
+    writeJson(configPathFor(root), cfg);
 }
 export function readState(scope) {
     const root = scopeRoot(scope);

package/dist/core/frontmatter.d.ts

@@ -5,4 +5,14 @@ export interface ParsedFrontmatter {
     raw: string;
 }
 export declare function parseFrontmatter(source: string): ParsedFrontmatter;
+export interface ParsedFrontmatterGeneric {
+    /** Raw, uncoerced key/value record from the YAML block (null when absent). */
+    data: Record<string, unknown> | null;
+    body: string;
+    raw: string;
+}
+/** Like parseFrontmatter but returns the raw key/value record instead of
+ *  coercing to SkillFrontmatter. Used by consumers (e.g. subagents) that read
+ *  fields skills don't declare, such as `tools` and `model`. */
+export declare function parseFrontmatterGeneric(source: string): ParsedFrontmatterGeneric;
 export declare function serializeFrontmatter(data: SkillFrontmatter): string;

package/dist/core/frontmatter.js

@@ -7,9 +7,30 @@ export function parseFrontmatter(source) {
     }
     const raw = match[1];
     const body = source.slice(match[0].length);
-    return { data: parseSimpleYaml(raw), body, raw };
+    return { data: toSkillFrontmatter(parseYamlRecord(raw)), body, raw };
 }
-function parseSimpleYaml(yaml) {
+/** Like parseFrontmatter but returns the raw key/value record instead of
+ *  coercing to SkillFrontmatter. Used by consumers (e.g. subagents) that read
+ *  fields skills don't declare, such as `tools` and `model`. */
+export function parseFrontmatterGeneric(source) {
+    const match = source.match(FRONTMATTER_RE);
+    if (!match) {
+        return { data: null, body: source, raw: '' };
+    }
+    const raw = match[1];
+    const body = source.slice(match[0].length);
+    return { data: parseYamlRecord(raw), body, raw };
+}
+function toSkillFrontmatter(out) {
+    const fm = {
+        name: typeof out.name === 'string' ? out.name : '',
+        description: typeof out.description === 'string' ? out.description : undefined,
+        keywords: Array.isArray(out.keywords) ? out.keywords : undefined,
+        type: isSkillType(out.type) ? out.type : undefined,
+    };
+    return fm;
+}
+function parseYamlRecord(yaml) {
     const lines = yaml.split(/\r?\n/);
     const out = {};
     let i = 0;
@@ -123,13 +144,7 @@ function parseSimpleYaml(yaml) {
         out[key] = stripQuotes(rest);
         i++;
     }
-    const fm = {
-        name: typeof out.name === 'string' ? out.name : '',
-        description: typeof out.description === 'string' ? out.description : undefined,
-        keywords: Array.isArray(out.keywords) ? out.keywords : undefined,
-        type: isSkillType(out.type) ? out.type : undefined,
-    };
-    return fm;
+    return out;
 }
 function stripQuotes(s) {
     if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {

package/dist/core/help.d.ts

@@ -47,17 +47,40 @@ export interface ContextFileParam {
     shape?: string;
 }
 export type InputParam = PositionalParam | FlagParam | StdinParam | ContextFileParam;
+/** A subtree's self-description at the parent (root) level. Each subtree owns
+ *  the content that represents it one level up: its vocabulary line, its
+ *  selection rubric, and any bounded block it contributes to the parent's -h.
+ *  defineRoot assembles the root help from these — root never hardcodes a
+ *  subtree's representation. See cli-design "Each node owns its parent-level
+ *  representation". */
+export interface RootEntry {
+    /** One-line vocabulary desc — what this subtree is. Rendered first in the
+     *  subtree's <name> block at root. */
+    concept: string;
+    /** Operations summary (verb list). Carried for completeness; the root block
+     *  leads with concept + rubric, so this is available but not rendered. */
+    desc: string;
+    /** The selection rubric — `use when X` in the subtree's <name> block. */
+    useWhen: string;
+    /** Optional bounded block this subtree contributes to its <name> block at
+     *  root. Returns a complete self-named state element (build it with
+     *  stateBlock), e.g. `<skills count="42">…</skills>`. Aggregate, never an
+     *  unbounded enumeration on a cold path. Soft-fails to omission on
+     *  null/throw. */
+    dynamicState?: () => string | null;
+}
 export interface RootHelp {
     tagline: string;
-    /** Vocabulary block — rendered before subtrees. */
-    concepts: {
-        name: string;
-        desc: string;
-    }[];
-    subtrees: {
+    /** One entry per listed subtree. Each renders as its own <name> XML block at
+     *  root, carrying the subtree's concept, selection rubric, and any nested
+     *  runtime-state block. Assembled from subtrees' RootEntry by defineRoot;
+     *  root hardcodes none of it. */
+    commands: {
         name: string;
+        concept: string;
         desc: string;
         useWhen: string;
+        dynamicState?: () => string | null;
     }[];
     globals: {
         name: string;
@@ -69,8 +92,9 @@ export interface BranchHelp {
     summary: string;
     /** Local lifecycle/model line that extends the parent definition. */
     model?: string;
-    /** Bounded runtime aggregate, e.g. "Current: 2 draft, 1 active".
-     *  Renderer soft-fails to omission if this returns null or throws. */
+    /** Bounded runtime aggregate as a complete self-named state element (build
+     *  it with stateBlock), e.g. `<skills count="42">…</skills>`. Renderer
+     *  soft-fails to omission if this returns null or throws. */
     dynamicState?: () => string | null;
     children: {
         name: string;
@@ -93,6 +117,13 @@ export interface LeafHelp {
      *  leaves use exactly: ["None. Read-only."] */
     effects: string[];
 }
+/** Build a self-named runtime-state element: `<tag attr="v">body</tag>`. The
+ *  subtree that owns the state authors it through this, so the tag name and any
+ *  scalar metadata (e.g. a count) travel with the data and render identically
+ *  at every level the block appears. The tag name carries the label, so the
+ *  body never repeats it. Attribute values are controlled (counts, short
+ *  tokens) and not escaped. */
+export declare function stateBlock(tag: string, attrs: Record<string, string | number>, body: string): string;
 export declare function renderRoot(h: RootHelp): string;
 export declare function renderBranch(h: BranchHelp): string;
 export declare function renderLeafArgv(h: LeafHelp): string;