@shrkcrft/inspector 0.1.0-alpha.1

package/dist/doctor-suppressions.js

@@ -0,0 +1,238 @@
+/**
+ * Doctor warning noise control.
+ *
+ * Reads `sharkcraft/doctor.suppressions.json` (and, optionally, a
+ * `doctorSuppressions` field on `sharkcraft.config.ts`) and lets callers
+ * mark specific findings as suppressed.
+ *
+ * Rules:
+ *  - Suppressed findings are counted, not deleted. Renderers know to hide
+ *    them from the headline output but include the count in summary.
+ *  - Expired suppressions surface as a warning so authors notice.
+ *  - Errors are NOT suppressed unless the suppression explicitly marks
+ *    `allowError: true`. The aggregate output also tells the user that
+ *    one or more errors were force-suppressed.
+ *
+ * Schema: sharkcraft.doctor-suppressions/v1
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { DoctorSeverity } from "./doctor-result.js";
+export const DOCTOR_SUPPRESSIONS_SCHEMA = 'sharkcraft.doctor-suppressions/v1';
+/** Default file path for doctor suppressions. */
+export function doctorSuppressionsFile(projectRoot) {
+    return nodePath.join(projectRoot, 'sharkcraft/doctor.suppressions.json');
+}
+export function loadDoctorSuppressions(projectRoot) {
+    const file = doctorSuppressionsFile(projectRoot);
+    if (!existsSync(file)) {
+        return { schema: DOCTOR_SUPPRESSIONS_SCHEMA, doctorSuppressions: [] };
+    }
+    try {
+        const raw = JSON.parse(readFileSync(file, 'utf8'));
+        const entries = Array.isArray(raw.doctorSuppressions) ? raw.doctorSuppressions : [];
+        return {
+            schema: DOCTOR_SUPPRESSIONS_SCHEMA,
+            doctorSuppressions: entries.filter((e) => e && typeof e.reason === 'string'),
+        };
+    }
+    catch {
+        return { schema: DOCTOR_SUPPRESSIONS_SCHEMA, doctorSuppressions: [] };
+    }
+}
+export function saveDoctorSuppressions(projectRoot, config) {
+    const file = doctorSuppressionsFile(projectRoot);
+    const out = {
+        schema: DOCTOR_SUPPRESSIONS_SCHEMA,
+        doctorSuppressions: config.doctorSuppressions,
+    };
+    writeFileSync(file, JSON.stringify(out, null, 2) + '\n', 'utf8');
+    return file;
+}
+/**
+ * Derive a stable id for a finding so the same warning can be suppressed
+ * across runs even when the message text shifts slightly.
+ */
+export function deriveStableId(check) {
+    // The base id is already deterministic in the doctor; we append a short
+    // message hash so duplicate-id rows still get distinct ids.
+    const msg = check.message ?? '';
+    let hash = 0;
+    for (let i = 0; i < msg.length; i++) {
+        hash = (hash * 31 + msg.charCodeAt(i)) | 0;
+    }
+    const slug = Math.abs(hash).toString(36).slice(0, 6);
+    return `${check.id}:${slug}`;
+}
+export function deriveCategory(check) {
+    const id = check.id || '';
+    // Match common prefixes seen in the doctor output.
+    if (id.startsWith('actionhints-') || id.startsWith('action-hint'))
+        return 'action-hint-quality';
+    if (id.startsWith('missing-'))
+        return 'missing-commands-or-mcp';
+    if (id.startsWith('pack:'))
+        return 'pack-doctor';
+    if (id.startsWith('boundary'))
+        return 'boundary';
+    return id.split(/[:.\s]/)[0] ?? 'general';
+}
+function isExpired(entry, now) {
+    if (!entry.expiresAt)
+        return false;
+    try {
+        return new Date(entry.expiresAt).getTime() < now.getTime();
+    }
+    catch {
+        return false;
+    }
+}
+function entryMatches(entry, finding) {
+    if (entry.id && entry.id === finding.stableId)
+        return true;
+    if (entry.id && entry.id === finding.id)
+        return true;
+    if (entry.code && entry.code === finding.id)
+        return true;
+    if (entry.category && entry.category === finding.category)
+        return true;
+    return false;
+}
+function shouldHideByCategory(category, hide) {
+    if (!hide || hide.length === 0)
+        return false;
+    return hide.includes(category);
+}
+function passesFocus(finding, focus) {
+    if (!focus || focus.length === 0 || focus.includes('all'))
+        return true;
+    const sev = finding.severity;
+    if (focus.includes('errors') && sev === DoctorSeverity.Error)
+        return true;
+    if (focus.includes('warnings') && sev === DoctorSeverity.Warning)
+        return true;
+    if (focus.includes('info') && sev === DoctorSeverity.Info)
+        return true;
+    if (focus.includes('ok') && sev === DoctorSeverity.Ok)
+        return true;
+    // "warnings-new" means: warnings that don't match a suppression. Filter
+    // later — at this point we let the row through and the caller will drop
+    // already-suppressed warnings via quietKnown.
+    if (focus.includes('warnings-new') && sev === DoctorSeverity.Warning)
+        return true;
+    return false;
+}
+export function filterDoctorResult(doctor, options = {}) {
+    const now = new Date();
+    const suppressions = options.suppressions ?? [];
+    const expired = [];
+    const liveSuppressions = [];
+    for (const s of suppressions) {
+        if (isExpired(s, now))
+            expired.push(s);
+        else
+            liveSuppressions.push(s);
+    }
+    const annotated = doctor.checks.map((c) => ({
+        ...c,
+        stableId: deriveStableId(c),
+        category: deriveCategory(c),
+    }));
+    const matched = new Map();
+    for (const s of liveSuppressions)
+        matched.set(s, 0);
+    const visible = [];
+    const suppressed = [];
+    for (const finding of annotated) {
+        // 1) hide by category list.
+        if (shouldHideByCategory(finding.category, options.hide)) {
+            suppressed.push(finding);
+            continue;
+        }
+        // 2) suppression entries.
+        const match = liveSuppressions.find((s) => entryMatches(s, finding));
+        if (match) {
+            const isError = finding.severity === DoctorSeverity.Error;
+            if (isError && !match.allowError) {
+                // Cannot suppress an error implicitly — keep it.
+                visible.push(finding);
+                continue;
+            }
+            matched.set(match, (matched.get(match) ?? 0) + 1);
+            suppressed.push(finding);
+            continue;
+        }
+        // 3) focus filter.
+        if (!passesFocus(finding, options.focus)) {
+            suppressed.push(finding);
+            continue;
+        }
+        visible.push(finding);
+    }
+    // 4) quiet-known: drop visible rows that have a matching suppression
+    //    (already moved to suppressed) — already handled. Additionally, when
+    //    quietKnown is set we drop "ok" rows that share a category with a
+    //    suppression so they don't clutter the headline.
+    if (options.quietKnown) {
+        const knownCats = new Set(liveSuppressions.map((s) => s.category).filter(Boolean));
+        for (let i = visible.length - 1; i >= 0; i--) {
+            const v = visible[i];
+            if (v && v.severity === DoctorSeverity.Ok && knownCats.has(v.category)) {
+                visible.splice(i, 1);
+            }
+        }
+    }
+    const summary = {
+        ok: 0,
+        info: 0,
+        warnings: 0,
+        errors: 0,
+        suppressedWarnings: 0,
+        suppressedInfo: 0,
+        suppressedErrors: 0,
+    };
+    for (const v of visible) {
+        if (v.severity === DoctorSeverity.Ok)
+            summary.ok += 1;
+        else if (v.severity === DoctorSeverity.Info)
+            summary.info += 1;
+        else if (v.severity === DoctorSeverity.Warning)
+            summary.warnings += 1;
+        else if (v.severity === DoctorSeverity.Error)
+            summary.errors += 1;
+    }
+    for (const s of suppressed) {
+        if (s.severity === DoctorSeverity.Warning)
+            summary.suppressedWarnings += 1;
+        else if (s.severity === DoctorSeverity.Info)
+            summary.suppressedInfo += 1;
+        else if (s.severity === DoctorSeverity.Error)
+            summary.suppressedErrors += 1;
+    }
+    return {
+        schema: 'sharkcraft.doctor-filtered/v1',
+        passed: summary.errors === 0,
+        checks: visible,
+        suppressedChecks: suppressed,
+        expiredSuppressions: expired,
+        appliedSuppressions: liveSuppressions.map((entry) => ({
+            entry,
+            matched: matched.get(entry) ?? 0,
+        })),
+        summary,
+    };
+}
+export function buildSuppressionEntry(input) {
+    const out = { reason: input.reason };
+    if (input.id)
+        out.id = input.id;
+    if (input.code)
+        out.code = input.code;
+    if (input.category)
+        out.category = input.category;
+    if (input.expiresAt)
+        out.expiresAt = input.expiresAt;
+    if (input.allowError)
+        out.allowError = input.allowError;
+    return out;
+}

package/dist/drift-baseline.d.ts

@@ -0,0 +1,29 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const DRIFT_BASELINE_SCHEMA = "sharkcraft.drift-baseline/v1";
+export interface IDriftBaselineFinding {
+    fingerprint: string;
+    category: string;
+    severity: string;
+    message: string;
+    ruleId?: string;
+    file?: string;
+}
+export interface IDriftBaseline {
+    schema: typeof DRIFT_BASELINE_SCHEMA;
+    createdAt: string;
+    projectRoot: string;
+    findings: readonly IDriftBaselineFinding[];
+}
+export interface IDriftBaselineComparison {
+    schema: 'sharkcraft.drift-baseline-comparison/v1';
+    baselineFile: string;
+    baseline: IDriftBaseline;
+    current: IDriftBaseline;
+    existing: readonly IDriftBaselineFinding[];
+    newFindings: readonly IDriftBaselineFinding[];
+    resolved: readonly IDriftBaselineFinding[];
+}
+export declare function createDriftBaseline(inspection: ISharkcraftInspection, outFile: string): IDriftBaseline;
+export declare function readDriftBaseline(file: string): IDriftBaseline | null;
+export declare function compareDriftBaseline(inspection: ISharkcraftInspection, baselineFile: string): IDriftBaselineComparison | null;
+//# sourceMappingURL=drift-baseline.d.ts.map

package/dist/drift-baseline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift-baseline.d.ts","sourceRoot":"","sources":["../src/drift-baseline.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAGvE,eAAO,MAAM,qBAAqB,iCAAiC,CAAC;AAEpE,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,OAAO,qBAAqB,CAAC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,yCAAyC,CAAC;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,cAAc,CAAC;IACzB,OAAO,EAAE,cAAc,CAAC;IACxB,QAAQ,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC3C,WAAW,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC9C,QAAQ,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAC5C;AA8BD,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,qBAAqB,EACjC,OAAO,EAAE,MAAM,GACd,cAAc,CAYhB;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAOrE;AAED,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,qBAAqB,EACjC,YAAY,EAAE,MAAM,GACnB,wBAAwB,GAAG,IAAI,CAwBjC"}

package/dist/drift-baseline.js

@@ -0,0 +1,80 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { buildDriftReport } from "./drift.js";
+export const DRIFT_BASELINE_SCHEMA = 'sharkcraft.drift-baseline/v1';
+function fingerprint(f) {
+    const ev = (f.evidence ?? {});
+    return [
+        f.category,
+        f.severity,
+        ev.ruleId ?? '',
+        ev.file ?? '',
+        f.message.slice(0, 80),
+    ].join('|');
+}
+function toBaselineFinding(f) {
+    const ev = (f.evidence ?? {});
+    const out = {
+        fingerprint: fingerprint(f),
+        category: f.category,
+        severity: f.severity,
+        message: f.message,
+    };
+    if (ev.ruleId)
+        out.ruleId = ev.ruleId;
+    if (ev.file)
+        out.file = ev.file;
+    return out;
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+export function createDriftBaseline(inspection, outFile) {
+    const drift = buildDriftReport(inspection);
+    const findings = drift.findings.map(toBaselineFinding);
+    const baseline = {
+        schema: DRIFT_BASELINE_SCHEMA,
+        createdAt: nowIso(),
+        projectRoot: inspection.projectRoot,
+        findings,
+    };
+    mkdirSync(nodePath.dirname(outFile), { recursive: true });
+    writeFileSync(outFile, JSON.stringify(baseline, null, 2) + '\n', 'utf8');
+    return baseline;
+}
+export function readDriftBaseline(file) {
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function compareDriftBaseline(inspection, baselineFile) {
+    const baseline = readDriftBaseline(baselineFile);
+    if (!baseline)
+        return null;
+    const drift = buildDriftReport(inspection);
+    const currentList = drift.findings.map(toBaselineFinding);
+    const baselineSet = new Set(baseline.findings.map((f) => f.fingerprint));
+    const currentSet = new Set(currentList.map((f) => f.fingerprint));
+    const existing = currentList.filter((f) => baselineSet.has(f.fingerprint));
+    const newFindings = currentList.filter((f) => !baselineSet.has(f.fingerprint));
+    const resolved = baseline.findings.filter((f) => !currentSet.has(f.fingerprint));
+    return {
+        schema: 'sharkcraft.drift-baseline-comparison/v1',
+        baselineFile,
+        baseline,
+        current: {
+            schema: DRIFT_BASELINE_SCHEMA,
+            createdAt: nowIso(),
+            projectRoot: inspection.projectRoot,
+            findings: currentList,
+        },
+        existing,
+        newFindings,
+        resolved,
+    };
+}

package/dist/drift.d.ts

@@ -0,0 +1,38 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export type DriftSeverity = 'error' | 'warning' | 'info';
+export type DriftCategory = 'boundary' | 'preset-reference' | 'preset-composition' | 'missing-pack-asset' | 'config-mismatch' | 'template-relationship' | 'pipeline-template-link';
+export interface IDriftFinding {
+    category: DriftCategory;
+    severity: DriftSeverity;
+    message: string;
+    evidence?: Record<string, unknown>;
+    suggestedFix?: string;
+    related?: {
+        kind: 'rule' | 'template' | 'path' | 'pipeline' | 'preset' | 'pack';
+        id: string;
+    }[];
+}
+export interface IDriftReport {
+    findings: IDriftFinding[];
+    counts: {
+        error: number;
+        warning: number;
+        info: number;
+    };
+}
+export interface IBuildDriftOptions {
+    /** When true, run the full boundary scan (slow on large repos). Default: true. */
+    runBoundaries?: boolean;
+}
+/**
+ * First-cut drift report. Combines:
+ *  - Boundary violations (when boundary rules are present).
+ *  - Preset reference resolution (missing pack assets).
+ *  - Preset composition issues.
+ *  - Pipeline → template references that don't resolve.
+ *
+ * Pure orchestration over existing services. Returns warnings by default;
+ * elevates clear architecture problems to errors.
+ */
+export declare function buildDriftReport(inspection: ISharkcraftInspection, options?: IBuildDriftOptions): IDriftReport;
+//# sourceMappingURL=drift.d.ts.map

package/dist/drift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift.d.ts","sourceRoot":"","sources":["../src/drift.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAGvE,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AACzD,MAAM,MAAM,aAAa,GACrB,UAAU,GACV,kBAAkB,GAClB,oBAAoB,GACpB,oBAAoB,GACpB,iBAAiB,GACjB,uBAAuB,GACvB,wBAAwB,CAAC;AAE7B,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,aAAa,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACjG;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1D;AAED,MAAM,WAAW,kBAAkB;IACjC,kFAAkF;IAClF,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,qBAAqB,EACjC,OAAO,GAAE,kBAAuB,GAC/B,YAAY,CAuGd"}

package/dist/drift.js

@@ -0,0 +1,107 @@
+import { evaluateBoundaries, loadTsconfigPaths, scanImports } from '@shrkcrft/boundaries';
+import { resolvePreset, resolvePresetReferences } from '@shrkcrft/presets';
+import { inspectionReferenceLookup } from "./reference-lookup.js";
+/**
+ * First-cut drift report. Combines:
+ *  - Boundary violations (when boundary rules are present).
+ *  - Preset reference resolution (missing pack assets).
+ *  - Preset composition issues.
+ *  - Pipeline → template references that don't resolve.
+ *
+ * Pure orchestration over existing services. Returns warnings by default;
+ * elevates clear architecture problems to errors.
+ */
+export function buildDriftReport(inspection, options = {}) {
+    const findings = [];
+    // 1. Boundary violations.
+    if ((options.runBoundaries ?? true) && inspection.boundaryRegistry.size() > 0) {
+        const scan = scanImports({ projectRoot: inspection.projectRoot });
+        const tsconfigPaths = loadTsconfigPaths(inspection.projectRoot);
+        const evalResult = evaluateBoundaries(scan, inspection.boundaryRegistry.list(), {
+            ...(tsconfigPaths.aliases.size > 0 ? { tsconfigPaths } : {}),
+        });
+        for (const v of evalResult.violations) {
+            findings.push({
+                category: 'boundary',
+                severity: v.severity,
+                message: v.message,
+                evidence: {
+                    ruleId: v.ruleId,
+                    file: v.file,
+                    line: v.line,
+                    importSpecifier: v.importSpecifier,
+                },
+                suggestedFix: v.suggestedFix,
+            });
+        }
+    }
+    // 2. Preset reference resolution + composition issues.
+    const refLookup = inspectionReferenceLookup(inspection);
+    for (const preset of inspection.presetRegistry.list()) {
+        const resolved = resolvePreset(inspection.presetRegistry, preset.id);
+        for (const issue of resolved.issues) {
+            findings.push({
+                category: 'preset-composition',
+                severity: 'error',
+                message: `Preset "${preset.id}": ${issue.message}`,
+                evidence: { presetId: preset.id, code: issue.code },
+            });
+        }
+        const refs = resolvePresetReferences(resolved, refLookup);
+        for (const missing of refs.missing) {
+            findings.push({
+                category: 'preset-reference',
+                severity: 'warning',
+                message: `Preset "${preset.id}" references missing ${missing.kind} id "${missing.id}".`,
+                evidence: { presetId: preset.id, ...missing },
+                suggestedFix: 'Install the pack that provides this asset, or add the asset locally.',
+            });
+        }
+    }
+    // 3. Pipeline step references to templates that don't exist.
+    for (const pipeline of inspection.pipelines) {
+        for (const step of pipeline.steps ?? []) {
+            for (const ref of step.references ?? []) {
+                if (!inspection.templates.some((t) => t.id === ref) &&
+                    !inspection.knowledgeEntries.some((e) => e.id === ref)) {
+                    findings.push({
+                        category: 'pipeline-template-link',
+                        severity: 'warning',
+                        message: `Pipeline "${pipeline.id}" step "${step.id}" references unknown id "${ref}".`,
+                        evidence: { pipelineId: pipeline.id, stepId: step.id, ref },
+                    });
+                }
+            }
+        }
+    }
+    // 4. Templates that declare related ids that don't resolve (action hints).
+    for (const entry of inspection.knowledgeEntries) {
+        const ah = entry.actionHints;
+        if (!ah)
+            continue;
+        for (const id of ah.relatedTemplates ?? []) {
+            if (!inspection.templates.some((t) => t.id === id)) {
+                findings.push({
+                    category: 'template-relationship',
+                    severity: 'info',
+                    message: `Entry "${entry.id}" hints relatedTemplate "${id}" but no template with that id is registered.`,
+                    evidence: { entryId: entry.id, templateId: id },
+                });
+            }
+        }
+        for (const id of ah.relatedPathConventions ?? []) {
+            if (!inspection.knowledgeEntries.some((e) => e.id === id && String(e.type) === 'path')) {
+                findings.push({
+                    category: 'template-relationship',
+                    severity: 'info',
+                    message: `Entry "${entry.id}" hints relatedPathConvention "${id}" but no path convention with that id is registered.`,
+                    evidence: { entryId: entry.id, pathId: id },
+                });
+            }
+        }
+    }
+    const counts = { error: 0, warning: 0, info: 0 };
+    for (const f of findings)
+        counts[f.severity] += 1;
+    return { findings, counts };
+}

package/dist/entrypoint-matrix.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Entrypoint matrix.
+ *
+ * Classifies SharkCraft's many "get me context" / "what should I do?" surfaces
+ * into four discrete entrypoint classes:
+ *
+ *   - human-interactive    — shells / TTY use; primary first answer.
+ *   - agent-mcp            — what an AI coding agent should call first.
+ *   - machine-json         — non-human, machine-consumable JSON packets.
+ *   - debug-explainability — ranker / boundary / search debugging.
+ *
+ * This is pure curated data. The CLI exposes it via `shrk commands matrix`,
+ * and individual commands (`shrk task`, `shrk context`, `shrk recommend`)
+ * include a one-line banner referencing this matrix so the operator sees
+ * which class they reached.
+ */
+export declare const ENTRYPOINT_MATRIX_SCHEMA = "sharkcraft.entrypoint-matrix/v1";
+export declare enum EntrypointClass {
+    HumanInteractive = "human-interactive",
+    AgentMcp = "agent-mcp",
+    MachineJson = "machine-json",
+    DebugExplainability = "debug-explainability"
+}
+export interface IEntrypointMatrixEntry {
+    readonly id: string;
+    readonly class: EntrypointClass;
+    readonly callShape: string;
+    readonly whenToUse: string;
+    readonly safety: 'read-only' | 'writes-drafts' | 'writes-source';
+    readonly docs?: string;
+    /** Identifier of an alternative entrypoint to consider, when relevant. */
+    readonly seeAlso?: ReadonlyArray<string>;
+}
+export interface IEntrypointMatrixReport {
+    readonly schema: typeof ENTRYPOINT_MATRIX_SCHEMA;
+    readonly entries: ReadonlyArray<IEntrypointMatrixEntry>;
+    /**
+     * Curated decision-tree the renderer leans on:
+     *   "If you are a … use …"
+     */
+    readonly decisionTree: ReadonlyArray<{
+        readonly when: string;
+        readonly use: string;
+    }>;
+}
+export declare function buildEntrypointMatrix(): IEntrypointMatrixReport;
+export declare function renderEntrypointMatrixText(report: IEntrypointMatrixReport): string;
+/**
+ * Short banner each command can print to make its role explicit.
+ * Wording aligned with the canonical-entrypoint message so every
+ * overlapping surface points back at `shrk recommend` for the
+ * "what should I do?" question.
+ *
+ *   shrk recommend  — canonical human entrypoint.
+ *   shrk context    — context for doing the task; recommend is the workflow.
+ *   shrk task       — machine/task-packet surface; recommend is the workflow.
+ *   shrk search     — registry search; recommend is the workflow.
+ *   shrk why        — ranker reasoning; recommend is the workflow.
+ */
+export declare function entrypointBanner(id: 'task' | 'context' | 'recommend' | 'search' | 'why' | 'task-json'): string;
+//# sourceMappingURL=entrypoint-matrix.d.ts.map

package/dist/entrypoint-matrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entrypoint-matrix.d.ts","sourceRoot":"","sources":["../src/entrypoint-matrix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,wBAAwB,oCAAoC,CAAC;AAE1E,oBAAY,eAAe;IACzB,gBAAgB,sBAAsB;IACtC,QAAQ,cAAc;IACtB,WAAW,iBAAiB;IAC5B,mBAAmB,yBAAyB;CAC7C;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,eAAe,GAAG,eAAe,CAAC;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,OAAO,wBAAwB,CAAC;IACjD,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAC;IACxD;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC;QACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;CACJ;AAoJD,wBAAgB,qBAAqB,IAAI,uBAAuB,CAM/D;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,uBAAuB,GAAG,MAAM,CA2BlF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,KAAK,GAAG,WAAW,GACpE,MAAM,CAeR"}