llmnav 0.5.1

package/CHANGELOG.md

@@ -0,0 +1,113 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The npm package follows Semantic Versioning. The `llmnav/N` source protocol is versioned independently.
+
+## [Unreleased]
+
+## [0.5.1] — 2026-08-09
+
+### Added
+
+* Added canonical-source `generate --full` verification for CI, release, and doctor gates.
+* Added repository-scoped generation locking, transaction owner checks, and atomic cache, registry, and stable-order recovery.
+* Added reusable project navigation snapshots with explicit refresh for long-lived provider-neutral hosts.
+* Added runtime-to-declaration export parity coverage.
+
+### Fixed
+
+* Normalized foreign path separators, encoded SARIF artifact URIs, and blocked cache and staging path escapes.
+* Corrected JavaScript import extraction and regex-body scanning, Python declaration body hashing, and Rust lifetime parsing.
+* Invalidated pre-fix file-state accelerators so corrected declaration and import data is rebuilt from source.
+* Preserved multi-target replacement ambiguity and detected cycles hidden in replacement branches.
+* Synchronized public TypeScript declarations with runtime return values and graph-aware options.
+* Normalized the npm executable path so current npm clients publish the `llmnav` binary without metadata correction.
+
+## [0.5.0] — 2026-08-09
+
+### Added
+
+* Added stable provider-neutral agent tool schemas and a bounded operation dispatcher for query, show, context, and check.
+* Added deterministic prompt-prefix bundles with explicit package, repository, and module cache partitions.
+* Added deterministic zero-based editor diagnostics and a generated VS Code task integration.
+* Added a runnable typed provider-neutral host example that binds repository authority outside tool input.
+
+## [0.4.0] — 2026-08-09
+
+### Added
+
+* Added strict repository-local imports for generated definition and reference indexes with `LNV014` diagnostics.
+* Added deterministic qualified repository graphs with source-card, local-import, and generated-index edge provenance and confidence.
+* Added confidence-weighted graph ranking and context packing bounded by depth, token budget, and edge count.
+* Added exact qualified and ambiguity-safe workspace semantic ID resolution with external definition rendering.
+* Added content-addressed graph partitions with safe incremental invalidation and byte-equivalent full rebuilds.
+
+## [0.3.0] — 2026-08-09
+
+### Added
+
+* Added deterministic exported API and effective configuration fingerprints with `LNV009` drift diagnostics.
+* Added TypeScript and Go declaration enrichment, declaration-level body hashes, and generated route, event, schema, migration, and command boundaries.
+* Added deterministic affected-boundary reports with modules, relations, and reverse semantic dependents.
+* Added deterministic SARIF 2.1.0 diagnostic serialization and `llmnav check --format sarif`.
+* Added opt-in deterministic card-range search shards with manifest hashes and transactional stale-shard removal.
+
+### Changed
+
+* Replaced the remaining Korean documentation examples with English equivalents.
+
+### Removed
+
+* Removed the Korean README so the project maintains one canonical English README.
+
+## [0.2.0] — 2026-08-09
+
+### Added
+
+* Deterministic compact `search-index.json` containing a sorted token dictionary, normalized phrase documents, and ordinal posting lists with sparse field vectors.
+* Card-level inverted-index updates keyed by deterministic search-document hashes.
+* Deterministic `file-state.json` for file-level incremental parsing and card reuse.
+* Volatile stat hints under `.llmnav/state/` to skip reading byte-identical files during no-op generation.
+* Transactional cache generation through staged writes, manifest verification, directory replacement, rollback, and crash recovery.
+* Automatic recovery before `query`, `generate`, and `doctor` read or replace generated cache data.
+* Retry handling for Windows-style `EACCES`, `EBUSY`, `EEXIST`, `ENOTEMPTY`, and `EPERM` rename and removal failures.
+* Machine-readable `changedCards`, `affectedCatalogs`, incremental metrics, and transaction state in `generate --json` output.
+* Large synthetic fixture regression tests for ranking equality, query speed, index size, RSS, and heap use.
+* Failure-injection tests before journaling, after moving the old cache, and after installing an uncommitted cache.
+* Fresh-process query and regeneration benchmark harness with raw JSON and Markdown reports.
+* npm tarball installation smoke test that initializes, generates, queries, validates, and diagnoses a clean project.
+* Public ESM exports and TypeScript declarations for the v0.2 indexing and transaction APIs.
+
+### Changed
+
+* `llmnav generate` now performs incremental scanning by default and commits cache changes transactionally.
+* `llmnav query` uses the generated inverted index and no longer tokenizes every card for every query.
+* `llmnav doctor` validates search-index compatibility, file-state compatibility, manifest hashes, and interrupted transactions.
+* Generated artifacts use locale-independent key and path ordering.
+* `.llmnav/.gitignore` now excludes volatile stat hints and transaction work directories.
+* CI runs the complete suite on Linux and Windows with Node.js 22 and 24, and runs the packed-package smoke test on Node.js 22.
+
+### Compatibility
+
+* The source grammar remains `llmnav/1`.
+* `.llmnav/cache/index.json` remains schemaVersion 1 and retains its v0.1 fields.
+* Existing v0.1 commands and default text output remain compatible.
+* `search-index.json` and `file-state.json` are additive generated artifacts. A missing, malformed, corrupted, or incompatible search index is rebuilt in memory from `index.json`.
+
+## [0.1.0] — 2026-08-09
+
+### Added
+
+* Initial `llmnav/1` source comment specification.
+* Zero-runtime-dependency Node.js CLI.
+* `init`, `check`, `format`, `generate`, `query`, `show`, `context`, `eval`, `doctor`, and `spec` commands.
+* Stable semantic ID registry and append-only catalog ordering.
+* Deterministic repository and module catalogs.
+* Multilingual aliases and CJK n-gram retrieval.
+* Search regression metrics and CI gates.
+* Managed instructions for AGENTS.md, Claude Code, GitHub Copilot, and Cursor.
+* JavaScript programmatic API and TypeScript declarations.
+* Data-loss-resistant formatting that refuses malformed or unknown metadata.
+* Strict configuration, registry-state, path-boundary, and CLI option validation.
+* Redirect-aware bounded context and monorepo root discovery.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 제로디
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,294 @@
+# LLMNav
+
+LLMNav is a deterministic semantic navigation layer for LLM coding agents.
+
+It adds compact, stable metadata to a small number of architectural and behavioral boundaries, compiles that metadata into repository catalogs and a persistent inverted index, and gives agents a fast path from task language to the code that matters.
+
+LLMNav is not a documentation generator, an embedding database, or a reason to annotate every function. It is a zero-runtime-dependency Node.js CLI and ESM library for reducing broad repository scans, irrelevant context, stale hand-written links, repeated card tokenization, and avoidable cache invalidation.
+
+## What v0.5 provides
+
+* The backward-compatible `llmnav/1` source comment specification
+* A parser and data-loss-resistant canonical formatter
+* Semantic lint rules with stable diagnostic codes
+* A schemaVersion 1 `index.json` compatible with v0.1 consumers
+* A deterministic persistent inverted index that reuses unchanged card tokenization
+* File and card-level incremental indexing
+* Repository-locked transactional cache generation with rollback and interrupted-run recovery
+* Machine-readable changed-card, affected-boundary, and affected-catalog output
+* Exported API and effective configuration contract fingerprints
+* TypeScript and Go declaration enrichment with declaration-level body hashes
+* Generated route, event, schema, migration, and command boundaries
+* SARIF 2.1.0 diagnostic output
+* Optional deterministic card-range search shards for very large repositories
+* Strict repository-local imports for generated definition and reference indexes
+* Deterministic qualified repository graphs with edge provenance and confidence
+* Confidence-aware graph ranking and context packing bounded by depth, tokens, and edges
+* Exact qualified and ambiguity-safe workspace semantic ID resolution
+* Content-addressed incremental graph partitions with safe invalidation
+* A runnable provider-neutral host adapter with a reusable project snapshot and typed package export
+* Repository and module catalogs designed for prompt-prefix reuse
+* Multilingual alias routing and CJK n-gram retrieval
+* Search regression tests with Recall@1, Recall@5, and MRR
+* Managed instructions for AGENTS.md, Claude Code, GitHub Copilot, and Cursor
+* Linux and Windows CI gates plus npm pack installation smoke tests
+
+The package supports Node.js 22 or newer, uses ESM, performs no network requests, and has no runtime dependencies.
+
+## Install
+
+```sh
+npm install --save-dev llmnav
+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.
+
+## Add the first card
+
+```ts
+/* llmnav/1 symbol
+id=auth.session.rotate
+role=Rotate one refresh-token family atomically and reject replayed tokens.
+search=refresh token|token rotation|token family|replay detection
+invariant=At most one live refresh token exists per family.
+invariant=Replay revokes the entire token family.
+effect=db.write(session_tokens)|event.emit(auth.session.revoked)
+risk=auth|concurrency
+rel=policy>auth.session.lifecycle
+rel=test>auth.session.rotate.contract
+stability=contract
+*/
+
+export async function rotateSession(
+  input: RotateSessionInput,
+): Promise<RotateSessionResult> {
+  // implementation
+}
+```
+
+The ID describes a durable capability, not a file path or current function name. It survives moves and renames.
+
+## Generate and search
+
+```sh
+npx llmnav format
+npx llmnav check
+npx llmnav generate
+npx llmnav query "replayed refresh token should revoke the family" --top 5
+npx llmnav show auth.session.rotate
+npx llmnav context auth.session.rotate --depth 1 --budget 2500
+```
+
+The generated inverted index stores a deterministic token dictionary, compact posting lists, and normalized phrase documents. A query tokenizes only the task text; it does not tokenize every card again. If `search-index.json` is missing or incompatible, the library rebuilds it in memory from the compatible schemaVersion 1 `index.json`.
+
+## Incremental and transactional generation
+
+The first generation parses every source file and indexes every card. Later runs compare persisted file state and volatile stat hints.
+
+```text
+unchanged stat fingerprint  → reuse parsed file without reading it
+changed stat, same SHA-256  → reuse parsed file after one content read
+changed content             → parse that file and retokenize changed cards only
+deleted file                → remove its cards and postings
+```
+
+All generated cache artifacts are completed and verified in a staging directory before the live cache is replaced. Registry additions and stable-order updates participate in the same recoverable transaction, so rollback cannot leave control state ahead of the cache. If writing, verification, rename, or the process itself fails, the previous generation state remains available or is restored before the next query or generation.
+
+One repository-scoped generation lock serializes the complete source-to-cache operation. Readers wait for an active writer and recover only abandoned journals, so they cannot roll back a live generation. Windows transient rename failures such as `EPERM`, `EBUSY`, `EACCES`, `EEXIST`, and `ENOTEMPTY` are retried. CI executes the transaction and interruption suite on `windows-latest` as well as Linux.
+
+## Machine-readable change output
+
+```sh
+npx llmnav generate --json
+```
+
+The JSON response preserves the v0.1 fields and adds stable records for changed cards, affected boundaries, affected catalogs, file reuse, card retokenization, and transaction recovery.
+
+```json
+{
+  "changedCards": [
+    {
+      "id": "auth.session.rotate",
+      "change": "modified",
+      "dimensions": ["semantic"]
+    }
+  ],
+  "affectedBoundaries": [
+    {
+      "id": "auth.session.rotate",
+      "modules": ["auth.session"],
+      "boundaries": [{ "kind": "route", "confidence": "high", "evidence": ["path"] }]
+    }
+  ],
+  "affectedCatalogs": [
+    {
+      "file": ".llmnav/cache/modules/auth.session.txt",
+      "kind": "module",
+      "id": "auth.session"
+    }
+  ]
+}
+```
+
+Locations and hashes are included in the complete records. Array ordering and generated JSON key ordering are deterministic.
+
+## The core separation
+
+| Layer | Examples | Owner | Storage |
+| --- | --- | --- | --- |
+| Stable meaning | role, invariant, domain search phrases, effects, risks, semantic relations | human or coding agent | source comment |
+| Generated structure | path, declaration, language, visibility, boundaries, imports, fingerprints, hashes | LLMNav | generated cache |
+| Task state | branch, diff, test output, current request | agent harness | never stored in a card |
+
+Paths, line numbers, commit hashes, callers, imports, and signatures are forbidden in source cards. They change too often and are more accurately generated.
+
+## Comment styles
+
+C-style block comments work in TypeScript, JavaScript, Go, Rust, Java, C, C++, C#, Swift, Dart, PHP, Svelte, Astro, and Vue files.
+
+```go
+/* 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
+*/
+```
+
+Line-comment cards require an explicit terminator and work with `//`, `#`, and `--`. HTML comments are supported for markup-oriented files.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `llmnav init` | Create configuration, registry, schemas, agent instructions, and the initial cache |
+| `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 |
+| `llmnav index` | Alias for `generate` |
+| `llmnav query` | Rank cards through the persistent inverted index |
+| `llmnav show` | Resolve one active or redirected semantic ID |
+| `llmnav context` | Build a bounded context bundle around one ID |
+| `llmnav eval` | Run repository-specific search regression queries |
+| `llmnav doctor` | Verify installation, cache integrity, transaction recovery, and drift |
+| `llmnav spec` | Print source-spec vocabularies and key order |
+| `llmnav tools` | Print stable provider-neutral agent tool schemas |
+| `llmnav bundle` | Inspect the generated prompt-prefix cache partitions |
+| `llmnav editor` | Print a deterministic editor task integration |
+
+See [docs/cli.md](docs/cli.md) for every option and exit code.
+
+## Generated layout
+
+```text
+.llmnav/
+  AGENT_INSTRUCTIONS.md
+  config.json
+  ids.jsonl
+  lexicon.json
+  order.lock
+  schema/
+    config.schema.json
+  eval/
+    queries.jsonl
+  state/                    # volatile, ignored
+    stat-hints.json
+  cache/                    # deterministic, commit this
+    index.json              # v0.1-compatible schemaVersion 1
+    cards.jsonl
+    search-index.json       # compact token dictionary, phrases, and postings
+    file-state.json         # deterministic parsed-file state
+    graph.json              # qualified nodes and provenance-aware edges
+    graph-state.json        # disposable content-addressed graph partitions
+    prompt-prefix.json      # explicit package, repository, and module cache partitions
+    repo-core.txt
+    agent-context.md
+    manifest.json
+    modules/
+      auth.session.txt
+      billing.credit.txt
+```
+
+`.llmnav/.transactions/`, `.llmnav/generation-transaction.json`, and `.llmnav/generation.lock` may exist only while a cache transaction is active or incomplete. They are ignored; abandoned state is recovered automatically after lock ownership is checked. Generated structure is never written back into source comments.
+
+`order.lock` is append-only under normal development. New IDs are appended rather than inserted into a globally re-sorted catalog, preserving larger prompt prefixes as the repository grows.
+
+## Multilingual task language
+
+Keep source cards in one repository language. Map product wording, local language, abbreviations, and retired names in `.llmnav/lexicon.json`.
+
+```json
+{
+  "version": 1,
+  "aliases": {
+    "session renewal": "auth.session.rotate",
+    "token replay attack": "auth.session.rotate",
+    "credit reservation": "billing.credit.reserve"
+  }
+}
+```
+
+## Search regression gates
+
+Add real task descriptions to `.llmnav/eval/queries.jsonl` and run `npx llmnav eval`. The default gates are Recall@1 at 0.75 and Recall@5 at 0.90. Large synthetic accuracy, speed, and memory regression tests are also part of this repository's test suite.
+
+The measured v0.2 benchmark report is in [docs/performance-v0.2.md](docs/performance-v0.2.md). It records the exact fixture, environment, fresh-process query timing, incremental and forced-full regeneration timing, memory, and byte-equivalence checks. The report does not present estimates as measurements.
+
+## Recommended adoption boundary
+
+Annotate architectural modules, public entry points, authentication and payment boundaries, privacy boundaries, migrations, orchestration code with multiple external effects, high fan-in symbols, and code with non-obvious invariants.
+
+Do not annotate trivial getters, generated files, obvious wrappers, every test function, or every private helper. LLMNav becomes worse when keyword-heavy comments cover the whole repository.
+
+## Current implementation boundary
+
+Version 0.5 adds stable provider-neutral agent tools, trusted-root operation dispatch, explicit prompt-prefix cache partitions, deterministic editor diagnostics, a VS Code task integration, and a runnable typed host example to the repository graph and incremental navigation layers.
+
+LLMNav does not discover sibling repositories automatically and does not ship an MCP server, embedding database, hosted service, SCIP generator, or complete language-aware call graph. External tools may export the documented compact graph-input schema. Generated structure never writes derived edges into source cards.
+
+## Documentation
+
+* [Quick start](docs/quickstart.md)
+* [Normative `llmnav/1` specification](docs/spec.md)
+* [CLI reference](docs/cli.md)
+* [Configuration reference](docs/configuration.md)
+* [Programmatic API](docs/api.md)
+* [Architecture and cache design](docs/architecture.md)
+* [Repository graph](docs/graph.md)
+* [Agent integration](docs/agent-integration.md)
+* [Editor integration](docs/editor-integration.md)
+* [Provider-neutral host integration](docs/provider-neutral-integration.md)
+* [CI and enforcement](docs/ci.md)
+* [Gradual migration](docs/migration.md)
+* [Language examples](docs/language-examples.md)
+* [Benchmarking methodology](docs/benchmarking.md)
+* [Measured v0.2 performance](docs/performance-v0.2.md)
+* [Research basis](docs/research.md)
+* [Publishing checklist](docs/publishing.md)
+* [FAQ](docs/faq.md)
+
+## Development
+
+```sh
+npm ci
+npm test
+npm run test:coverage
+npm run lint
+npm run check
+npm run smoke:pack
+npm run benchmark:v0.2
+```
+
+The project uses the Node.js standard library and built-in test runner. There is no build step and no production dependency tree to audit.
+
+## Status
+
+LLMNav is an experimental protocol and a usable v0.5 CLI. The source format remains `llmnav/1`; npm package changes and source-grammar changes are versioned independently.
+
+## License
+
+MIT

package/ROADMAP.md

@@ -0,0 +1,71 @@
+# Roadmap
+
+## 0.1 — semantic foundation
+
+Implemented:
+
+* `llmnav/1` parser and formatter
+* semantic validation and stable diagnostics
+* persistent ID registry and append-only catalog order
+* deterministic JSON, JSONL, repository, and module catalogs
+* local multilingual lexical retrieval
+* bounded semantic relation context
+* search regression evaluation
+* agent instruction adapters
+* zero-runtime-dependency npm CLI
+
+## 0.2 — deterministic incremental core
+
+Implemented:
+
+* persistent deterministic inverted index
+* no per-query card retokenization
+* file-level parsed-state reuse
+* card-level posting-list updates
+* transactionally staged cache generation
+* rollback and interrupted-process recovery
+* Windows transient rename and removal retries plus a mandatory Windows CI matrix
+* changed-card and affected-catalog JSON output
+* large fixture accuracy, speed, and memory regression gates
+* fresh-process query and regeneration benchmark reports
+* npm pack installation smoke test
+* v0.1 index-schema and `llmnav/1` source compatibility
+
+## 0.3 — stronger local structure
+
+Implemented:
+
+* exported API and configuration contract fingerprints
+* route, event, schema, migration, and command-boundary detection
+* language-aware TypeScript and Go declaration enrichers
+* selective body hashes at declaration granularity
+* richer affected-boundary reports
+* SARIF diagnostic output
+* sharded generated search artifacts for very large monorepos
+
+## 0.4 — repository graphs
+
+Implemented:
+
+* optional import of generated definition and reference indexes
+* edge provenance and confidence
+* graph-aware ranking and bounded context packing
+* workspace and cross-repository semantic ID resolution
+* incremental graph invalidation
+
+## 0.5 — agent protocol integrations
+
+Implemented:
+
+* stable tool-schema adapters over existing query, show, context, and check operations
+* prompt-prefix bundle generation with explicit cache partitions
+* editor integrations and diagnostics
+* provider-neutral integration examples
+
+## 1.0 criteria
+
+The source grammar and generated formats will be declared stable only after use across multiple TypeScript, Go, Rust, Python, and mixed-language repositories. A 1.0 release requires migration tooling, documented compatibility guarantees, benchmark fixtures with published methodology, sustained Windows and Linux verification, and no unresolved high-severity parser or transaction ambiguity.
+
+## Non-goals
+
+LLMNav will not become a general documentation generator, a source-of-truth call graph maintained by comments, an autonomous code modification service, a hosted source-ingestion platform, or a mandatory embedding database.

package/bin/llmnav.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+import { runCli } from "../src/cli.js";
+
+try {
+  const exitCode = await runCli(process.argv.slice(2));
+  process.exitCode = exitCode;
+} catch (error) {
+  const message = error instanceof Error
+    ? process.env.LLMNAV_DEBUG
+      ? error.stack ?? error.message
+      : error.message
+    : String(error);
+  console.error(`llmnav: ${message}`);
+  process.exitCode = Number.isInteger(error?.exitCode) ? error.exitCode : 1;
+}

package/docs/agent-integration.md

@@ -0,0 +1,114 @@
+# Agent integration
+
+## Explicit initialization
+
+Installing an npm package must not unexpectedly edit the host repository. LLMNav therefore performs no `postinstall` mutation.
+
+Run the integration step explicitly:
+
+```sh
+npx llmnav init --agents all
+```
+
+The command writes one managed navigation protocol to the selected instruction files and always writes the canonical copy at `.llmnav/AGENT_INSTRUCTIONS.md`.
+
+## Supported adapters
+
+| Adapter | File |
+| --- | --- |
+| `agents` | `AGENTS.md` |
+| `claude` | `CLAUDE.md` |
+| `copilot` | `.github/copilot-instructions.md` |
+| `cursor` | `.cursor/rules/llmnav.mdc` |
+
+The adapters contain the same operational rules so agents do not develop vendor-specific navigation behavior.
+
+Each Markdown adapter uses managed markers:
+
+```md
+<!-- llmnav:start -->
+...
+<!-- llmnav:end -->
+```
+
+Re-running initialization replaces the managed block and preserves unrelated repository instructions.
+
+## Protocol installed for agents
+
+The generated instruction tells an agent to:
+
+1. Run `npm exec -- llmnav query "<task>" --top 5` before broad grep or directory scans.
+2. Resolve a selected card with `npm exec -- llmnav show <id>`.
+3. Use `npm exec -- llmnav context <id>` only when related semantic context is necessary.
+4. Treat generated paths and signatures as volatile.
+5. Keep IDs stable across moves and renames.
+6. Update semantic fields only when meaning changes.
+7. Never hand-maintain call, import, reference, implementation, export, or override relations.
+8. Run format, check, and generation after semantic changes.
+9. 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.
+
+The protocol does not order an agent to trust a card over source code. It uses the card to choose what source to inspect.
+
+## Package runners
+
+Generated instructions use `npm exec -- llmnav` so a local dev dependency works without a global installation. Equivalent package-manager runners include:
+
+```sh
+npx llmnav query "task"
+npm exec -- llmnav query "task"
+pnpm exec llmnav query "task"
+bunx llmnav query "task"
+```
+
+A project may replace command examples in its surrounding instructions, but re-running initialization restores the managed npm runner. The package has no install hook and `npm exec` resolves the already installed local binary.
+
+## Prompt-cache placement
+
+An agent harness that controls model input should use this order:
+
+```text
+stable tool definitions
+stable agent protocol
+.llmnav/cache/repo-core.txt
+cache breakpoint
+selected .llmnav/cache/modules/<module>.txt
+cache breakpoint
+user task
+branch and diff state
+query results
+selected source bodies
+test and tool output
+```
+
+The first two layers change rarely. The task and source bodies change frequently and belong after cache breakpoints.
+
+Generation writes this ordering and the exact content into `.llmnav/cache/prompt-prefix.json`. Each partition records package, repository, or module cache scope, a content hash, an estimated token count, and an explicit boundary-after hint. `llmnav bundle` verifies the artifact against `manifest.json` before displaying it.
+
+The host selects only the modules relevant to the current task, preserves the declared base order, and appends volatile task, diff, source, and tool-result context after the selected partitions. LLMNav deliberately leaves provider-specific cache-control syntax to the host.
+
+## Tool wrappers
+
+LLMNav v0.5 does not ship an MCP server. A wrapper can pass `getAgentToolDefinitions()` to its provider SDK and route calls through `executeAgentOperation(root, name, input)`.
+
+Suggested contract:
+
+```json
+{
+  "schemaVersion": 1,
+  "operations": ["llmnav_query", "llmnav_show", "llmnav_context", "llmnav_check"]
+}
+```
+
+Every execution returns the same schemaVersion 1 envelope with `operation`, `ok`, `data`, and `error`. Expected validation and not-found failures use stable `LNVAP` codes. Keep the definition and operation order stable across sessions so provider prompt caches can reuse the tool prefix.
+
+See [Provider-neutral host integration](provider-neutral-integration.md) for the packaged typed adapter and complete host-boundary examples.
+
+## Failure behavior
+
+An agent should not stop when a repository is partially annotated.
+
+When `query` returns no credible result, the correct fallback is normal symbol search, grep, or language-server navigation. After completing the task, the agent may propose a new card only when the missed boundary satisfies the repository's annotation policy.
+
+Search failure alone is not permission to annotate every function sharing a keyword.