semantic-js-mcp 0.10.1 → 0.10.3

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.10.3] - 2026-07-18
+
+### Changed
+
+- Consolidate installation into `SETUP.md`, the shared setup procedure for people and coding agents. README now provides only a brief entry point. The procedure places guards, prerequisites, installation, and verification before troubleshooting and background; uses direct explanatory language; requires exact host and version checks; rejects partial npm extraction; and does not treat installation as permission to inspect source code.
+
+## [0.10.2] - 2026-07-17
+
+### Added
+
+- Add `AGENT_SETUP.md` with safe installation, verification, update, rollback, and removal steps for Codex and standard stdio MCP hosts.
+- Expand semantic-navigation guidance for values assembled from multiple sources so agents inspect existing merge rules, related helpers, consumers, and boundary cases before changing precedence or fallback behavior.
+
 ## [0.10.1] - 2026-07-17
 
 ### Added

package/README.md

@@ -1,5 +1,19 @@
 # Semantic JS MCP
 
+## Setup
+
+Before running an installation command, follow [SETUP.md](SETUP.md). It is the
+single source of truth for setup by either a person or a coding agent, including
+prerequisites, host selection, installation, verification, updates, rollback,
+and removal.
+
+Semantic JS MCP requires Node.js 22 or newer and `rg` (ripgrep). It can be
+installed through the verified Codex plugin route or registered as a local
+stdio server in another compatible MCP host. Package installation alone does not configure an MCP host.
+
+After setup, see [Getting started](docs/getting-started.md) for practical
+investigation prompts and compact evidence examples.
+
 **Your coding agent is only as good as its understanding of your codebase.**
 
 Coding agents can generate code quickly, but reliable engineering requires more than reading files and matching text. They need to understand which declaration a reference belongs to, how symbols cross workspace boundaries, whether the collected evidence is complete, and whether that evidence is still accurate.
@@ -16,45 +30,7 @@ For each file, it identifies the owning workspace and uses the corresponding Typ
 
 ## Project Status
 
-Version `0.10.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.
-
-## Installation
-
-### Codex plugin
-
-Add the public marketplace, then install the plugin:
-
-```bash
-codex plugin marketplace add elnonathan/semantic-js-mcp
-codex plugin add semantic-js-mcp@elnonathan
-```
-
-Codex CLI 0.144.4 or newer is required for npm-backed marketplace installation. Start a new Codex session after installation. The plugin bundles both the MCP server configuration and the semantic-navigation skill.
-
-### Updating the Codex plugin
-
-Codex installs from a local snapshot of each configured marketplace. Refresh that snapshot before reinstalling so `plugin add` resolves the version currently declared by the marketplace:
-
-```bash
-codex plugin marketplace upgrade elnonathan
-codex plugin add semantic-js-mcp@elnonathan
-codex plugin list
-```
-
-`plugin add` reinstalls the plugin; a separate removal is not required. Start a new Codex session after the command reports the expected version.
-
-### MCP executable
-
-Install the package globally when using an MCP host that accepts a command-based stdio configuration:
-
-```bash
-npm install --global semantic-js-mcp
-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).
+Version `0.10.3` 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.
 
 ## Runtime
 
@@ -62,7 +38,7 @@ For practical investigation prompts and compact evidence examples, see [Getting
 - 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.
-- TypeScript, `typescript-language-server`, and the Vue language server are pinned dependencies. Published packages bundle every production dependency so Codex installations do not require a separate dependency installation step. Source checkouts use `npm ci`; startup verifies provider entry points before accepting MCP requests.
+- TypeScript, `typescript-language-server`, and the Vue language server are pinned dependencies. Published packages bundle every production dependency so Codex installations do not require a separate dependency installation step. Startup verifies provider entry points before accepting MCP requests.
 - Source discovery and language selection include `.ts`, `.tsx`, `.mts`, `.cts`, `.js`, `.jsx`, `.mjs`, `.cjs`, and `.vue` files.
 - Run `npm run check:runtime` to report every required component and its resolved file path.
 
@@ -70,10 +46,10 @@ The package exposes a `semantic-js-mcp` executable. `semantic-js-mcp serve` star
 
 ## Development Setup
 
-From a source checkout:
+Complete the [source-checkout setup](SETUP.md#source-checkout), then run the
+checks applicable to the change:
 
 ```bash
-npm ci
 npm run check
 npm run check:runtime
 npm run doctor
@@ -85,34 +61,6 @@ npm run smoke:lifecycle
 
 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:
-
-```json
-{
-  "mcpServers": {
-    "semantic-js-mcp": {
-      "command": "node",
-      "args": ["/absolute/path/to/semantic-js-mcp/server.mjs"]
-    }
-  }
-}
-```
-
-The bundled [`.mcp.json`](.mcp.json) provides the relative-path configuration used when the repository is installed as a Codex plugin.
-
-When the package executable is available on the host's `PATH`, the equivalent stdio configuration is:
-
-```json
-{
-  "mcpServers": {
-    "semantic-js-mcp": {
-      "command": "semantic-js-mcp",
-      "args": ["serve"]
-    }
-  }
-}
-```
-
 ## Tool Graph
 
 Tools are ordered from smaller responses to deeper evidence:

package/SETUP.md

@@ -0,0 +1,413 @@
+# Setup
+
+This guide provides one setup procedure for both people and coding agents. For
+a new installation, complete Guards, Prerequisites, Choose A Version, one
+installation route, and Verify The Installation in that order.
+
+For an update, rollback, removal, or source checkout, go directly to the named
+section and follow its references to the shared verification steps.
+
+## Guards
+
+Setup changes software or MCP configuration on the user's machine. Before
+making a change, confirm all of the following:
+
+1. The user explicitly requested the setup operation.
+2. Choose exactly one installation route. Use the Codex route for Codex and the
+   generic stdio route for another compatible MCP host.
+3. Keep the package out of the current project's dependencies.
+   Do not run `npm install semantic-js-mcp` without `--global`.
+4. Inspect existing MCP configuration before editing it, and preserve every
+   unrelated server and setting.
+5. Obtain any approval required for network access, global installation,
+   configuration changes, cleanup, or restart.
+6. Respect the security policy and configuration schema of the operating
+   system, organization, repository, and MCP host.
+
+If a guard cannot be satisfied, stop and report `blocked` with the specific
+reason. Do not continue from a failed command, a partial installation, or an
+unknown configuration format.
+
+Setup does not authorize source-code analysis. No source-code call is required
+to verify installation unless the user separately requests a functional test.
+
+## Prerequisites
+
+Run:
+
+```bash
+node --version
+rg --version
+```
+
+Both commands must succeed. Semantic JS MCP requires Node.js 22 or newer and
+`rg` (ripgrep) on `PATH`.
+
+If either prerequisite is missing, report `blocked`. Installing, replacing, or
+downgrading Node.js or ripgrep is a separate system change and requires the
+user's approval.
+
+## Choose A Version
+
+When the supplied npm URL ends in `/v/X.Y.Z`, use that exact numeric version.
+For example, `/v/0.10.2` requests version `0.10.2`.
+
+When no version is supplied for an installation or update, run:
+
+```bash
+npm view semantic-js-mcp version
+```
+
+Record the returned numeric version. Commands in this guide use `X.Y.Z` as a
+placeholder; replace it before execution. A command containing the literal
+`X.Y.Z` is not ready to run.
+
+Do not silently substitute `latest`, an installed version, or a newer version
+for the version the user requested.
+
+## Install With Codex
+
+Use this route when Codex is the MCP host. The plugin supplies both the MCP
+server configuration and the semantic-navigation skill, so a separate global
+npm installation is unnecessary.
+
+### 1. Inspect Codex State
+
+Run:
+
+```bash
+codex --version
+codex plugin marketplace list
+codex plugin list
+```
+
+Codex CLI must be version 0.144.4 or newer. The two list commands establish
+whether the marketplace or plugin already exists. There is no need to locate
+or edit a Codex configuration file.
+
+If the Codex version is too old, report `blocked`.
+
+### 2. Add Or Refresh The Marketplace
+
+If marketplace `elnonathan` is absent, run:
+
+```bash
+codex plugin marketplace add elnonathan/semantic-js-mcp
+```
+
+If marketplace `elnonathan` is already present, refresh it instead:
+
+```bash
+codex plugin marketplace upgrade elnonathan
+```
+
+### 3. Confirm The Offered Version
+
+Run:
+
+```bash
+codex plugin list
+```
+
+Find `semantic-js-mcp@elnonathan` and confirm that its offered version matches
+the version recorded in Choose A Version. If it differs, report `blocked`
+instead of installing a different release.
+
+### 4. Install The Plugin
+
+Run:
+
+```bash
+codex plugin add semantic-js-mcp@elnonathan
+codex plugin list
+```
+
+The final list must show `semantic-js-mcp@elnonathan` as `installed, enabled`
+at the requested version.
+
+Do not also run `npm install` or `semantic-js-mcp doctor` for this route. The
+plugin owns the package and server configuration.
+
+### 5. Restart Codex
+
+Start a new Codex session so it can load the plugin. A coding agent cannot
+restart its own active session; in that case, report `pending-restart` and ask
+the user to start the new session.
+
+After restart, continue with Verify The Installation.
+
+## Install With Another MCP Host
+
+Use this route only when the application is not Codex and its official
+documentation confirms support for local MCP servers over `stdio`.
+
+### 1. Confirm The Host Configuration
+
+Before installing the package:
+
+1. identify the MCP host by name;
+2. find its documented MCP configuration location and schema;
+3. inspect the existing configuration;
+4. record any existing Semantic JS MCP entry; and
+5. preserve every unrelated entry.
+
+If the host, stdio support, configuration location, or schema cannot be
+confirmed, report `blocked`. Configuration formats are host-specific, so do
+not copy a filename, JSON shape, URL, or port from another application.
+
+### 2. Install The Exact Global Version
+
+Replace `X.Y.Z` with the recorded version, then run:
+
+```bash
+npm install --global semantic-js-mcp@X.Y.Z
+```
+
+Read the complete npm output. A zero exit code is not sufficient when npm also
+reports a permission or extraction problem.
+Treat `EPERM`, `EACCES`, `TAR_ENTRY_ERROR`, or a missing-file error as a partial installation.
+
+Do not edit the host configuration after a partial installation. Remove the
+partial global package only with the user's approval, then report `blocked`
+with the npm error.
+
+### 3. Check The Executable
+
+Run:
+
+```bash
+semantic-js-mcp --version
+semantic-js-mcp doctor
+```
+
+The version must exactly match the requested version. Interpret the structured
+doctor status as follows:
+
+- `pass`: continue;
+- `untrusted`: continue, but preserve the reported uncertainty;
+- `blocked` or `fail`: do not configure the host until the reported problem is
+  corrected with the user's approval.
+
+### 4. Register The Server
+
+Using the host's documented schema, add one server with these values:
+
+- server name: `semanticjsmcp`
+- transport: `stdio`
+- executable or command: `semantic-js-mcp`
+- arguments: one argument, `serve`
+- enabled: `true`, only when the host schema defines an enabled field
+
+Save the smallest possible configuration change and preserve every unrelated
+entry. Do not add a URL, port, shell command, credentials, or background
+service.
+
+Do not start `semantic-js-mcp serve` manually. The MCP host must start the
+process and communicate with it through standard input and standard output.
+
+### 5. Restart The Host
+
+Restart or reload the host exactly as its documentation requires, then continue
+with Verify The Installation.
+
+## Verify The Installation
+
+Verification occurs after the required restart or reload.
+
+### Codex
+
+1. Run `codex plugin list`.
+2. Confirm that `semantic-js-mcp@elnonathan` is `installed, enabled` at the
+   requested version.
+3. Open the MCP tool list in the new Codex session.
+
+### Another MCP Host
+
+Run:
+
+```bash
+semantic-js-mcp --version
+semantic-js-mcp doctor
+```
+
+The version must match. Doctor must return `pass` or `untrusted`; preserve any
+uncertainty reported by `untrusted`.
+
+Confirm that the host still contains the `semanticjsmcp` entry, then open the
+host's MCP tool list.
+
+### Expected Result
+
+The host must expose tools whose base names begin with `lsp_`. Some hosts add
+the server name as a prefix.
+
+Use one of these outcomes:
+
+- `success`: the requested version is registered and `lsp_*` tools are
+  available;
+- `pending-restart`: installation and configuration succeeded, but a new host
+  session is still required to check tool discovery;
+- `blocked`: a prerequisite, installation, configuration, doctor, version, or
+  tool-discovery check failed.
+
+Package installation or configuration text by itself is not `success`. Missing
+tools are a reason to inspect registration and restart state, not to start the
+server manually.
+
+An installation-only request ends after tool discovery. Do not call an `lsp_*`
+tool against source code unless the user separately requests a functional test
+or explicitly approves the target file.
+
+Report the outcome, detected host, requested and installed versions, changed
+Semantic JS MCP entry, doctor status for a generic installation, tool-discovery
+result, and any remaining blocker or uncertainty. Do not expose credentials or
+unrelated configuration values.
+
+## Troubleshooting
+
+| Symptom                                                             | Action                                                                                                                |
+| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| Node.js is older than 22 or `node` is missing                       | Report `blocked`. Change Node.js only with separate user approval.                                                    |
+| `rg` is missing                                                     | Report `blocked`. Install ripgrep only with separate user approval.                                                   |
+| npm reports `EPERM`, `EACCES`, `TAR_ENTRY_ERROR`, or a missing file | Treat the installation as partial. Do not configure the host. Remove only the partial global package when authorized. |
+| `semantic-js-mcp --version` differs from the requested version      | Report `blocked`; do not configure the different version.                                                             |
+| Doctor returns `blocked` or `fail`                                  | Correct only the reported prerequisite and only with user approval.                                                   |
+| Codex offers the wrong version                                      | Run `codex plugin marketplace upgrade elnonathan`, check again, and report `blocked` if it still differs.             |
+| The host does not show `lsp_*` tools                                | Confirm the saved entry, command, arguments, enabled state, and required restart. Do not invent a URL or port.        |
+| The host configuration location or schema is unknown                | Use installed help or official host documentation. Report `blocked` rather than guessing.                             |
+
+Troubleshooting never requires disabling a security control, bypassing a
+sandbox, executing a remote shell pipeline, or replacing an entire
+configuration file.
+
+## Update
+
+Record the installed version and existing Semantic JS MCP entry first. Resolve
+the exact target version with Choose A Version.
+
+For Codex, run:
+
+```bash
+codex plugin marketplace upgrade elnonathan
+codex plugin list
+codex plugin add semantic-js-mcp@elnonathan
+codex plugin list
+```
+
+Confirm the offered version before `plugin add`. Start a new Codex session,
+then complete Verify The Installation.
+
+For another host, replace `X.Y.Z` and run:
+
+```bash
+npm install --global semantic-js-mcp@X.Y.Z
+```
+
+Repeat the executable check, doctor, required restart, and Verify The
+Installation. Keep an existing host entry when it is already correct.
+
+## Rollback
+
+Record the previously known working version and Semantic JS MCP entry. Do not
+replace that version with the current registry version.
+
+For another host, replace `X.Y.Z` with the previous numeric version:
+
+```bash
+npm install --global semantic-js-mcp@X.Y.Z
+```
+
+Restore only the recorded Semantic JS MCP entry. Restart the host and complete
+Verify The Installation.
+
+A Codex marketplace can install only the version it currently offers. If it
+does not offer the requested rollback version, report `blocked`; do not
+substitute another version or edit the marketplace cache.
+
+## Removal
+
+Record the installed version and current Semantic JS MCP entry before making a
+change.
+
+For Codex, run:
+
+```bash
+codex plugin remove semantic-js-mcp@elnonathan
+```
+
+Remove marketplace `elnonathan` only when no other installed plugin uses it
+and the user approves:
+
+```bash
+codex plugin marketplace remove elnonathan
+```
+
+For another host:
+
+1. Remove only the `semanticjsmcp` entry from the documented host
+   configuration.
+2. Preserve every unrelated server and setting.
+3. Run:
+
+```bash
+npm uninstall --global semantic-js-mcp
+```
+
+Restart or reload the host. Confirm that Semantic JS MCP tools are no longer
+registered.
+
+## Source Checkout
+
+Use this section for repository development or when the user explicitly asks
+to run a source checkout. Do not combine it with a registry or Codex plugin
+installation.
+
+From the repository root, run:
+
+```bash
+npm ci
+npm run check:runtime
+npm run doctor
+```
+
+For a non-Codex host that supports direct stdio commands, use its documented
+schema and these values:
+
+- server name: `semanticjsmcp`
+- transport: `stdio`
+- executable or command: `node`
+- arguments: the absolute path to the checkout's `server.mjs`
+
+Preserve every unrelated host entry. Restart or reload the host and complete
+the source-checkout verification below. Do not run the global executable checks
+for this route.
+
+After restart, confirm that the host still contains the `semanticjsmcp` entry
+with the recorded `node` command and absolute `server.mjs` argument. Open the
+host's MCP tool list and apply the outcomes under
+[Expected Result](#expected-result). Do not call an `lsp_*` tool unless the
+user separately requests a functional test or explicitly approves the target
+file.
+
+The repository's `.mcp.json` is the relative-path configuration bundled by the
+Codex plugin. It is not a universal configuration file for other MCP hosts.
+
+## Background
+
+An MCP host is the application that starts the server and exposes its tools.
+Installing an npm package places files and an executable on the machine, but it
+does not register that executable with an MCP host.
+
+A generic stdio host starts `semantic-js-mcp serve` as a child process and
+communicates through standard input and standard output. The host owns that
+process lifecycle, which is why manually starting the command does not make
+tools appear in the host.
+
+The Codex plugin route supplies both MCP configuration and the
+semantic-navigation skill. Codex plugin state and tool discovery verify that
+route, so it does not need a separate global npm installation or doctor run.
+
+This procedure does not override system, developer, organization, repository,
+or host security policy. Its authority is limited to the requested Semantic JS
+MCP operation and never includes unrelated configuration, credentials, or
+source-code analysis.

package/docs/distribution.md

@@ -4,22 +4,15 @@ The package manifest defines an explicit public file allowlist and exposes the `
 
 ## Codex
 
-```bash
-codex plugin marketplace add elnonathan/semantic-js-mcp
-codex plugin add semantic-js-mcp@elnonathan
-```
-
-The marketplace entry pins a concrete npm package version. Codex CLI 0.144.4 is the minimum verified client for npm-backed marketplace installation. A release updates the package version, plugin manifest, and marketplace entry together.
-
-For an existing marketplace installation, refresh its local snapshot before reinstalling the plugin:
-
-```bash
-codex plugin marketplace upgrade elnonathan
-codex plugin add semantic-js-mcp@elnonathan
-codex plugin list
-```
+The marketplace entry pins a concrete npm package version. Codex CLI 0.144.4
+is the minimum verified client for npm-backed marketplace installation. A
+release updates the package version, plugin manifest, and marketplace entry
+together.
 
-`plugin add` reinstalls the plugin selected by the refreshed marketplace. Start a new Codex session after the listed version matches the release being installed.
+Follow [Install With Codex](../SETUP.md#install-with-codex) for installation or
+update commands, version checks, restart handling, and tool verification. This
+document describes the distribution contract and does not define a second
+setup procedure.
 
 ## Executable
 
@@ -85,7 +78,7 @@ The `publish.yml` workflow publishes tags matching `v*` from a GitHub-hosted Nod
 
 Configure the npm trusted publisher for GitHub user `elnonathan`, repository `semantic-js-mcp`, workflow filename `publish.yml`, and environment `npm-publish`. Allow `npm publish` only. In package publishing access, require two-factor authentication and disallow tokens.
 
-Create and push the matching `v<version>` tag only after the release commit is on `main` and its CI matrix passes. Approve the protected environment deployment, verify the published package, and then create the matching GitHub release.
+Create and push the matching `v<version>` tag only after the release commit is on `main` and its CI matrix passes. If the protected environment requires review, approve the waiting deployment. Verify the published package before creating the matching GitHub release.
 
 ## Continuous Integration
 

package/docs/getting-started.md

@@ -10,6 +10,10 @@ Semantic JS MCP adds static semantic evidence to an agent's existing code invest
 
 > 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.
 
+## Review Combination Logic
+
+> Review this precedence, fallback, normalization, or merge change. Identify every producer of the combined domain value, recover the invariant encoded by existing helpers and direct consumers, verify the discovered symbols and references with semantic evidence, and test a boundary case that could disprove the proposed rule.
+
 ## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "semantic-js-mcp",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "description": "Semantic understanding of JavaScript codebases for AI agents",
   "keywords": [
     "mcp",
@@ -28,6 +28,7 @@
     ".codex-plugin/",
     ".mcp.json",
     ".prettierrc.json",
+    "SETUP.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "ROADMAP.md",
@@ -66,8 +67,8 @@
     "verify:published": "node scripts/postpublication-smoke.mjs",
     "benchmark": "node scripts/benchmark.mjs",
     "benchmark:lifecycle-memory": "node scripts/lifecycle-memory-benchmark.mjs",
-    "format": "prettier --write \".codex-plugin/**/*.json\" \".agents/plugins/marketplace.json\" \".github/**/*.yml\" \".mcp.json\" \".prettierrc.json\" \"package.json\" \"package-lock.json\" \"CHANGELOG.md\" \"CONTRIBUTING.md\" \"README.md\" \"ROADMAP.md\" \"SECURITY.md\" \"*.mjs\" \"docs/**/*.md\" \"lib/**/*.mjs\" \"scripts/**/*.mjs\" \"skills/**/SKILL.md\" \"skills/**/agents/*.yaml\"",
-    "format:check": "prettier --check \".codex-plugin/**/*.json\" \".agents/plugins/marketplace.json\" \".github/**/*.yml\" \".mcp.json\" \".prettierrc.json\" \"package.json\" \"package-lock.json\" \"CHANGELOG.md\" \"CONTRIBUTING.md\" \"README.md\" \"ROADMAP.md\" \"SECURITY.md\" \"*.mjs\" \"docs/**/*.md\" \"lib/**/*.mjs\" \"scripts/**/*.mjs\" \"skills/**/SKILL.md\" \"skills/**/agents/*.yaml\""
+    "format": "prettier --write \".codex-plugin/**/*.json\" \".agents/plugins/marketplace.json\" \".github/**/*.yml\" \".mcp.json\" \".prettierrc.json\" \"package.json\" \"package-lock.json\" \"CHANGELOG.md\" \"CONTRIBUTING.md\" \"README.md\" \"ROADMAP.md\" \"SECURITY.md\" \"SETUP.md\" \"*.mjs\" \"docs/**/*.md\" \"lib/**/*.mjs\" \"scripts/**/*.mjs\" \"skills/**/SKILL.md\" \"skills/**/agents/*.yaml\"",
+    "format:check": "prettier --check \".codex-plugin/**/*.json\" \".agents/plugins/marketplace.json\" \".github/**/*.yml\" \".mcp.json\" \".prettierrc.json\" \"package.json\" \"package-lock.json\" \"CHANGELOG.md\" \"CONTRIBUTING.md\" \"README.md\" \"ROADMAP.md\" \"SECURITY.md\" \"SETUP.md\" \"*.mjs\" \"docs/**/*.md\" \"lib/**/*.mjs\" \"scripts/**/*.mjs\" \"skills/**/SKILL.md\" \"skills/**/agents/*.yaml\""
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.27.1",

package/protocol.mjs

@@ -408,7 +408,7 @@ export const RESULT_SCHEMA = Object.freeze({
   VERSION: 7,
 });
 
-export const SERVER_VERSION = "0.10.1";
+export const SERVER_VERSION = "0.10.3";
 
 export const REQUIRED_RUNTIME_COMPONENT = Object.freeze({
   TYPESCRIPT_LANGUAGE_SERVER: "typescript-language-server/lib/cli.mjs",

package/scripts/distribution-policy.mjs

@@ -2,6 +2,7 @@ export const REQUIRED_PACKAGE_FILE = Object.freeze({
   PACKAGE_MANIFEST: "package.json",
   PRETTIER_CONFIGURATION: ".prettierrc.json",
   README: "README.md",
+  SETUP: "SETUP.md",
   LICENSE: "LICENSE",
   CLI: "cli.mjs",
   SERVER: "server.mjs",

package/scripts/documentation-contract.mjs

@@ -2,36 +2,103 @@ import {DOCTOR_REASON, SEMANTIC_EVIDENCE_FOLLOW_UP_REASON} from "../protocol.mjs
 
 export const DOCUMENTATION_FILE = Object.freeze({
   README: "README.md",
+  SETUP: "SETUP.md",
+  DISTRIBUTION: "docs/distribution.md",
   GETTING_STARTED: "docs/getting-started.md",
+  SEMANTIC_NAVIGATION_SKILL: "skills/semantic-navigation/SKILL.md",
   CONTRIBUTING: "CONTRIBUTING.md",
   SECURITY: "SECURITY.md",
 });
 
-export const PUBLIC_ROOT_DOCUMENT = Object.freeze(["CHANGELOG.md", "CONTRIBUTING.md", "README.md", "ROADMAP.md", "SECURITY.md"]);
+export const PUBLIC_ROOT_DOCUMENT = Object.freeze([
+  "CHANGELOG.md",
+  "CONTRIBUTING.md",
+  "README.md",
+  "ROADMAP.md",
+  "SECURITY.md",
+  "SETUP.md",
+]);
 
 export const PUBLIC_DOCUMENT_DIRECTORY = Object.freeze(["docs", "skills"]);
 
 export const DOCUMENTATION_REQUIREMENT = Object.freeze({
-  README_HEADINGS: Object.freeze([
-    "Installation",
-    "Updating the Codex plugin",
-    "Runtime",
-    "Verification",
-    "Current Limitations",
-    "Reporting Problems",
-  ]),
-  README_LITERALS: Object.freeze(["codex plugin marketplace upgrade elnonathan", "codex plugin add semantic-js-mcp@elnonathan"]),
+  README_HEADINGS: Object.freeze(["Setup", "Runtime", "Development Setup", "Verification", "Current Limitations", "Reporting Problems"]),
+  README_FIRST_SECTION: "Setup",
+  README_SETUP_ENTRY_LITERALS: Object.freeze([
+    "Before running an installation command, follow [SETUP.md](SETUP.md).",
+    "single source of truth",
+    "Package installation alone does not configure an MCP host.",
+  ]),
+  README_FORBIDDEN_SETUP_HEADINGS: Object.freeze(["Agent Installation", "Installation", "Updating the Codex plugin"]),
+  README_FORBIDDEN_SETUP_LITERALS: Object.freeze([
+    "codex plugin marketplace add elnonathan/semantic-js-mcp",
+    "codex plugin add semantic-js-mcp@elnonathan",
+    "npm install --global semantic-js-mcp",
+    "npm ci",
+  ]),
+  DISTRIBUTION_FORBIDDEN_SETUP_LITERALS: Object.freeze([
+    "codex plugin marketplace add elnonathan/semantic-js-mcp",
+    "codex plugin marketplace upgrade elnonathan",
+    "codex plugin add semantic-js-mcp@elnonathan",
+  ]),
   GETTING_STARTED_HEADINGS: Object.freeze([
     "Trace A Symbol",
     "Review A Security-Sensitive Change",
+    "Review Combination Logic",
     "Check Current Diagnostics",
     "Complete Evidence",
     "Partial Evidence",
     "Untrusted Diagnostics",
     "Startup Failure",
   ]),
-  README_LINKS: Object.freeze(["docs/getting-started.md", "CONTRIBUTING.md", "SECURITY.md"]),
+  SETUP_HEADINGS: Object.freeze([
+    "Guards",
+    "Prerequisites",
+    "Choose A Version",
+    "Install With Codex",
+    "Install With Another MCP Host",
+    "Verify The Installation",
+    "Troubleshooting",
+    "Update",
+    "Rollback",
+    "Removal",
+    "Source Checkout",
+    "Background",
+  ]),
+  SETUP_FIRST_SECTION: "Guards",
+  SETUP_LAST_SECTION: "Background",
+  DISTRIBUTION_HEADINGS: Object.freeze(["Release Verification", "npm Trusted Publishing"]),
+  SEMANTIC_NAVIGATION_SKILL_HEADINGS: Object.freeze(["Preserve Combination Invariants"]),
+  README_LINKS: Object.freeze(["SETUP.md", "docs/getting-started.md", "CONTRIBUTING.md", "SECURITY.md"]),
   GETTING_STARTED_LITERALS: Object.freeze([SEMANTIC_EVIDENCE_FOLLOW_UP_REASON.COLLECTION_PARTIAL, DOCTOR_REASON.RUNTIME_COMPONENT_MISSING]),
+  SETUP_LITERALS: Object.freeze([
+    "semantic-js-mcp doctor",
+    "semantic-js-mcp serve",
+    "does not override system, developer, organization, repository",
+    "npm uninstall --global semantic-js-mcp",
+    "server name: `semanticjsmcp`",
+    "codex plugin marketplace upgrade elnonathan",
+    "Do not run `npm install semantic-js-mcp` without `--global`.",
+    "Treat `EPERM`, `EACCES`, `TAR_ENTRY_ERROR`, or a missing-file error as a partial installation.",
+    "Do not start `semantic-js-mcp serve` manually.",
+    "Choose exactly one installation route.",
+    "pending-restart",
+    "No source-code call is required",
+    "Do not run the global executable checks",
+  ]),
+  DISTRIBUTION_LITERALS: Object.freeze([
+    "npm run release:verify",
+    "npm run verify:published -- <version>",
+    "The `publish.yml` workflow publishes tags matching `v*`",
+    "protected `npm-publish` environment",
+    "No long-lived npm token is used.",
+    "Verify the published package before creating the matching GitHub release.",
+  ]),
+  SEMANTIC_NAVIGATION_SKILL_LITERALS: Object.freeze([
+    "Identify every producer of the value",
+    "boundary case that could disprove",
+    "conceptual relationships that an LSP cannot establish",
+  ]),
 });
 
 export const DOCUMENTATION_REASON = Object.freeze({
@@ -39,6 +106,12 @@ export const DOCUMENTATION_REASON = Object.freeze({
   HEADING_MISSING: "required-heading-missing",
   LINK_MISSING: "required-link-missing",
   LITERAL_MISSING: "required-literal-missing",
+  SETUP_ENTRY_POINT_NOT_FIRST: "setup-entry-point-not-first",
+  DUPLICATE_SETUP_SECTION: "duplicate-setup-section",
+  DUPLICATE_SETUP_COMMAND: "duplicate-setup-command",
+  SETUP_GUARDS_NOT_FIRST: "setup-guards-not-first",
+  SETUP_SECTION_ORDER_INVALID: "setup-section-order-invalid",
+  SETUP_BACKGROUND_NOT_LAST: "setup-background-not-last",
   PRIVATE_COORDINATION: "private-coordination-language-found",
   LOCAL_PATH: "local-absolute-path-found",
 });

package/scripts/documentation-gate-smoke.mjs

@@ -6,14 +6,116 @@ import {evaluateDocumentation} from "./documentation-gate.mjs";
 
 const headingText = (headings) => headings.map((heading) => `## ${heading}`).join("\n");
 const valid = {
-  [DOCUMENTATION_FILE.README]: `${headingText(DOCUMENTATION_REQUIREMENT.README_HEADINGS)}\n${DOCUMENTATION_REQUIREMENT.README_LINKS.map((link) => `[doc](${link})`).join("\n")}\n${DOCUMENTATION_REQUIREMENT.README_LITERALS.join("\n")}`,
+  [DOCUMENTATION_FILE.README]: `${headingText(DOCUMENTATION_REQUIREMENT.README_HEADINGS)}\n${DOCUMENTATION_REQUIREMENT.README_LINKS.map((link) => `[doc](${link})`).join("\n")}\n${DOCUMENTATION_REQUIREMENT.README_SETUP_ENTRY_LITERALS.join("\n")}`,
+  [DOCUMENTATION_FILE.SETUP]: `${headingText(DOCUMENTATION_REQUIREMENT.SETUP_HEADINGS)}\n${DOCUMENTATION_REQUIREMENT.SETUP_LITERALS.join("\n")}`,
+  [DOCUMENTATION_FILE.DISTRIBUTION]: `${headingText(DOCUMENTATION_REQUIREMENT.DISTRIBUTION_HEADINGS)}\n${DOCUMENTATION_REQUIREMENT.DISTRIBUTION_LITERALS.join("\n")}`,
   [DOCUMENTATION_FILE.GETTING_STARTED]: `${headingText(DOCUMENTATION_REQUIREMENT.GETTING_STARTED_HEADINGS)}\n${DOCUMENTATION_REQUIREMENT.GETTING_STARTED_LITERALS.join("\n")}`,
+  [DOCUMENTATION_FILE.SEMANTIC_NAVIGATION_SKILL]: `${headingText(DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_HEADINGS)}\n${DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_LITERALS.join("\n")}`,
   [DOCUMENTATION_FILE.CONTRIBUTING]: "# Contributing",
   [DOCUMENTATION_FILE.SECURITY]: "# Security",
 };
 
 strictEqual(evaluateDocumentation(valid).length, 0, "Valid public documentation failed the gate");
 
+const lateSetupGuards = {
+  ...valid,
+  [DOCUMENTATION_FILE.SETUP]: valid[DOCUMENTATION_FILE.SETUP].replace("## Guards\n", "").concat("\n## Guards\n"),
+};
+strictEqual(
+  evaluateDocumentation(lateSetupGuards).some((finding) => finding.reason === DOCUMENTATION_REASON.SETUP_GUARDS_NOT_FIRST),
+  true,
+  "Late setup guards were accepted",
+);
+
+const fencedSetupGuards = {
+  ...valid,
+  [DOCUMENTATION_FILE.SETUP]: valid[DOCUMENTATION_FILE.SETUP].replace("## Guards\n", "```md\n## Guards\n```\n"),
+};
+strictEqual(
+  evaluateDocumentation(fencedSetupGuards).some(
+    (finding) =>
+      finding.reason === DOCUMENTATION_REASON.HEADING_MISSING &&
+      finding.file === DOCUMENTATION_FILE.SETUP &&
+      finding.heading === DOCUMENTATION_REQUIREMENT.SETUP_FIRST_SECTION,
+  ),
+  true,
+  "Setup heading inside a fenced block was accepted",
+);
+
+const invalidSetupOrder = {
+  ...valid,
+  [DOCUMENTATION_FILE.SETUP]: valid[DOCUMENTATION_FILE.SETUP]
+    .replace("## Prerequisites\n", "## Setup Order Placeholder\n")
+    .replace("## Choose A Version\n", "## Prerequisites\n")
+    .replace("## Setup Order Placeholder\n", "## Choose A Version\n"),
+};
+strictEqual(
+  evaluateDocumentation(invalidSetupOrder).some((finding) => finding.reason === DOCUMENTATION_REASON.SETUP_SECTION_ORDER_INVALID),
+  true,
+  "Invalid setup section order was accepted",
+);
+
+const earlySetupBackground = {
+  ...valid,
+  [DOCUMENTATION_FILE.SETUP]: valid[DOCUMENTATION_FILE.SETUP]
+    .replace("## Background\n", "")
+    .replace("## Troubleshooting\n", "## Background\n## Troubleshooting\n"),
+};
+strictEqual(
+  evaluateDocumentation(earlySetupBackground).some((finding) => finding.reason === DOCUMENTATION_REASON.SETUP_BACKGROUND_NOT_LAST),
+  true,
+  "Setup background outside the final section was accepted",
+);
+
+const lateSetupEntryPoint = {
+  ...valid,
+  [DOCUMENTATION_FILE.README]: valid[DOCUMENTATION_FILE.README].replace("## Setup\n", "").concat("\n## Setup\n"),
+};
+strictEqual(
+  evaluateDocumentation(lateSetupEntryPoint).some((finding) => finding.reason === DOCUMENTATION_REASON.SETUP_ENTRY_POINT_NOT_FIRST),
+  true,
+  "Late setup entry point was accepted",
+);
+
+const duplicateSetupSection = {
+  ...valid,
+  [DOCUMENTATION_FILE.README]: `${valid[DOCUMENTATION_FILE.README]}\n## ${DOCUMENTATION_REQUIREMENT.README_FORBIDDEN_SETUP_HEADINGS[1]}`,
+};
+strictEqual(
+  evaluateDocumentation(duplicateSetupSection).some((finding) => finding.reason === DOCUMENTATION_REASON.DUPLICATE_SETUP_SECTION),
+  true,
+  "Duplicate README setup section was accepted",
+);
+
+for (const literal of DOCUMENTATION_REQUIREMENT.README_FORBIDDEN_SETUP_LITERALS) {
+  const duplicateSetupCommand = {
+    ...valid,
+    [DOCUMENTATION_FILE.README]: `${valid[DOCUMENTATION_FILE.README]}\n${literal}`,
+  };
+  strictEqual(
+    evaluateDocumentation(duplicateSetupCommand).some(
+      (finding) => finding.reason === DOCUMENTATION_REASON.DUPLICATE_SETUP_COMMAND && finding.literal === literal,
+    ),
+    true,
+    `Duplicate README setup command was accepted: ${literal}`,
+  );
+}
+
+const duplicateDistributionSetupCommand = {
+  ...valid,
+  [DOCUMENTATION_FILE.DISTRIBUTION]: `${valid[DOCUMENTATION_FILE.DISTRIBUTION]}\n${DOCUMENTATION_REQUIREMENT.DISTRIBUTION_FORBIDDEN_SETUP_LITERALS[0]}`,
+};
+strictEqual(
+  evaluateDocumentation(duplicateDistributionSetupCommand).some(
+    (finding) =>
+      finding.file === DOCUMENTATION_FILE.DISTRIBUTION &&
+      finding.reason === DOCUMENTATION_REASON.DUPLICATE_SETUP_COMMAND &&
+      finding.literal === DOCUMENTATION_REQUIREMENT.DISTRIBUTION_FORBIDDEN_SETUP_LITERALS[0],
+  ),
+  true,
+  "Duplicate distribution setup command was accepted",
+);
+
 const missingHeading = {...valid, [DOCUMENTATION_FILE.README]: valid[DOCUMENTATION_FILE.README].replace("## Verification", "")};
 strictEqual(
   evaluateDocumentation(missingHeading).some((finding) => finding.reason === DOCUMENTATION_REASON.HEADING_MISSING),
@@ -46,26 +148,137 @@ strictEqual(
   "Missing canonical example literal was accepted",
 );
 
-const missingMarketplaceUpgrade = {
+const missingSetupLink = {
+  ...valid,
+  [DOCUMENTATION_FILE.README]: valid[DOCUMENTATION_FILE.README].replaceAll(
+    `](${DOCUMENTATION_REQUIREMENT.README_LINKS[0]})`,
+    "](missing-setup.md)",
+  ),
+};
+strictEqual(
+  evaluateDocumentation(missingSetupLink).some(
+    (finding) => finding.reason === DOCUMENTATION_REASON.LINK_MISSING && finding.link === DOCUMENTATION_REQUIREMENT.README_LINKS[0],
+  ),
+  true,
+  "Missing setup README link was accepted",
+);
+
+const missingSetupEntryInstruction = {
+  ...valid,
+  [DOCUMENTATION_FILE.README]: valid[DOCUMENTATION_FILE.README].replace(DOCUMENTATION_REQUIREMENT.README_SETUP_ENTRY_LITERALS[0], ""),
+};
+strictEqual(
+  evaluateDocumentation(missingSetupEntryInstruction).some(
+    (finding) =>
+      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING &&
+      finding.literal === DOCUMENTATION_REQUIREMENT.README_SETUP_ENTRY_LITERALS[0],
+  ),
+  true,
+  "Missing README setup instruction was accepted",
+);
+
+const missingSetup = {...valid};
+delete missingSetup[DOCUMENTATION_FILE.SETUP];
+strictEqual(
+  evaluateDocumentation(missingSetup).some(
+    (finding) => finding.reason === DOCUMENTATION_REASON.FILE_MISSING && finding.file === DOCUMENTATION_FILE.SETUP,
+  ),
+  true,
+  "Missing setup guide was accepted",
+);
+
+for (const [literal, message] of [
+  ["does not override system, developer, organization, repository", "Missing setup safety boundary was accepted"],
+  ["server name: `semanticjsmcp`", "Missing generic MCP server name was accepted"],
+  ["codex plugin marketplace upgrade elnonathan", "Missing Codex marketplace refresh was accepted"],
+  ["Do not run `npm install semantic-js-mcp` without `--global`.", "Missing local npm installation prohibition was accepted"],
+  [
+    "Treat `EPERM`, `EACCES`, `TAR_ENTRY_ERROR`, or a missing-file error as a partial installation.",
+    "Missing partial-installation warning was accepted",
+  ],
+  ["Do not start `semantic-js-mcp serve` manually.", "Missing manual stdio startup prohibition was accepted"],
+  ["Choose exactly one installation route.", "Missing single-route boundary was accepted"],
+  ["No source-code call is required", "Missing installation authority boundary was accepted"],
+]) {
+  const missingInstruction = {
+    ...valid,
+    [DOCUMENTATION_FILE.SETUP]: valid[DOCUMENTATION_FILE.SETUP].replace(literal, ""),
+  };
+  strictEqual(
+    evaluateDocumentation(missingInstruction).some(
+      (finding) => finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING && finding.literal === literal,
+    ),
+    true,
+    message,
+  );
+}
+
+const missingCombinationInvariant = {
+  ...valid,
+  [DOCUMENTATION_FILE.SEMANTIC_NAVIGATION_SKILL]: valid[DOCUMENTATION_FILE.SEMANTIC_NAVIGATION_SKILL].replace(
+    DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_LITERALS[1],
+    "",
+  ),
+};
+strictEqual(
+  evaluateDocumentation(missingCombinationInvariant).some(
+    (finding) =>
+      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING &&
+      finding.literal === DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_LITERALS[1],
+  ),
+  true,
+  "Missing combination-invariant guidance was accepted",
+);
+
+const missingTrustedPublishingPolicy = {
+  ...valid,
+  [DOCUMENTATION_FILE.DISTRIBUTION]: valid[DOCUMENTATION_FILE.DISTRIBUTION].replace(DOCUMENTATION_REQUIREMENT.DISTRIBUTION_LITERALS[2], ""),
+};
+strictEqual(
+  evaluateDocumentation(missingTrustedPublishingPolicy).some(
+    (finding) =>
+      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING && finding.literal === DOCUMENTATION_REQUIREMENT.DISTRIBUTION_LITERALS[2],
+  ),
+  true,
+  "Missing trusted-publishing policy was accepted",
+);
+
+const missingPostpublicationOrder = {
   ...valid,
-  [DOCUMENTATION_FILE.README]: valid[DOCUMENTATION_FILE.README].replace(DOCUMENTATION_REQUIREMENT.README_LITERALS[0], ""),
+  [DOCUMENTATION_FILE.DISTRIBUTION]: valid[DOCUMENTATION_FILE.DISTRIBUTION].replace(DOCUMENTATION_REQUIREMENT.DISTRIBUTION_LITERALS[5], ""),
 };
 strictEqual(
-  evaluateDocumentation(missingMarketplaceUpgrade).some(
+  evaluateDocumentation(missingPostpublicationOrder).some(
     (finding) =>
-      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING && finding.literal === DOCUMENTATION_REQUIREMENT.README_LITERALS[0],
+      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING && finding.literal === DOCUMENTATION_REQUIREMENT.DISTRIBUTION_LITERALS[5],
   ),
   true,
-  "Missing marketplace upgrade guidance was accepted",
+  "Missing postpublication order was accepted",
 );
 
 process.stdout.write(
   `${JSON.stringify(
     {
       validDocumentation: "pass",
+      lateSetupGuards: "rejected",
+      fencedSetupGuards: "rejected",
+      invalidSetupOrder: "rejected",
+      earlySetupBackground: "rejected",
+      lateSetupEntryPoint: "rejected",
+      duplicateSetupSection: "rejected",
+      duplicateSetupCommand: "rejected",
+      duplicateDistributionSetupCommand: "rejected",
       missingHeading: "rejected",
       missingLiteral: "rejected",
-      missingMarketplaceUpgrade: "rejected",
+      missingSetupLink: "rejected",
+      missingSetupEntryInstruction: "rejected",
+      missingSetup: "rejected",
+      missingSetupSafetyBoundary: "rejected",
+      missingGenericServerName: "rejected",
+      missingCodexMarketplaceRefresh: "rejected",
+      missingCombinationInvariant: "rejected",
+      missingTrustedPublishingPolicy: "rejected",
+      missingPostpublicationOrder: "rejected",
       privateCoordination: "rejected",
     },
     null,

package/scripts/documentation-gate.mjs

@@ -13,15 +13,49 @@ import {
   PUBLIC_ROOT_DOCUMENT,
 } from "./documentation-contract.mjs";
 
+function markdownStructuralLines(source) {
+  const lines = [];
+  let fence;
+  for (const line of source.split("\n")) {
+    const match = /^\s{0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+    if (match && fence === undefined) {
+      fence = {marker: match[1][0], length: match[1].length};
+      continue;
+    }
+    if (match && match[1][0] === fence?.marker && match[1].length >= fence.length && match[2].trim() === "") {
+      fence = undefined;
+      continue;
+    }
+    if (fence === undefined) lines.push(line);
+  }
+  return lines;
+}
+
 function markdownHeadings(source) {
   return new Set(
-    source
-      .split("\n")
+    markdownStructuralLines(source)
       .map((line) => /^#{1,6}\s+(.+?)\s*$/.exec(line)?.[1])
       .filter(Boolean),
   );
 }
 
+function levelTwoHeadings(source) {
+  return markdownStructuralLines(source)
+    .map((line) => /^##\s+(.+?)\s*$/.exec(line)?.[1])
+    .filter(Boolean);
+}
+
+function requiredHeadingsAreOrdered(source, requiredHeadings) {
+  const headings = levelTwoHeadings(source);
+  let nextIndex = 0;
+  for (const requiredHeading of requiredHeadings) {
+    const index = headings.indexOf(requiredHeading, nextIndex);
+    if (index === -1) return false;
+    nextIndex = index + 1;
+  }
+  return true;
+}
+
 function repositoryPath(root, absolute) {
   return path.relative(root, absolute).split(path.sep).join("/");
 }
@@ -35,7 +69,10 @@ export function evaluateDocumentation(documents) {
 
   const headingRequirements = [
     [DOCUMENTATION_FILE.README, DOCUMENTATION_REQUIREMENT.README_HEADINGS],
+    [DOCUMENTATION_FILE.SETUP, DOCUMENTATION_REQUIREMENT.SETUP_HEADINGS],
+    [DOCUMENTATION_FILE.DISTRIBUTION, DOCUMENTATION_REQUIREMENT.DISTRIBUTION_HEADINGS],
     [DOCUMENTATION_FILE.GETTING_STARTED, DOCUMENTATION_REQUIREMENT.GETTING_STARTED_HEADINGS],
+    [DOCUMENTATION_FILE.SEMANTIC_NAVIGATION_SKILL, DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_HEADINGS],
   ];
   for (const [file, requiredHeadings] of headingRequirements) {
     if (documents[file] === undefined) continue;
@@ -48,14 +85,30 @@ export function evaluateDocumentation(documents) {
 
   const readme = documents[DOCUMENTATION_FILE.README];
   if (readme !== undefined) {
+    if (levelTwoHeadings(readme)[0] !== DOCUMENTATION_REQUIREMENT.README_FIRST_SECTION) {
+      findings.push({
+        file: DOCUMENTATION_FILE.README,
+        reason: DOCUMENTATION_REASON.SETUP_ENTRY_POINT_NOT_FIRST,
+        expectedHeading: DOCUMENTATION_REQUIREMENT.README_FIRST_SECTION,
+      });
+    }
     for (const link of DOCUMENTATION_REQUIREMENT.README_LINKS) {
       if (readme.includes(`](${link})`)) continue;
       findings.push({file: DOCUMENTATION_FILE.README, reason: DOCUMENTATION_REASON.LINK_MISSING, link});
     }
-    for (const literal of DOCUMENTATION_REQUIREMENT.README_LITERALS) {
+    for (const literal of DOCUMENTATION_REQUIREMENT.README_SETUP_ENTRY_LITERALS) {
       if (readme.includes(literal)) continue;
       findings.push({file: DOCUMENTATION_FILE.README, reason: DOCUMENTATION_REASON.LITERAL_MISSING, literal});
     }
+    const readmeHeadings = markdownHeadings(readme);
+    for (const heading of DOCUMENTATION_REQUIREMENT.README_FORBIDDEN_SETUP_HEADINGS) {
+      if (!readmeHeadings.has(heading)) continue;
+      findings.push({file: DOCUMENTATION_FILE.README, reason: DOCUMENTATION_REASON.DUPLICATE_SETUP_SECTION, heading});
+    }
+    for (const literal of DOCUMENTATION_REQUIREMENT.README_FORBIDDEN_SETUP_LITERALS) {
+      if (!readme.includes(literal)) continue;
+      findings.push({file: DOCUMENTATION_FILE.README, reason: DOCUMENTATION_REASON.DUPLICATE_SETUP_COMMAND, literal});
+    }
   }
 
   const gettingStarted = documents[DOCUMENTATION_FILE.GETTING_STARTED];
@@ -66,6 +119,59 @@ export function evaluateDocumentation(documents) {
     }
   }
 
+  const setup = documents[DOCUMENTATION_FILE.SETUP];
+  if (setup !== undefined) {
+    const setupHeadings = levelTwoHeadings(setup);
+    if (setupHeadings[0] !== DOCUMENTATION_REQUIREMENT.SETUP_FIRST_SECTION) {
+      findings.push({
+        file: DOCUMENTATION_FILE.SETUP,
+        reason: DOCUMENTATION_REASON.SETUP_GUARDS_NOT_FIRST,
+        expectedHeading: DOCUMENTATION_REQUIREMENT.SETUP_FIRST_SECTION,
+      });
+    }
+    if (!requiredHeadingsAreOrdered(setup, DOCUMENTATION_REQUIREMENT.SETUP_HEADINGS)) {
+      findings.push({
+        file: DOCUMENTATION_FILE.SETUP,
+        reason: DOCUMENTATION_REASON.SETUP_SECTION_ORDER_INVALID,
+      });
+    }
+    if (setupHeadings.at(-1) !== DOCUMENTATION_REQUIREMENT.SETUP_LAST_SECTION) {
+      findings.push({
+        file: DOCUMENTATION_FILE.SETUP,
+        reason: DOCUMENTATION_REASON.SETUP_BACKGROUND_NOT_LAST,
+        expectedHeading: DOCUMENTATION_REQUIREMENT.SETUP_LAST_SECTION,
+      });
+    }
+    for (const literal of DOCUMENTATION_REQUIREMENT.SETUP_LITERALS) {
+      if (setup.includes(literal)) continue;
+      findings.push({file: DOCUMENTATION_FILE.SETUP, reason: DOCUMENTATION_REASON.LITERAL_MISSING, literal});
+    }
+  }
+
+  const semanticNavigationSkill = documents[DOCUMENTATION_FILE.SEMANTIC_NAVIGATION_SKILL];
+  if (semanticNavigationSkill !== undefined) {
+    for (const literal of DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_LITERALS) {
+      if (semanticNavigationSkill.includes(literal)) continue;
+      findings.push({
+        file: DOCUMENTATION_FILE.SEMANTIC_NAVIGATION_SKILL,
+        reason: DOCUMENTATION_REASON.LITERAL_MISSING,
+        literal,
+      });
+    }
+  }
+
+  const distribution = documents[DOCUMENTATION_FILE.DISTRIBUTION];
+  if (distribution !== undefined) {
+    for (const literal of DOCUMENTATION_REQUIREMENT.DISTRIBUTION_LITERALS) {
+      if (distribution.includes(literal)) continue;
+      findings.push({file: DOCUMENTATION_FILE.DISTRIBUTION, reason: DOCUMENTATION_REASON.LITERAL_MISSING, literal});
+    }
+    for (const literal of DOCUMENTATION_REQUIREMENT.DISTRIBUTION_FORBIDDEN_SETUP_LITERALS) {
+      if (!distribution.includes(literal)) continue;
+      findings.push({file: DOCUMENTATION_FILE.DISTRIBUTION, reason: DOCUMENTATION_REASON.DUPLICATE_SETUP_COMMAND, literal});
+    }
+  }
+
   for (const [file, source] of Object.entries(documents)) {
     if (PRIVATE_COORDINATION_PATTERN.test(source)) {
       findings.push({file, reason: DOCUMENTATION_REASON.PRIVATE_COORDINATION});

package/skills/semantic-navigation/SKILL.md

@@ -131,6 +131,24 @@ Omitted collection limits still mean unlimited. The server never inserts a hidde
 4. Inspect focused tests for asserted behavior; run them when permitted.
 5. Re-read cited locations before presenting a finding.
 
+### Preserve Combination Invariants
+
+When a change combines multiple sources into one domain value or introduces
+precedence, fallback, normalization, ordering, or merge logic:
+
+1. Identify every producer of the value, not only the source involved in the
+   reported example.
+2. Find existing comparison, normalization, fallback, and combination helpers
+   and state the invariant they encode.
+3. Inspect direct consumers and focused tests to confirm how the combined value
+   is treated as a contract.
+4. Exercise a boundary case that could disprove the proposed precedence or
+   merge rule.
+
+Semantic tools verify the identities and references discovered during this
+work. Use text search, direct source inspection, tests, and domain reasoning for
+conceptual relationships that an LSP cannot establish.
+
 An actionable finding requires a reachable path, a violated contract, and concrete impact. For commit or pull-request reviews, compare with the exact parent and classify material conclusions as `introduced`, `modified`, or `pre-existing`.
 
 Empty symbol, reference, or diagnostic results are evidence to investigate. Use `collection`, `textSearch`, `rg`, and direct inspection to establish the supported conclusion.

package/skills/semantic-navigation/references/protocol-literals.md

@@ -2,7 +2,7 @@
 
 Generated from `protocol.mjs`. Do not edit this file directly.
 
-Producer: `semantic-js-mcp` version `0.10.1`
+Producer: `semantic-js-mcp` version `0.10.3`
 Display name: `Semantic JS MCP`
 Result schema version: `7`