semantic-js-mcp 0.8.1 → 0.10.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "semantic-js-mcp",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "Semantic understanding of JavaScript codebases for AI agents",
   "author": {
     "name": "Jonathan Muñoz Lucas"

package/.prettierrc.json

@@ -1,5 +1,6 @@
 {
   "bracketSpacing": false,
+  "endOfLine": "lf",
   "printWidth": 140,
   "proseWrap": "preserve",
   "semi": true,

package/CHANGELOG.md

@@ -4,6 +4,49 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-07-17
+
+### Added
+
+- Add a deterministic semantic-evidence usability status to named counts and audits, with explicit follow-up reasons for incomplete collection or ambiguous definition selection.
+- Add a repeated post-disposal memory benchmark that separates MCP heap, MCP resident memory, and child-provider resident memory under an explicitly scoped measurement method.
+- Add cross-platform CI coverage for supported Node.js LTS lines.
+- Add focused negative-verification and public-documentation gates.
+- Add concise starter prompts and evidence examples for common agent workflows.
+
+### Fixed
+
+- Recover with fresh language-server and Vue tsserver clients after an initialized provider exits, while settling pending requests and diagnostics without leaving timeout handles active.
+- Resolve cross-project import aliases consistently when a language server first returns the local import binding.
+- Canonicalize Windows source positions when verifying and grouping cross-project references.
+- Make release verification portable across Windows paths, executable shims, temporary-file locking, and checkout line endings.
+- Keep declaration filtering and language-server client eviction stable across platform-specific provider output and slow initialization.
+
+## [0.9.0] - 2026-07-16
+
+### Changed
+
+- Make count and audit results compact by default while preserving complete requested reference collections for paged follow-up tools.
+- Centralize concise, tool-specific continuation guidance in the versioned protocol vocabulary.
+- Consolidate server and schema identity under `producer`, and represent document fingerprints as `sha256:<hex>`.
+- Return continuation guidance as exact tool-name lists, expose one reusable reference-set identifier per logical response, and remove page fields derivable from the normalized request and presentation counts.
+- Group verified page locations by source file while preserving explicit ranges, discovery methods, location-based pagination, and evidence accounting.
+- Advance the canonical result schema to version 6 for the compact audit presentation contract.
+- Document migration from schema 5 and reject legacy envelopes in canonical-result validation.
+- Report whether named-symbol filtering selected zero, one, or multiple exact definitions, and recommend only continuation tools supported by the returned evidence.
+- Verify import and usage bindings against `fileHint` during named audits without treating the hinted filename as a declaration.
+- Share concurrent diagnostic acquisition, negotiate provider pull support, and reject evidence when file content changes during acquisition.
+- Report the owning diagnostic provider and document language once per result, with source region and embedded language on each diagnostic when its range establishes them.
+- Order continuation tools so position-based disambiguation and unresolved-candidate inspection precede broader follow-up pages when those uncertainties are present.
+
+### Added
+
+- Add deterministic release verification, isolated postpublication package verification, and externally configured repository-matrix commands.
+- Reject repository-matrix diagnostic paths whose canonical target escapes the configured repository root.
+- Add model-independent fixtures for compact-result continuation and coverage decisions.
+- Cover named symbol discovery and audits for standalone JavaScript modules at workspace-root and nested source locations.
+- Add npm keywords for MCP, language-server, JavaScript, and semantic-navigation discovery.
+
 ## [0.8.1] - 2026-07-15
 
 ### Fixed

package/CONTRIBUTING.md

@@ -19,13 +19,18 @@ npm run doctor
 npm run smoke:ci
 npm run smoke
 npm run smoke:vue
+npm run smoke:lifecycle
+npm run smoke:release
+npm run smoke:evaluation
+npm run smoke:matrix
+npm run smoke:distribution
 ```
 
-Run `npm run benchmark` for changes that affect repository scanning, reference verification, caching, lifecycle, or memory.
+Run `npm run benchmark` for changes that affect repository scanning, reference verification, caching, lifecycle, or memory. Provider disposal changes should also run `npm run benchmark:lifecycle-memory`; it uses explicit garbage collection and POSIX process metrics, remains separate from the deterministic release gate, and reports its measurement scope.
 
 ## Source Of Truth
 
-- `protocol.mjs` owns public literals, server identity, schema identity, runtime components, and defaults.
+- `protocol.mjs` owns public literals, producer identity, schema identity, runtime components, and defaults.
 - `.prettierrc.json` and the `format` scripts define the public source style.
 - `skills/semantic-navigation/references/protocol-literals.md` is generated; update it with `node scripts/generate-protocol-reference.mjs`.
 - `README.md` documents implemented behavior and known limitations.
@@ -34,6 +39,7 @@ Run `npm run benchmark` for changes that affect repository scanning, reference v
 ## Change Expectations
 
 - Centralize public literals in `protocol.mjs`.
+- Keep release, host, fixture, and CI-only literals in their focused modules rather than expanding the public protocol vocabulary.
 - Run `npm run format` after changing public source or documentation.
 - Regenerate protocol documentation instead of editing it directly.
 - Add isolated fixtures for positive, partial, and failed evidence.
@@ -51,10 +57,24 @@ npm run check:runtime
 npm run smoke:ci
 npm run smoke
 npm run smoke:vue
+npm run smoke:lifecycle
+npm run smoke:release
+npm run smoke:evaluation
+npm run smoke:matrix
 npm run smoke:distribution
 ```
 
-Also run `npm run benchmark` when collection cost or memory could change. Run `npm run doctor` when changing runtime resolution, provider startup, the CLI, or diagnostic trust. New behavior should use generic fixtures and cover complete, partial, limited, failed, stale, or untrusted outcomes as applicable.
+Also run `npm run benchmark` when collection cost or memory could change, and `npm run benchmark:lifecycle-memory` when provider disposal behavior changes. Run `npm run doctor` when changing runtime resolution, provider startup, the CLI, or diagnostic trust. New behavior should use generic fixtures and cover complete, partial, limited, failed, stale, or untrusted outcomes as applicable.
+
+`npm run check:documentation` validates the durable public documentation contract. `npm run smoke:negative` exercises missing runtime providers, invalid workspaces and limits, stale or expired reference sets, repository mutation, unresolved candidates, and diagnostic trust. The complete `npm run release:verify` gate includes both checks.
+
+`npm run release:verify` executes the complete local release gate and reports every check in one machine-readable result. It does not publish, tag, or modify an installed plugin.
+
+Use `npm run verify:published -- <version>` after publishing npm and the matching `v<version>` repository tag. It queries that exact registry version, installs it with isolated temporary state, verifies the installed executable, runs its doctor, then installs the plugin from the tag-pinned Codex marketplace in a temporary `CODEX_HOME`. Registry or network unavailability returns `blocked` rather than passing or failing the package.
+
+Use `npm run validate:repositories -- <configuration.json|yaml>` for authorized real-repository observations. Configuration stays external to the project and contains repository entries with an `id`, absolute `root`, and `probes`. Supported probe kinds are `named-symbol` with `symbol` and optional `fileHint`, and `diagnostics` with a repository-relative `file`. The runner reports tool failures, incomplete evidence, untrusted diagnostics, and unavailable repositories separately.
+
+`npm run evaluate:agent` prints model-independent compact-result cases. An answer file can be graded with `npm run evaluate:agent -- --answers <file>`; hosted or local model execution remains optional and outside the fixture contract.
 
 ## Changelog And Versioning
 

package/README.md

@@ -6,6 +6,8 @@ Coding agents can generate code quickly, but reliable engineering requires more
 
 Semantic JS MCP gives coding agents structured, read-only semantic context so they can navigate, review, and change code with explicit uncertainty.
 
+Its scope is intentionally narrow: it strengthens an agent's understanding of symbol identity, types, references, diagnostics, and evidence coverage. It does not replace architectural reasoning, source inspection, dependency analysis, tests, or runtime observation.
+
 **Better agents begin with better evidence.**
 
 It supports the JavaScript ecosystem, including TypeScript, JavaScript, TSX, JSX, Node module variants, and Vue projects. Language servers provide the underlying semantic data, which the server turns into structured results designed for coding agents.
@@ -14,7 +16,7 @@ For each file, it identifies the owning workspace and uses the corresponding Typ
 
 ## Project Status
 
-Version `0.8.1` is the current release. APIs and result contracts may evolve while the project remains on the `0.x` release line. See the [roadmap](ROADMAP.md) for areas under consideration.
+Version `0.10.0` is the current release. APIs and result contracts may evolve while the project remains on the `0.x` release line. See the [roadmap](ROADMAP.md) for areas under consideration.
 
 ## Installation
 
@@ -40,9 +42,11 @@ semantic-js-mcp doctor
 
 Configure the host to run `semantic-js-mcp serve`.
 
+For practical investigation prompts and compact evidence examples, see [Getting started](docs/getting-started.md).
+
 ## Runtime
 
-- Node.js 22 or newer is supported.
+- Node.js 22 or newer is required.
 - Node.js 24 LTS is recommended for new installations. See the [Node.js release schedule](https://nodejs.org/en/about/previous-releases).
 - `rg` (ripgrep) must be available on `PATH` for repository-wide discovery.
 - The nearest workspace TypeScript SDK is used when available; the bundled TypeScript SDK is the fallback.
@@ -64,9 +68,10 @@ npm run doctor
 npm run smoke:ci
 npm run smoke
 npm run smoke:vue
+npm run smoke:lifecycle
 ```
 
-Run `npm run benchmark` after changes to scanning, references, caching, lifecycle, or memory. Normal analysis is local and read-only; it does not require network access after dependencies are installed.
+Run `npm run benchmark` after changes to scanning, references, caching, lifecycle, or memory. Provider disposal changes can also be characterized with `npm run benchmark:lifecycle-memory`; its output declares the garbage-collection and platform measurement method. Normal analysis is local and read-only; it does not require network access after dependencies are installed.
 
 For an MCP host that accepts a direct stdio configuration, point it at the checked-out server using an absolute path:
 
@@ -108,30 +113,33 @@ Tools are ordered from smaller responses to deeper evidence:
 | `lsp_hover`                     | Inferred type and documentation                           | `lsp_definition`, `lsp_audit_symbol`               |
 | `lsp_diagnostics`               | Focused diagnostics for one file                          | `lsp_definition`, `lsp_hover`                      |
 | `lsp_count_text_matches`        | Exact identifier text count without semantic verification | `lsp_count_named_symbol`, `lsp_audit_named_symbol` |
-| `lsp_count_named_symbol`        | Definition and reference counts by name                   | `lsp_audit_named_symbol`, `lsp_references`         |
-| `lsp_count_references`          | Reference counts at a position                            | `lsp_audit_symbol`, `lsp_references`               |
-| `lsp_audit_named_symbol`        | Composed summary by symbol name                           | `lsp_references`                                   |
-| `lsp_audit_symbol`              | Composed summary at a position                            | `lsp_references`                                   |
+| `lsp_count_named_symbol`        | Definition and reference counts by name                   | `lsp_audit_named_symbol`, `lsp_reference_page`     |
+| `lsp_count_references`          | Reference counts at a position                            | `lsp_audit_symbol`, `lsp_reference_page`           |
+| `lsp_audit_named_symbol`        | Compact composed summary by symbol name                   | `lsp_reference_page`                               |
+| `lsp_audit_symbol`              | Compact composed summary at a position                    | `lsp_reference_page`                               |
 | `lsp_references`                | First page of verified locations                          | `lsp_reference_page`                               |
 | `lsp_reference_page`            | A later page from the same collection                     | `lsp_definition`                                   |
 | `lsp_unresolved_reference_page` | Unresolved candidates with locations and literal reasons  | `lsp_definition`                                   |
 
-Composite audits reuse the same internal definition, hover, and reference primitives as the narrow tools. Compatible count, audit, and reference calls reuse a short-lived reference set.
+Composite audits reuse the same internal definition, hover, and reference primitives as the narrow tools. Their default response contains definition identity, signature, reference and text-match counts, unresolved count, files affected, collection status, and freshness. Use `lsp_reference_page` with a returned `referenceSetId` for verified locations and detailed collection evidence, or `lsp_unresolved_reference_page` for unresolved candidates. Use `lsp_references` when starting from an exact source position without an existing reference set.
+
+Compatible count, audit, and reference calls reuse a short-lived reference set. Compact presentation changes response size, not collection scope.
 
 ## Result Contract
 
 Every successful result contains:
 
-- `server`: the literal semantic-js-mcp server name and version that produced the response.
-- `resultSchema`: the literal canonical result schema name and version.
+- `producer`: the literal semantic-js-mcp name, server version, and result-schema version that produced the response.
 - `request`: normalized inputs and explicit limit interpretation.
 - `result`: evidence produced by the tool.
 - `collection`: how evidence collection completed.
 - `presentation`: how much collected evidence appears in this response.
-- `continueWith`: exact MCP tool names that can add the next kind of evidence.
+- `continueWith`: a list of exact MCP tool names that can add the next kind of evidence.
 
 `structuredContent` is the canonical JSON object. The text content is YAML generated from that same object and parses back to the same data.
 
+Consumers upgrading from result schema 5 should follow the [schema migration guide](docs/result-schema-migration.md).
+
 ### Collection status
 
 - `complete`: the requested collection scope completed and every discovered item was classified.
@@ -139,19 +147,17 @@ Every successful result contains:
 - `partial`: collection completed with explicitly reported items whose definition or owning file could not be resolved.
 - `failed`: the tool call failed and the error object explains why.
 
-Collection and presentation are independent. A complete collection may use `presentation.mode: page`, `count-only`, `summary-by-file`, or `subset` without weakening its counts.
+Collection and presentation are independent. A complete collection may use `presentation.mode: compact-summary`, `page`, `count-only`, or `subset` without weakening its counts. Audits use `compact-summary` by default and retain their full reference set for focused follow-up calls.
 
 For reference results, `includeDeclaration: false` excludes locations that resolve to the requested declaration. It never excludes the source position merely because that position initiated the query. The reported invariant is `verifiedTotal = foundByOwningWorkspaceLanguageServer + verifiedFromOtherWorkspaces` after declaration filtering and deduplication.
 
-### Vue template definitions
-
-Definition lookup uses the Vue language server and TypeScript server first. If both leave a Vue template tag unresolved, the server parses the SFC and follows only a matching local import from `<script>` or `<script setup>`. A successful fallback reports `resolutionMethod: vue-template-import-binding-definition`. This proves an imported component binding; it does not infer global component registration or filename-based identity.
+Reference pages group the locations returned in that page under `referenceGroups` by their exact source `file`. Each location keeps its explicit `range` and `discoveryMethod`, while `locationsAvailable` and `locationsReturned` continue to count locations rather than file groups. Pagination selects locations before grouping, so grouping does not change page membership or collection status. File groups follow first appearance in the page, and locations preserve their relative order within each file; cross-file interleaving is not part of the reference contract.
 
-The Vue parser and TypeScript AST dependencies are loaded lazily only when this fallback is needed.
+Named counts and audits report `definitionSelectionStatus` as `no-definition-selected`, `one-definition-selected`, or `multiple-definitions-selected`. This status describes exact declarations remaining after `fileHint` filtering, before any `maxDefinitions` analysis limit. When selection is empty or ambiguous, `continueWith` recommends structural or position-based tools. It recommends `lsp_reference_page` only when the response contains a reusable reference set.
 
-### Signature source
+They also report `semanticEvidence.status` as `usable-as-requested` or `follow-up-required`. Follow-up reasons combine incomplete collection and ambiguous definition selection without treating a compact, paged, or subset presentation as incomplete evidence. This status evaluates only the requested semantic result; it does not declare the code correct.
 
-Position audits first request hover information at the query position. If that position has a resolved definition but no hover information, the audit requests hover at the resolved declaration. `signatureSource` reports `query-position-hover`, `resolved-definition-hover`, or `not-reported`; `signatureDefinition` identifies the declaration used by the fallback.
+When `fileHint` selects no declaration, a named audit can verify whether source bindings resolve to the hinted file while keeping declaration identity and uncertainty explicit.
 
 ### Limits
 
@@ -162,30 +168,15 @@ Collection limits accept positive integers only:
 
 Omitting `maxCandidates` or `maxDefinitions` requests unlimited collection. `pageSize` and `maxResults` only control returned items for tools that expose them as presentation parameters.
 
-### Text-match accounting
-
-Repository verification reports:
-
-- `matchesFound`
-- `matchesChecked`
-- `matchesToRequestedSymbol`
-- `matchesToDifferentSymbols`
-- `matchesWhoseDefinitionCouldNotBeResolved`
-- `accountingStatus: complete | incomplete`
-
-`accountingStatus: complete` means every discovered text match appears in exactly one classification. Unresolved matches remain explicit and make semantic collection `partial`.
-
-Count and audit responses expose the `referenceSetId` and unresolved-candidate count. Use `lsp_unresolved_reference_page` to inspect those candidates without inflating every summary. The server also queries tsserver `projectInfo` for unresolved candidates and reports whether the file belongs to a configured or inferred TypeScript project. Reasons describe only observed behavior; they do not speculate that an alias caused a failure.
-
 ### Freshness
 
-Reusable reference sets store SHA-256 fingerprints for the source file, native reference files, every cross-workspace candidate file, and the relevant `package.json`, `tsconfig.json`, or `jsconfig.json` files. They also store a repository source-inventory fingerprint built from every relevant path, file size, and high-resolution modification time. Reuse and pagination verify both layers, so new, deleted, renamed, or normally modified source files invalidate repository-wide completeness. Changed evidence produces `REFERENCE_SET_CONTENT_CHANGED` and requires a new `lsp_references` collection. Expired or evicted sets produce `REFERENCE_SET_NOT_FOUND_OR_EXPIRED`.
-
-The inventory is sampled before and after collection. If repository sources change during collection, the server retries once and then returns `REPOSITORY_CHANGED_DURING_COLLECTION` instead of publishing an unstable result.
+Reusable reference sets verify participating file content and the repository
+source inventory before returning another page. Added, removed, renamed, or
+changed sources invalidate stale evidence instead of silently reusing it.
 
-Diagnostics clear their cache on `didChange` and report the analyzed document version and SHA-256 content fingerprint. Only a language-server report for that exact document version appears under `diagnosticsForCurrentDocument`. Otherwise that field is `null`, `evidence.status` is `untrusted`, and any unconfirmed report is isolated under `unconfirmedDiagnosticReport`. Untrusted diagnostics always produce a partial collection.
-
-Diagnostic severities are preserved literally. If a language server omits severity, the result reports `not-reported`; it is not silently treated as information, warning, or error.
+Diagnostics are current only when the owning provider confirms the analyzed
+document snapshot. Unconfirmed reports remain isolated and explicitly
+`untrusted`; an empty unconfirmed report is never presented as a clean file.
 
 ### CI policy adapter
 
@@ -196,42 +187,21 @@ MCP tools report evidence; they do not decide whether a code change passes. `npm
 - `untrusted`, exit `2`: collection is partial or limited.
 - `blocked`, exit `3`: the tool failed or the input is not a semantic-js-mcp result.
 
-Pass `--yaml` after the input path for a YAML representation. The adapter accepts canonical JSON or YAML, validates the server and result-schema identity plus public tool and presentation literals, and never converts incomplete evidence into a pass.
-
-### Installation doctor
-
-`semantic-js-mcp doctor` returns a structured installation report with the same deterministic status vocabulary and exit codes as the CI adapter:
-
-- `pass`, exit `0`: every installation and semantic fixture check passed;
-- `fail`, exit `1`: the server ran, but a functional check returned the wrong result;
-- `untrusted`, exit `2`: runtime checks passed, but a provider did not confirm current diagnostic evidence;
-- `blocked`, exit `3`: a runtime requirement, provider component, or MCP startup step was unavailable.
-
-Use `semantic-js-mcp doctor --yaml` for a YAML representation. An `untrusted` result is not converted to a package failure by the distribution smoke test, but the reason remains explicit in the report.
+Pass `--yaml` after the input path for a YAML representation. The adapter accepts canonical JSON or YAML, validates the producer and result-schema version plus public tool and presentation literals, and never converts incomplete evidence into a pass.
 
 ### Cost visibility
 
-`lsp_count_text_matches` scans repository text without issuing per-match semantic requests. Use it to measure common identifiers before requesting verified counts or audits. Semantic collections preserve omitted limits as unlimited and report text-search time, semantic-verification time, semantic request count, and maximum concurrency. There is no hidden candidate cap.
-
-The bundled Codex MCP configuration allows up to 300 seconds for one tool call. Reaching a client or language-server timeout returns a failed call; it never changes collection scope or reports a timed-out collection as complete.
+`lsp_count_text_matches` measures a common identifier before semantic
+verification. Compact tools omit operational metrics; detailed reference calls
+retain timing, semantic request, concurrency, and memory observations. The
+server applies no hidden candidate cap.
 
 ## Memory Management
 
-Language-server clients and reusable reference sets are released automatically using idle timeout, TTL, and LRU policies. These policies affect reuse only; they do not cap a collection being computed.
-
-Environment variables:
-
-- `SEMANTIC_JS_MCP_CLIENT_IDLE_TIMEOUT_MS` default `60000`
-- `SEMANTIC_JS_MCP_CLIENT_MINIMUM_EVICTION_AGE_MS` default `15000`
-- `SEMANTIC_JS_MCP_MAXIMUM_ACTIVE_CLIENTS` default `4`
-- `SEMANTIC_JS_MCP_REFERENCE_SET_TTL_MS` default `300000`
-- `SEMANTIC_JS_MCP_MAXIMUM_REFERENCE_SETS` default `12`
-- `SEMANTIC_JS_MCP_MAXIMUM_CHANGED_REFERENCE_SET_MARKERS` default `24`
-- `SEMANTIC_JS_MCP_MAXIMUM_CACHED_REFERENCE_LOCATIONS` default `50000`
-- `SEMANTIC_JS_MCP_DEFAULT_REFERENCE_PAGE_SIZE` default `100`
-- `SEMANTIC_JS_MCP_CROSS_WORKSPACE_CONCURRENCY` default `6`
-
-A single reference collection may exceed the cache-location budget so it can still be paged. Older collections are evicted first.
+Language-server clients and reusable reference sets use idle timeout, TTL, and
+LRU policies. These policies govern reuse; they never impose a hidden limit on
+the collection in progress. Configuration literals and defaults are listed in
+the generated [protocol reference](skills/semantic-navigation/references/protocol-literals.md).
 
 ## Verification
 
@@ -242,6 +212,7 @@ npm run doctor
 npm run smoke
 npm run smoke:ci
 npm run smoke:vue
+npm run smoke:lifecycle
 npm run smoke:distribution
 ```
 
@@ -251,6 +222,10 @@ npm run smoke:distribution
 
 The smoke tests create temporary generic TypeScript and Vue projects. They do not depend on a specific application repository.
 
+## Reporting Problems
+
+Run `semantic-js-mcp doctor` and include its structured output, the package version, Node.js version, operating system, affected source type, and the smallest reproducible workspace or public repository. Remove proprietary source, credentials, local absolute paths, and customer data before opening an issue. See [Contributing](CONTRIBUTING.md) for validation details and the [Security policy](SECURITY.md) for private vulnerability reports.
+
 ## Current Limitations
 
 - The server provides static semantic evidence, not runtime call tracing or behavioral proof.

package/ROADMAP.md

@@ -23,12 +23,12 @@ Semantic JS MCP is under active development. This roadmap outlines areas of inve
 ## Agent-Facing Results
 
 - Keep result vocabulary literal, finite, and versioned.
-- Improve compact presentation without hiding collection scope or unresolved evidence.
+- Measure compact audit summaries against large real-world symbols and smaller models without hiding collection scope or unresolved evidence.
 - Expand examples for combining count, audit, reference, diagnostic, text-search, source-inspection, and test evidence.
 
 ## Distribution
 
-- Expand reproducible package and plugin release checks across supported Node.js LTS releases and hosted CI.
+- Maintain reproducible package and plugin release checks across supported Node.js LTS releases and operating systems.
 - Document setup for additional MCP hosts using the same public server contract.
 - Add immutable release-source, upgrade, rollback, and installed-plugin verification.
 

package/docs/architecture-decisions.md

@@ -2,30 +2,23 @@
 
 This document records accepted product boundaries. These decisions may be revised through an explicit change that documents the reason and migration impact.
 
-## DEC-001: Independent MCPs By Semantic Domain
-
-Status: accepted
+## Independent MCPs By Semantic Domain
 
 Semantic support for JavaScript, CSS, PHP, and other domains belongs in independent projects with separate dependencies, processes, releases, installation, and lifecycle management.
 
 This project is `semantic-js-mcp`; it does not load or bundle semantic providers for other domains.
 
-## DEC-002: Composition Belongs To The Consumer
-
-Status: accepted
+## Composition Belongs To The Consumer
 
 One MCP does not call another MCP. A model, skill, CI adapter, or other consumer decides whether evidence from multiple semantic domains is needed.
 
 This avoids runtime coupling, chained failures, implicit configuration, and assumptions that another product exists.
 
-## DEC-003: Common Representation, Domain-Specific Evidence
-
-Status: accepted
+## Common Representation, Domain-Specific Evidence
 
 Related semantic MCPs should use a compatible evidence envelope when practical:
 
-- server identity;
-- result-schema identity;
+- producer identity and result-schema version;
 - tool and normalized request;
 - result;
 - collection status;
@@ -34,23 +27,27 @@ Related semantic MCPs should use a compatible evidence envelope when practical:
 
 Each domain owns the vocabulary inside its result. A CSS class relationship is not represented as a JavaScript LSP reference.
 
-## DEC-004: Continuations Stay Inside One MCP
-
-Status: accepted
+## Continuations Stay Inside One MCP
 
 `continueWith` names tools from the server that produced the response. It does not recommend tools from another MCP. Cross-product guidance belongs in consumer documentation or skills.
 
-## DEC-005: Narrow And Composed Tools Coexist
-
-Status: accepted
+## Narrow And Composed Tools Coexist
 
 Narrow tools provide one focused fact with a small response. Composed audits reuse the same internal primitives to reduce tool calls for consumers that can use a larger evidence summary.
 
 Composed tools do not remove access to narrow tools and do not weaken collection accounting.
 
-## DEC-006: Preserve Provider-Native Embedded Evidence
+## Diagnostics Require Current Snapshot Evidence
 
-Status: accepted
+The server uses advertised diagnostic-pull capability when available and push
+notifications otherwise. Concurrent requests for the same document snapshot
+share one acquisition. A version match or completed pull request is not enough
+when the file content changes before the result is returned.
+
+Diagnostics that cannot be correlated to the current document remain
+explicitly untrusted.
+
+## Preserve Provider-Native Embedded Evidence
 
 The JavaScript ecosystem includes mixed-language documents. When the owning provider reports diagnostics for a Vue template or embedded CSS, SCSS, or Less block, semantic-js-mcp preserves that evidence instead of filtering it according to another provider's domain.
 
@@ -63,10 +60,26 @@ Where it can be determined safely, diagnostic evidence should identify:
 
 Unknown provenance remains explicit. Provider-native style diagnostics do not imply complete CSS graph analysis.
 
-## DEC-007: Extract Shared Code Only After A Second Implementation
-
-Status: accepted
+## Extract Shared Code Only After A Second Implementation
 
 The project may document transferable concepts, but it will not create a shared runtime package or universal provider framework before a second semantic MCP demonstrates concrete duplication.
 
 Compatibility should begin with result concepts and conformance fixtures, not premature runtime coupling.
+
+## Compact Summaries Preserve Complete Collections
+
+Count and audit tools return the smallest summary that preserves symbol identity, signature, reference and text-match accounting, unresolved evidence, collection status, and freshness. They do not include per-file reference groups, locations, performance, or memory observations by default.
+
+The complete requested reference set remains available through `lsp_reference_page` and `lsp_unresolved_reference_page` using the returned `referenceSetId`. `lsp_references` creates or reuses a set when the consumer starts from an exact source position.
+
+This keeps model context proportional to the question without making a compact response look more complete than its underlying collection. Presentation size never changes `collection.status`.
+
+Detailed verified locations may be grouped by their exact source file because the file is a shared property of every location in that group. Pagination and counts remain location-based, and each location keeps its explicit range and discovery method. Reference locations have no cross-file ordering contract. Status, freshness, unresolved candidates, and unlike evidence are not grouped merely to shorten output.
+
+## Named Selection Reports Ambiguity Without Inferring Identity
+
+Named-symbol tools report whether exact declaration filtering selected zero, one, or multiple definitions. A `fileHint` narrows declarations already reported by the owning provider; it does not turn a matching filename, Vue component name, import alias, or test double into declaration evidence.
+
+When selection is empty or ambiguous, continuation guidance points consumers toward structural or position-based tools. Reference-page guidance appears only when the response contains a reusable reference set. This keeps ambiguity actionable without guessing which homonymous symbol the consumer intended.
+
+A named audit may separately verify that an exact text occurrence resolves to a `fileHint` target. This binding evidence retains its source position, target definitions, resolution method, complete classification counts, and unresolved accounting. It does not promote the target filename or local alias into a named declaration, and the lighter count tool does not perform these per-match definition requests.

package/docs/distribution.md

@@ -45,10 +45,29 @@ Run the complete local validation sequence before reviewing a distribution chang
 ```bash
 npm run check
 npm run check:runtime
+npm run check:documentation
 npm run smoke:ci
+npm run smoke:negative
+npm run smoke:doctor
 npm run smoke
 npm run smoke:vue
+npm run smoke:lifecycle
 npm run smoke:distribution
 ```
 
 Run `npm run doctor` separately when the structured installation evidence is part of the review. Exit `2` is an explicit untrusted diagnostic result and must not be described as a clean semantic pass.
+
+## Release Verification
+
+```bash
+npm run release:verify
+npm run verify:published -- <version>
+```
+
+The local release gate runs every configured source, runtime, semantic, evaluation, distribution, and benchmark check and reports all failures instead of stopping at the first one. It performs no publication or installed-plugin mutation.
+
+Postpublication verification requires an explicit version and the matching `v<version>` repository tag. It queries that immutable registry version, installs it with a fresh temporary npm cache and consumer project, verifies the installed executable and manifest, then runs the installed doctor to cover MCP startup, tool discovery, TypeScript evidence, and Vue navigation. It also installs the plugin from the tag-pinned marketplace inside a temporary `CODEX_HOME` and verifies the enabled plugin version. Temporary state is removed afterward. An unavailable registry, marketplace, or network is reported as `blocked`.
+
+## Continuous Integration
+
+GitHub Actions runs the complete release gate on Node.js 22 and 24 across Ubuntu, macOS, and Windows. A second Linux matrix runs the same gate on Node.js 22 across Ubuntu, Fedora, Arch Linux, and openSUSE. The gate verifies ripgrep before running static checks, runtime resolution, documentation, CI policy, negative fixtures, doctor, TypeScript and Vue semantics, provider lifecycle, package installation, and the short benchmark.

package/docs/getting-started.md

@@ -0,0 +1,72 @@
+# Getting Started
+
+Semantic JS MCP adds static semantic evidence to an agent's existing code investigation. These prompts are starting points; the agent should still inspect source, search text, and run focused checks when behavior matters.
+
+## Trace A Symbol
+
+> Trace the named symbol `parseRequest` across this repository. Measure its scope first, verify the exact declaration and references, then inspect its direct callers and callees. Report unresolved or incomplete evidence explicitly.
+
+## Review A Security-Sensitive Change
+
+> Review the authentication changes in this diff. Use semantic evidence to verify every material symbol and cross-workspace reference, corroborate reachability with text search and direct source inspection, and distinguish introduced defects from pre-existing behavior.
+
+## Check Current Diagnostics
+
+> Check current diagnostics for `src/handler.ts`. Treat the file as clean only if the language server confirms the current document snapshot; otherwise report the result as untrusted and explain the required follow-up.
+
+## Reading Compact Results
+
+The examples below show the decision-bearing fields. Actual responses also identify the producer, normalized request, presentation mode, and exact continuation tools.
+
+### Complete Evidence
+
+```yaml
+result:
+  definitionSelectionStatus: one-definition-selected
+  semanticEvidence:
+    status: usable-as-requested
+    followUpReasons: []
+collection:
+  status: complete
+```
+
+This supports the requested static symbol claim. It does not prove runtime behavior or approve a change.
+
+### Partial Evidence
+
+```yaml
+result:
+  semanticEvidence:
+    status: follow-up-required
+    followUpReasons:
+      - collection-is-partial
+collection:
+  status: partial
+continueWith:
+  - lsp_unresolved_reference_page
+```
+
+Inspect the unresolved candidates and relevant source before making a coverage claim.
+
+### Untrusted Diagnostics
+
+```yaml
+result:
+  evidence:
+    status: untrusted
+    reason: language-server-did-not-report-current-document
+  diagnosticsForCurrentDocument: null
+collection:
+  status: partial
+```
+
+An empty unconfirmed report is not a clean diagnostic result.
+
+### Startup Failure
+
+```yaml
+status: blocked
+reason: runtime-component-missing
+```
+
+Run `semantic-js-mcp doctor` and report its structured runtime component evidence. A missing provider or unavailable command is an environment blocker, not a code pass or diagnostic result.

package/docs/result-schema-migration.md

@@ -0,0 +1,67 @@
+# Result Schema Migration
+
+Semantic JS MCP increments `producer.resultSchemaVersion` when a tool-result
+shape changes incompatibly. Consumers should validate this value before parsing
+tool-specific evidence.
+
+## Schema 7
+
+Schema 7 adds `result.semanticEvidence` to named counts and audits. Its
+`status` is `usable-as-requested` only when collection is complete and exactly
+one definition is selected. Otherwise `follow-up-required` includes every
+applicable collection or definition-selection reason under `followUpReasons`.
+
+Presentation mode, page size, and subset presentation never affect this
+status. It summarizes whether the requested semantic result needs another
+semantic step; it does not establish code correctness or runtime behavior.
+
+## Schema 6
+
+Schema 6 replaces representational duplication with a compact response while
+preserving collection scope and reusable evidence.
+
+| Schema 5                                                                      | Schema 6                                                                |
+| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `server` and `resultSchema` objects                                           | one `producer` object with `name`, `version`, and `resultSchemaVersion` |
+| `continueWith` objects containing `tool` and `provides`                       | a list of exact tool names                                              |
+| `presentation.mode: summary-by-file` for audits                               | `presentation.mode: compact-summary`                                    |
+| per-file locations and operational metrics in count and audit summaries       | `filesContainingReferences` plus a reusable `referenceSetId`            |
+| flat `result.locations` in reference pages                                    | `result.referenceGroups`, grouped by exact source file                  |
+| repeated `referenceSetId` values across result sections                       | one identifier in the initial count, audit, or reference result         |
+| diagnostic algorithm and hash in separate fields                              | `contentFingerprint: sha256:<hex>`                                      |
+| page offsets, requested page size, and derivable subset flags in presentation | normalized request values, returned counts, and `nextCursor`            |
+
+Use `lsp_reference_page` with a count or audit `referenceSetId` to retrieve
+verified locations. Use `lsp_references` when starting from an exact source
+position without an existing reference set.
+
+Named counts and audits also report `definitionSelectionStatus`. Continuation
+lists include `lsp_reference_page` only when at least one selected definition
+produced a reusable reference set. Empty or multiple selection recommends
+structural or position-based navigation instead of implying that a filename or
+common symbol name established identity.
+
+When `fileHint` selects no exact declaration, a named audit may additionally
+return `fileHintResolution`. Its counts classify exact text matches by whether
+their definitions resolve to the hinted path, elsewhere, or not at all. A
+reported `sourcePositionForAudit` is one verified follow-up position and does
+not change `definitionSelectionStatus`.
+
+The collection contract is unchanged: omitted collection limits remain
+unlimited, pagination affects presentation only, and unresolved candidates keep
+the collection partial. Schema 6 does not convert incomplete evidence into a
+complete result.
+
+The CI adapter accepts only its canonical schema version. A schema 5 result is
+reported as `blocked` rather than being interpreted through schema 6 rules.
+
+Schema 6 diagnostic evidence may use
+`current-document-snapshot-confirmed` for a pull result or
+`document-content-changed-during-diagnostic-acquisition` when the source no
+longer matches the analyzed snapshot.
+
+Diagnostic results include one `provenance` object with `provider` and
+`documentLanguage`. Each diagnostic item includes `embeddedRegion` and
+`embeddedLanguage`. The finite values are generated in the protocol reference;
+`unknown` means the source range or declared language did not establish a
+supported classification.