@shrkcrft/cli 0.1.0-alpha.30 → 0.1.0-alpha.31

package/dist/commands/help.command.js

@@ -1,38 +1,61 @@
+import { detectSharkcraftRepo } from '@shrkcrft/inspector';
+import { resolveCwd } from "../command-registry.js";
 import { header } from "../output/format-output.js";
-import { COMMAND_CATALOG, defaultShowInHelp, listExplainFamily } from "./command-catalog.js";
+import { nearest } from "../dispatch/closest-match.js";
+import { CommandDispatchKind } from "../surface/command-dispatch-kind.js";
+import { commandIndexFor, findCommandIndexEntry, subverbNamesOf, } from "../surface/command-index.js";
+import { loadSurfaceContext } from "../surface/load-surface-context.js";
+import { buildSurfaceSummary, findCommandInSummary, } from "../surface/surface-summary.js";
+import { TierSource } from "../surface/tier.js";
+import { defaultShowInHelp, isExplainFamily } from "./command-catalog.js";
 /**
- * Every multi-token command path the catalog documents. These are real,
- * callable verbs that the command trie never sees, because their parent
- * dispatches them from a positional argument rather than registering them.
+ * Help's topics come from THE command index — the same inventory `surface
+ * list`, `commands doctor`, the command-string resolver and the dispatcher's
+ * help intercept read (one memoised object per registry). It used to walk
+ * COMMAND_CATALOG itself (a third inventory), so a registered verb with no
+ * catalog row had no help and a catalog row nothing dispatches still did.
  */
-function catalogHelpPaths() {
+function helpIndex(registry) {
+    return commandIndexFor(registry);
+}
+/** Every command path (and alias spelling) the index knows — help topics. */
+function indexHelpPaths(index) {
     const paths = new Set();
-    for (const entry of COMMAND_CATALOG) {
-        // Strip the flag/argument tail a few catalog entries carry in `command`.
-        const clean = entry.command.split(/\s+--/)[0].trim();
-        if (clean.length > 0)
-            paths.add(clean);
+    for (const e of index.entries) {
+        if (e.dispatch === CommandDispatchKind.Meta)
+            continue;
+        paths.add(e.path);
+        for (const a of e.aliases)
+            paths.add(a);
     }
     return paths;
 }
 /**
- * Render help for a command path the trie could not resolve but the catalog
- * documents, plus its sibling verbs under the same parent so the family is
- * discoverable from any one member.
+ * Render help for an index path the trie could not resolve verbatim — a
+ * subverb its parent dispatches from a positional (`check wiring`) — plus its
+ * sibling verbs under the same parent so the family is discoverable from any
+ * one member.
  */
-function renderCatalogHelp(tokens) {
+function renderIndexHelp(index, tokens) {
     const want = tokens.join(' ');
-    const entry = COMMAND_CATALOG.find((e) => e.command.split(/\s+--/)[0].trim() === want);
-    if (!entry)
+    const entry = findCommandIndexEntry(index, want);
+    if (!entry || entry.dispatch === CommandDispatchKind.Meta)
         return undefined;
-    let out = `${want} — ${entry.description}\n`;
-    const extra = EXTRA_HELP_LINES[want];
+    let out = `${entry.path} — ${entry.description}\n`;
+    // A catalog-documented subverb its handler does not declare has no usage of
+    // its own: fall back to the dispatching handler's, so help always shows how
+    // to invoke it (and never an empty page).
+    const usage = entry.usage ?? (entry.parent ? index.byPath.get(entry.parent)?.usage : undefined);
+    if (usage)
+        out += `${usage}\n`;
+    const extra = EXTRA_HELP_LINES[entry.path];
     if (extra)
         out += extra.join('\n') + '\n';
-    const parent = tokens.slice(0, -1).join(' ');
+    const parent = entry.tokens.slice(0, -1).join(' ');
     if (parent.length > 0) {
-        const siblings = [...catalogHelpPaths()]
-            .filter((p) => p !== want && p.startsWith(parent + ' ') && !p.slice(parent.length + 1).includes(' '))
+        const siblings = subverbNamesOf(index, parent)
+            .map((name) => `${parent} ${name}`)
+            .filter((p) => p !== entry.path)
             .sort();
         if (siblings.length > 0) {
             out += `\nSiblings: ${siblings.join(', ')}\n`;
@@ -46,64 +69,28 @@ function firstSentence(description) {
     const head = dot > 0 ? description.slice(0, dot + 1) : description;
     return head.length > 100 ? head.slice(0, 97).trimEnd() + '…' : head;
 }
-/** Levenshtein edit distance — small, local helper for the unknown-topic guard. */
-function editDistance(a, b) {
-    const m = a.length;
-    const n = b.length;
-    if (m === 0)
-        return n;
-    if (n === 0)
-        return m;
-    let prev = Array.from({ length: n + 1 }, (_, i) => i);
-    let curr = new Array(n + 1);
-    for (let i = 1; i <= m; i += 1) {
-        curr[0] = i;
-        for (let j = 1; j <= n; j += 1) {
-            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-            curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
-        }
-        [prev, curr] = [curr, prev];
-    }
-    return prev[n];
-}
 /**
- * The set of real, callable help topics: every registered top-level command
- * and group name, plus every top-level verb in the catalog. Used only to
- * suggest a near-typo when an unknown topic is requested — never to fabricate
- * one that isn't real.
+ * The set of real, callable top-level help topics: the first token of every
+ * index path, plus every top-level alias. Used only to suggest a near-typo
+ * when an unknown topic is requested — never to fabricate one that isn't real.
+ * The suggestion goes through the ONE did-you-mean scorer (`nearest`, the
+ * `max(1, len/4)`-edit tolerance main.ts uses), ties broken lexically.
  */
-function realHelpTopics(registry) {
+function realHelpTopics(index) {
     const topics = new Set();
-    for (const c of registry.list())
-        topics.add(c.name);
-    for (const g of registry.listGroups())
-        topics.add(g);
-    for (const entry of COMMAND_CATALOG) {
-        const verb = entry.command.split(/\s+/)[0];
-        if (verb)
-            topics.add(verb);
-    }
-    return topics;
-}
-/**
- * Nearest real topic to `attempt` within a typo-tolerant edit-distance bound,
- * or undefined when nothing is close enough. Mirrors main.ts's confidence
- * tolerance (`max(1, len/4)` edits) so a fingers-on-keys typo suggests but a
- * genuinely-unrelated token does not. Deterministic: ties break lexically.
- */
-function nearestHelpTopic(attempt, topics) {
-    const lower = attempt.toLowerCase();
-    const tolerance = Math.max(1, Math.floor(lower.length / 4));
-    let best;
-    let bestDist = Number.POSITIVE_INFINITY;
-    for (const topic of topics) {
-        const dist = editDistance(lower, topic.toLowerCase());
-        if (dist < bestDist || (dist === bestDist && best !== undefined && topic < best)) {
-            bestDist = dist;
-            best = topic;
+    for (const e of index.entries) {
+        if (e.dispatch === CommandDispatchKind.Meta)
+            continue;
+        const head = e.tokens[0];
+        if (head)
+            topics.add(head);
+        for (const a of e.aliases) {
+            const aliasHead = a.split(' ')[0];
+            if (aliasHead)
+                topics.add(aliasHead);
         }
     }
-    return best !== undefined && bestDist <= tolerance ? best : undefined;
+    return topics;
 }
 const EXTRA_HELP_LINES = Object.freeze({
     graph: [
@@ -115,54 +102,91 @@ const EXTRA_HELP_LINES = Object.freeze({
         '  graph context    — inspect one file or symbol with bridge enrichment',
         '  graph impact     — reverse dependent closure for a file or symbol',
         '  graph callers    — files that call/reference a symbol',
+        '  graph importers  — every module that imports a module (alias/type-only/re-export aware)',
         '  graph cycles     — list import cycles',
         '  graph unresolved — list unresolved imports grouped by file',
         '  graph deps       — inbound/outbound package dependencies',
         '  graph why        — shortest-path explanation in the knowledge graph',
     ],
 });
+const START_SECTIONS = [
+    {
+        title: 'Bootstrap:',
+        lines: [
+            { command: 'init', text: '  $ shrk init --infer --write      — scan the repo + populate sharkcraft/ from real signals (new repos)' },
+            { command: 'doctor', text: '  $ shrk doctor                    — is the workspace healthy?' },
+            { command: 'onboard', text: '  $ shrk onboard                   — analyze an existing repo (advisory)' },
+        ],
+    },
+    {
+        title: 'Use it for a task:',
+        lines: [
+            { command: 'recommend', text: '  $ shrk recommend "<task>"        — what should I do?' },
+            { command: 'context', text: '  $ shrk context --task "<task>"   — token-budgeted relevant context' },
+            { command: 'task', text: '  $ shrk task "<task>"             — full AI-ready task packet (JSON)' },
+            { command: 'why', text: '  $ shrk why <file>                — which rules govern this file' },
+            { command: 'impact', text: '  $ shrk impact <file>             — blast radius: what breaks if I change this' },
+        ],
+    },
+    {
+        title: 'Generate code safely:',
+        lines: [
+            { command: 'gen', text: '  $ shrk gen <template> <name>     — generate from template (dry-run by default)' },
+            { command: 'apply', text: '  $ shrk apply <plan.json>         — apply a reviewed plan (CLI is the only write path)' },
+            { command: 'check boundaries', text: '  $ shrk check boundaries          — enforce layer / import boundaries' },
+            { command: 'quality', text: '  $ shrk quality                   — pre-PR gate (doctor + boundaries + coverage + drift)' },
+        ],
+    },
+    {
+        title: 'Browse what shrk knows:',
+        lines: [
+            { command: 'graph status', text: '  $ shrk graph status              — code-graph freshness and health' },
+            { command: 'coverage', text: '  $ shrk coverage                  — what knowledge is missing' },
+            { command: 'knowledge list', text: '  $ shrk knowledge list            — knowledge entries' },
+        ],
+    },
+    {
+        title: 'Run shrk for an agent:',
+        lines: [
+            { command: 'mcp serve', text: '  $ shrk mcp serve                 — start the MCP server (stdio) for live queries' },
+            { command: 'dashboard', text: '  $ shrk dashboard                 — start the local read-only dashboard' },
+        ],
+    },
+];
 /**
  * Product start screen for bare `shrk` / `shrk --help`. Shows the
  * curated ~20-command "starter" surface organized by workflow phase.
  * Everything else stays callable; users see the full ~70-verb catalog
  * via `shrk --full-help` or browse it through `shrk surface list`.
  *
+ * `shown(command)` is the repository's surface: a curated line whose command
+ * `surface.hidden` hides, or the surface gate refuses (`surface.disabled`,
+ * experimental, tool-maintenance), is dropped — and a section left empty with
+ * it. The default shows every line (the text is then byte-identical to the
+ * pre-round-11 screen).
+ *
  * Returns the lines (without trailing newline). Pulled into a function
  * so tests can assert on the structure without grepping stdout.
  */
-export function renderStartScreen() {
+export function renderStartScreen(shown = () => true) {
     const lines = [];
     lines.push('SharkCraft CLI — deterministic, local-first project intelligence for AI coding agents.');
     lines.push('Usage: shrk [--cwd <dir>] <command> [...args]');
     lines.push('');
-    lines.push('Bootstrap:');
-    lines.push('  $ shrk init --infer --write      — scan the repo + populate sharkcraft/ from real signals (new repos)');
-    lines.push('  $ shrk doctor                    — is the workspace healthy?');
-    lines.push('  $ shrk onboard                   — analyze an existing repo (advisory)');
-    lines.push('');
-    lines.push('Use it for a task:');
-    lines.push('  $ shrk recommend "<task>"        — what should I do?');
-    lines.push('  $ shrk context --task "<task>"   — token-budgeted relevant context');
-    lines.push('  $ shrk task "<task>"             — full AI-ready task packet (JSON)');
-    lines.push('  $ shrk why <file>                — which rules govern this file');
-    lines.push('  $ shrk impact <file>             — blast radius: what breaks if I change this');
-    lines.push('');
-    lines.push('Generate code safely:');
-    lines.push('  $ shrk gen <template> <name>     — generate from template (dry-run by default)');
-    lines.push('  $ shrk apply <plan.json>         — apply a reviewed plan (CLI is the only write path)');
-    lines.push('  $ shrk check boundaries          — enforce layer / import boundaries');
-    lines.push('  $ shrk quality                   — pre-PR gate (doctor + boundaries + coverage + drift)');
-    lines.push('');
-    lines.push('Browse what shrk knows:');
-    lines.push('  $ shrk graph status              — code-graph freshness and health');
-    lines.push('  $ shrk coverage                  — what knowledge is missing');
-    lines.push('  $ shrk knowledge list            — knowledge entries');
-    lines.push('');
-    lines.push('Run shrk for an agent:');
-    lines.push('  $ shrk mcp serve                 — start the MCP server (stdio) for live queries');
-    lines.push('  $ shrk dashboard                 — start the local read-only dashboard');
-    lines.push('');
-    lines.push('Discover the rest (everything stays callable — this screen shows ~17 of ~70 verbs):');
+    let dropped = 0;
+    for (const section of START_SECTIONS) {
+        const kept = section.lines.filter((l) => shown(l.command));
+        dropped += section.lines.length - kept.length;
+        if (kept.length === 0)
+            continue;
+        lines.push(section.title);
+        for (const l of kept)
+            lines.push(l.text);
+        lines.push('');
+    }
+    lines.push(dropped === 0
+        ? 'Discover the rest (everything stays callable — this screen shows ~17 of ~70 verbs):'
+        : `Discover the rest (${dropped} curated command(s) are hidden or disabled by this repository's surface config):`);
     lines.push('  $ shrk surface list              — full catalog by tier');
     lines.push('  $ shrk help <command>            — usage for a specific command');
     lines.push('  $ shrk --full-help               — long, exhaustive help (incl. the explain/dry-run family)');
@@ -171,11 +195,169 @@ export function renderStartScreen() {
     lines.push('Free-form input is fine — `shrk "<task>"` routes to `shrk recommend`.');
     return lines.join('\n') + '\n';
 }
+/**
+ * The surface this repository presents — THE visibility authority: the
+ * surface summary over this registry's index, composed with the project's
+ * `surface{}` config, its profile and the host (tool repo or consumer). The
+ * start screen and `--full-help` render it, so `surface explain X` →
+ * `visible-in-help` and the help output can no longer disagree.
+ *
+ * Failure-soft: when the workspace cannot be loaded, the DEFAULT surface (no
+ * config; the host still detected) is rendered and one note says so.
+ */
+async function helpSurface(registry, cwd) {
+    const index = helpIndex(registry);
+    try {
+        const { context } = await loadSurfaceContext({ cwd });
+        return { summary: buildSurfaceSummary(context, index) };
+    }
+    catch (e) {
+        const context = {
+            spineCommands: new Set(),
+            packContributions: new Map(),
+            surfaceConfig: undefined,
+            isToolRepo: detectSharkcraftRepo(cwd),
+        };
+        return {
+            summary: buildSurfaceSummary(context, index),
+            note: `note: surface config not loaded (${e instanceof Error ? e.message : String(e)}) — showing the default surface.\n`,
+        };
+    }
+}
+/** A curated start-screen line stays unless this repository hides or gates its command. */
+function startScreenFilter(summary) {
+    return (command) => {
+        const view = findCommandInSummary(summary, command);
+        return view === undefined || (view.callable && !view.hidden);
+    };
+}
+/** `(hidden)` / `(gated: …)` for `--full-help --all`. */
+function helpAnnotation(v) {
+    const notes = [];
+    if (!v.visibleInHelp)
+        notes.push('hidden');
+    if (!v.callable) {
+        notes.push(v.source === TierSource.ToolMaintenance
+            ? 'gated: tool-maintenance'
+            : v.source === TierSource.Disabled
+                ? 'gated: disabled'
+                : 'gated');
+    }
+    return notes.length > 0 ? `  (${notes.join(', ')})` : '';
+}
+/**
+ * `--full-help`, rendered FROM the surface summary. Without `all` it lists
+ * exactly the views whose `visibleInHelp` is true — every one at least once —
+ * so `surface.hidden`, profiles, `surface.disabled` and the tool-maintenance
+ * host gate all reach it. With `all` it lists every view, annotated
+ * `(hidden)` / `(gated: …)` rather than dropped.
+ *
+ * Placement (not visibility) still reads the catalog: a visible view on the
+ * rent-paying surface goes under its top-level verb or group; an explain /
+ * dry-run view goes in its own section (and, when it is also rent-paying, in
+ * its group too).
+ */
+export function renderFullHelp(registry, summary, all) {
+    const index = helpIndex(registry);
+    const views = [...summary.tiers.core, ...summary.tiers.extended, ...summary.tiers.experimental];
+    const listed = views.filter((v) => all || v.visibleInHelp);
+    const rowOf = (v) => index.byPath.get(v.command)?.catalogEntry;
+    const inExplainFamily = (v) => {
+        const row = rowOf(v);
+        return row !== undefined && isExplainFamily(row);
+    };
+    const explainOnly = (v) => {
+        if (all)
+            return false;
+        const row = rowOf(v);
+        return row !== undefined && isExplainFamily(row) && !defaultShowInHelp(row);
+    };
+    // Registration order (init, inspect, doctor, …) — the order the top-level
+    // list has always had — then alphabetical.
+    const rank = new Map();
+    for (const name of [...registry.list().map((c) => c.name), ...registry.listGroups()]) {
+        if (!rank.has(name))
+            rank.set(name, rank.size);
+    }
+    const headRank = (path) => rank.get(path.split(' ')[0] ?? '') ?? Number.MAX_SAFE_INTEGER;
+    const byRegistration = (a, b) => headRank(a.command) - headRank(b.command) || a.command.localeCompare(b.command);
+    const line = (v, width) => `  ${v.command.padEnd(width)} — ${firstSentence(v.description) || '(no description)'}${all ? helpAnnotation(v) : ''}\n`;
+    let out = 'SharkCraft CLI — structured project intelligence for AI coding agents\n';
+    out += 'Usage: shrk [--cwd <dir>] <command> [...args]\n';
+    const main = listed.filter((v) => v.dispatch !== CommandDispatchKind.Meta && !explainOnly(v));
+    out += header('Top-level commands');
+    for (const v of main.filter((m) => !m.command.includes(' ')).sort(byRegistration))
+        out += line(v, 10);
+    if (!all) {
+        const hiddenCount = views.filter((v) => v.dispatch !== CommandDispatchKind.Meta && !v.visibleInHelp).length;
+        if (hiddenCount > 0) {
+            out +=
+                `\n  …and ${hiddenCount} more hidden from default help (not on the curated surface, or hidden / gated by ` +
+                    "this repository's surface config). Run `shrk --full-help --all` to see them, or `shrk surface list` to browse by tier.\n";
+        }
+    }
+    const groups = new Map();
+    for (const v of main) {
+        const head = v.command.split(' ')[0] ?? '';
+        if (!v.command.includes(' ') || head.length === 0)
+            continue;
+        const members = groups.get(head) ?? [];
+        members.push(v);
+        groups.set(head, members);
+    }
+    const aliasesByCanonical = new Map();
+    for (const [alias, canonical] of registry.listGroupAliases().entries()) {
+        const list = aliasesByCanonical.get(canonical) ?? [];
+        list.push(alias);
+        aliasesByCanonical.set(canonical, list);
+    }
+    const heads = [...groups.keys()].sort((a, b) => headRank(a) - headRank(b) || a.localeCompare(b));
+    for (const head of heads) {
+        const members = (groups.get(head) ?? []).sort((a, b) => a.command.localeCompare(b.command));
+        const aliases = aliasesByCanonical.get(head) ?? [];
+        out += header(`shrk ${head} <sub>${aliases.length ? ` (also: ${aliases.join(', ')})` : ''}`);
+        const width = Math.min(28, Math.max(...members.map((m) => m.command.length)));
+        for (const v of members)
+            out += line(v, width);
+    }
+    // Explain / dry-run family — several carry an Advanced surface, so they are
+    // not rent-paying, yet this section is WHY `visibleInHelp` counts them: they
+    // show what a gate, ranker, or graph SEES before you act.
+    const explain = listed.filter(inExplainFamily).sort((a, b) => a.command.localeCompare(b.command));
+    if (explain.length > 0) {
+        out += header('Inspect / explain (dry-run what a gate, ranker, or graph sees)');
+        for (const v of explain)
+            out += line(v, 24);
+        out += '  (also: shrk check wiring --explain <ruleId>)\n';
+    }
+    const meta = listed.filter((v) => v.dispatch === CommandDispatchKind.Meta);
+    if (meta.length > 0) {
+        out += header('Meta flags');
+        for (const v of meta)
+            out += line(v, 12);
+    }
+    out += '\nRun `shrk help <command>` for detailed usage.\n';
+    return out;
+}
+/** Bare `help` / `--help` (start screen) and `--full-help [--all]`, over the repository's surface. */
+async function runListing(registry, args, wantsFull) {
+    const { summary, note } = await helpSurface(registry, resolveCwd({ ...args, multiFlags: new Map() }));
+    if (note)
+        process.stderr.write(note);
+    if (!wantsFull) {
+        process.stdout.write(renderStartScreen(startScreenFilter(summary)));
+        return 0;
+    }
+    process.stdout.write(renderFullHelp(registry, summary, args.flags.get('all') === true));
+    return 0;
+}
 export function makeHelpCommand(registry) {
     return {
         name: 'help',
         description: 'Show CLI help. Bare `shrk help` prints a short start screen — pass `--full` for the long catalog.',
-        usage: 'shrk help [<command>] [--full]',
+        usage: 'shrk help [<command>] [--full [--all]]  ·  shrk <command> [...] --help | -h  (anywhere before `--`; runs nothing)',
+        // Topic help is synchronous (it reads only the command index); the start
+        // screen and `--full-help` read the repository's surface, so they are async.
         run(args) {
             const requested = args.positional[0];
             const wantsFull = args.flags.get('full') === true ||
@@ -196,21 +378,38 @@ export function makeHelpCommand(registry) {
                     // that exits 0. Error out honestly instead, with a did-you-mean when
                     // a real topic is a near-typo of the request.
                     const attempt = tokens.join(' ');
-                    // The trie matched nothing, but the CATALOG may still document this
-                    // path — a documented verb whose parent isn't a registered command
-                    // is still real and callable.
-                    const viaCatalog = renderCatalogHelp(tokens);
-                    if (viaCatalog !== undefined) {
-                        process.stdout.write(viaCatalog);
+                    const index = helpIndex(registry);
+                    // The trie matched nothing, but the INDEX may still know the path
+                    // under an alias spelling or as a folded variant.
+                    const viaIndex = renderIndexHelp(index, tokens);
+                    if (viaIndex !== undefined) {
+                        process.stdout.write(viaIndex);
                         return 0;
                     }
                     process.stderr.write(`no such help topic: '${attempt}'\n`);
-                    const suggestion = nearestHelpTopic(attempt, realHelpTopics(registry)) ??
-                        nearestHelpTopic(attempt, catalogHelpPaths());
+                    const suggestion = nearest(attempt, realHelpTopics(index)) ?? nearest(attempt, indexHelpPaths(index));
                     if (suggestion)
                         process.stderr.write(`Did you mean: ${suggestion}?\n`);
                     return 1;
                 }
+                // A tail the trie did not consume (`graph importers`, `check wiring`,
+                // `templates lst`) is answered by the INDEX alone: a declared or
+                // catalogued subverb prints its own help; anything else is an unknown
+                // topic (exit 1) — never the parent group's listing at exit 0.
+                if (tokens.length > matchedPath.length) {
+                    const index = helpIndex(registry);
+                    const indexHelp = renderIndexHelp(index, tokens);
+                    if (indexHelp !== undefined) {
+                        process.stdout.write(indexHelp);
+                        return 0;
+                    }
+                    const attempt = tokens.join(' ');
+                    process.stderr.write(`no such help topic: '${attempt}'\n`);
+                    const near = nearest(attempt, indexHelpPaths(index));
+                    if (near)
+                        process.stderr.write(`Did you mean: shrk help ${near}?\n`);
+                    return 1;
+                }
                 if (handler && matchedPath.join(' ') === tokens.join(' ') && node.children.size === 0) {
                     // Exact match on a callable command.
                     const canonical = registry.listCommandAliases().get(tokens[0]);
@@ -248,101 +447,26 @@ export function makeHelpCommand(registry) {
                     }
                     return 0;
                 }
-                // The trie could not resolve the full path, but the CATALOG may still
-                // document it. Verbs like `check wiring` are dispatched from inside
-                // their parent's handler on a positional, so they are real, callable
-                // and documented — yet never trie nodes. Falling through to "Unknown
+                // The trie could not resolve the full path, but the INDEX may still
+                // list it. Verbs like `check wiring` are dispatched from inside their
+                // parent's handler on a positional, so they are real, callable and
+                // documented — yet never trie nodes. Falling through to "Unknown
                 // command" made an entire documented surface look non-existent.
-                const catalogHelp = renderCatalogHelp(tokens);
-                if (catalogHelp !== undefined) {
-                    process.stdout.write(catalogHelp);
+                const index = helpIndex(registry);
+                const indexHelp = renderIndexHelp(index, tokens);
+                if (indexHelp !== undefined) {
+                    process.stdout.write(indexHelp);
                     return 0;
                 }
                 process.stderr.write(`no such help topic: '${tokens.join(' ')}'\n`);
-                const near = nearestHelpTopic(tokens.join(' '), catalogHelpPaths());
+                const near = nearest(tokens.join(' '), indexHelpPaths(index));
                 if (near)
                     process.stderr.write(`Did you mean: shrk help ${near}?\n`);
                 return 1;
             }
-            if (!wantsFull) {
-                process.stdout.write(renderStartScreen());
-                return 0;
-            }
-            const wantsAll = args.flags.get('all') === true;
-            process.stdout.write(`SharkCraft CLI — structured project intelligence for AI coding agents\n`);
-            process.stdout.write(`Usage: shrk [--cwd <dir>] <command> [...args]\n`);
-            // The catalog has ~360 entries; only ~30 top-level verbs pay
-            // rent (see PRIMARY_VERBS_ALLOWLIST in command-catalog.ts).
-            // Default --full-help filters to that set; `--full-help --all`
-            // dumps the entire catalog for power users.
-            const visibleVerbs = new Set();
-            if (!wantsAll) {
-                for (const entry of COMMAND_CATALOG) {
-                    if (defaultShowInHelp(entry)) {
-                        const verb = entry.command.split(/\s+/)[0] ?? '';
-                        if (verb)
-                            visibleVerbs.add(verb);
-                    }
-                }
-            }
-            const visibleTopLevel = registry.list().filter((c) => {
-                if (wantsAll)
-                    return true;
-                return visibleVerbs.has(c.name);
-            });
-            process.stdout.write(header('Top-level commands'));
-            for (const c of visibleTopLevel) {
-                process.stdout.write(`  ${c.name.padEnd(10)} — ${c.description}\n`);
-            }
-            if (!wantsAll) {
-                const hiddenCount = registry.list().length - visibleTopLevel.length;
-                if (hiddenCount > 0) {
-                    process.stdout.write(`\n  …and ${hiddenCount} more, hidden from default help. Run \`shrk --full-help --all\` to see them, ` +
-                        `or \`shrk surface list\` to browse by tier.\n`);
-                }
-            }
-            // Show each canonical group once — also filtered by the allowlist
-            // unless --all was passed.
-            const canonicalGroups = [];
-            const aliasMap = registry.listGroupAliases();
-            const seen = new Set();
-            for (const g of registry.listGroups()) {
-                const canonical = aliasMap.get(g) ?? g;
-                if (!seen.has(canonical)) {
-                    seen.add(canonical);
-                    if (wantsAll || visibleVerbs.has(canonical)) {
-                        canonicalGroups.push(canonical);
-                    }
-                }
-            }
-            const aliasesByCanonical = new Map();
-            for (const [alias, canonical] of aliasMap.entries()) {
-                const list = aliasesByCanonical.get(canonical) ?? [];
-                list.push(alias);
-                aliasesByCanonical.set(canonical, list);
-            }
-            for (const group of canonicalGroups) {
-                const aliases = aliasesByCanonical.get(group) ?? [];
-                const aliasNote = aliases.length ? ` (also: ${aliases.join(', ')})` : '';
-                process.stdout.write(header(`shrk ${group} <sub>${aliasNote}`));
-                for (const s of registry.listGroup(group)) {
-                    process.stdout.write(`  ${group} ${s.name.padEnd(10)} — ${s.description}\n`);
-                }
-            }
-            // Explain / dry-run family — several carry an Advanced surface and are
-            // filtered out of the listings above, so surface them explicitly. These
-            // show you what a gate, ranker, or graph SEES before you act; an agent
-            // would otherwise find them only by guessing (the #4.4 friction).
-            const explainFamily = listExplainFamily();
-            if (explainFamily.length > 0) {
-                process.stdout.write(header('Inspect / explain (dry-run what a gate, ranker, or graph sees)'));
-                for (const e of explainFamily) {
-                    process.stdout.write(`  ${e.command.padEnd(24)} — ${firstSentence(e.description)}\n`);
-                }
-                process.stdout.write('  (also: shrk check wiring --explain <ruleId>)\n');
-            }
-            process.stdout.write('\nRun `shrk help <command>` for detailed usage.\n');
-            return 0;
+            // No topic: the start screen or `--full-help`, over THIS repository's
+            // surface (the one visibility authority — see renderFullHelp).
+            return runListing(registry, args, wantsFull);
         },
     };
 }

package/dist/commands/helper.command.d.ts

@@ -2,5 +2,6 @@ import { type ICommandHandler } from '../command-registry.js';
 export declare const helperListCommand: ICommandHandler;
 export declare const helperGetCommand: ICommandHandler;
 export declare const helperPlanCommand: ICommandHandler;
+export declare const helperDoctorCommand: ICommandHandler;
 export declare const helperCommand: ICommandHandler;
 //# sourceMappingURL=helper.command.d.ts.map

package/dist/commands/helper.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helper.command.d.ts","sourceRoot":"","sources":["../../src/commands/helper.command.ts"],"names":[],"mappings":"AAoBA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAUhC,eAAO,MAAM,iBAAiB,EAAE,eAgB/B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,eA6B9B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,eAiF/B,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,eAqB3B,CAAC"}
+{"version":3,"file":"helper.command.d.ts","sourceRoot":"","sources":["../../src/commands/helper.command.ts"],"names":[],"mappings":"AA6BA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAsBhC,eAAO,MAAM,iBAAiB,EAAE,eA2C/B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,eAiD9B,CAAC;AAyBF,eAAO,MAAM,iBAAiB,EAAE,eAgF/B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAkEjC,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,eA2B3B,CAAC"}