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

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

@@ -1 +1 @@
-{"version":3,"file":"gen.command.d.ts","sourceRoot":"","sources":["../../src/commands/gen.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkBhC,eAAO,MAAM,UAAU,EAAE,eAmJxB,CAAC"}
+{"version":3,"file":"gen.command.d.ts","sourceRoot":"","sources":["../../src/commands/gen.command.ts"],"names":[],"mappings":"AASA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkBhC,eAAO,MAAM,UAAU,EAAE,eA+JxB,CAAC"}

package/dist/commands/gen.command.js

@@ -19,7 +19,7 @@ const CHANGE_LABEL = {
 export const genCommand = {
     name: 'gen',
     description: 'Generate code from a template. Defaults to dry-run.',
-    usage: 'shrk gen <templateId> [<name>] [--var key=value ...] [--dry-run] [--write] [--force] [--save-plan <file>] [--json]',
+    usage: 'shrk gen <templateId> [<name>] [--var key=value ...] [--dry-run] [--write] [--force] [--save-plan <file>] [--show-content] [--json]',
     async run(args) {
         const templateId = args.positional[0];
         const name = args.positional[1];
@@ -114,6 +114,18 @@ export const genCommand = {
         for (const change of plan.changes) {
             process.stdout.write(`${CHANGE_LABEL[change.type]} ${change.relativePath} (${change.sizeBytes} bytes) — ${change.reason}\n`);
         }
+        // --show-content: print the already-computed virtual file content so an
+        // agent can review what a template would generate WITHOUT writing to disk
+        // (the saved plan stays content-free). The bytes are identical in dry-run
+        // and --write; this is purely additive.
+        if (flagBool(args, 'show-content')) {
+            process.stdout.write('\nVirtual content (not written to disk):\n');
+            for (const change of plan.changes) {
+                const body = change.contents ?? '';
+                process.stdout.write(`\n----- ${change.relativePath} (${change.sizeBytes} bytes) -----\n`);
+                process.stdout.write(body.endsWith('\n') ? body : body + '\n');
+            }
+        }
         if (plan.postGenerationNotes.length) {
             process.stdout.write('\nPost-generation notes:\n');
             for (const note of plan.postGenerationNotes)

package/dist/commands/graph-code-subverbs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-code-subverbs.d.ts","sourceRoot":"","sources":["../../src/commands/graph-code-subverbs.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAoC,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAkH3F,wBAAsB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBrE;AA4FD,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+DtE;AAiBD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAwF1E;AAID,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA8EpE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAmFtE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgDtE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgMvE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAuHtE;AAID;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+CpE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAoEvE;AAyBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgHpE"}
+{"version":3,"file":"graph-code-subverbs.d.ts","sourceRoot":"","sources":["../../src/commands/graph-code-subverbs.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAoC,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAiI3F,wBAAsB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBrE;AA4FD,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+DtE;AAiBD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAwF1E;AAID,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA8EpE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAmFtE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAiDtE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgMvE;AAID,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAuHtE;AAID;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA+CpE;AAID,wBAAsB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA0EvE;AAyBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgHpE"}

package/dist/commands/graph-code-subverbs.js

@@ -58,19 +58,37 @@ function maybeColumnarize(payload, args) {
     return out;
 }
 const STALE_HINT = `Index is missing or stale. Run 'shrk graph index' to build it.`;
-const STALE_RESULT_HINT = 'Some result files changed since the index was built — run `shrk graph index --changed` (or pass --refresh) for fresh results.';
+const STALE_RESULT_HINT = 'Some result files changed since the index was built — auto-refresh is on by default (you passed --no-refresh / SHRK_GRAPH_NO_REFRESH). Drop the opt-out, or run `shrk graph index --changed`, for fresh results.';
 /**
- * `--refresh`: incrementally reindex changed/deleted files BEFORE querying so
- * the agent's just-saved edits are reflected. CLI-only — it writes the
- * gitignored `.sharkcraft` cache; MCP never does this (read-only contract).
+ * Refresh-by-default: incrementally reindex changed/deleted files BEFORE
+ * querying so an agent's just-saved edits are reflected, then print a one-line
+ * `(refreshed, N files)` notice to stderr. The incremental updater is
+ * sub-second on SharkCraft-sized indexes, so this removes the manual `shrk
+ * graph index --changed` step that otherwise leaves every read command
+ * answering from a silently-stale index — the #1 daily-friction tax.
+ *
+ * Opt out with `--no-refresh` or `SHRK_GRAPH_NO_REFRESH=1` (e.g. to keep a read
+ * perfectly side-effect-free, or on a huge repo where the rewrite is felt).
+ * `--refresh` is still accepted as a harmless explicit-on alias.
+ *
+ * CLI-only — it writes the gitignored `.sharkcraft` cache; MCP never calls this
+ * (the read-only contract). When there is no index yet, `detectChangedAndDeleted`
+ * returns nothing, so `updateChanged` (which requires an existing store) is
+ * never reached. The notice goes to stderr so it never corrupts a `--json`
+ * payload on stdout.
  */
 function maybeRefresh(args, cwd) {
-    if (!flagBool(args, 'refresh'))
+    if (flagBool(args, 'no-refresh'))
+        return;
+    if ((process.env.SHRK_GRAPH_NO_REFRESH ?? '').trim().length > 0)
         return;
     const d = detectChangedAndDeleted(cwd);
-    if (d.changed.length > 0 || d.deleted.length > 0) {
-        updateChanged({ projectRoot: cwd, changedFiles: d.changed, deletedFiles: d.deleted });
-    }
+    if (d.changed.length === 0 && d.deleted.length === 0)
+        return;
+    const result = updateChanged({ projectRoot: cwd, changedFiles: d.changed, deletedFiles: d.deleted });
+    const n = result.updated.length + result.deleted.length;
+    if (n > 0)
+        process.stderr.write(`(refreshed, ${n} file${n === 1 ? '' : 's'})\n`);
 }
 /**
  * Targeted staleness over a query's result file paths: which changed (flag)
@@ -519,6 +537,7 @@ export async function runGraphSearch(args) {
     }
     const kindFlag = flagString(args, 'kind');
     const limit = Number(flagString(args, 'limit') ?? '20');
+    maybeRefresh(args, cwd);
     const api = loadOrFail(cwd, wantJson);
     if (!api)
         return 1;
@@ -923,10 +942,16 @@ export async function runGraphCallers(args) {
     const wantJson = flagBool(args, 'json');
     const target = args.positional[1];
     if (!target) {
-        process.stderr.write('Usage: shrk graph callers <symbol> [--mode call|reference] [--refresh]\n');
+        process.stderr.write('Usage: shrk graph callers <symbol> [--mode call|reference] [--limit N] [--no-refresh]\n');
         return 2;
     }
     const mode = (flagString(args, 'mode') ?? 'call');
+    // --limit N: cap the returned call sites (default 200). `total` still reports
+    // the true uncapped count, so a truncated result stays honest. Guard against
+    // non-numeric input — `Number('foo')` is NaN and `slice(0, NaN)` would zero
+    // the callers list while `total` kept showing the real count.
+    const parsedLimit = Number.parseInt(flagString(args, 'limit') ?? '200', 10);
+    const limit = Number.isFinite(parsedLimit) && parsedLimit > 0 ? parsedLimit : 200;
     maybeRefresh(args, cwd);
     const api = loadOrFail(cwd, wantJson);
     if (!api)
@@ -961,7 +986,7 @@ export async function runGraphCallers(args) {
         symbol: nodeSummary(sym),
         mode,
         total: liveSites.length,
-        callers: liveSites.slice(0, 200).map((s) => ({
+        callers: liveSites.slice(0, limit).map((s) => ({
             ...nodeSummary(s.node),
             ...(s.line ? { line: s.line } : {}),
         })),
@@ -978,7 +1003,7 @@ export async function runGraphCallers(args) {
         process.stdout.write(`  ⓘ ${note}\n`);
     // Render `path:line` so the agent jumps straight to the call site instead
     // of having to grep inside each returned file.
-    for (const c of payload.callers.slice(0, 50)) {
+    for (const c of payload.callers.slice(0, Math.min(50, limit))) {
         process.stdout.write(`  ${c.path ?? c.id}${c.line ? ':' + c.line : ''}\n`);
     }
     if (fresh.field) {
@@ -1025,7 +1050,7 @@ export async function runGraphPath(args) {
     const fromArg = args.positional[1];
     const toArg = args.positional[2];
     if (!fromArg || !toArg) {
-        process.stderr.write('Usage: shrk graph path <from> <to> [--max-depth N] [--refresh] [--json]\n');
+        process.stderr.write('Usage: shrk graph path <from> <to> [--max-depth N] [--no-refresh] [--json]\n');
         return 2;
     }
     const maxDepth = Math.max(1, Math.min(32, Number(flagString(args, 'max-depth') ?? '16')));

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/cli",
-  "version": "0.1.0-alpha.18",
+  "version": "0.1.0-alpha.19",
   "description": "SharkCraft CLI (`shrk`): structured project intelligence for AI coding agents.",
   "license": "MIT",
   "author": "SharkCraft contributors",
@@ -47,38 +47,38 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.18",
-    "@shrkcrft/compress": "^0.1.0-alpha.18",
-    "@shrkcrft/config": "^0.1.0-alpha.18",
-    "@shrkcrft/workspace": "^0.1.0-alpha.18",
-    "@shrkcrft/knowledge": "^0.1.0-alpha.18",
-    "@shrkcrft/context": "^0.1.0-alpha.18",
-    "@shrkcrft/rules": "^0.1.0-alpha.18",
-    "@shrkcrft/paths": "^0.1.0-alpha.18",
-    "@shrkcrft/templates": "^0.1.0-alpha.18",
-    "@shrkcrft/plugin-api": "^0.1.0-alpha.18",
-    "@shrkcrft/dashboard": "^0.1.0-alpha.18",
-    "@shrkcrft/dashboard-api": "^0.1.0-alpha.18",
-    "@shrkcrft/pipelines": "^0.1.0-alpha.18",
-    "@shrkcrft/presets": "^0.1.0-alpha.18",
-    "@shrkcrft/boundaries": "^0.1.0-alpha.18",
-    "@shrkcrft/graph": "^0.1.0-alpha.18",
-    "@shrkcrft/rule-graph": "^0.1.0-alpha.18",
-    "@shrkcrft/structural-search": "^0.1.0-alpha.18",
-    "@shrkcrft/impact-engine": "^0.1.0-alpha.18",
-    "@shrkcrft/context-planner": "^0.1.0-alpha.18",
-    "@shrkcrft/architecture-guard": "^0.1.0-alpha.18",
-    "@shrkcrft/framework-scanners": "^0.1.0-alpha.18",
-    "@shrkcrft/api-surface-diff": "^0.1.0-alpha.18",
-    "@shrkcrft/quality-gates": "^0.1.0-alpha.18",
-    "@shrkcrft/migrate": "^0.1.0-alpha.18",
-    "@shrkcrft/generator": "^0.1.0-alpha.18",
-    "@shrkcrft/importer": "^0.1.0-alpha.18",
-    "@shrkcrft/inspector": "^0.1.0-alpha.18",
-    "@shrkcrft/ai": "^0.1.0-alpha.18",
-    "@shrkcrft/embeddings": "^0.1.0-alpha.18",
-    "@shrkcrft/shared": "^0.1.0-alpha.18",
-    "@shrkcrft/mcp-server": "^0.1.0-alpha.18",
+    "@shrkcrft/core": "^0.1.0-alpha.19",
+    "@shrkcrft/compress": "^0.1.0-alpha.19",
+    "@shrkcrft/config": "^0.1.0-alpha.19",
+    "@shrkcrft/workspace": "^0.1.0-alpha.19",
+    "@shrkcrft/knowledge": "^0.1.0-alpha.19",
+    "@shrkcrft/context": "^0.1.0-alpha.19",
+    "@shrkcrft/rules": "^0.1.0-alpha.19",
+    "@shrkcrft/paths": "^0.1.0-alpha.19",
+    "@shrkcrft/templates": "^0.1.0-alpha.19",
+    "@shrkcrft/plugin-api": "^0.1.0-alpha.19",
+    "@shrkcrft/dashboard": "^0.1.0-alpha.19",
+    "@shrkcrft/dashboard-api": "^0.1.0-alpha.19",
+    "@shrkcrft/pipelines": "^0.1.0-alpha.19",
+    "@shrkcrft/presets": "^0.1.0-alpha.19",
+    "@shrkcrft/boundaries": "^0.1.0-alpha.19",
+    "@shrkcrft/graph": "^0.1.0-alpha.19",
+    "@shrkcrft/rule-graph": "^0.1.0-alpha.19",
+    "@shrkcrft/structural-search": "^0.1.0-alpha.19",
+    "@shrkcrft/impact-engine": "^0.1.0-alpha.19",
+    "@shrkcrft/context-planner": "^0.1.0-alpha.19",
+    "@shrkcrft/architecture-guard": "^0.1.0-alpha.19",
+    "@shrkcrft/framework-scanners": "^0.1.0-alpha.19",
+    "@shrkcrft/api-surface-diff": "^0.1.0-alpha.19",
+    "@shrkcrft/quality-gates": "^0.1.0-alpha.19",
+    "@shrkcrft/migrate": "^0.1.0-alpha.19",
+    "@shrkcrft/generator": "^0.1.0-alpha.19",
+    "@shrkcrft/importer": "^0.1.0-alpha.19",
+    "@shrkcrft/inspector": "^0.1.0-alpha.19",
+    "@shrkcrft/ai": "^0.1.0-alpha.19",
+    "@shrkcrft/embeddings": "^0.1.0-alpha.19",
+    "@shrkcrft/shared": "^0.1.0-alpha.19",
+    "@shrkcrft/mcp-server": "^0.1.0-alpha.19",
     "@huggingface/transformers": "^3.7.5"
   },
   "publishConfig": {