llmnav 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -6,6 +6,12 @@ The npm package follows Semantic Versioning. The `llmnav/N` source protocol is v
 
 ## [Unreleased]
 
+## [0.9.0] — 2026-08-15
+
+### Added
+
+* Added `llmnav explain <file>` and `explainProjectFile` to report one file's navigation cards, module coverage, audit score evidence, reviewed disposition, and bounded next action without modifying source.
+
 ## [0.8.0] — 2026-08-15
 
 ### Added

package/README.md

@@ -47,7 +47,7 @@ npx llmnav init --agents all --package-scripts
 
 Initialization is explicit. LLMNav never edits a consumer repository from an npm `postinstall` script. Use `--agents none` when only the machine-readable control directory is desired.
 
-Before writing cards, run `npx llmnav audit`. It ranks likely architectural boundaries and explains each score. The command never edits source and remains advisory unless `--fail-on high`, `medium`, or `low` is selected. Review the candidates: a high score is evidence to inspect a file, not permission to generate semantic meaning automatically. For a reviewed false positive or implementation detail, add its exact path and a concrete reason to `audit.dispositions`; stale decisions remain visible instead of becoming permanent hidden ignores.
+Before writing cards, run `npx llmnav audit`. It ranks likely architectural boundaries and explains each score. Use `npx llmnav explain <file>` when you need to know why one file is carded, covered by another module card, ranked as a candidate, suppressed by a reviewed disposition, or omitted from the candidate list. Neither command edits source. Review the evidence: a high score is a reason to inspect a file, not permission to generate semantic meaning automatically. For a reviewed false positive or implementation detail, add its exact path and a concrete reason to `audit.dispositions`; stale decisions remain visible instead of becoming permanent hidden ignores.
 
 ## Add the first card
 
@@ -172,6 +172,7 @@ Line-comment cards require an explicit terminator and work with `//`, `#`, and `
 | --- | --- |
 | `llmnav init` | Create configuration, registry, schemas, agent instructions, and the initial cache |
 | `llmnav audit` | Rank unannotated architectural boundary candidates, with compact or file-backed output |
+| `llmnav explain` | Explain one file's card coverage, audit score, disposition, and recommended next action |
 | `llmnav check` | Validate cards, relations, coverage rules, and registry state |
 | `llmnav format` | Rewrite safe cards into canonical order and spacing |
 | `llmnav generate` | Incrementally compile and transactionally commit generated artifacts |

package/docs/agent-integration.md

@@ -49,7 +49,7 @@ The generated instruction tells an agent to:
 10. Run format, check, and generation after semantic changes.
 11. Fall back to broad search when no credible card is returned.
 
-When a host supports structured tool calls, `llmnav tools --json` returns four stable provider-neutral definitions in fixed order: `llmnav_query`, `llmnav_show`, `llmnav_context`, and `llmnav_check`. The schemas reject unknown fields and omit the repository root so the trusted host binds scope outside model-generated input.
+When a host supports structured tool calls, `llmnav tools --json` returns five stable provider-neutral definitions in fixed order: `llmnav_query`, `llmnav_show`, `llmnav_context`, `llmnav_check`, and `llmnav_explain`. The new definition is appended so the existing stable tool prefix keeps its order. The schemas reject unknown fields and omit the repository root so the trusted host binds scope outside model-generated input.
 
 The protocol does not order an agent to trust a card over source code. It uses the card to choose what source to inspect.
 
@@ -99,7 +99,7 @@ Suggested contract:
 ```json
 {
   "schemaVersion": 1,
-  "operations": ["llmnav_query", "llmnav_show", "llmnav_context", "llmnav_check"]
+  "operations": ["llmnav_query", "llmnav_show", "llmnav_context", "llmnav_check", "llmnav_explain"]
 }
 ```
 

package/docs/api.md

@@ -65,7 +65,7 @@ Attached symbol declarations expose generated `language`, `exported`, `visibilit
 ## Audit annotation coverage
 
 ```js
-import { auditHasFindings, auditProject } from "llmnav";
+import { auditHasFindings, auditProject, explainProjectFile } from "llmnav";
 
 const result = await auditProject(process.cwd());
 for (const candidate of result.candidates) {
@@ -73,9 +73,12 @@ for (const candidate of result.candidates) {
 }
 
 if (auditHasFindings(result, "high")) process.exitCode = 1;
+
+const explanation = await explainProjectFile(process.cwd(), "src/runtime.ts");
+console.log(explanation.status, explanation.candidate?.score, explanation.recommendation.action);
 ```
 
-`auditProject` is read-only and returns schemaVersion 1 data with repository-relative paths and deterministic ordering. Candidate signals are structural heuristics, not generated semantic meaning. Exact reviewed decisions from `audit.dispositions` are returned separately with `suppressed` or `stale` status; `auditHasFindings` considers only active candidates. Consumers should review high and medium candidates before adding a card and should never turn the suggested coverage rule into automatic source annotation.
+`auditProject` is read-only and returns schemaVersion 1 data with repository-relative paths and deterministic ordering. Candidate signals are structural heuristics, not generated semantic meaning. Exact reviewed decisions from `audit.dispositions` are returned separately with `suppressed` or `stale` status; `auditHasFindings` considers only active candidates. `explainProjectFile` applies the same analysis to one path, preserving candidate score evidence and package-level coverage without mutating source. Consumers should review high and medium candidates before adding a card and should never turn a suggested coverage rule or recommendation into automatic source annotation.
 
 ## Generate incrementally and transactionally
 

package/docs/cli.md

@@ -41,6 +41,16 @@ The command never modifies source, configuration, registries, or generated cache
 
 JSON output uses schemaVersion 1, repository-relative paths, deterministic ordering, explainable `reasons` and `signals`, and a path-specific `suggestedCoverageRule` for high and medium candidates. Reviewed `audit.dispositions` appear separately as `suppressed` or `stale`; only active candidates participate in `--fail-on`. Stale reasons are `file-not-scanned`, `already-carded`, or `not-a-candidate`. `--summary` omits candidate and disposition details but retains their counters. `--output <path>` writes the selected report inside the repository and emits only a compact confirmation envelope to stdout; escaping paths and symbolic-link traversal are rejected. Suggestions require human or agent review: LLMNav cannot infer a durable role, ownership boundary, invariant, or semantic ID from structure alone.
 
+## `llmnav explain`
+
+```sh
+llmnav explain <file> [--json]
+```
+
+Explains one repository-relative or repository-contained absolute file path without modifying the repository. The result distinguishes active candidates, reviewed suppressions, direct cards, package-level module coverage, files with no ranked audit signal, files excluded from the scanned source set, and stale dispositions. Candidate results retain the audit's representative path, priority, score, reasons, signals, and suggested coverage rule; this matters for Go packages, where the requested file and representative candidate can differ.
+
+The recommendation is deliberately bounded. It may ask for card review, disposition review, stale-disposition cleanup, or no action, but it never invents a semantic ID or writes a source comment. A file outside the repository or an invalid positional argument exits with status 2. A valid path that is not in the scanned source set returns its explanation and exits with status 1.
+
 ## `llmnav check`
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llmnav",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "A deterministic semantic navigation layer for LLM coding agents.",
   "type": "module",
   "bin": {

package/src/agent-protocol.js

@@ -6,6 +6,7 @@ excludes=provider SDK transport|repository discovery|source mutation
 search=agent tool schema|provider neutral tools|tool dispatcher|agent operation protocol
 rel=workflow>llmnav.search.query
 rel=workflow>llmnav.rules.validate
+rel=workflow>llmnav.audit.coverage
 stability=contract
 */
 
@@ -14,6 +15,7 @@ import { scanProject } from "./project.js";
 import { buildContext, queryProject, showProjectCard } from "./search.js";
 import { countDiagnostics, validateProject } from "./validator.js";
 import { getAgentToolDefinitions } from "./agent-tools.js";
+import { explainProjectFile } from "./audit.js";
 
 export { AGENT_TOOL_SCHEMA_VERSION, getAgentToolDefinitions } from "./agent-tools.js";
 export const AGENT_OPERATION_SCHEMA_VERSION = 1;
@@ -25,6 +27,7 @@ const OPERATIONS = new Map([
   ["llmnav_show", "show"],
   ["llmnav_context", "context"],
   ["llmnav_check", "check"],
+  ["llmnav_explain", "explain"],
 ]);
 
 export async function executeAgentOperation(root, name, input = {}, options = {}) {
@@ -58,6 +61,9 @@ export async function executeAgentOperation(root, name, input = {}, options = {}
         ? options.session.context(input.id.trim(), contextOptions)
         : await buildContext(root, input.id.trim(), contextOptions));
     }
+    if (operation === "explain") {
+      return success(operation, await explainProjectFile(root, input.file.trim()));
+    }
     const project = await scanProject(root, { paths: input.paths ?? [] });
     const graphInputs = await loadGraphInputs(root, project.config);
     const diagnostics = [...validateProject(project), ...graphInputs.diagnostics].sort(compareDiagnostics);

package/src/agent-tools.js

@@ -32,6 +32,9 @@ const DEFINITIONS = [
       default: [],
     },
   }),
+  tool("llmnav_explain", "Explain one file's card coverage, audit evidence, disposition, and recommended next action.", {
+    file: stringProperty("Repository-relative or repository-contained absolute file path."),
+  }, ["file"]),
 ];
 
 export function getAgentToolDefinitions() {

package/src/agents.js

@@ -32,6 +32,8 @@ Do not add hand-maintained \`calls\`, \`imports\`, \`references\`, \`implements\
 
 After initialization and whenever public entrypoints, commands, routes, schemas, migrations, or high fan-in modules change, run \`npm exec -- llmnav audit\`. Review high and medium candidates; never add cards automatically. Add a module card only after confirming a durable responsibility, then encode the accepted boundary in a path-specific \`coverageRules\` entry and add a representative retrieval query. When a reviewed candidate has no durable navigation responsibility, record its exact path and a concrete reason in \`audit.dispositions\`; never use a glob or broad directory suppression.
 
+When deciding whether one specific file needs a card, run \`npm exec -- llmnav explain <file>\`. Use its coverage, score, and disposition evidence to guide review, but never turn its recommendation into automatic source annotation.
+
 After semantic changes, run \`npm exec -- llmnav format\`, \`npm exec -- llmnav check\`, and \`npm exec -- llmnav generate\`. Use broad text search only when LLMNav returns no credible candidate.
 ${END}`;
 

package/src/audit.js

@@ -1,9 +1,9 @@
 /* llmnav/1 module
 id=llmnav.audit.coverage
 role=Identify high-value source modules that lack semantic navigation boundaries without modifying source.
-owns=annotation coverage audit|candidate prioritization|coverage rule suggestions
+owns=annotation coverage audit|candidate prioritization|file explanation|coverage rule suggestions
 excludes=automatic source annotation|semantic role generation
-search=llmnav audit|missing module cards|coverage suggestions
+search=llmnav audit|missing module cards|explain missing annotation|coverage suggestions
 invariant=Audit output is deterministic, repository-relative, and advisory unless an explicit fail threshold is selected.
 rel=workflow>llmnav.project.scan
 stability=contract
@@ -17,6 +17,7 @@ import { compareText, readJsonSafe, toPosix } from "./util.js";
 
 export const AUDIT_SCHEMA_VERSION = 1;
 export const AUDIT_PRIORITIES = Object.freeze(["high", "medium", "low"]);
+export const FILE_EXPLANATION_SCHEMA_VERSION = 1;
 
 const SOURCE_EXTENSIONS = Object.freeze([
   ".astro", ".c", ".cc", ".cjs", ".cpp", ".cs", ".cts", ".dart", ".go", ".h", ".hpp", ".java",
@@ -28,6 +29,65 @@ const NON_PRODUCTION_PATH_PATTERN = /(?:^|\/)(?:__tests__|benchmarks?|fixtures?|
 const LARGE_SOURCE_BYTES = 12_000;
 
 export async function auditProject(root) {
+  return (await analyzeAuditProject(root)).result;
+}
+
+export async function explainProjectFile(root, inputPath) {
+  const file = normalizeExplanationPath(root, inputPath);
+  const analysis = await analyzeAuditProject(root);
+  const { project, fileByPath, candidates, result } = analysis;
+  const moduleKey = fileByPath.has(file) ? moduleKeyForFile(file) : null;
+  const navigationCards = project.records
+    .filter((record) => toPosix(record.relativePath) === file)
+    .map((record) => ({ id: record.card.id, scope: record.card.scope, path: file }))
+    .sort((left, right) => compareText(left.id, right.id));
+  const coverageCards = moduleKey === null ? [] : project.records
+    .filter((record) => {
+      const cardPath = toPosix(record.relativePath);
+      if (record.card.scope === "file") return cardPath === file;
+      return record.card.scope === "module" && moduleKeyForFile(cardPath) === moduleKey;
+    })
+    .map((record) => ({ id: record.card.id, scope: record.card.scope, path: toPosix(record.relativePath) }))
+    .sort((left, right) => compareText(left.id, right.id));
+  const candidate = moduleKey === null ? null : candidates.find((item) => moduleKeyForFile(item.path) === moduleKey) ?? null;
+  const dispositionPath = candidate?.path ?? file;
+  const disposition = result.dispositions.find((item) => item.path === dispositionPath) ??
+    result.dispositions.find((item) => item.path === file) ?? null;
+
+  if (disposition?.status === "stale") {
+    return buildFileExplanation(result.repositoryId, file, moduleKey, "stale-disposition", navigationCards, coverageCards, candidate, disposition, [
+      `stale-disposition:${disposition.staleReason}`,
+    ], "remove-or-review-disposition", "Remove or update the stale exact-path disposition after reviewing the current file state.");
+  }
+  if (!fileByPath.has(file)) {
+    return buildFileExplanation(result.repositoryId, file, null, "not-scanned", [], [], null, disposition, ["file-not-scanned"],
+      "check-scan-configuration", "Check that the file exists under a source root and is not excluded by extension, directory, or file rules.");
+  }
+  if (coverageCards.length > 0) {
+    const status = coverageCards.some((card) => card.path === file) ? "carded" : "covered";
+    return buildFileExplanation(result.repositoryId, file, moduleKey, status, navigationCards, coverageCards, null, disposition,
+      [status === "carded" ? "file-has-coverage-card" : "module-covered-by-card"],
+      "keep-current-coverage", "No additional file or module card is needed unless this file gains a separate durable responsibility.");
+  }
+  if (candidate && disposition?.status === "suppressed") {
+    return buildFileExplanation(result.repositoryId, file, moduleKey, "suppressed", navigationCards, coverageCards, candidate, disposition,
+      ["reviewed-exact-path-disposition", ...candidate.reasons], "keep-or-review-disposition",
+      "Keep the disposition while its reason remains true; remove it if the file gains a durable navigation responsibility.");
+  }
+  if (candidate) {
+    const action = candidate.priority === "low" ? "review-or-disposition" : "review-card";
+    const message = candidate.priority === "low"
+      ? "Review the low-priority signal, but do not add a card unless the file owns a durable navigation responsibility."
+      : "Review the candidate and either add one durable card with exact coverage or record an exact-path disposition with a concrete reason.";
+    return buildFileExplanation(result.repositoryId, file, moduleKey, "candidate", navigationCards, coverageCards, candidate, null,
+      candidate.reasons, action, message);
+  }
+  const reasons = /\.d\.[cm]?ts$/u.test(file) ? ["declaration-file"] : ["no-ranked-audit-signal"];
+  return buildFileExplanation(result.repositoryId, file, moduleKey, "not-candidate", navigationCards, coverageCards, null, disposition, reasons,
+    "no-card-needed", "Do not add a card solely for coverage; revisit only if the file gains a durable responsibility or stronger structural signals.");
+}
+
+async function analyzeAuditProject(root) {
   const project = await scanProject(root);
   const fileByPath = new Map(
     project.fileRecords.map((record) => [toPosix(record.relativePath), record]),
@@ -197,13 +257,41 @@ export async function auditProject(root) {
     suppressedCandidates: dispositions.filter((disposition) => disposition.status === "suppressed").length,
     staleDispositions: dispositions.filter((disposition) => disposition.status === "stale").length,
   };
-  return {
+  const result = {
     schemaVersion: AUDIT_SCHEMA_VERSION,
     repositoryId: project.config.repositoryId,
     summary,
     candidates: activeCandidates,
     dispositions,
   };
+  return { project, fileByPath, candidates, result };
+}
+
+function normalizeExplanationPath(root, inputPath) {
+  if (typeof inputPath !== "string" || inputPath.trim() === "") throw new TypeError("explain requires one file path.");
+  const rootPath = path.resolve(root);
+  const absolutePath = path.resolve(rootPath, inputPath);
+  const relativePath = path.relative(rootPath, absolutePath);
+  if (relativePath === "" || relativePath === ".." || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath)) {
+    throw new RangeError("explain path must name one file inside the repository root.");
+  }
+  return toPosix(relativePath);
+}
+
+function buildFileExplanation(repositoryId, file, moduleKey, status, navigationCards, coverageCards, candidate, disposition, reasons, action, message) {
+  return {
+    schemaVersion: FILE_EXPLANATION_SCHEMA_VERSION,
+    repositoryId,
+    path: file,
+    moduleKey,
+    status,
+    navigationCards,
+    coverageCards,
+    candidate,
+    disposition,
+    reasons,
+    recommendation: { action, message },
+  };
 }
 
 function classifyStaleDisposition(file, fileByPath, exactCardPaths, coveredModules) {

package/src/cli.js

@@ -38,7 +38,7 @@ import { renderGraphNode } from "./graph.js";
 import { getAgentToolDefinitions } from "./agent-protocol.js";
 import { loadPromptPrefixBundle } from "./prompt-bundle.js";
 import { diagnosticsToEditor, getEditorIntegration } from "./editor.js";
-import { AUDIT_PRIORITIES, auditHasFindings, auditProject } from "./audit.js";
+import { AUDIT_PRIORITIES, auditHasFindings, auditProject, explainProjectFile } from "./audit.js";
 import { migrateProject } from "./migration.js";
 
 const VALUE_OPTIONS = new Set(["--root", "--format", "--top", "--depth", "--budget", "--max-edges", "--agents", "--file", "--fail-on", "--output"]);
@@ -56,6 +56,7 @@ const COMMAND_OPTIONS = Object.freeze({
   doctor: new Set(["--root", "--json"]),
   migrate: new Set(["--check", "--write", "--root", "--json"]),
   audit: new Set(["--root", "--json", "--summary", "--fail-on", "--output"]),
+  explain: new Set(["--root", "--json"]),
   spec: new Set(["--root", "--json"]),
   tools: new Set(["--json"]),
   bundle: new Set(["--root", "--json"]),
@@ -106,6 +107,8 @@ export async function runCli(argv) {
       return runMigrate(root, args, json);
     case "audit":
       return runAudit(root, args, json);
+    case "explain":
+      return runExplain(root, args, json);
     case "spec":
       return runSpec(json);
     case "bundle":
@@ -364,6 +367,44 @@ async function runAudit(root, args, json) {
   return auditHasFindings(result, failOn) ? 1 : 0;
 }
 
+async function runExplain(root, args, json) {
+  const files = getPositionals(args);
+  if (files.length !== 1) throw usageError("explain requires exactly one file path.");
+  let result;
+  try {
+    result = await explainProjectFile(root, files[0]);
+  } catch (error) {
+    if ((error instanceof TypeError || error instanceof RangeError) && /^explain (?:requires|path)/u.test(error.message)) {
+      throw usageError(error.message);
+    }
+    throw error;
+  }
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`file ${result.path}`);
+    console.log(`status ${result.status}`);
+    if (result.moduleKey) console.log(`module ${result.moduleKey}`);
+    for (const card of result.navigationCards) console.log(`card ${card.scope} @${card.id} ${card.path}`);
+    for (const card of result.coverageCards) {
+      if (!result.navigationCards.some((item) => item.id === card.id && item.path === card.path)) {
+        console.log(`coverage ${card.scope} @${card.id} ${card.path}`);
+      }
+    }
+    if (result.candidate) {
+      console.log(`candidate ${result.candidate.priority} ${result.candidate.path} score=${result.candidate.score}`);
+      console.log(`why ${result.candidate.reasons.join(",")}`);
+      const signals = Object.entries(result.candidate.signals)
+        .filter(([, value]) => Array.isArray(value) ? value.length > 0 : Boolean(value))
+        .map(([name, value]) => `${name}=${Array.isArray(value) ? value.join("|") : value}`);
+      if (signals.length > 0) console.log(`signals ${signals.join(",")}`);
+    }
+    if (result.disposition) console.log(`disposition ${result.disposition.status}: ${result.disposition.reason}`);
+    console.log(`next ${result.recommendation.action}: ${result.recommendation.message}`);
+  }
+  return result.status === "not-scanned" ? 1 : 0;
+}
+
 function runSpec(json) {
   const spec = {
     specVersion: SPEC_VERSION,
@@ -522,6 +563,7 @@ Usage
   llmnav doctor
   llmnav migrate [--check|--write]
   llmnav audit [--summary] [--output path] [--fail-on none|high|medium|low]
+  llmnav explain <file>
   llmnav spec
   llmnav tools [--json]
   llmnav bundle [--json]

package/src/index.d.ts

@@ -3,6 +3,7 @@ export type LlmnavStability = "architecture" | "contract" | "implementation";
 export type DiagnosticSeverity = "error" | "warning" | "info";
 export type AuditPriority = "high" | "medium" | "low";
 export type AuditDispositionStaleReason = "file-not-scanned" | "already-carded" | "not-a-candidate";
+export type FileExplanationStatus = "candidate" | "suppressed" | "carded" | "covered" | "not-candidate" | "not-scanned" | "stale-disposition";
 
 export interface LlmnavCard {
   scope: LlmnavScope;
@@ -119,6 +120,23 @@ export interface AuditResult {
   >;
 }
 
+export interface FileExplanationResult {
+  schemaVersion: 1;
+  repositoryId: string;
+  path: string;
+  moduleKey: string | null;
+  status: FileExplanationStatus;
+  navigationCards: Array<{ id: string; scope: LlmnavScope; path: string }>;
+  coverageCards: Array<{ id: string; scope: "file" | "module"; path: string }>;
+  candidate: AuditCandidate | null;
+  disposition: AuditResult["dispositions"][number] | null;
+  reasons: string[];
+  recommendation: {
+    action: "review-card" | "review-or-disposition" | "keep-or-review-disposition" | "keep-current-coverage" | "no-card-needed" | "check-scan-configuration" | "remove-or-review-disposition";
+    message: string;
+  };
+}
+
 export interface IndexedLocation {
   path: string;
   startLine: number;
@@ -297,7 +315,7 @@ export interface LlmnavConfig {
 
 export interface AgentToolDefinition {
   schemaVersion: 1;
-  name: "llmnav_query" | "llmnav_show" | "llmnav_context" | "llmnav_check";
+  name: "llmnav_query" | "llmnav_show" | "llmnav_context" | "llmnav_check" | "llmnav_explain";
   description: string;
   inputSchema: {
     type: "object";
@@ -309,7 +327,7 @@ export interface AgentToolDefinition {
 
 export interface AgentOperationResult<T = unknown> {
   schemaVersion: 1;
-  operation: "query" | "show" | "context" | "check" | "unknown";
+  operation: "query" | "show" | "context" | "check" | "explain" | "unknown";
   ok: boolean;
   data: T | null;
   error: { code: string; message: string } | null;
@@ -621,6 +639,7 @@ export interface EvaluationResult {
 export const AGENT_PROTOCOL: string;
 export const AUDIT_PRIORITIES: readonly AuditPriority[];
 export const AUDIT_SCHEMA_VERSION: 1;
+export const FILE_EXPLANATION_SCHEMA_VERSION: 1;
 export const AGENT_OPERATION_SCHEMA_VERSION: 1;
 export const AGENT_TOOL_SCHEMA_VERSION: 1;
 export const BOUNDARY_KINDS: readonly DetectedBoundary["kind"][];
@@ -698,6 +717,7 @@ export function loadConfig(root: string): Promise<{ config: LlmnavConfig; config
 export function validateConfig(config: LlmnavConfig, configPath?: string): void;
 export function auditProject(root: string): Promise<AuditResult>;
 export function auditHasFindings(result: AuditResult, minimumPriority?: AuditPriority | "none"): boolean;
+export function explainProjectFile(root: string, file: string): Promise<FileExplanationResult>;
 export function findAttachedDeclaration(source: string, block: LlmnavBlock, filePath: string): Declaration | null;
 export function extractImports(source: string, filePath: string): string[];
 export function doctorProject(root: string): Promise<{ ok: boolean; checks: Array<{ name: string; ok: boolean; message: string }> }>;

package/src/index.js

@@ -14,7 +14,14 @@ export {
 } from "./prompt-bundle.js";
 export { compareCardIndexes, describeAffectedBoundaries, describeAffectedCatalogs } from "./changes.js";
 export { loadConfig, validateConfig } from "./config.js";
-export { AUDIT_PRIORITIES, AUDIT_SCHEMA_VERSION, auditHasFindings, auditProject } from "./audit.js";
+export {
+  AUDIT_PRIORITIES,
+  AUDIT_SCHEMA_VERSION,
+  FILE_EXPLANATION_SCHEMA_VERSION,
+  auditHasFindings,
+  auditProject,
+  explainProjectFile,
+} from "./audit.js";
 export { BOUNDARY_KINDS, detectBoundaries } from "./boundaries.js";
 export {
   diagnosticsToEditor,

package/src/spec.js

@@ -10,7 +10,7 @@ rel=workflow>llmnav.rules.validate
 stability=contract
 */
 
-export const PACKAGE_VERSION = "0.8.0";
+export const PACKAGE_VERSION = "0.9.0";
 export const SPEC_VERSION = "1";
 
 export const SCOPES = Object.freeze(["file", "module", "symbol"]);