@shrkcrft/cli 0.1.0-alpha.17 → 0.1.0-alpha.19

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

@@ -1 +1 @@
-{"version":3,"file":"graph.command.d.ts","sourceRoot":"","sources":["../../src/commands/graph.command.ts"],"names":[],"mappings":"AAUA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA0BhC,eAAO,MAAM,YAAY,EAAE,eA2M1B,CAAC"}
+{"version":3,"file":"graph.command.d.ts","sourceRoot":"","sources":["../../src/commands/graph.command.ts"],"names":[],"mappings":"AAUA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA4BhC,eAAO,MAAM,YAAY,EAAE,eA+M1B,CAAC"}

package/dist/commands/graph.command.js

@@ -3,7 +3,7 @@ import * as nodePath from 'node:path';
 import { analyzeImportGraph, buildKnowledgeGraph, findGraphPath, getGraphNode, inspectSharkcraft, } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
-import { runGraphCallers, runGraphContext, runGraphCycles, runGraphDeps, runGraphImpact, runGraphIndex, runGraphSearch, runGraphStatus, runGraphUnresolved, } from "./graph-code-subverbs.js";
+import { runGraphCallers, runGraphContext, runGraphCycles, runGraphDeps, runGraphHubs, runGraphImpact, runGraphIndex, runGraphPath, runGraphSearch, runGraphStatus, runGraphUnresolved, } from "./graph-code-subverbs.js";
 const KNOWN_KINDS = [
     'knowledge',
     'rule',
@@ -17,9 +17,11 @@ const KNOWN_KINDS = [
 ];
 export const graphCommand = {
     name: 'graph',
-    description: 'Show the SharkCraft knowledge graph and the code-intelligence graph surface. Use `shrk graph <id>` for asset-graph nodes and `shrk graph index|status|search|context|impact|callers|cycles|unresolved|deps|why|export` for code-graph workflows.',
+    description: 'Show the SharkCraft knowledge graph and the code-intelligence graph surface. Use `shrk graph <id>` for asset-graph nodes and `shrk graph index|status|search|context|impact|path|hubs|callers|cycles|unresolved|deps|why|export` for code-graph workflows.',
     usage: 'shrk [--cwd <dir>] graph [<id>] [--type <kind>] [--format text|json|dot|mermaid] [--output <file>] [--json]\n' +
-        'shrk graph index|status|search|context|impact|callers|cycles|unresolved|deps|why|export ...',
+        'shrk graph index|status|search|context|impact|path|hubs|callers|cycles|unresolved|deps|why|export ...\n' +
+        'shrk graph path <from> <to>   — is code A wired to code B? (shortest import/call path)\n' +
+        'shrk graph hubs [--limit N] [--path <dir>]   — most-depended-on symbols/files (load-bearing code; scope to a subsystem)',
     async run(args) {
         // Code-intelligence subverbs (R65) don't need the knowledge graph —
         // dispatch them before the expensive inspection so they stay fast.
@@ -34,6 +36,10 @@ export const graphCommand = {
             return runGraphContext(args);
         if (earlySub === 'impact')
             return runGraphImpact(args);
+        if (earlySub === 'path')
+            return runGraphPath(args);
+        if (earlySub === 'hubs')
+            return runGraphHubs(args);
         if (earlySub === 'callers')
             return runGraphCallers(args);
         if (earlySub === 'cycles')

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

@@ -1 +1 @@
-{"version":3,"file":"help.command.d.ts","sourceRoot":"","sources":["../../src/commands/help.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAqB9D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAmD1C;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe;;;;cAK3C;QAAE,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAA;KAAE,GAAG,MAAM;EA2HpF"}
+{"version":3,"file":"help.command.d.ts","sourceRoot":"","sources":["../../src/commands/help.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAqB9D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAwC1C;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe;;;;cAK3C;QAAE,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAA;KAAE,GAAG,MAAM;EA2HpF"}

package/dist/commands/help.command.js

@@ -31,21 +31,16 @@ export function renderStartScreen() {
     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 (recommended for new repos)');
-    lines.push('  $ shrk import claude-md ./CLAUDE.md --populate --write  — populate sharkcraft/ from existing CLAUDE.md / AGENTS.md / .cursor/rules');
-    lines.push('  $ shrk init --with-claude-skill --write  — scaffold sharkcraft/ AND inline rules into .claude/skills/ (one-step)');
-    lines.push('  $ shrk init                      — scaffold sharkcraft/ + config skeleton (preset defaults)');
+    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 inspect                   — detect frameworks, paths, package manager');
     lines.push('  $ shrk onboard                   — analyze an existing repo (advisory)');
     lines.push('');
     lines.push('Use it for a task:');
-    lines.push('  $ shrk brief                     — single-page brief Claude reads first (project + rules + paths + verification)');
     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 code-intel                — one-shot code-intelligence health summary');
-    lines.push('  $ shrk coverage                  — what knowledge is missing');
+    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)');
@@ -54,22 +49,16 @@ export function renderStartScreen() {
     lines.push('  $ shrk quality                   — pre-PR gate (doctor + boundaries + coverage + drift)');
     lines.push('');
     lines.push('Browse what shrk knows:');
-    lines.push('  $ shrk graph status             — current code-graph freshness and health');
+    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('  $ shrk rules list                — rules + conventions');
-    lines.push('  $ shrk templates list            — generator templates');
-    lines.push('  $ shrk import                    — parse AGENTS.md / CLAUDE.md / .cursor/rules');
-    lines.push('  $ shrk export                    — render to a flat agent-rule file');
     lines.push('');
     lines.push('Run shrk for an agent:');
-    lines.push('  $ shrk export claude-skill --write — generate .claude/skills/<name>/SKILL.md (rules INTO the prompt — no MCP roundtrip)');
-    lines.push('  $ shrk export agents-md --write  — generate AGENTS.md / CLAUDE.md / .cursor/rules / copilot-instructions');
     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 (always callable, hidden from this screen by default):');
-    lines.push('  $ shrk surface list              — full ~70-verb catalog by tier');
-    lines.push('  $ shrk surface profiles          — named profiles (small-app / monorepo / ci / agent / pack-author)');
+    lines.push('Discover the rest (everything stays callable — this screen shows ~17 of ~70 verbs):');
+    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');
     lines.push('  $ shrk --about                   — what shrk is and is not');

package/dist/commands/knowledge-author.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"knowledge-author.command.d.ts","sourceRoot":"","sources":["../../src/commands/knowledge-author.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAoBH,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAwChC,eAAO,MAAM,mBAAmB,EAAE,eAgEjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA0GpC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAoEpC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eA2DlC,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAE,eAmB3C,CAAC"}
+{"version":3,"file":"knowledge-author.command.d.ts","sourceRoot":"","sources":["../../src/commands/knowledge-author.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAoBH,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAwChC,eAAO,MAAM,mBAAmB,EAAE,eAgEjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA0GpC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAoEpC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAsElC,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAE,eAmB3C,CAAC"}

package/dist/commands/knowledge-author.command.js

@@ -300,6 +300,15 @@ export const knowledgeLintCommand = {
     async run(args) {
         const cwd = resolveCwd(args);
         const inspection = await inspectSharkcraft({ cwd });
+        // Loud guard: a 0-entry scan is NOT a clean pass — it almost always means
+        // the loader found nothing (wrong cwd / no `sharkcraft/` folder / no
+        // entries), which otherwise reads as "lint passed". Surface it on stderr so
+        // it can't be mistaken for success, while keeping stdout/JSON clean.
+        if (inspection.knowledgeEntries.length === 0) {
+            process.stderr.write('WARN  knowledge lint scanned 0 entries — there is nothing to lint (this is NOT a clean pass).\n' +
+                '      Likely causes: no `sharkcraft/` folder here, not at the workspace root, or no\n' +
+                '      knowledge entries are defined. Run `shrk doctor` to confirm how many entries load.\n');
+        }
         const entryIds = flagList(args, 'id');
         const includeAdvisory = !flagBool(args, 'no-advisory');
         const stale = buildKnowledgeStaleReport(inspection);

package/dist/commands/knowledge-propose.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"knowledge-propose.command.d.ts","sourceRoot":"","sources":["../../src/commands/knowledge-propose.command.ts"],"names":[],"mappings":"AAqBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkDhC,eAAO,MAAM,uBAAuB,EAAE,eA0ErC,CAAC"}
+{"version":3,"file":"knowledge-propose.command.d.ts","sourceRoot":"","sources":["../../src/commands/knowledge-propose.command.ts"],"names":[],"mappings":"AAqBA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkDhC,eAAO,MAAM,uBAAuB,EAAE,eA4ErC,CAAC"}

package/dist/commands/knowledge-propose.command.js

@@ -10,7 +10,7 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import * as nodePath from 'node:path';
 import { AssetKind, AssetProvenanceOperation, KNOWLEDGE_PROPOSE_SCHEMA, proposeKnowledge, recordProvenance, renderKnowledgeProposeMarkdown, } from '@shrkcrft/inspector';
-import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { flagBool, flagNumber, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson } from "../output/format-output.js";
 import { detectAuthoringSource } from "../authoring/authoring-kit.js";
 function renderProposalAsTs(p) {
@@ -54,13 +54,14 @@ function writeDraftFiles(cwd, report) {
 export const knowledgeProposeCommand = {
     name: 'propose',
     description: 'Propose stub knowledge entries for exported top-level constructs that lack coverage. Preview-first; --write materialises drafts under .sharkcraft/authoring/proposed/.',
-    usage: 'shrk knowledge propose [--path <file>] [--symbol <name>] [--since <ref>|--all] [--json] [--write]',
+    usage: 'shrk knowledge propose [--path <file>] [--symbol <name>] [--since <ref>|--all] [--max <n>] [--json] [--write]',
     async run(args) {
         const cwd = resolveCwd(args);
         const path = flagString(args, 'path');
         const symbol = flagString(args, 'symbol');
         const sinceFlag = flagString(args, 'since');
         const all = flagBool(args, 'all');
+        const max = flagNumber(args, 'max');
         const since = path
             ? undefined
             : symbol
@@ -73,6 +74,7 @@ export const knowledgeProposeCommand = {
             ...(path ? { path } : {}),
             ...(symbol ? { symbol } : {}),
             ...(since !== undefined ? { since } : {}),
+            ...(max !== undefined && max >= 0 ? { max } : {}),
         });
         if (flagBool(args, 'json')) {
             const payload = flagBool(args, 'write')

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

@@ -1 +1 @@
-{"version":3,"file":"knowledge.command.d.ts","sourceRoot":"","sources":["../../src/commands/knowledge.command.ts"],"names":[],"mappings":"AAaA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAoFhC,eAAO,MAAM,oBAAoB,EAAE,eAsBlC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAuBjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAqCpC,CAAC;AAoBF,eAAO,MAAM,0BAA0B,EAAE,eAWxC,CAAC;AA8NF,eAAO,MAAM,sBAAsB,EAAE,eAQpC,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eA8CxC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAuBrC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,EAAE,eA8B1C,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eA8BxC,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,eAkC1C,CAAC"}
+{"version":3,"file":"knowledge.command.d.ts","sourceRoot":"","sources":["../../src/commands/knowledge.command.ts"],"names":[],"mappings":"AAaA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAoFhC,eAAO,MAAM,oBAAoB,EAAE,eA2ClC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eAuBjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAqCpC,CAAC;AAoBF,eAAO,MAAM,0BAA0B,EAAE,eAWxC,CAAC;AA8NF,eAAO,MAAM,sBAAsB,EAAE,eAQpC,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eA8CxC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAuBrC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,EAAE,eA8B1C,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eA8BxC,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,eAkC1C,CAAC"}

package/dist/commands/knowledge.command.js

@@ -54,7 +54,7 @@ ${p.ci.exitNonZero ? `<p style="color:#a40000;font-weight:bold">FAIL: ${esc(p.ci
 export const knowledgeListCommand = {
     name: 'list',
     description: 'List knowledge entries.',
-    usage: 'shrk knowledge list [--type rule] [--scope x,y] [--json]',
+    usage: 'shrk knowledge list [--type rule] [--scope x,y] [--top N] [--brief] [--json]',
     async run(args) {
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
         const types = flagList(args, 'type');
@@ -64,8 +64,28 @@ export const knowledgeListCommand = {
             entries = entries.filter((e) => types.includes(String(e.type)));
         if (scope.length)
             entries = entries.filter((e) => scope.some((s) => e.scope.includes(s)));
+        // --top N: a deterministic, token-bounded slice. Sort by id first so the
+        // "top N" is stable across machines (entries otherwise load in fs-scan
+        // order). Reduce at the source instead of piping through `shrk compress`.
+        const top = flagNumber(args, 'top');
+        if (top !== undefined && top > 0) {
+            entries = [...entries].sort((a, b) => a.id.localeCompare(b.id)).slice(0, top);
+        }
         if (flagBool(args, 'json')) {
-            process.stdout.write(asJson(entries.map((e) => ({ ...e }))) + '\n');
+            // --brief: project to the high-signal fields, dropping content / examples
+            // / metadata (the bulk of the payload) so an agent pays far fewer tokens.
+            const payload = flagBool(args, 'brief')
+                ? entries.map((e) => ({
+                    id: e.id,
+                    type: e.type,
+                    priority: e.priority,
+                    title: e.title,
+                    scope: e.scope,
+                    tags: e.tags,
+                    appliesWhen: e.appliesWhen,
+                }))
+                : entries.map((e) => ({ ...e }));
+            process.stdout.write(asJson(payload) + '\n');
             return 0;
         }
         process.stdout.write(header(`Knowledge (${entries.length})`));

package/dist/commands/move-plan.command.js

@@ -48,7 +48,7 @@ export const movePlanCommand = {
         }
         const store = new GraphStore(cwd);
         if (!store.exists()) {
-            process.stderr.write('No SharkCraft graph found. Run `shrk graph build` so move-plan can trace importers.\n');
+            process.stderr.write('No SharkCraft graph found. Run `shrk graph index` so move-plan can trace importers.\n');
             return 1;
         }
         const api = GraphQueryApi.fromStore(cwd);

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

@@ -1 +1 @@
-{"version":3,"file":"preflight.command.d.ts","sourceRoot":"","sources":["../../src/commands/preflight.command.ts"],"names":[],"mappings":"AAoBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgBhC,eAAO,MAAM,gBAAgB,EAAE,eAmF9B,CAAC"}
+{"version":3,"file":"preflight.command.d.ts","sourceRoot":"","sources":["../../src/commands/preflight.command.ts"],"names":[],"mappings":"AAoBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAiBhC,eAAO,MAAM,gBAAgB,EAAE,eAoG9B,CAAC"}

package/dist/commands/preflight.command.js

@@ -13,6 +13,7 @@
  */
 import { planChangedPreflight, PreflightAction, PreflightProfile, renderChangedPreflightText, resolveChangedFiles, } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { loadProjectConfig } from '@shrkcrft/config';
 import { asJson, header } from "../output/format-output.js";
 function parseProfile(value) {
     if (value === 'quick')
@@ -55,10 +56,24 @@ export const preflightCommand = {
             resolveOpts.includeWorktree = true;
         }
         const changed = resolveChangedFiles(resolveOpts);
+        // Ground the test/typecheck gates in the project's declared verification
+        // commands when present, rather than the generic `bun test` / tsc defaults.
+        // Best-effort: a repo without sharkcraft/ config keeps the defaults.
+        let testCommand;
+        let typecheckCommand;
+        const loaded = await loadProjectConfig(cwd);
+        if (loaded.ok) {
+            const vcs = loaded.value.config.verificationCommands ?? [];
+            const pick = (...ids) => vcs.find((v) => ids.includes(v.id))?.command;
+            testCommand = pick('test', 'tests', 'unit', 'unit-tests');
+            typecheckCommand = pick('typecheck', 'tsc', 'types', 'typecheck-all');
+        }
         const plan = planChangedPreflight({
             projectRoot: cwd,
             changedFiles: changed.files,
             profile,
+            ...(testCommand ? { testCommand } : {}),
+            ...(typecheckCommand ? { typecheckCommand } : {}),
         });
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson({ plan, scopeMode: changed.mode }) + '\n');

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

@@ -1,4 +1,10 @@
 import { type ICommandHandler } from '../command-registry.js';
 export declare const recommendCommand: ICommandHandler;
+/**
+ * Does the query look like create/build work (a routing hint's `shrk gen`
+ * playbook is most useful here)? Mirrors {@link looksLikePlanning}: a
+ * create/build verb leading the query or in slots 1–3.
+ */
+export declare function looksLikeCreateBuild(query: string): boolean;
 export declare function looksLikePlanning(query: string): boolean;
 //# sourceMappingURL=recommend.command.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"recommend.command.d.ts","sourceRoot":"","sources":["../../src/commands/recommend.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAShC,eAAO,MAAM,gBAAgB,EAAE,eA0K9B,CAAC;AAoGF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAcxD"}
+{"version":3,"file":"recommend.command.d.ts","sourceRoot":"","sources":["../../src/commands/recommend.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAShC,eAAO,MAAM,gBAAgB,EAAE,eA+M9B,CAAC;AAgHF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAY3D;AAcD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAcxD"}

package/dist/commands/recommend.command.js

@@ -79,6 +79,36 @@ export const recommendCommand = {
                 searchReport = null;
             }
         }
+        // R1 — promote a strongly-matched task-routing hint's recommends.commands
+        // into the HEADLINE for create/build intents. Routing hints are scored by
+        // explainTaskRouting but were previously only shown under --verbose, so the
+        // headline fell back to generic review/report/impact commands even when the
+        // pack declared the right `shrk gen <template>` playbook. When the top hint
+        // clears the threshold AND the query looks like create/build work, its
+        // commands lead and the generic defaults slide to the tail. Deterministic.
+        const topHint = routingMatches[0];
+        const hintCommands = topHint?.hint.recommends.commands ?? [];
+        if (query.length > 0 &&
+            looksLikeCreateBuild(query) &&
+            topHint &&
+            topHint.score >= ROUTING_HINT_PROMOTE_THRESHOLD &&
+            hintCommands.length > 0) {
+            const promoted = hintCommands.map((command) => ({
+                command,
+                why: `Routing hint "${topHint.hint.id}" matched (score ${topHint.score}) — project playbook for this create/build task.`,
+                safetyLevel: promotedSafetyLevel(command),
+            }));
+            const promotedSet = new Set(promoted.map((p) => p.command));
+            const isGenericDefault = (c) => /^(bun run )?shrk (review|report|impact)\b/i.test(c);
+            const existing = report.recommendations;
+            const keptNonGeneric = existing.filter((r) => !promotedSet.has(r.command) && !isGenericDefault(r.command));
+            const keptGeneric = existing.filter((r) => !promotedSet.has(r.command) && isGenericDefault(r.command));
+            report.recommendations = [
+                ...promoted,
+                ...keptNonGeneric,
+                ...keptGeneric,
+            ];
+        }
         if (machineJson) {
             process.stdout.write(asJson({
                 ...report,
@@ -250,6 +280,48 @@ const PLANNING_VERBS = new Set([
     'evaluate',
     'assess',
 ]);
+/**
+ * Minimum routing-hint score (from `explainTaskRouting`: +2 per keyword, +3 per
+ * phrase, +2 per regex, + confidenceBoost) required to promote a hint's
+ * commands into the recommend headline. 3 ⇒ at least one phrase match or two
+ * keyword/regex hits — a real match, not a single weak keyword.
+ */
+const ROUTING_HINT_PROMOTE_THRESHOLD = 3;
+const CREATE_BUILD_VERBS = new Set([
+    'create', 'build', 'add', 'generate', 'scaffold', 'implement', 'make', 'new', 'introduce', 'write',
+]);
+/**
+ * Does the query look like create/build work (a routing hint's `shrk gen`
+ * playbook is most useful here)? Mirrors {@link looksLikePlanning}: a
+ * create/build verb leading the query or in slots 1–3.
+ */
+export function looksLikeCreateBuild(query) {
+    const tokens = query
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, ' ')
+        .split(/\s+/)
+        .filter((t) => t.length > 0);
+    if (tokens.length === 0)
+        return false;
+    if (CREATE_BUILD_VERBS.has(tokens[0]))
+        return true;
+    for (let i = 1; i < Math.min(4, tokens.length); i++) {
+        if (CREATE_BUILD_VERBS.has(tokens[i]))
+            return true;
+    }
+    return false;
+}
+/** Conservative safety classification for a promoted routing-hint command. */
+function promotedSafetyLevel(command) {
+    if (/^(bun run )?shrk (gen|init|apply|import)\b/i.test(command))
+        return 'writes-source';
+    if (/^(bun run )?shrk (brief|dev|onboard|simulate|orchestrate|spec)\b/i.test(command)) {
+        return 'writes-drafts';
+    }
+    if (/^(bun|bunx|npm|pnpm|node|git|nx) /i.test(command))
+        return 'runs-shell';
+    return 'read-only';
+}
 export function looksLikePlanning(query) {
     const tokens = query
         .toLowerCase()

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

@@ -1 +1 @@
-{"version":3,"file":"rules.command.d.ts","sourceRoot":"","sources":["../../src/commands/rules.command.ts"],"names":[],"mappings":"AAcA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAQhC,eAAO,MAAM,gBAAgB,EAAE,eAe9B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,eAuB7B,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAmClC,CAAC;AAuBF,eAAO,MAAM,oBAAoB,EAAE,eAiFlC,CAAC;AAkBF;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,EAAE,eAsB7B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,EAAE,eA6BhC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,EAAE,eA6BhC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,eA2F9B,CAAC;AAoCF,eAAO,MAAM,kBAAkB,EAAE,eAiChC,CAAC"}
+{"version":3,"file":"rules.command.d.ts","sourceRoot":"","sources":["../../src/commands/rules.command.ts"],"names":[],"mappings":"AAcA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAQhC,eAAO,MAAM,gBAAgB,EAAE,eAgC9B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,eAuB7B,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAmClC,CAAC;AAuBF,eAAO,MAAM,oBAAoB,EAAE,eAiFlC,CAAC;AAkBF;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,EAAE,eAsB7B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,EAAE,eA6BhC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,EAAE,eA6BhC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,eA2F9B,CAAC;AAoCF,eAAO,MAAM,kBAAkB,EAAE,eAiChC,CAAC"}

package/dist/commands/rules.command.js

@@ -8,12 +8,29 @@ import { knowledgeAddCommand, knowledgeRemoveCommand, knowledgeUpdateCommand, }
 export const rulesListCommand = {
     name: 'list',
     description: 'List all rules.',
-    usage: 'shrk rules list [--json]',
+    usage: 'shrk rules list [--top N] [--brief] [--json]',
     async run(args) {
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
-        const rules = inspection.ruleService.list();
+        let rules = inspection.ruleService.list();
+        // --top N: deterministic, token-bounded slice (id-sorted so it's stable).
+        const top = flagNumber(args, 'top');
+        if (top !== undefined && top > 0) {
+            rules = [...rules].sort((a, b) => a.id.localeCompare(b.id)).slice(0, top);
+        }
         if (flagBool(args, 'json')) {
-            process.stdout.write(asJson(rules) + '\n');
+            // --brief: project to the high-signal fields (drop content/examples).
+            const payload = flagBool(args, 'brief')
+                ? rules.map((r) => ({
+                    id: r.id,
+                    type: r.type,
+                    priority: r.priority,
+                    title: r.title,
+                    scope: r.scope,
+                    tags: r.tags,
+                    appliesWhen: r.appliesWhen,
+                }))
+                : rules;
+            process.stdout.write(asJson(payload) + '\n');
             return 0;
         }
         process.stdout.write(header(`Rules (${rules.length})`));

package/dist/commands/smart-context.command.d.ts

@@ -1,21 +1,4 @@
 import { type ICommandHandler } from '../command-registry.js';
-/**
- * Gemini-backed context enrichment.
- *
- * Sits next to `shrk ask` as an explicit, opt-in AI surface — the
- * deterministic engine (`shrk context`, `shrk brief`, MCP tools) stays
- * AI-free. See docs/smart-context.md and the
- * `.claude/skills/shrk-smart-context/` skill for the agent workflow.
- *
- * Verbs:
- *   - `smart-context "<task>"`               — single brief (default).
- *   - `smart-context "<task>" --plan`        — single structured plan.
- *   - `smart-context "<task>" --ai-plan`     — two-stage AI-assisted plan.
- *   - `smart-context "<task>" --save`        — persist under .sharkcraft/smart-context/.
- *   - `smart-context plan-ahead "t1" "t2"`   — batch-save plans for an upcoming queue.
- *   - `smart-context list`                   — list saved entries.
- *   - `smart-context show <slug>`            — print a saved entry.
- */
 export declare const smartContextCommand: ICommandHandler;
 /** `shrk smart-context plan-ahead "task1" "task2" ...` — batch-saves plans. */
 export declare const smartContextPlanAheadCommand: ICommandHandler;
@@ -55,4 +38,30 @@ export declare const smartContextAuditPipelinesCommand: ICommandHandler;
 export declare const smartContextEmbeddingsBuildCommand: ICommandHandler;
 /** `shrk smart-context embeddings-status` — freshness report (no model load). */
 export declare const smartContextEmbeddingsStatusCommand: ICommandHandler;
+interface IIndexFreshness {
+    /** Files currently in the semantic index. */
+    indexed: number;
+    /** stale + missing + untracked — how far the index is behind the working tree. */
+    behind: number;
+    stale: number;
+    missing: number;
+    untracked: number;
+    /** True when this run refreshed the index inline (--refresh or under the auto cap). */
+    refreshed: boolean;
+    /**
+     * Deleted-file suggestions DROPPED from this query's results — a stale index
+     * returned hits for files no longer on disk; they were pruned before the agent
+     * ever saw them. Present (and > 0) only when the prune actually fired.
+     */
+    prunedDeleted?: number;
+    /** Command to bring the index current, when it is still behind. */
+    nextCommand?: string;
+}
+/**
+ * Render the one-line freshness warning for a stale semantic index — including
+ * how many deleted-file suggestions were dropped from the results this query.
+ * Returns null when the index is current (no noise). Pure + testable.
+ */
+export declare function renderIndexFreshnessWarning(f: IIndexFreshness | undefined): string | null;
+export {};
 //# sourceMappingURL=smart-context.command.d.ts.map

package/dist/commands/smart-context.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"smart-context.command.d.ts","sourceRoot":"","sources":["../../src/commands/smart-context.command.ts"],"names":[],"mappings":"AAyBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAyDhC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mBAAmB,EAAE,eA6LjC,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,EAAE,eAmF1C,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,uBAAuB,EAAE,eAwBrC,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,uBAAuB,EAAE,eAkCrC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAmH/C,CAAC;AA2JF;;;;;;;GAOG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAoH/C,CAAC;AA2JF;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAgG/C,CAAC;AAyPF,4EAA4E;AAC5E,eAAO,MAAM,kCAAkC,EAAE,eAuHhD,CAAC;AAMF,iFAAiF;AACjF,eAAO,MAAM,mCAAmC,EAAE,eAsCjD,CAAC"}
+{"version":3,"file":"smart-context.command.d.ts","sourceRoot":"","sources":["../../src/commands/smart-context.command.ts"],"names":[],"mappings":"AAyBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAmFhC,eAAO,MAAM,mBAAmB,EAAE,eAuNjC,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,EAAE,eAmF1C,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,uBAAuB,EAAE,eAwBrC,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,uBAAuB,EAAE,eAkCrC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAmH/C,CAAC;AA2JF;;;;;;;GAOG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAoH/C,CAAC;AA2JF;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,EAAE,eAgG/C,CAAC;AAyPF,4EAA4E;AAC5E,eAAO,MAAM,kCAAkC,EAAE,eAuHhD,CAAC;AAMF,iFAAiF;AACjF,eAAO,MAAM,mCAAmC,EAAE,eAsCjD,CAAC;AAqJF,UAAU,eAAe;IACvB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,eAAe,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAWzF"}