@shrkcrft/inspector 0.1.0-alpha.1

package/dist/uncertainty-report.js

@@ -0,0 +1,108 @@
+/**
+ * Shared uncertainty report shape.
+ *
+ * Extends `IUncertaintySummary` with a richer surface: reasons /
+ * missingSignals / conflictingSignals / suggestedCommands /
+ * safeFallbackCommand / whatWouldIncreaseConfidence.
+ *
+ * Pure, deterministic; can be derived from `IUncertaintySummary` or a
+ * fresh task packet.
+ */
+import { buildUncertaintySummary, UncertaintyLevel, } from "./uncertainty.js";
+export const UNCERTAINTY_REPORT_SCHEMA = 'sharkcraft.uncertainty-report/v1';
+function levelToString(level) {
+    if (level === UncertaintyLevel.High)
+        return 'high';
+    if (level === UncertaintyLevel.Medium)
+        return 'medium';
+    return 'low';
+}
+export function uncertaintyReportFromSummary(summary, fallback = 'shrk task "<task>" --commands-first') {
+    const missing = [];
+    const conflicting = [];
+    const reasons = [];
+    for (const s of summary.uncertainty) {
+        if (s.code.startsWith('conflict-')) {
+            conflicting.push({ id: s.code, message: s.message });
+        }
+        else {
+            missing.push({ id: s.code, message: s.message });
+        }
+        reasons.push(s.message);
+    }
+    const increaseConfidence = missing.map((m) => {
+        if (m.id.startsWith('no-template'))
+            return 'Add a matching template (shrk templates list).';
+        if (m.id.startsWith('no-pipeline'))
+            return 'Add a pipeline (sharkcraft/pipelines.ts).';
+        if (m.id.startsWith('no-path-convention'))
+            return 'Add a path convention (shrk paths list).';
+        if (m.id.startsWith('no-validation-command'))
+            return 'Declare verificationCommands on the matched rule.';
+        if (m.id.startsWith('weak-knowledge'))
+            return 'Add knowledge with broader appliesWhen tokens.';
+        if (m.id.startsWith('low-ranker-confidence'))
+            return 'Add search-tuning bias for the task tokens.';
+        return `Resolve "${m.id}".`;
+    });
+    return {
+        schema: UNCERTAINTY_REPORT_SCHEMA,
+        confidence: levelToString(summary.confidence),
+        reasons,
+        missingSignals: missing,
+        conflictingSignals: conflicting,
+        suggestedCommands: summary.suggestedCommands,
+        safeFallbackCommand: fallback,
+        whatWouldIncreaseConfidence: Array.from(new Set(increaseConfidence)),
+    };
+}
+export function buildUncertaintyReportFromPacket(packet) {
+    const summary = buildUncertaintySummary(packet);
+    return uncertaintyReportFromSummary(summary);
+}
+export function buildUncertaintyReport(input) {
+    return {
+        schema: UNCERTAINTY_REPORT_SCHEMA,
+        confidence: input.confidence,
+        reasons: input.reasons ?? [],
+        missingSignals: input.missingSignals ?? [],
+        conflictingSignals: input.conflictingSignals ?? [],
+        suggestedCommands: input.suggestedCommands ?? [],
+        safeFallbackCommand: input.safeFallbackCommand,
+        whatWouldIncreaseConfidence: input.whatWouldIncreaseConfidence ?? [],
+    };
+}
+export function renderUncertaintyReportText(report) {
+    const lines = [];
+    lines.push(`Confidence: ${report.confidence.toUpperCase()}`);
+    if (report.confidence === 'low' || report.confidence === 'unknown') {
+        lines.push('⚠  Low confidence — review carefully before acting on these recommendations.');
+    }
+    if (report.reasons.length > 0) {
+        lines.push('Reasons:');
+        for (const r of report.reasons.slice(0, 6))
+            lines.push(`  • ${r}`);
+    }
+    if (report.missingSignals.length > 0) {
+        lines.push('Missing signals:');
+        for (const m of report.missingSignals.slice(0, 6))
+            lines.push(`  • ${m.id} — ${m.message}`);
+    }
+    if (report.conflictingSignals.length > 0) {
+        lines.push('Conflicting signals:');
+        for (const c of report.conflictingSignals.slice(0, 6))
+            lines.push(`  • ${c.id} — ${c.message}`);
+    }
+    if (report.whatWouldIncreaseConfidence.length > 0) {
+        lines.push('What would increase confidence:');
+        for (const w of report.whatWouldIncreaseConfidence.slice(0, 6))
+            lines.push(`  • ${w}`);
+    }
+    if (report.suggestedCommands.length > 0) {
+        lines.push('Suggested commands:');
+        for (const c of report.suggestedCommands.slice(0, 6))
+            lines.push(`  • ${c}`);
+    }
+    lines.push(`Safe fallback: ${report.safeFallbackCommand}`);
+    return lines.join('\n');
+}

package/dist/uncertainty.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Uncertainty reporting.
+ *
+ * Builds a small `IUncertaintySummary` that `task` / `context` / `brief` /
+ * `contract` / `handoff` can surface so the agent does not miss silently.
+ *
+ * Signals:
+ *  - no template matched
+ *  - no playbook matched
+ *  - no helper matched
+ *  - no path convention matched
+ *  - weak knowledge matches only
+ *  - low ranker confidence
+ *  - missing validation command
+ *  - missing scaffold coverage axis
+ *
+ * Pure, deterministic. Schema: sharkcraft.uncertainty/v1.
+ */
+import type { ITaskPacket } from './task-packet.js';
+export declare const UNCERTAINTY_SCHEMA = "sharkcraft.uncertainty/v1";
+export declare enum UncertaintyLevel {
+    High = "high",
+    Medium = "medium",
+    Low = "low"
+}
+export interface IUncertaintySignal {
+    code: string;
+    message: string;
+}
+export interface IUncertaintySummary {
+    schema: typeof UNCERTAINTY_SCHEMA;
+    confidence: UncertaintyLevel;
+    uncertainty: readonly IUncertaintySignal[];
+    suggestedCommands: readonly string[];
+}
+export declare function buildUncertaintySummary(packet: ITaskPacket): IUncertaintySummary;
+export declare function renderUncertaintyText(summary: IUncertaintySummary): string;
+//# sourceMappingURL=uncertainty.d.ts.map

package/dist/uncertainty.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uncertainty.d.ts","sourceRoot":"","sources":["../src/uncertainty.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAE9D,oBAAY,gBAAgB;IAC1B,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,GAAG,QAAQ;CACZ;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,OAAO,kBAAkB,CAAC;IAClC,UAAU,EAAE,gBAAgB,CAAC;IAC7B,WAAW,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC3C,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAgBD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,WAAW,GAAG,mBAAmB,CAgEhF;AAsBD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAc1E"}

package/dist/uncertainty.js

@@ -0,0 +1,115 @@
+export const UNCERTAINTY_SCHEMA = 'sharkcraft.uncertainty/v1';
+export var UncertaintyLevel;
+(function (UncertaintyLevel) {
+    UncertaintyLevel["High"] = "high";
+    UncertaintyLevel["Medium"] = "medium";
+    UncertaintyLevel["Low"] = "low";
+})(UncertaintyLevel || (UncertaintyLevel = {}));
+function thresholdForTokens(taskTokens) {
+    // Heuristic: weak token-hit thresholds adapt to task length.
+    if (taskTokens >= 6)
+        return { weakScore: 6 };
+    if (taskTokens >= 3)
+        return { weakScore: 4 };
+    return { weakScore: 3 };
+}
+function tokenize(s) {
+    return s
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length >= 3);
+}
+export function buildUncertaintySummary(packet) {
+    const signals = [];
+    const task = packet.task;
+    const taskTokens = tokenize(task);
+    const threshold = thresholdForTokens(taskTokens.length);
+    if (packet.relevantTemplates.length === 0) {
+        signals.push({
+            code: 'no-template-matched',
+            message: `No template matched the task — consider adding one.`,
+        });
+    }
+    if (packet.recommendedPipelines.length === 0) {
+        signals.push({
+            code: 'no-pipeline-matched',
+            message: 'No recommended pipeline.',
+        });
+    }
+    if (packet.relevantPaths.length === 0) {
+        signals.push({
+            code: 'no-path-convention-matched',
+            message: 'No path convention matched.',
+        });
+    }
+    if (packet.verificationCommands.length === 0) {
+        signals.push({
+            code: 'no-validation-command',
+            message: 'No verification commands declared on the matching rules.',
+        });
+    }
+    // Weak knowledge matches when ranker scores cluster under the threshold.
+    const ranking = packet.rankingReasons;
+    if (ranking?.rules && ranking.rules.length > 0) {
+        const top = ranking.rules[0]?.score ?? 0;
+        if (top < threshold.weakScore) {
+            signals.push({
+                code: 'weak-knowledge-matches',
+                message: `Top knowledge match score is ${top} (< threshold ${threshold.weakScore}).`,
+            });
+        }
+    }
+    // Low ranker confidence overall.
+    if (packet.relevantTemplates.length === 0 && packet.relevantPaths.length === 0) {
+        signals.push({
+            code: 'low-ranker-confidence',
+            message: 'Both templates and paths missed — the ranker has low confidence.',
+        });
+    }
+    const confidence = signals.length === 0
+        ? UncertaintyLevel.High
+        : signals.length <= 2
+            ? UncertaintyLevel.Medium
+            : UncertaintyLevel.Low;
+    const suggestedCommands = buildSuggestedCommands(task, signals);
+    return {
+        schema: UNCERTAINTY_SCHEMA,
+        confidence,
+        uncertainty: signals,
+        suggestedCommands,
+    };
+}
+function buildSuggestedCommands(task, signals) {
+    const out = [];
+    if (signals.some((s) => s.code === 'no-template-matched' || s.code === 'no-path-convention-matched')) {
+        out.push(`shrk coverage scaffolds --task "${task}"`);
+    }
+    if (signals.some((s) => s.code === 'weak-knowledge-matches' || s.code === 'low-ranker-confidence')) {
+        out.push(`shrk why-not <id> --for-task "${task}"`);
+        out.push(`shrk search tuning explain "${task}"`);
+        out.push(`shrk search "${task}" --explain`);
+    }
+    if (signals.some((s) => s.code === 'no-validation-command')) {
+        out.push('shrk fix preview --action-hints');
+    }
+    if (out.length === 0)
+        out.push(`shrk brief "${task}"`);
+    return out;
+}
+export function renderUncertaintyText(summary) {
+    const lines = [];
+    lines.push(`Confidence: ${summary.confidence}`);
+    if (summary.uncertainty.length === 0) {
+        lines.push('No uncertainty signals — coverage looks complete.');
+        return lines.join('\n');
+    }
+    lines.push('Uncertainty:');
+    for (const s of summary.uncertainty)
+        lines.push(`  - ${s.message}`);
+    if (summary.suggestedCommands.length > 0) {
+        lines.push('Suggested:');
+        for (const c of summary.suggestedCommands)
+            lines.push(`  $ ${c}`);
+    }
+    return lines.join('\n');
+}

package/dist/universal-search.d.ts

@@ -0,0 +1,64 @@
+import { type IUncertaintyReport } from './uncertainty-report.js';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const UNIVERSAL_SEARCH_SCHEMA = "sharkcraft.universal-search/v2";
+export declare enum SearchResultKind {
+    Command = "command",
+    McpTool = "mcp-tool",
+    Knowledge = "knowledge",
+    Rule = "rule",
+    Path = "path",
+    Convention = "convention",
+    Template = "template",
+    Helper = "helper",
+    Playbook = "playbook",
+    Construct = "construct",
+    Policy = "policy",
+    Decision = "decision",
+    ScaffoldPattern = "scaffold-pattern",
+    ContractTemplate = "contract-template",
+    MigrationProfile = "migration-profile",
+    PluginLifecycleProfile = "plugin-lifecycle-profile",
+    FeedbackRule = "feedback-rule",
+    TaskRoutingHint = "task-routing-hint",
+    Docs = "docs",
+    Report = "report",
+    Action = "action"
+}
+export interface IUniversalSearchHit {
+    readonly kind: SearchResultKind;
+    readonly id: string;
+    readonly title: string;
+    readonly source: 'builtin' | 'local' | 'pack' | 'fixture';
+    readonly packageName?: string;
+    readonly score: number;
+    readonly reasons: readonly string[];
+    readonly snippet?: string;
+    readonly nextCommand?: string;
+}
+export interface IUniversalSearchSections {
+    readonly bestActions: readonly IUniversalSearchHit[];
+    readonly commands: readonly IUniversalSearchHit[];
+    readonly contributions: readonly IUniversalSearchHit[];
+    readonly knowledge: readonly IUniversalSearchHit[];
+    readonly validation: readonly IUniversalSearchHit[];
+}
+export interface IUniversalSearchReport {
+    readonly schema: typeof UNIVERSAL_SEARCH_SCHEMA;
+    readonly generatedAt: string;
+    readonly query: string;
+    readonly sections: IUniversalSearchSections;
+    readonly uncertainty: IUncertaintyReport;
+    readonly whyTheseRanked: readonly string[];
+    readonly nextSuggestions: readonly string[];
+}
+export interface IUniversalSearchOptions {
+    readonly kind?: SearchResultKind;
+    readonly source?: 'builtin' | 'local' | 'pack' | 'fixture';
+    readonly limit?: number;
+    readonly commandsOnly?: boolean;
+    readonly actionsOnly?: boolean;
+}
+export declare function buildUniversalSearch(inspection: ISharkcraftInspection, query: string, options?: IUniversalSearchOptions): Promise<IUniversalSearchReport>;
+export declare function renderUniversalSearchText(report: IUniversalSearchReport): string;
+export declare function renderUniversalSearchMarkdown(report: IUniversalSearchReport): string;
+//# sourceMappingURL=universal-search.d.ts.map

package/dist/universal-search.d.ts.map

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

package/dist/universal-search.js

@@ -0,0 +1,347 @@
+/**
+ * Universal search (v2).
+ *
+ * `shrk search "<query>"` becomes a discovery palette across every
+ * contribution kind the workspace can produce. Output is a 7-section
+ * report — read-only, deterministic.
+ *
+ *   1. Best actions
+ *   2. Exact / strong command matches
+ *   3. Relevant project / pack contributions
+ *   4. Relevant knowledge / docs
+ *   5. Relevant validation commands
+ *   6. Uncertainty / no-match explanation
+ *   7. Why these ranked
+ */
+import { buildPackContributionsInventory } from "./pack-contributions-inventory.js";
+import { listConventions } from "./convention-registry.js";
+import { listPackHelpers } from "./pack-helper-registry.js";
+import { explainTaskRouting } from "./task-routing-hint-registry.js";
+import { listPluginLifecycleProfiles } from "./plugin-lifecycle-profile-registry.js";
+import { uncertaintyReportFromSummary } from "./uncertainty-report.js";
+import { buildUncertaintySummary } from "./uncertainty.js";
+import { buildTaskPacket } from "./task-packet.js";
+export const UNIVERSAL_SEARCH_SCHEMA = 'sharkcraft.universal-search/v2';
+export var SearchResultKind;
+(function (SearchResultKind) {
+    SearchResultKind["Command"] = "command";
+    SearchResultKind["McpTool"] = "mcp-tool";
+    SearchResultKind["Knowledge"] = "knowledge";
+    SearchResultKind["Rule"] = "rule";
+    SearchResultKind["Path"] = "path";
+    SearchResultKind["Convention"] = "convention";
+    SearchResultKind["Template"] = "template";
+    SearchResultKind["Helper"] = "helper";
+    SearchResultKind["Playbook"] = "playbook";
+    SearchResultKind["Construct"] = "construct";
+    SearchResultKind["Policy"] = "policy";
+    SearchResultKind["Decision"] = "decision";
+    SearchResultKind["ScaffoldPattern"] = "scaffold-pattern";
+    SearchResultKind["ContractTemplate"] = "contract-template";
+    SearchResultKind["MigrationProfile"] = "migration-profile";
+    SearchResultKind["PluginLifecycleProfile"] = "plugin-lifecycle-profile";
+    SearchResultKind["FeedbackRule"] = "feedback-rule";
+    SearchResultKind["TaskRoutingHint"] = "task-routing-hint";
+    SearchResultKind["Docs"] = "docs";
+    SearchResultKind["Report"] = "report";
+    SearchResultKind["Action"] = "action";
+})(SearchResultKind || (SearchResultKind = {}));
+function score(text, q) {
+    const reasons = [];
+    let s = 0;
+    const tLower = text.toLowerCase();
+    const qLower = q.toLowerCase();
+    if (tLower === qLower) {
+        s += 20;
+        reasons.push('exact match');
+    }
+    else if (tLower.includes(qLower)) {
+        s += 10;
+        reasons.push('substring match');
+    }
+    const tokens = qLower.split(/[^a-z0-9]+/).filter((x) => x.length >= 3);
+    for (const tok of tokens) {
+        if (tLower.includes(tok)) {
+            s += 3;
+            reasons.push(`token "${tok}"`);
+        }
+    }
+    return { score: s, reasons };
+}
+function makeHit(kind, id, title, source, packageName, raw, nextCommand, snippet) {
+    return {
+        kind,
+        id,
+        title,
+        source,
+        ...(packageName ? { packageName } : {}),
+        score: raw.score,
+        reasons: raw.reasons,
+        ...(snippet ? { snippet } : {}),
+        ...(nextCommand ? { nextCommand } : {}),
+    };
+}
+export async function buildUniversalSearch(inspection, query, options = {}) {
+    const q = query.trim();
+    const limit = options.limit ?? 8;
+    // Pull pieces we'll rank against.
+    const inv = buildPackContributionsInventory(inspection);
+    const conventions = await listConventions(inspection);
+    const helpers = await listPackHelpers(inspection);
+    const routing = await explainTaskRouting(inspection, q);
+    const lifecycle = await listPluginLifecycleProfiles(inspection);
+    const knowledgeEntries = inspection.knowledgeEntries;
+    const allHits = [];
+    // Knowledge
+    for (const k of knowledgeEntries) {
+        const s = score(`${k.id} ${k.title} ${(k.tags ?? []).join(' ')}`, q);
+        if (s.score > 0) {
+            allHits.push(makeHit(SearchResultKind.Knowledge, k.id, k.title, k.source?.loader === 'pack' ? 'pack' : 'local', undefined, s, `shrk knowledge get ${k.id}`, k.summary?.slice(0, 120)));
+        }
+    }
+    // Conventions
+    for (const c of conventions) {
+        const s = score(`${c.convention.id} ${c.convention.title} ${(c.convention.tags ?? []).join(' ')}`, q);
+        if (s.score > 0) {
+            allHits.push(makeHit(SearchResultKind.Convention, c.convention.id, c.convention.title, c.source === 'pack' ? 'pack' : 'local', c.packageName, s, `shrk conventions get ${c.convention.id}`));
+        }
+    }
+    // Pack helpers
+    for (const h of helpers) {
+        const s = score(`${h.helper.id} ${h.helper.title} ${(h.helper.tags ?? []).join(' ')}`, q);
+        if (s.score > 0) {
+            allHits.push(makeHit(SearchResultKind.Helper, h.helper.id, h.helper.title, h.source === 'pack' ? 'pack' : 'local', h.packageName, s, `shrk helper plan ${h.helper.id}`));
+        }
+    }
+    // Plugin lifecycle profiles
+    for (const p of lifecycle) {
+        const s = score(`${p.profile.id} ${p.profile.title} ${(p.profile.tags ?? []).join(' ')}`, q);
+        if (s.score > 0) {
+            allHits.push(makeHit(SearchResultKind.PluginLifecycleProfile, p.profile.id, p.profile.title, p.source === 'pack' ? 'pack' : 'local', p.packageName, s, `shrk plugin lifecycle profile ${p.profile.id}`));
+        }
+    }
+    // Pack contributions (catch-all for kinds we didn't iterate above)
+    for (const e of inv.entries) {
+        if (allHits.find((h) => h.id === e.id && String(h.kind) === e.kind))
+            continue;
+        const s = score(`${e.id} ${e.title ?? ''}`, q);
+        if (s.score > 0) {
+            const kindMap = {
+                knowledge: SearchResultKind.Knowledge,
+                rule: SearchResultKind.Rule,
+                path: SearchResultKind.Path,
+                'path-convention': SearchResultKind.Path,
+                template: SearchResultKind.Template,
+                pipeline: SearchResultKind.Action,
+                playbook: SearchResultKind.Playbook,
+                construct: SearchResultKind.Construct,
+                'scaffold-pattern': SearchResultKind.ScaffoldPattern,
+                policy: SearchResultKind.Policy,
+                decision: SearchResultKind.Decision,
+                'contract-template': SearchResultKind.ContractTemplate,
+                'migration-profile': SearchResultKind.MigrationProfile,
+                'plugin-lifecycle-profile': SearchResultKind.PluginLifecycleProfile,
+                'feedback-rule': SearchResultKind.FeedbackRule,
+                'task-routing-hint': SearchResultKind.TaskRoutingHint,
+                helper: SearchResultKind.Helper,
+                convention: SearchResultKind.Convention,
+                docs: SearchResultKind.Docs,
+            };
+            const kind = kindMap[e.kind] ?? SearchResultKind.Action;
+            allHits.push(makeHit(kind, e.id, e.title ?? e.id, e.source, e.packageName, s, undefined));
+        }
+    }
+    // Routing hints — promote them as "best actions".
+    const routingHits = routing.slice(0, limit).map((m) => ({
+        kind: SearchResultKind.Action,
+        id: m.hint.id,
+        title: m.hint.title,
+        source: m.source === 'pack' ? 'pack' : 'local',
+        ...(m.packageName ? { packageName: m.packageName } : {}),
+        score: m.score,
+        reasons: m.reasons,
+        ...(m.hint.recommends.commands && m.hint.recommends.commands.length > 0
+            ? { nextCommand: m.hint.recommends.commands[0] }
+            : {}),
+    }));
+    // Filter by options.
+    let filtered = allHits;
+    if (options.kind)
+        filtered = filtered.filter((h) => h.kind === options.kind);
+    if (options.source)
+        filtered = filtered.filter((h) => h.source === options.source);
+    filtered.sort((a, b) => b.score - a.score);
+    const sections = {
+        bestActions: routingHits.slice(0, limit),
+        commands: filtered.filter((h) => h.nextCommand && h.kind !== SearchResultKind.Knowledge).slice(0, limit),
+        contributions: filtered
+            .filter((h) => [
+            SearchResultKind.Convention,
+            SearchResultKind.Helper,
+            SearchResultKind.Template,
+            SearchResultKind.Playbook,
+            SearchResultKind.Construct,
+            SearchResultKind.Policy,
+            SearchResultKind.ContractTemplate,
+            SearchResultKind.MigrationProfile,
+            SearchResultKind.PluginLifecycleProfile,
+            SearchResultKind.ScaffoldPattern,
+            SearchResultKind.FeedbackRule,
+            SearchResultKind.TaskRoutingHint,
+            SearchResultKind.Path,
+            SearchResultKind.Rule,
+        ].includes(h.kind))
+            .slice(0, limit),
+        knowledge: filtered.filter((h) => h.kind === SearchResultKind.Knowledge || h.kind === SearchResultKind.Docs).slice(0, limit),
+        validation: filtered
+            .filter((h) => /\bvalidat|doctor|drift|stale|safety|check\b/i.test(h.title))
+            .slice(0, limit),
+    };
+    // Apply commandsOnly / actionsOnly.
+    if (options.commandsOnly) {
+        return {
+            schema: UNIVERSAL_SEARCH_SCHEMA,
+            generatedAt: new Date().toISOString(),
+            query: q,
+            sections: {
+                bestActions: [],
+                commands: sections.commands,
+                contributions: [],
+                knowledge: [],
+                validation: [],
+            },
+            uncertainty: uncertaintyReportFromSummary(buildUncertaintySummary(buildTaskPacket(inspection, q))),
+            whyTheseRanked: [`Filtered to commands-only.`],
+            nextSuggestions: [],
+        };
+    }
+    if (options.actionsOnly) {
+        return {
+            schema: UNIVERSAL_SEARCH_SCHEMA,
+            generatedAt: new Date().toISOString(),
+            query: q,
+            sections: {
+                bestActions: sections.bestActions,
+                commands: [],
+                contributions: [],
+                knowledge: [],
+                validation: [],
+            },
+            uncertainty: uncertaintyReportFromSummary(buildUncertaintySummary(buildTaskPacket(inspection, q))),
+            whyTheseRanked: [`Filtered to actions-only (task routing hints).`],
+            nextSuggestions: [],
+        };
+    }
+    // Uncertainty.
+    const packet = buildTaskPacket(inspection, q);
+    const uncertainty = uncertaintyReportFromSummary(buildUncertaintySummary(packet), `shrk search "${q}"`);
+    const totalHits = sections.bestActions.length +
+        sections.commands.length +
+        sections.contributions.length +
+        sections.knowledge.length +
+        sections.validation.length;
+    const nextSuggestions = [];
+    if (totalHits === 0) {
+        nextSuggestions.push(`shrk coverage scaffolds --task "${q}"`, `shrk feedback ingest <file>`, `shrk why <id> --for-task "${q}"`, `shrk commands suggest "${q}"`);
+    }
+    const whyTheseRanked = [
+        'Scoring: exact match +20, substring +10, token ≥3 chars +3 per match.',
+        'Best actions come from pack/local task routing hints (highest score first).',
+        'Validation section filters titles for `doctor / drift / stale / safety / check`.',
+    ];
+    return {
+        schema: UNIVERSAL_SEARCH_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        query: q,
+        sections,
+        uncertainty,
+        whyTheseRanked,
+        nextSuggestions,
+    };
+}
+export function renderUniversalSearchText(report) {
+    const lines = [];
+    lines.push(`=== shrk search "${report.query}" ===`);
+    lines.push('');
+    const renderSection = (title, hits) => {
+        lines.push(`▶ ${title} (${hits.length})`);
+        if (hits.length === 0) {
+            lines.push('   (none)');
+        }
+        else {
+            for (const h of hits) {
+                const src = h.source === 'pack' ? `pack:${h.packageName ?? '?'}` : h.source;
+                lines.push(`   • [${h.kind}] ${h.id.padEnd(28)} ${h.title}  [${src}] score=${h.score}`);
+                if (h.snippet)
+                    lines.push(`        ${h.snippet}`);
+                if (h.nextCommand)
+                    lines.push(`        → ${h.nextCommand}`);
+            }
+        }
+        lines.push('');
+    };
+    renderSection('Best actions', report.sections.bestActions);
+    renderSection('Exact / strong command matches', report.sections.commands);
+    renderSection('Relevant project / pack contributions', report.sections.contributions);
+    renderSection('Relevant knowledge / docs', report.sections.knowledge);
+    renderSection('Relevant validation commands', report.sections.validation);
+    lines.push('▶ Uncertainty');
+    lines.push(`   confidence: ${report.uncertainty.confidence.toUpperCase()}`);
+    if (report.uncertainty.confidence === 'low' || report.uncertainty.confidence === 'unknown') {
+        lines.push('   ⚠ Low confidence — see "What would increase confidence" below.');
+    }
+    for (const r of report.uncertainty.reasons.slice(0, 4))
+        lines.push(`     • ${r}`);
+    if (report.uncertainty.whatWouldIncreaseConfidence.length > 0) {
+        lines.push('   What would increase confidence:');
+        for (const w of report.uncertainty.whatWouldIncreaseConfidence.slice(0, 4)) {
+            lines.push(`     • ${w}`);
+        }
+    }
+    lines.push(`   safe fallback: ${report.uncertainty.safeFallbackCommand}`);
+    lines.push('');
+    if (report.nextSuggestions.length > 0) {
+        lines.push('▶ No matches — try:');
+        for (const s of report.nextSuggestions)
+            lines.push(`   $ ${s}`);
+        lines.push('');
+    }
+    lines.push('▶ Why these ranked');
+    for (const w of report.whyTheseRanked)
+        lines.push(`   • ${w}`);
+    return lines.join('\n') + '\n';
+}
+export function renderUniversalSearchMarkdown(report) {
+    const lines = [];
+    lines.push(`# Search "${report.query}"`);
+    lines.push('');
+    const renderSection = (title, hits) => {
+        lines.push(`## ${title}`);
+        if (hits.length === 0) {
+            lines.push('(none)');
+        }
+        else {
+            lines.push('| Kind | Id | Title | Source | Score | Next |');
+            lines.push('| --- | --- | --- | --- | --- | --- |');
+            for (const h of hits) {
+                const src = h.source === 'pack' ? `pack:${h.packageName ?? '?'}` : h.source;
+                lines.push(`| \`${h.kind}\` | \`${h.id}\` | ${h.title} | ${src} | ${h.score} | ${h.nextCommand ?? ''} |`);
+            }
+        }
+        lines.push('');
+    };
+    renderSection('Best actions', report.sections.bestActions);
+    renderSection('Exact / strong command matches', report.sections.commands);
+    renderSection('Relevant project / pack contributions', report.sections.contributions);
+    renderSection('Relevant knowledge / docs', report.sections.knowledge);
+    renderSection('Relevant validation commands', report.sections.validation);
+    lines.push(`## Uncertainty`);
+    lines.push(`- confidence: **${report.uncertainty.confidence.toUpperCase()}**`);
+    for (const r of report.uncertainty.reasons.slice(0, 4))
+        lines.push(`- ${r}`);
+    lines.push('');
+    lines.push('## Why these ranked');
+    for (const w of report.whyTheseRanked)
+        lines.push(`- ${w}`);
+    return lines.join('\n') + '\n';
+}