@shrkcrft/cli 0.1.0-alpha.21 → 0.1.0-alpha.23

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

@@ -1 +1 @@
-{"version":3,"file":"commands.command.d.ts","sourceRoot":"","sources":["../../src/commands/commands.command.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"commands.command.d.ts","sourceRoot":"","sources":["../../src/commands/commands.command.ts"],"names":[],"mappings":"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"}

package/dist/commands/commands.command.js

@@ -1,12 +1,13 @@
-import { flagBool, flagString } from "../command-registry.js";
+import { flagBool, flagString, resolveCwd } from "../command-registry.js";
 import { asJson, header } from "../output/format-output.js";
+import { BUILTIN_PROFILES, getProfile } from "../surface/profiles.js";
 import { buildCommandSafetyMatrix, COMMAND_CATALOG, CommandLifecycle, commandLifecycle, CommandSurface, commandSurface, commandTaskRole, defaultShowInHelp, R46_OVERLAY, renderCommandSafetyMatrixMarkdown, SafetyLevel } from "./command-catalog.js";
 import { buildCommandTaxonomy, buildPrimaryCommandsReport, renderCommandTaxonomyMarkdown, renderCommandTaxonomyText, renderPrimaryCommandsText } from '@shrkcrft/inspector';
 export function makeCommandsCommand(registry) {
     return {
         name: 'commands',
-        description: 'Browse the command catalog. Default view is compact (primary + common); pass --all for the full catalog. Subcommands: primary | advanced | deprecated | hidden | retirement-plan | docs-check | surface | machine | legacy | overlaps | taxonomy | matrix | tree | search | suggest | explain | entrypoints | doctor | ux-check.',
-        usage: 'shrk commands [primary|advanced|deprecated|hidden|retirement-plan|docs-check|surface <s>|machine|legacy|overlaps|taxonomy|matrix|tree|search <q>|suggest <p>|explain <cmd>|entrypoints|doctor|ux-check] [--all] [--safety <level>] [--category <name>] [--json]',
+        description: 'Browse the command catalog. Default view is compact (primary + common); pass --all for the full catalog, or --profile <id> (e.g. agent) for the surface a profile sees. Subcommands: primary | advanced | deprecated | hidden | retirement-plan | docs-check | surface | profile | machine | legacy | overlaps | taxonomy | matrix | tree | search | suggest | explain | entrypoints | doctor | ux-check.',
+        usage: 'shrk commands [primary|advanced|deprecated|hidden|retirement-plan|docs-check|surface <s>|profile [<id>]|machine|legacy|overlaps|taxonomy|matrix|tree|search <q>|suggest <p>|explain <cmd>|entrypoints|doctor|ux-check] [--all] [--profile <id>] [--safety <level>] [--category <name>] [--json]',
         async run(args) {
             const sub = args.positional[0];
             if (sub === 'doctor') {
@@ -95,6 +96,12 @@ export function makeCommandsCommand(registry) {
             if (sub === 'surface') {
                 return runCommandsSurface(args);
             }
+            // `shrk commands profile [<id>]` — list surface profiles, or render the
+            // catalog as one profile sees it (the curated view, e.g. `agent`).
+            if (sub === 'profile') {
+                const id = args.positional[1];
+                return id ? runCommandsProfile(args, id) : runCommandsProfileList(args);
+            }
             if (sub === 'machine') {
                 return runCommandsMachine(args);
             }
@@ -120,8 +127,34 @@ export function makeCommandsCommand(registry) {
             if (sub === 'docs-check') {
                 return runCommandsDocsCheck(args);
             }
+            // `--profile <id>` renders the catalog curated for a surface profile
+            // (e.g. `--profile agent` hides CI/release/pack-maintenance machinery an
+            // inline agent doesn't need). Commands stay callable; this is a listing
+            // filter, not a disable.
+            const profileFilter = flagString(args, 'profile');
+            if (profileFilter) {
+                return runCommandsProfile(args, profileFilter);
+            }
             const safetyFilter = flagString(args, 'safety');
             const categoryFilter = flagString(args, 'category');
+            // Validate the filter values against real allowlists — a typo (e.g.
+            // `--safety read` or `--category typo`) previously matched nothing and
+            // returned "commands (0)" with exit 0, which reads like an empty result
+            // rather than a mistake. Reject with the valid set + exit 2 instead.
+            if (safetyFilter !== undefined) {
+                const validSafety = new Set(Object.values(SafetyLevel));
+                if (!validSafety.has(safetyFilter)) {
+                    process.stderr.write(`Unknown --safety "${safetyFilter}". Valid: ${[...validSafety].sort().join(', ')}\n`);
+                    return 2;
+                }
+            }
+            if (categoryFilter !== undefined) {
+                const validCategories = new Set(COMMAND_CATALOG.map((e) => e.category));
+                if (!validCategories.has(categoryFilter)) {
+                    process.stderr.write(`Unknown --category "${categoryFilter}". Valid: ${[...validCategories].sort().join(', ')}\n`);
+                    return 2;
+                }
+            }
             const wantsAll = flagBool(args, 'all');
             let entries = COMMAND_CATALOG;
             if (safetyFilter) {
@@ -186,6 +219,97 @@ function runCommandsSurface(args) {
     }
     return 0;
 }
+/**
+ * Pure: render the catalog as a surface profile sees it. Every command the
+ * profile lists in `hidden` is filtered out of `entries` (commands stay
+ * callable — this is a listing filter, not a disable). Returns undefined when
+ * the profile id is unknown. Exported for tests.
+ */
+export function buildCommandsProfileView(profileId, packProfiles = []) {
+    const profile = getProfile(profileId, packProfiles);
+    if (!profile)
+        return undefined;
+    const hidden = new Set(profile.hidden ?? []);
+    const entries = COMMAND_CATALOG.filter((e) => !hidden.has(e.command));
+    return { profile, entries, hidden: [...hidden].sort(), catalogTotal: COMMAND_CATALOG.length };
+}
+/**
+ * `shrk commands --profile <id>` / `shrk commands profile <id>` renders the
+ * catalog curated for a surface profile (e.g. `agent` hides
+ * CI/release/pack-maintenance machinery an inline agent doesn't need) without
+ * editing `sharkcraft.config.ts`. Builtin profiles resolve instantly; an
+ * unknown id falls back to discovering pack-contributed profiles via the
+ * surface context (best-effort — needs a workspace).
+ */
+async function runCommandsProfile(args, profileId) {
+    let view = buildCommandsProfileView(profileId);
+    let validIds = BUILTIN_PROFILES.map((p) => p.id);
+    if (!view) {
+        try {
+            const { loadSurfaceContext } = await import("../surface/load-surface-context.js");
+            const ctx = await loadSurfaceContext({ cwd: resolveCwd(args) });
+            validIds = ctx.availableProfiles.map((p) => p.id);
+            view = buildCommandsProfileView(profileId, ctx.availableProfiles);
+        }
+        catch {
+            // Pack discovery failed (e.g. outside a project) — builtin-only.
+        }
+    }
+    if (!view) {
+        process.stderr.write(`Unknown profile "${profileId}". Valid: ${[...validIds].sort().join(', ')}\n`);
+        return 2;
+    }
+    const { profile, entries, hidden, catalogTotal } = view;
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson({
+            profile: profile.id,
+            description: profile.description,
+            source: profile.source,
+            total: entries.length,
+            catalogTotal,
+            hiddenCount: hidden.length,
+            hidden,
+            entries,
+        }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Commands — profile=${profile.id} (${entries.length} of ${catalogTotal} visible)`));
+    process.stdout.write(`  ${profile.description}\n`);
+    if (hidden.length > 0) {
+        process.stdout.write(`  (${hidden.length} command(s) hidden by this profile — still callable)\n`);
+    }
+    const grouped = new Map();
+    for (const e of entries) {
+        const arr = grouped.get(e.category) ?? [];
+        arr.push(e);
+        grouped.set(e.category, arr);
+    }
+    for (const [cat, items] of [...grouped.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        process.stdout.write(`\n## ${cat}\n`);
+        for (const e of items.sort((a, b) => a.command.localeCompare(b.command))) {
+            process.stdout.write(`  ${safetyTag(e.safetyLevel)}  ${e.command.padEnd(34)} ${e.description}\n`);
+        }
+    }
+    return 0;
+}
+/** `shrk commands profile` (no id) lists the available surface profiles. */
+function runCommandsProfileList(args) {
+    const rows = BUILTIN_PROFILES.map((p) => ({
+        id: p.id,
+        description: p.description,
+        hides: (p.hidden ?? []).length,
+    }));
+    if (flagBool(args, 'json')) {
+        process.stdout.write(asJson({ total: rows.length, profiles: rows }) + '\n');
+        return 0;
+    }
+    process.stdout.write(header(`Surface profiles (${rows.length})`));
+    for (const r of rows) {
+        process.stdout.write(`  ${r.id.padEnd(12)} hides=${String(r.hides).padEnd(4)} ${r.description}\n`);
+    }
+    process.stdout.write(`\nUsage: shrk commands profile <id>   |   shrk commands --profile <id>   (render the curated view)\n`);
+    return 0;
+}
 /** `shrk commands machine` lists machine-oriented commands. */
 function runCommandsMachine(args) {
     const matches = COMMAND_CATALOG.filter((e) => commandSurface(e) === CommandSurface.Machine || e.machineOnly === true);
@@ -487,6 +611,10 @@ export const commandsCommand = {
         // Keep the new views available even via the back-compat entry.
         if (sub === 'surface')
             return runCommandsSurface(args);
+        if (sub === 'profile') {
+            const id = args.positional[1];
+            return id ? runCommandsProfile(args, id) : runCommandsProfileList(args);
+        }
         if (sub === 'machine')
             return runCommandsMachine(args);
         if (sub === 'legacy')
@@ -503,6 +631,10 @@ export const commandsCommand = {
             return runCommandsRetirementPlan(args);
         if (sub === 'docs-check')
             return await runCommandsDocsCheck(args);
+        const profileFilter = flagString(args, 'profile');
+        if (profileFilter) {
+            return runCommandsProfile(args, profileFilter);
+        }
         const safetyFilter = flagString(args, 'safety');
         const categoryFilter = flagString(args, 'category');
         let entries = COMMAND_CATALOG;
@@ -882,6 +1014,33 @@ export function buildCommandsDoctorReport(registry) {
                 });
             }
         }
+        // 8. registerSubcommand-only GROUPS without a catalog entry.
+        // Check #7 above only sees depth-1 nodes that carry a handler
+        // (registry.list()). Groups registered purely via registerSubcommand
+        // (e.g. paths / pipelines / checks / audit / ownership) are handler-less
+        // group nodes — they resolve live yet never appear in list(), so the
+        // doctor reported "No issues" while those groups had zero catalog
+        // coverage. Walk listGroups() and flag any group no catalog entry
+        // covers. Pure alias groups (listGroupAliases) are skipped — their
+        // canonical target carries the entry.
+        const aliasGroups = new Set(registry.listGroupAliases().keys());
+        const catalogTopWords = new Set();
+        for (const e of COMMAND_CATALOG) {
+            const top = e.command.split(/\s+/)[0];
+            if (top)
+                catalogTopWords.add(top);
+        }
+        for (const g of registry.listGroups()) {
+            if (aliasGroups.has(g))
+                continue;
+            if (!catalogTopWords.has(g)) {
+                issues.push({
+                    code: 'missing-catalog-entry',
+                    message: `command group "${g}" is registered (registerSubcommand) but no catalog entry covers it`,
+                    severity: 'error',
+                });
+            }
+        }
     }
     const errors = issues.filter((i) => i.severity === 'error').length;
     const warnings = issues.filter((i) => i.severity === 'warning').length;

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

@@ -1 +1 @@
-{"version":3,"file":"compress.command.d.ts","sourceRoot":"","sources":["../../src/commands/compress.command.ts"],"names":[],"mappings":"AAQA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgChC,eAAO,MAAM,eAAe,EAAE,eA8F7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,eA4B3B,CAAC"}
+{"version":3,"file":"compress.command.d.ts","sourceRoot":"","sources":["../../src/commands/compress.command.ts"],"names":[],"mappings":"AAQA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAqEhC,eAAO,MAAM,eAAe,EAAE,eAoG7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,eA4B3B,CAAC"}

package/dist/commands/compress.command.js

@@ -5,6 +5,35 @@ import { flagBool, flagNumber, flagString, resolveCwd, } from "../command-regist
 import { asJson } from "../output/format-output.js";
 import { ccrDir, openCcrStore } from "../output/ccr-store-config.js";
 const CONTENT_TYPES = new Set(Object.values(EContentType));
+// `--type` accepts the EContentType wire strings plus ergonomic aliases. `code`
+// is an alias for `source-code`: it routes to the structure-preserving code
+// outline (ECompressionStrategy.Code), NOT the markdown line-omission a bare
+// `code` used to silently fall through to under auto-detect.
+const TYPE_ALIASES = {
+    code: EContentType.SourceCode,
+};
+// The full set of accepted `--type` tokens (content-type wire strings +
+// aliases), sorted and rendered once so the rejection message and the
+// passthrough hint advertise exactly what `resolveContentType` accepts.
+const VALID_TYPE_TOKENS = [...CONTENT_TYPES, ...Object.keys(TYPE_ALIASES)].sort().join(', ');
+/**
+ * Resolve a raw `--type` value into a forced {@link EContentType}. Unlike the
+ * old `CONTENT_TYPES.has` check — which silently dropped unknown values and let
+ * the phantom `code` fall through to auto-detect (markdown line-omission) — an
+ * unrecognized non-empty value yields an `error` so the caller can reject with a
+ * non-zero exit, and `code` is mapped to the real source-code strategy. A
+ * missing/empty value is a no-op (auto-detect).
+ */
+function resolveContentType(raw) {
+    if (raw === undefined || raw === '')
+        return {};
+    const aliased = TYPE_ALIASES[raw];
+    if (aliased)
+        return { type: aliased };
+    if (CONTENT_TYPES.has(raw))
+        return { type: raw };
+    return { error: `compress: unknown --type "${raw}". Valid types: ${VALID_TYPE_TOKENS}.` };
+}
 // Below this size a passthrough no-op isn't worth a warning (tiny snippets
 // legitimately have nothing to compress). Above it, a silent `−0%` re-emit is
 // the opposite of the tool's purpose — nudge the user toward `--type`.
@@ -36,6 +65,13 @@ export const compressCommand = {
     booleanFlags: COMPRESS_BOOLEAN_FLAGS,
     run(args) {
         const cwd = resolveCwd(args);
+        // Validate `--type` up front: an unknown value is a user error, not a
+        // silent fall-through to auto-detect — fail fast before reading input.
+        const resolvedType = resolveContentType(flagString(args, 'type'));
+        if (resolvedType.error) {
+            process.stderr.write(resolvedType.error + '\n');
+            return 1;
+        }
         let content;
         try {
             content = readInput(args);
@@ -59,9 +95,8 @@ export const compressCommand = {
             opts.maxItems = Math.floor(max);
         if (flagBool(args, 'lossless'))
             opts.lossless = true;
-        const type = flagString(args, 'type');
-        if (type && CONTENT_TYPES.has(type))
-            opts.contentType = type;
+        if (resolvedType.type)
+            opts.contentType = resolvedType.type;
         const result = compressContent(content, opts);
         const pct = Math.round(result.savings.ratio * 100);
         // A lossy result with no cached original (i.e. --no-cache) can't be undone
@@ -109,7 +144,7 @@ export const compressCommand = {
             inputBytes >= PASSTHROUGH_HINT_MIN_BYTES &&
             !flagBool(args, 'lossless')) {
             process.stderr.write(`hint: nothing was compressed — auto-detect classified this as ${result.contentType} and found no win. ` +
-                'Try `--type <content-type>` to force a strategy (json, git-diff, search-results, build-log, source-code, markdown).\n');
+                `Try \`--type <content-type>\` to force a strategy (${VALID_TYPE_TOKENS}).\n`);
         }
         return 0;
     },

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

@@ -1 +1 @@
-{"version":3,"file":"constructs.command.d.ts","sourceRoot":"","sources":["../../src/commands/constructs.command.ts"],"names":[],"mappings":"AA8BA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAiGhC,eAAO,MAAM,qBAAqB,EAAE,eAqBnC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAoDlC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAwFpC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAoErC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAmCtC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAwBpC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAiClC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAiBrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAiBrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eA4BrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eA8BrC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA0DpC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA0LpC,CAAC"}
+{"version":3,"file":"constructs.command.d.ts","sourceRoot":"","sources":["../../src/commands/constructs.command.ts"],"names":[],"mappings":"AA8BA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAkHhC,eAAO,MAAM,qBAAqB,EAAE,eAqBnC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAoDlC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAiGpC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eA0ErC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAmCtC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA4BpC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,eAkClC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAiBrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eAkBrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eA4BrC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,eA8BrC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA0DpC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eA0LpC,CAAC"}

package/dist/commands/constructs.command.js

@@ -68,6 +68,20 @@ function enrichTraceWithGraph(declaredFiles, declaredNames, cwd) {
         undeclaredSymbols: [...undeclared].sort(),
     };
 }
+/**
+ * The AUTHORITATIVE file set for a construct: declared globs replaced by their
+ * graph-resolved matches, declared concrete files kept as-is. This is what the
+ * counts, the `files` subverb, and the impact risk heuristic should use — the
+ * declared list under-counts because a single `src/**` glob is one entry that
+ * really covers N files. Falls back to the raw declared list when the graph is
+ * missing, preserving offline/no-index determinism.
+ */
+function effectiveConstructFiles(declaredFiles, graph) {
+    if (graph.graphState !== 'fresh')
+        return [...declaredFiles];
+    const concrete = declaredFiles.filter((f) => !GLOB_MAGIC.test(f));
+    return [...new Set([...concrete, ...graph.resolvedFiles])].sort();
+}
 export const constructsListCommand = {
     name: 'list',
     description: 'List registered constructs.',
@@ -184,14 +198,21 @@ export const constructsTraceCommand = {
                 registryHints: c.tags?.filter((t) => /(registry|barrel)/i.test(t)) ?? [],
             }
             : undefined;
+        const effectiveFiles = effectiveConstructFiles(trace.files, graph);
         if (flagBool(args, 'json')) {
-            process.stdout.write(asJson({ ...trace, graph, ...(deepBlock ? { deep: deepBlock } : {}) }) + '\n');
+            process.stdout.write(asJson({ ...trace, effectiveFiles, graph, ...(deepBlock ? { deep: deepBlock } : {}) }) + '\n');
             return 0;
         }
         process.stdout.write(header(`Trace: ${id}`));
-        process.stdout.write(`Files (${trace.files.length}):\n`);
-        for (const f of trace.files)
+        // Show the graph-resolved file set (globs expanded) as the count, not the
+        // raw declared list — otherwise a single `src/**` glob reads as "1 file".
+        process.stdout.write(`Files (${effectiveFiles.length}):\n`);
+        for (const f of effectiveFiles)
             process.stdout.write(`  • ${f}\n`);
+        const declaredGlobs = trace.files.filter((f) => GLOB_MAGIC.test(f));
+        if (graph.graphState === 'fresh' && declaredGlobs.length > 0) {
+            process.stdout.write(`  (expanded from declared glob(s): ${declaredGlobs.join(', ')})\n`);
+        }
         if (trace.publicApi.length > 0) {
             process.stdout.write(`Public API:\n`);
             for (const a of trace.publicApi)
@@ -271,13 +292,19 @@ export const constructsImpactCommand = {
         const verCfg = inspection.config?.verificationCommands ?? [];
         for (const v of verCfg.slice(0, 3))
             verificationCommands.push(v.command);
-        const fileCount = trace.files.length;
+        // Risk must be computed from the graph-resolved file set: a glob-declared
+        // construct (`src/**`) is one declared entry but really touches N files, so
+        // the old `trace.files.length` under-counted it to risk='low'.
+        const declaredNames = new Set([...trace.publicApi, ...trace.tokens, ...trace.events]);
+        const graph = enrichTraceWithGraph(trace.files, declaredNames, resolveCwd(args));
+        const effectiveFiles = effectiveConstructFiles(trace.files, graph);
+        const fileCount = effectiveFiles.length;
         const risk = fileCount > 12 ? 'high' : fileCount > 4 ? 'medium' : 'low';
         const humanReview = risk !== 'low';
         const report = {
             schema: 'sharkcraft.construct-impact/v1',
             id,
-            files: trace.files,
+            files: effectiveFiles,
             publicApi: trace.publicApi,
             events: trace.events,
             tokens: trace.tokens,
@@ -366,18 +393,22 @@ export const constructsFilesCommand = {
             return 1;
         }
         const trace = traceConstruct(c);
+        // Emit the graph-resolved files (globs expanded), not the raw declared
+        // globs — consumers piping `constructs files` expect real paths.
+        const graph = enrichTraceWithGraph(trace.files, new Set(), resolveCwd(args));
+        const effectiveFiles = effectiveConstructFiles(trace.files, graph);
         if (flagBool(args, 'json')) {
-            process.stdout.write(asJson({ id, files: trace.files }) + '\n');
+            process.stdout.write(asJson({ id, files: effectiveFiles }) + '\n');
             return 0;
         }
-        for (const f of trace.files)
+        for (const f of effectiveFiles)
             process.stdout.write(`${f}\n`);
         return 0;
     },
 };
 export const constructsApiCommand = {
     name: 'api',
-    description: 'Show public-API entries for a construct. --public-only emits the raw list with no header.',
+    description: 'Show the DECLARED public-API entries for a construct (the hand-authored list, not an exhaustive scan — run `shrk constructs trace <id>` for graph-verified symbols defined in the files). --public-only emits the raw list with no header.',
     usage: 'shrk constructs api <id> [--public-only] [--json]',
     async run(args) {
         const id = args.positional[0];
@@ -432,7 +463,7 @@ export const constructsEventsCommand = {
 };
 export const constructsTokensCommand = {
     name: 'tokens',
-    description: 'List tokens contributed by constructs.',
+    description: 'List the DECLARED tokens contributed by constructs (the hand-authored list, not an exhaustive scan).',
     usage: 'shrk constructs tokens [<id>] [--json]',
     async run(args) {
         const id = args.positional[0];

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

@@ -1 +1 @@
-{"version":3,"file":"context.command.d.ts","sourceRoot":"","sources":["../../src/commands/context.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgChC,eAAO,MAAM,cAAc,EAAE,eAyI5B,CAAC"}
+{"version":3,"file":"context.command.d.ts","sourceRoot":"","sources":["../../src/commands/context.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAML,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgChC,eAAO,MAAM,cAAc,EAAE,eA2I5B,CAAC"}

package/dist/commands/context.command.js

@@ -1,4 +1,4 @@
-import { entrypointBanner, inspectSharkcraft } from '@shrkcrft/inspector';
+import { contextTuningBoostFor, entrypointBanner, inspectSharkcraft } from '@shrkcrft/inspector';
 import { buildContext } from '@shrkcrft/context';
 import { loadIntentBenchmark, runIntentBenchmark, STARTER_INTENT_BENCHMARK, writeBenchmarkRun, } from '@shrkcrft/context-planner';
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
@@ -67,6 +67,7 @@ export const contextCommand = {
         const includeCommands = flagBool(args, 'include-commands');
         const inspection = await inspectSharkcraft({ cwd: resolveCwd(args) });
         const overview = buildProjectOverview(inspection.workspace, inspection.config?.projectName);
+        const contextBoost = contextTuningBoostFor(inspection, task);
         const result = buildContext(inspection.knowledgeEntries, {
             task,
             framework,
@@ -81,6 +82,7 @@ export const contextCommand = {
             includeDocs,
             includeCommands,
             projectOverview: renderOverviewText(overview),
+            ...(contextBoost ? { boostFor: contextBoost } : {}),
         });
         // Surface top commands prominently before the long context body.
         // Auto-promote commands-first for action-like tasks (rename / add /

package/dist/commands/daily.commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"daily.commands.d.ts","sourceRoot":"","sources":["../../src/commands/daily.commands.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAMhC,eAAO,MAAM,WAAW,EAAE,eAsFzB,CAAC;AAcF,eAAO,MAAM,WAAW,EAAE,eAoGzB,CAAC;AAKF,eAAO,MAAM,cAAc,EAAE,eA6D5B,CAAC"}
+{"version":3,"file":"daily.commands.d.ts","sourceRoot":"","sources":["../../src/commands/daily.commands.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAMhC,eAAO,MAAM,WAAW,EAAE,eAsFzB,CAAC;AAcF,eAAO,MAAM,WAAW,EAAE,eAoGzB,CAAC;AAKF,eAAO,MAAM,cAAc,EAAE,eAyG5B,CAAC"}

package/dist/commands/daily.commands.js

@@ -186,14 +186,33 @@ export const explainCommand = {
         const top = inspection.knowledgeEntries
             .filter((e) => matches(topic, e.id, e.title, e.content, e.tags.join(' ')))
             .slice(0, maxEntries);
+        // Surface the matched items themselves, not just counts. `explain`
+        // otherwise duplicates `shrk search`'s job while hiding what matched.
+        const relevantRules = packet.relevantRules.map((r) => ({
+            id: r.id,
+            title: r.title,
+            priority: r.priority,
+        }));
+        const relevantPaths = packet.relevantPaths.map((p) => ({
+            id: p.id,
+            title: p.title,
+            priority: p.priority,
+        }));
+        const relevantTemplates = packet.relevantTemplates.map((t) => ({
+            id: t.id,
+            name: t.name,
+        }));
         if (flagBool(args, 'json')) {
             process.stdout.write(asJson({
                 topic,
                 summary: {
-                    relevantRules: packet.relevantRules.length,
-                    relevantPaths: packet.relevantPaths.length,
-                    relevantTemplates: packet.relevantTemplates.length,
+                    relevantRules: relevantRules.length,
+                    relevantPaths: relevantPaths.length,
+                    relevantTemplates: relevantTemplates.length,
                 },
+                relevantRules,
+                relevantPaths,
+                relevantTemplates,
                 entries: top.map((e) => ({
                     id: e.id,
                     title: e.title,
@@ -205,11 +224,35 @@ export const explainCommand = {
             return 0;
         }
         process.stdout.write(header(`explain: ${topic}`));
-        process.stdout.write(kv('matches', `rules=${packet.relevantRules.length} paths=${packet.relevantPaths.length} templates=${packet.relevantTemplates.length}`) + '\n\n');
+        process.stdout.write(kv('matches', `rules=${relevantRules.length} paths=${relevantPaths.length} templates=${relevantTemplates.length}`) + '\n\n');
+        if (relevantRules.length > 0) {
+            process.stdout.write('Rules:\n');
+            for (const r of relevantRules) {
+                process.stdout.write(`  • [${r.priority}] ${r.id} — ${r.title}\n`);
+            }
+            process.stdout.write('\n');
+        }
+        if (relevantPaths.length > 0) {
+            process.stdout.write('Paths:\n');
+            for (const p of relevantPaths) {
+                process.stdout.write(`  • [${p.priority}] ${p.id} — ${p.title}\n`);
+            }
+            process.stdout.write('\n');
+        }
+        if (relevantTemplates.length > 0) {
+            process.stdout.write('Templates:\n');
+            for (const t of relevantTemplates) {
+                process.stdout.write(`  • ${t.id} — ${t.name}\n`);
+            }
+            process.stdout.write('\n');
+        }
         if (top.length === 0) {
-            process.stdout.write('(no matching knowledge entries)\n');
+            if (relevantRules.length + relevantPaths.length + relevantTemplates.length === 0) {
+                process.stdout.write('(no matching knowledge entries)\n');
+            }
             return 0;
         }
+        process.stdout.write('Knowledge:\n');
         for (const e of top) {
             process.stdout.write(`• [${e.priority}] ${e.id} — ${e.title}\n`);
             const body = e.content

package/dist/commands/diff-check.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diff-check.command.d.ts","sourceRoot":"","sources":["../../src/commands/diff-check.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAcH,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA0GhC,eAAO,MAAM,gBAAgB,EAAE,eAiI9B,CAAC"}
+{"version":3,"file":"diff-check.command.d.ts","sourceRoot":"","sources":["../../src/commands/diff-check.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAcH,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AA6GhC,eAAO,MAAM,gBAAgB,EAAE,eAkI9B,CAAC"}

package/dist/commands/diff-check.command.js

@@ -34,9 +34,12 @@ function resolveScope(args, cwd) {
     const staged = flagBool(args, 'staged');
     const since = flagString(args, 'since');
     const filesRaw = flagString(args, 'files');
+    // Files come from `--files a,b` or as bare positional args
+    // (`shrk diff-check a.ts b.ts`). Positionals were previously ignored, which
+    // silently widened the scope back to the full worktree.
     const files = filesRaw
         ? filesRaw.split(',').map((s) => s.trim()).filter((s) => s.length > 0)
-        : [];
+        : args.positional.filter((s) => s.length > 0);
     if (files.length > 0) {
         return { mode: 'files', options: { projectRoot: cwd, files } };
     }
@@ -97,7 +100,8 @@ function deriveVerdict(env) {
 export const diffCheckCommand = {
     name: 'diff-check',
     description: 'Self-check the current git diff against this project\'s boundary + import-hygiene rules. Single-call composite of `shrk check boundaries --changed-only` + `shrk check imports --changed-only`, with one verdict and one nextAction line. Designed for AI agents to run after editing — pass --json for the structured envelope.',
-    usage: 'shrk [--cwd <dir>] diff-check [--staged | --since <ref> | --files a.ts,b.ts] [--json]',
+    usage: 'shrk [--cwd <dir>] diff-check [files... | --files a.ts,b.ts | --staged | --since <ref>] [--json]',
+    booleanFlags: new Set(['json', 'staged']),
     async run(args) {
         const cwd = resolveCwd(args);
         const wantJson = flagBool(args, 'json');

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

@@ -1 +1 @@
-{"version":3,"file":"feedback.command.d.ts","sourceRoot":"","sources":["../../src/commands/feedback.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAgBhC,eAAO,MAAM,qBAAqB,EAAE,eAiCnC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eA0CtC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAyDpC,CAAC;AAEF,eAAO,MAAM,+BAA+B,EAAE,eAwB7C,CAAC;AAIF,eAAO,MAAM,wBAAwB,EAAE,eAqBtC,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eAiDxC,CAAC;AAGF,eAAO,MAAM,sBAAsB,EAAE,eAqBpC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAqBnC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eA6BjC,CAAC"}
+{"version":3,"file":"feedback.command.d.ts","sourceRoot":"","sources":["../../src/commands/feedback.command.ts"],"names":[],"mappings":"AAiBA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAiBhC,eAAO,MAAM,qBAAqB,EAAE,eAiCnC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eA0CtC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,eAyDpC,CAAC;AAEF,eAAO,MAAM,+BAA+B,EAAE,eAwB7C,CAAC;AAIF,eAAO,MAAM,wBAAwB,EAAE,eAqBtC,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,eAoDxC,CAAC;AAGF,eAAO,MAAM,sBAAsB,EAAE,eAqBpC,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,eAqBnC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,eA6BjC,CAAC"}

package/dist/commands/feedback.command.js

@@ -10,6 +10,7 @@ import * as nodePath from 'node:path';
 import { FeedbackBucket, ingestFeedbackFile, inspectSharkcraft, loadFeedbackRules, renderFeedbackBacklog, } from '@shrkcrft/inspector';
 import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson, header } from "../output/format-output.js";
+import { feedbackRulesDoctorHints, renderFailureHints } from "../output/failure-hints.js";
 function ingestPositional(args) {
     return args.positional[0];
 }
@@ -256,6 +257,9 @@ export const feedbackRulesDoctorCommand = {
             process.stdout.write(`  ERROR   ${e.id}: ${e.message}\n`);
         for (const w of warnings)
             process.stdout.write(`  WARN    ${w.id}: ${w.message}\n`);
+        if (errors.length > 0) {
+            process.stdout.write(renderFailureHints(feedbackRulesDoctorHints()));
+        }
         return errors.length > 0 ? 1 : 0;
     },
 };

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

@@ -1 +1 @@
-{"version":3,"file":"framework.command.d.ts","sourceRoot":"","sources":["../../src/commands/framework.command.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,EAAE,eAe9B,CAAC"}
+{"version":3,"file":"framework.command.d.ts","sourceRoot":"","sources":["../../src/commands/framework.command.ts"],"names":[],"mappings":"AAOA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAIhC;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,EAAE,eAe9B,CAAC"}

package/dist/commands/framework.command.js

@@ -1,7 +1,8 @@
 import { buildRegistryWithPacks, defaultRegistry, FrameworkQueryApi, runExtractors, } from '@shrkcrft/framework-scanners';
 import { inspectSharkcraft } from '@shrkcrft/inspector';
-import { flagBool, flagString, resolveCwd, } from "../command-registry.js";
+import { flagBool, flagPositiveInt, flagString, resolveCwd, } from "../command-registry.js";
 import { asJson, header, kv } from "../output/format-output.js";
+import { computeMtimeFreshness } from "../status/freshness.js";
 /**
  * `shrk framework` — run / inspect the framework-aware extractors.
  *
@@ -109,8 +110,20 @@ async function runStatus(args) {
     }
     const api = FrameworkQueryApi.fromStore(cwd);
     const m = api.manifest();
+    // Honest freshness: the framework store is stale once a source file changed
+    // after it was built. Mirror the `state + lastBuiltAt + drift` shape that
+    // `graph status` exposes.
+    const fresh = computeMtimeFreshness(cwd, m.lastBuiltAt);
     if (wantJson) {
-        process.stdout.write(asJson({ ok: true, manifest: m }) + '\n');
+        process.stdout.write(asJson({
+            ok: true,
+            state: fresh.state,
+            lastBuiltAt: m.lastBuiltAt,
+            lastChangedAt: fresh.lastChangedAt,
+            behindMs: fresh.behindMs,
+            ...(fresh.state === 'stale' ? { nextCommand: 'shrk framework index' } : {}),
+            manifest: m,
+        }) + '\n');
         return 0;
     }
     process.stdout.write(header('Framework status'));
@@ -120,6 +133,10 @@ async function runStatus(args) {
         process.stdout.write(kv(`  ${k}`, String(v)) + '\n');
     }
     process.stdout.write(kv('last built', m.lastBuiltAt) + '\n');
+    process.stdout.write(kv('state', fresh.state) + '\n');
+    if (fresh.state === 'stale') {
+        process.stdout.write(`! stale — source changed since last build${fresh.lastChangedAt ? ` (last change ${fresh.lastChangedAt})` : ''}; re-run \`shrk framework index\`\n`);
+    }
     return 0;
 }
 async function runList(args) {
@@ -134,7 +151,7 @@ async function runList(args) {
     const framework = flagString(args, 'framework');
     const subtype = flagString(args, 'subtype');
     const file = flagString(args, 'file');
-    const limit = Number(flagString(args, 'limit') ?? '50');
+    const limit = flagPositiveInt(args, 'limit', 50);
     const entities = api.list({
         ...(framework ? { framework } : {}),
         ...(subtype ? { subtype } : {}),

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

@@ -1 +1 @@
-{"version":3,"file":"gate.command.d.ts","sourceRoot":"","sources":["../../src/commands/gate.command.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,EAAE,eA+FzB,CAAC"}
+{"version":3,"file":"gate.command.d.ts","sourceRoot":"","sources":["../../src/commands/gate.command.ts"],"names":[],"mappings":"AAaA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAGhC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,EAAE,eAiMzB,CAAC"}