llmnav 0.5.1

package/docs/configuration.md

@@ -0,0 +1,117 @@
+# Configuration reference
+
+`llmnav init` creates `.llmnav/config.json` and a local JSON schema at `.llmnav/schema/config.schema.json`.
+
+## Complete shape
+
+```json
+{
+  "$schema": "./schema/config.schema.json",
+  "version": 1,
+  "repositoryId": "example-service",
+  "sourceRoots": ["src", "packages"],
+  "includeExtensions": [".ts", ".tsx", ".go", ".rs", ".py"],
+  "excludeDirectories": ["node_modules", "dist", "target"],
+  "excludeFiles": ["*.generated.*", "*.gen.*"],
+  "coverageRules": [],
+  "graph": {
+    "indexFiles": []
+  },
+  "lint": {
+    "maxRoleLength": 180,
+    "maxSearchTerms": 6,
+    "minSearchTerms": 2,
+    "maxInvariants": 4,
+    "maxEffects": 6,
+    "maxRelations": 6,
+    "maxBlockBytes": {
+      "file": 400,
+      "module": 1200,
+      "symbol": 900
+    },
+    "maxSemanticRatio": 0.015,
+    "minimumSourceBytesForRatio": 50000,
+    "searchTermSaturation": 0.05,
+    "minimumCardsForSaturation": 20,
+    "genericSearchTerms": ["service", "manager", "handler"],
+    "vagueRoleWords": ["handle", "manage", "process"],
+    "strictRisks": ["auth", "money", "privacy"],
+    "additionalEffects": [],
+    "additionalRisks": [],
+    "additionalRelations": [],
+    "requireCanonicalOrder": true,
+    "requireCanonicalFormatting": true
+  },
+  "generation": {
+    "cacheDirectory": ".llmnav/cache",
+    "moduleDepth": 2,
+    "searchShardSize": 0,
+    "repositoryCatalogStabilities": ["architecture"],
+    "moduleCatalogStabilities": ["architecture", "contract"]
+  },
+  "evaluation": {
+    "queryFile": ".llmnav/eval/queries.jsonl",
+    "minimumRecallAt1": 0.75,
+    "minimumRecallAt5": 0.9
+  }
+}
+```
+
+Initialization writes the full default object. Later releases may add defaults without requiring every repository to rewrite its file because configuration is merged with the active profile. Unknown properties are rejected at every supported level, preventing misspelled enforcement settings from being silently ignored.
+
+## Repository identity
+
+`repositoryId` distinguishes generated catalogs and future cross-repository relations. Use a stable lowercase repository name. Renaming an npm package does not require changing it when existing cross-repository IDs depend on the old value.
+
+## Source selection
+
+`sourceRoots` defines the only directory trees scanned during a normal command. CLI path arguments narrow that set for formatting or diagnostics.
+
+Every source root must remain inside the repository and cannot be a symbolic link. Nested symbolic-link entries are not traversed.
+
+`includeExtensions` is an allowlist. LLMNav does not scan Markdown or YAML by default because documentation examples routinely contain card syntax.
+
+`excludeDirectories` matches directory names at any depth. `excludeFiles` uses repository-relative globs with `*`, `?`, and `**`.
+
+## Coverage rules
+
+Coverage is opt-in and path-specific.
+
+```json
+{
+  "name": "payment webhooks",
+  "match": ["src/webhooks/payment/**/*.ts"],
+  "scope": "file",
+  "requiredFields": ["effect", "risk", "invariant"]
+}
+```
+
+A coverage rule checks files already selected by `sourceRoots` and extension filters. Its fields are closed and `requiredFields` must name valid LLMNav keys. It should target a real architectural boundary, never an entire source tree.
+
+## Lint profile
+
+Byte and field-count limits prevent semantic cards from becoming mini-documents. `maxSemanticRatio` produces a warning after the scanned source exceeds `minimumSourceBytesForRatio`.
+
+Search saturation warns when one exact search phrase appears in too many cards. Repository-wide vocabulary such as a product name usually belongs in module IDs or aliases rather than every card.
+
+`additionalEffects`, `additionalRisks`, and `additionalRelations` extend controlled vocabularies. Add namespaced values rather than weakening validation globally. Each entry is a lower-case controlled identifier, not a complete source expression. Configure `queue.publish`, then write `effect=queue.publish(job_ready)` in a card. Configuration values such as `queue.publish(name)`, `Data Loss`, and `calls>` are rejected.
+
+## Generation
+
+`generation.cacheDirectory` must be a relative path below `.llmnav/`. Generation removes and rebuilds that directory, so it cannot be pointed at ordinary source or arbitrary repository paths.
+
+`moduleDepth` groups IDs by their first segments. With a depth of two, `auth.session.rotate` belongs to the `auth.session` catalog.
+
+`searchShardSize` is `0` by default. Set a positive card limit in very large repositories to emit deterministic `search-shards.json` and `search-shards/NNNN.json` artifacts. Shards are sliced from the compact index without retokenizing cards. The compatible `search-index.json` remains available for existing consumers and preserves ranking behavior.
+
+Stability filters decide which cards enter long-lived repository and module prompt material. Every card remains in `index.json` regardless of catalog filters.
+
+## Graph inputs
+
+`graph.indexFiles` lists optional generated definition and reference indexes. Paths must remain inside the repository and are loaded as data only. See [Repository graph](graph.md) for the schema and validation contract.
+
+## Evaluation
+
+`queryFile` must remain inside the repository. Each JSONL record contains task text and one or more accepted IDs.
+
+The thresholds gate `llmnav eval`. Keep the default until the query set represents real work, then raise the values based on measured retrieval quality.

package/docs/editor-integration.md

@@ -0,0 +1,29 @@
+# Editor integration
+
+## Deterministic diagnostics
+
+```sh
+llmnav check --format editor
+```
+
+The schemaVersion 1 report groups diagnostics by repository-relative path. Ranges use zero-based line and character coordinates, while each item retains numeric severity, textual level, stable diagnostic code, source, and message. The output contains no absolute workspace path, timestamp, editor identity, or platform separator.
+
+An editor adapter should bind the repository root itself, map each relative path to its workspace document, and replace the previous LLMNav diagnostics for that document. Do not let model-generated input choose the root.
+
+## Visual Studio Code
+
+```sh
+llmnav editor vscode
+```
+
+This prints a schemaVersion 1 integration envelope whose `config` value is a VS Code `tasks.json` configuration. The task runs the local package with `npm exec -- llmnav check` and maps LLMNav's standard text output into the Problems panel through a custom problem matcher.
+
+If `.vscode/tasks.json` already exists, merge the generated task into its `tasks` array instead of replacing unrelated tasks. The generated command performs no file mutation.
+
+The matcher follows the current [VS Code task and problem matcher contract](https://code.visualstudio.com/docs/debugtest/tasks): repository-relative file, line, column, severity, code, and message capture groups are declared explicitly.
+
+## Other editors
+
+Editors and language-client wrappers should consume `check --format editor` or call `diagnosticsToEditor(diagnostics)`. This keeps coordinate conversion and severity mapping in LLMNav while leaving document URI construction, lifecycle, debounce, and Problems-panel ownership to the editor integration.
+
+LLMNav does not run a watcher or language server. A host decides when to invoke checks and how to cancel or replace stale results.

package/docs/faq.md

@@ -0,0 +1,59 @@
+# FAQ
+
+## Should every function receive a card?
+
+No. That makes retrieval noisier and creates a second copy of the program in prose. Start with architectural modules, public boundaries, risky workflows, orchestration points, and non-obvious invariants.
+
+## Why not use JSDoc or docstrings alone?
+
+JSDoc and docstrings target generated human documentation and language tooling. They do not define durable semantic IDs, controlled effects and risks, append-only catalog order, relation validation, deterministic search artifacts, or search regression gates. They can coexist with LLMNav cards.
+
+## Does v0.5 change the `llmnav/1` syntax?
+
+No. The source grammar remains `llmnav/1`. v0.5 adds independently versioned agent-operation, prompt-bundle, and editor-diagnostic contracts beside the existing schemaVersion 1 `index.json`.
+
+## Does every query still tokenize every card?
+
+No. `search-index.json` stores a sorted token dictionary, compact posting lists, and normalized phrase documents. A query tokenizes task text and reads only matching posting lists, while preserving v0.1 ranking behavior. Missing or incompatible search indexes are rebuilt in memory from `index.json`.
+
+## What is the difference between `file-state.json` and `stat-hints.json`?
+
+`file-state.json` is deterministic generated cache and can be committed. It stores content hashes and parsed records.
+
+`stat-hints.json` is volatile and ignored. It stores size, mtime, and ctime only to avoid reading unchanged files. Deleting it changes performance, not generated output.
+
+## What happens when generation fails halfway through?
+
+The live cache is never edited one file at a time. LLMNav builds and verifies a staged cache, journals the directory swap, and retains a backup until commit. A thrown error rolls back immediately. A killed process is recovered by the next query, generation, or doctor command.
+
+## Why is the built-in search lexical?
+
+It is deterministic, local, measurable, multilingual enough for routing aliases, and requires no model or vector database. Embeddings should be considered only after real evaluation queries expose a persistent lexical gap.
+
+## Why are paths and callers forbidden in cards?
+
+They change during routine refactoring and can be derived more accurately. LLMNav writes current paths and declarations into generated indexes. Generated structure is never copied back into source comments.
+
+## Why commit `.llmnav/cache`?
+
+The files are deterministic agent context. Committing them makes drift reviewable, lets agents query without an initial setup run, and allows CI to verify byte equality. Do not commit `.llmnav/state`, `.llmnav/.transactions`, or an interrupted transaction journal.
+
+## Does LLMNav execute project code?
+
+No. Version 0.5 reads text and configured repository-local JSON files, then writes generated artifacts or explicitly requested card formatting. Its tool dispatcher remains local and has no plugin loader, install hook, or network request.
+
+## Can cards be written in Korean?
+
+Yes, but one repository language produces more consistent retrieval. Keep source cards in the codebase's primary language and place Korean task phrases in `.llmnav/lexicon.json`.
+
+## Is the generated cache a model prompt cache?
+
+No. It is stable prompt material designed to be placed before volatile task context. The model provider or agent harness controls actual prompt caching.
+
+## Are benchmark numbers guaranteed on another machine?
+
+No. The repository records exact measured values, environment, fixture size, and methodology. Correctness and memory limits are regression gates; wall-clock numbers must be remeasured on the target machine.
+
+## Can multiple repositories share IDs?
+
+Each repository has a `repositoryId`. Configured graph inputs can add qualified `repository-id/semantic.id` nodes to one explicit workspace. Qualified IDs resolve exactly; unqualified external IDs resolve only when unique. LLMNav does not scan sibling directories or fetch remote repositories automatically.

package/docs/graph.md

@@ -0,0 +1,92 @@
+# Repository graph
+
+## Optional generated inputs
+
+LLMNav never executes repository code to discover definitions or references. Configure explicit generated JSON inputs instead:
+
+```json
+{
+  "graph": {
+    "indexFiles": [".llmnav/imports/payments.json"]
+  }
+}
+```
+
+Every path must stay inside the repository, use forward slashes, avoid parent traversal, and pass symlink traversal checks. Missing, malformed, or unsafe inputs produce blocking diagnostic `LNV014` during `check` and `generate`.
+
+## Input schema
+
+```json
+{
+  "schemaVersion": 1,
+  "repositoryId": "payments",
+  "generator": "scip-adapter@1",
+  "definitions": [
+    {
+      "id": "billing.capture.run",
+      "symbol": "runCapture",
+      "path": "src/capture.ts",
+      "line": 8,
+      "kind": "function"
+    }
+  ],
+  "references": [
+    {
+      "from": "billing.capture.run",
+      "to": "accounts/auth.session.rotate",
+      "kind": "calls",
+      "path": "src/capture.ts",
+      "line": 19,
+      "confidence": 0.9
+    }
+  ]
+}
+```
+
+Local IDs are qualified with the input `repositoryId`. A repository-qualified ID uses `repository-id/semantic.id`. Definitions are sorted by qualified ID and references by source, target, kind, path, and line.
+
+`confidence` is a number from 0 to 1 and defaults to `0.8`. It records the generator's evidence strength; it does not grant authority to modify source or override semantic cards. Unknown fields, duplicate definitions, unsafe paths, invalid IDs, and out-of-range confidence values are rejected.
+
+This normalized input is deliberately smaller than SCIP, LSIF, or a language-server database. External adapters own format conversion. LLMNav owns validation, qualification, graph generation, ranking, and bounded context consumption.
+
+## Generated graph
+
+Generation writes `.llmnav/cache/graph.json` schemaVersion 1. Nodes use `repository-id/semantic.id` keys and retain local card roles, generated locations, imported definitions, external status, and unresolved status.
+
+Edges contain a stable SHA-256 ID, qualified `from` and `to` keys, kind, confidence, and provenance:
+
+| Provenance | Default confidence | Evidence |
+| --- | --- | --- |
+| `source-card` | `1.0` | explicit semantic `rel` field |
+| `local-import` | `0.85` | deterministically resolved relative source import |
+| `generated-index` | supplied value, default `0.8` | configured definition/reference index |
+
+Provenance records the owning input or source file, optional referenced path and line, and generator identity. Missing targets remain unresolved placeholder nodes rather than disappearing. The graph is part of the transactional cache and its bytes are covered by `manifest.json`.
+
+## Incremental invalidation
+
+Generation also writes `.llmnav/cache/graph-state.json` schemaVersion 1. It is a disposable, content-addressed acceleration artifact split into one partition per local card and configured graph input.
+
+Local partition hashes cover graph-relevant card fields plus a repository path-to-ID resolution hash. A body-only edit therefore reuses the graph partition, while a role, relation, import, declaration location, or import-resolution change rebuilds it. Imported partitions use the validated input content hash. Removed cards and inputs remove their partitions and edges.
+
+Malformed, incompatible, or wrong-repository state is ignored and rebuilt from current source and configured inputs. Incremental and forced-full generation must serialize byte-identical `graph.json` and `graph-state.json` files. Both files are published in the same recoverable cache transaction and covered by `manifest.json`.
+
+## Ranking and context
+
+Lexical retrieval remains the seed authority. LLMNav takes at most the first three lexical seeds and applies a bounded one-hop graph bonus:
+
+```text
+seed score × 0.08 × edge confidence × direction weight
+```
+
+Outgoing edges use direction weight `1.0`; incoming edges use `0.6`. An edge cannot create a result for a node that has no loaded card. Result reasons retain direction, kind, and confidence such as `graph-out:calls@0.90`.
+
+`llmnav context` traverses confidence-ordered incoming and outgoing edges breadth-first. `--depth`, `--budget`, and `--max-edges` independently bound traversal and output. Selected cards are packed before compact edge evidence so a small token budget preserves the requested root card first.
+
+## Workspace and cross-repository IDs
+
+Configured graph inputs may contribute nodes from multiple repository IDs. LLMNav treats those imported nodes as one explicit logical workspace; it does not scan sibling directories automatically.
+
+Qualified IDs such as `accounts/auth.session.rotate` resolve exactly. An unqualified ID first prefers the local repository. If no local node exists, it resolves only when exactly one workspace node has that semantic ID. Multiple matches return an ambiguity with sorted qualified candidates and require the caller to choose one.
+
+`show` renders external definitions when no local card exists. `context` can start from an external or unresolved graph node and pack its definitions and bounded edge evidence. External nodes do not become searchable lexical cards merely because they were imported.

package/docs/language-examples.md

@@ -0,0 +1,130 @@
+# Language examples
+
+## TypeScript and JavaScript
+
+Place file or module cards before imports. Symbol cards may precede JSDoc and decorators.
+
+```ts
+/* llmnav/1 symbol
+id=billing.credit.reserve
+role=Reserve credits before an external generation job starts.
+search=credit hold|reserve credits|generation billing
+invariant=Captured credits never exceed the active reservation.
+effect=db.write(credit_reservations)
+risk=concurrency
+stability=contract
+*/
+/** Creates an expiring reservation. */
+export async function reserveCredits() {}
+```
+
+## Go
+
+A Go package card belongs after `package` and before `import` so it does not interfere with the normal package doc comment.
+
+```go
+package session
+
+/* llmnav/1 module
+id=auth.session
+role=Own refresh-token issuance, rotation, replay detection, and revocation.
+owns=refresh-token family|session revocation
+excludes=access-token signing|user profile storage
+search=session lifecycle|token family|session revocation
+invariant=One token family has at most one live refresh token.
+stability=architecture
+*/
+
+import "context"
+```
+
+A symbol card belongs before the ordinary exported declaration comment.
+
+```go
+/* llmnav/1 symbol
+id=auth.session.rotate
+role=Rotate one refresh-token family atomically and reject replayed tokens.
+search=refresh token|token rotation|replay detection
+stability=contract
+*/
+
+// RotateSession returns the replacement token.
+func RotateSession(ctx context.Context) error { return nil }
+```
+
+## Rust
+
+```rust
+/* llmnav/1 symbol
+id=privacy.export.prepare
+role=Build one immutable export manifest from the user's authorized data snapshot.
+search=data export|privacy archive|export manifest
+invariant=Every manifest entry belongs to the authorized subject.
+effect=db.read(privacy_snapshot)|fs.write
+risk=privacy
+rel=test>privacy.export.prepare.contract
+stability=contract
+*/
+pub async fn prepare_export() -> Result<Manifest, Error> {
+    todo!()
+}
+```
+
+## Python
+
+Use explicit `# /llmnav` termination. The card may precede decorators.
+
+```py
+# llmnav/1 symbol
+# id=billing.payment.apply-provider-event
+# role=Apply one provider event idempotently to the payment ledger.
+# search=duplicate webhook|provider event|payment idempotency
+# invariant=One provider event ID changes the ledger at most once.
+# effect=db.write(payment_ledger)
+# risk=money
+# rel=test>billing.payment.apply-provider-event.contract
+# stability=contract
+# /llmnav
+@transactional
+def apply_provider_event(event):
+    ...
+```
+
+## SQL
+
+Use `--` line cards for migration files and terminate explicitly.
+
+```sql
+-- llmnav/1 file
+-- id=billing.migration.credit-reservations
+-- role=Create the reservation ledger without changing existing credit balances.
+-- search=credit migration|reservation ledger|billing schema
+-- invariant=Existing account balances remain unchanged after migration.
+-- effect=db.write(schema)
+-- risk=migration|money
+-- rel=test>billing.migration.credit-reservations.contract
+-- stability=contract
+-- /llmnav
+
+CREATE TABLE credit_reservations (...);
+```
+
+## Svelte, Astro, Vue, and HTML
+
+Use a block comment inside the script region when the card attaches to a script declaration. Use an HTML comment for a component or page file card.
+
+```svelte
+<!-- llmnav/1 file
+id=ui.checkout.page
+role=Render checkout state and submit one payment confirmation request.
+search=checkout page|payment confirmation|purchase flow
+effect=net.call(billing.confirm)
+risk=money
+rel=test>ui.checkout.page.contract
+stability=contract
+-->
+```
+
+## Shell and YAML-adjacent files
+
+Use `#` cards only in source types included by configuration. LLMNav does not scan Markdown or YAML by default because documentation examples and configuration comments would create false cards.

package/docs/migration.md

@@ -0,0 +1,130 @@
+# Gradual migration
+
+## Upgrade to 0.5
+
+No source-card migration is required. Keep every `llmnav/1` comment and the existing `.llmnav/cache/index.json` consumer contract.
+
+Upgrade and regenerate:
+
+```sh
+npm install --save-dev llmnav@^0.5.1
+npx llmnav init --agents all
+npx llmnav generate
+npx llmnav doctor
+```
+
+The regeneration preserves the schemaVersion 1 primary index and existing graph artifacts, then adds deterministic `prompt-prefix.json`. Initialization refreshes the managed agent protocol so structured-tool hosts learn the trusted-root boundary. Volatile `state/`, `.transactions/`, and `generation-transaction.json` remain ignored.
+
+Review `generate --json` during the first upgrade. Existing cards are reported as added only when no previous compatible primary index exists. The prompt-prefix artifact appears in affected catalogs when its bytes change. `LNV009` remains a non-failing contract-fingerprint review signal.
+
+Do not delete `index.json`, rewrite semantic IDs, or copy generated paths or graph edges into comments. v0.5 tool schemas, prompt partitions, editor diagnostics, and host examples are additive; no source-card migration is required.
+
+## Do not annotate the whole repository
+
+The fastest way to destroy LLMNav's value is a campaign that adds a card to every declaration. It creates search-term competition, maintenance burden, and larger prompts before the repository has evidence that those cards help.
+
+Adopt it in measured layers.
+
+## Phase 1: baseline
+
+Collect 20 to 50 historical coding tasks before adding cards.
+
+Record:
+
+* first correct file or symbol rank
+* number of files opened
+* grep or search calls before the correct location
+* uncached input tokens when available
+* task success and test result
+
+These tasks become the first `.llmnav/eval/queries.jsonl` entries.
+
+## Phase 2: architecture cards
+
+Add one `module` card to each domain boundary that agents routinely confuse.
+
+Prioritize ownership and exclusions. A strong module card prevents an agent from entering an adjacent service with similar vocabulary.
+
+Generate the repository core catalog and update agent instructions.
+
+## Phase 3: high-cost behavioral boundaries
+
+Add `symbol` or `file` cards to:
+
+* authentication and authorization flows
+* money and credit accounting
+* privacy access and deletion
+* migrations and compatibility boundaries
+* external provider orchestration
+* event consumers with idempotency requirements
+* concurrency-sensitive state transitions
+* algorithms with non-obvious invariants
+
+Require test relations for auth, money, and privacy cards.
+
+## Phase 4: aliases
+
+Read failed and low-ranked historical queries. Add aliases when the task language uses product terminology, local language, abbreviations, or retired names that source identifiers do not contain.
+
+Do not add aliases for every synonym an LLM can invent. Add phrases observed in real tasks.
+
+## Phase 5: search gates
+
+Turn `llmnav eval` into a required CI check after the benchmark contains representative tasks.
+
+The initial default gates are not sacred. Raise them when the repository's query set is broad enough that a higher score reflects real navigation quality.
+
+## Phase 6: selective expansion
+
+Add cards only when one of these is true:
+
+* repeated task queries fail to retrieve a boundary
+* a high fan-in symbol is hard to identify by name
+* a serious bug was caused by an unstated invariant
+* agents repeatedly edit the wrong adjacent module
+* a semantic workflow or fallback is invisible to syntax
+
+A missing card should have a concrete navigation failure behind it.
+
+## Existing JSDoc and docstrings
+
+Keep human-facing API documentation. LLMNav sits before it and serves a different purpose.
+
+```ts
+/* llmnav/1 symbol
+id=auth.session.rotate
+role=Rotate one refresh-token family atomically and reject replayed tokens.
+search=refresh token|token rotation|replay detection
+stability=contract
+*/
+/** Rotates a refresh token and returns its replacement. */
+export async function rotateSession() {}
+```
+
+Do not copy full JSDoc into `role`. Do not add LLMNav fields to generated API documentation unless the output has a clear consumer.
+
+## Renames and moves
+
+Keep the semantic ID unchanged.
+
+Run generation to update path, line, signature, structure hash, and body hash.
+
+A rename that leaves behavior intact should usually produce no semantic hash change.
+
+## Splits and merges
+
+When one capability splits, mark the old registry record as replaced.
+
+```json
+{"id":"billing.credit.charge","state":"replaced","by":["billing.credit.reserve","billing.credit.capture"]}
+```
+
+A multi-target replacement is intentionally ambiguous. `show` reports every candidate and `context` requires the caller to choose one; LLMNav never treats array order as semantic priority. Use `redirect` when exactly one successor should resolve automatically.
+
+When an old name redirects to one capability:
+
+```json
+{"id":"auth.session.renew","state":"redirect","to":"auth.session.rotate"}
+```
+
+Never assign a retired ID to unrelated new code.

package/docs/performance-v0.2.md

@@ -0,0 +1,42 @@
+# LLMNav v0.2 performance report
+
+This report contains measured results from `npm run benchmark:v0.2`. It is not an estimate. The raw record is `benchmarks/results/v0.2-win32-x64-node24.json`.
+
+## Environment
+
+| Property | Value |
+| --- | --- |
+| Platform | win32 x64 |
+| Node.js | v24.18.0 |
+| CPU | AMD Ryzen 5 7430U with Radeon Graphics          |
+| Logical CPUs | 12 |
+| Fixture | 1,000 files, 5,000 cards |
+| Filesystem cache | Not flushed |
+
+## Generation
+
+| Scenario | Time | Parsed files | Reused files | Retokenized cards |
+| --- | ---: | ---: | ---: | ---: |
+| Cold initial generation | 7190.90 ms | 1000 | 0 | 5000 |
+| One-file incremental regeneration | 4901.54 ms | 1 | 999 | 1 |
+| Same change, forced full regeneration | 7450.25 ms | 1000 | 0 | 5000 |
+| No-op incremental regeneration | 2209.92 ms | 0 | 1000 | 0 |
+
+The one-file incremental run was 1.52× faster than the forced full run on this machine. Incremental and full generation produced byte-identical cache trees across 507 files (33.25 MiB).
+
+## Fresh-process query
+
+Each sample started a fresh Node.js process and included reading and parsing the required generated JSON. The operating-system filesystem cache was not flushed.
+
+| Search path | Correct runs | Median | p95 | Median RSS | Input artifacts |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| v0.1-compatible legacy retokenization | 7/7 | 394.47 ms | 429.81 ms | 146.52 MiB | 4.78 MiB index |
+| v0.2 deterministic inverted index | 7/7 | 221.11 ms | 253.12 ms | 118.12 MiB | 16.22 MiB index + search index |
+
+The v0.2 median was 1.78× faster. Both paths returned the same result checksum, and all runs returned the expected semantic ID.
+
+## Interpretation
+
+The query comparison deliberately includes JSON loading. It therefore measures the cost seen by a one-shot CLI process rather than only the in-memory ranking loop. The generation comparison uses two copies of the same fixture and verifies the resulting cache bytes before reporting the timing.
+
+The changed source file contains five cards, so the machine-readable body-hash diff reports five modified cards. Only one card changed searchable fields, and the card-level inverted index retokenized exactly that one card.

package/docs/provider-neutral-integration.md

@@ -0,0 +1,66 @@
+# Provider-neutral host integration
+
+LLMNav exposes repository navigation contracts without choosing a model provider, transport, tool-call event shape, or cache-control header.
+
+## Bind authority outside model input
+
+The host chooses one repository root and closes over it. The model never receives a `root` field in a tool schema and cannot redirect a call to another checkout.
+
+```js
+import { createLlmnavHost } from "llmnav/examples/provider-neutral-host.mjs";
+
+const host = await createLlmnavHost(process.cwd());
+```
+
+The packaged example returns fixed tool definitions, verified prompt partitions, and one executor. It loads the index, search postings, graph, lexicon, and registry once into a project session instead of reopening the generated cache for every tool call. Copy the small adapter into a host when its packaging system does not import example files directly.
+
+## Register tools
+
+Pass `host.toolDefinitions` through the provider SDK's tool-definition mapping without changing names, descriptions, input properties, required fields, or order. Provider-specific wrapper keys may differ; the nested LLMNav JSON Schemas stay unchanged.
+
+When a tool call arrives:
+
+```js
+const result = await host.execute({
+  name: call.name,
+  input: call.arguments,
+});
+```
+
+Return the complete result envelope to the model. Do not convert an expected `LNVAP002` or `LNVAP404` result into an uncaught transport failure.
+
+The session is an intentional immutable snapshot. After generation or a checkout change, call `await host.refresh()` before accepting more navigation calls. Refresh reloads both prompt partitions and the project session; LLMNav does not silently mix old and new generation state.
+
+## Assemble a cacheable prefix
+
+```js
+const base = host.basePromptPartitions;
+const selected = host.selectPromptPartitions(["auth.session"]);
+```
+
+`basePromptPartitions` contains package tool definitions, the agent protocol, and the repository core in declared order. The selected form appends requested module partitions in bundle order. A missing module fails explicitly instead of silently dropping context.
+
+Map each partition's `cacheBoundaryAfter` hint to the provider's cache-control mechanism only when that mechanism exists. Append user requests, branch state, diffs, source bodies, and tool results after all selected LLMNav partitions. Never store those volatile values back into `prompt-prefix.json`.
+
+## Minimal host loop
+
+```js
+const host = await createLlmnavHost(repositoryRoot);
+const request = {
+  tools: mapToolDefinitions(host.toolDefinitions),
+  prefix: mapPromptPartitions(host.basePromptPartitions),
+  messages: currentMessages,
+};
+
+const response = await provider.generate(request);
+for (const call of extractToolCalls(response)) {
+  const result = await host.execute({ name: call.name, input: call.arguments });
+  currentMessages.push(mapToolResult(call, result));
+}
+```
+
+`mapToolDefinitions`, `mapPromptPartitions`, `extractToolCalls`, and `mapToolResult` are intentionally host-owned. This keeps provider churn outside the LLMNav contract and makes it possible to test the navigation adapter without network access or model credentials.
+
+## Editor diagnostics
+
+Headless hosts can call the `llmnav_check` operation. Editor hosts that need document ranges should run `llmnav check --format editor` or call `diagnosticsToEditor`; see [Editor integration](editor-integration.md).