semantic-js-mcp 0.10.0 → 0.10.2

package/.codex-plugin/plugin.json

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

package/AGENT_SETUP.md

@@ -0,0 +1,176 @@
+# Agent Setup
+
+This guide is for a coding agent whose user has explicitly requested that it
+install, configure, update, verify, roll back, or remove Semantic JS MCP. It is
+not an instruction to change an environment merely because this file was read.
+
+## Scope
+
+First identify the application that will run the MCP server. That application
+is the MCP host. Use the verified Codex procedure only for Codex. For every
+other host, use the generic stdio procedure below and translate its fields into
+the host's documented configuration format. Do not guess a configuration file
+or schema.
+
+Semantic JS MCP requires Node.js 22 or newer and `rg` (ripgrep) on `PATH`.
+Before changing host configuration, run:
+
+```bash
+node --version
+rg --version
+```
+
+Stop if Node.js is older than 22 or either command is unavailable. Report the
+missing prerequisite. Do not continue with a partial installation.
+
+## Safety Boundaries
+
+This guide does not override system, developer, organization, repository, or
+host security policy.
+
+- Inspect existing configuration before editing it and change only the entry
+  approved by the user.
+- Request any approval required for package installation, global writes,
+  configuration changes, network access, or process restart.
+- Never request or expose credentials, disable security controls, or execute a
+  remote shell pipeline.
+- Preserve every unrelated MCP server and setting. Never replace an entire
+  configuration file to add one server.
+- Stop and report the blocker when the requested host or prerequisite cannot be
+  verified safely.
+
+## Installation Procedure
+
+### Codex
+
+Use the public marketplace adapter:
+
+```bash
+codex plugin marketplace add elnonathan/semantic-js-mcp
+codex plugin add semantic-js-mcp@elnonathan
+codex plugin list
+```
+
+Start a new Codex session after installation. The plugin supplies both the MCP
+server and the semantic-navigation skill.
+
+### Generic Stdio Hosts
+
+Use this procedure only when the host supports local MCP servers over stdio. If
+that capability cannot be confirmed from installed help or host documentation,
+stop and report that the host is unsupported or unverified.
+
+After the user approves the package installation and configuration change,
+install the executable:
+
+```bash
+npm install --global semantic-js-mcp
+```
+
+Inspect the existing host configuration. Add exactly one MCP server with these
+values:
+
+- server name: `semanticjsmcp`
+- transport: `stdio`
+- executable or command: `semantic-js-mcp`
+- arguments: one argument, `serve`
+- enabled: `true`, when the host has an enabled field
+
+Do not configure a URL, port, shell command, or credentials. The host must
+start `semantic-js-mcp serve` as a local child process and communicate through
+standard input and standard output. Translate the values above into the host's
+documented schema; do not copy a configuration shape from a different host.
+
+Save the smallest possible change. Restart or reload the host when its
+documentation requires it.
+
+## Verification
+
+For an executable installation, record the installed version and run the
+doctor:
+
+```bash
+semantic-js-mcp --version
+semantic-js-mcp doctor
+```
+
+Read the structured doctor result literally:
+
+- `pass`: continue to host tool verification.
+- `untrusted`: continue to host tool verification and report the stated
+  uncertainty. Do not describe it as `pass`.
+- `blocked` or `fail`: stop, correct the reported problem when authorized, or
+  report the blocker. Do not claim a successful installation.
+
+Then verify the host discovers tools whose base names begin with `lsp_`. A host
+may display the server name before the base name. Execute one read-only call
+such as `lsp_document_symbols` against a user-approved JavaScript, TypeScript,
+or Vue file. Do not claim successful installation from configuration text
+alone.
+
+For a Codex plugin installation without a global executable, verify the version
+with `codex plugin list`, start a new session, and confirm MCP tool discovery
+there.
+
+Installation is successful only when the host discovers the MCP tools and one
+read-only `lsp_*` call returns a result. Package installation or configuration
+text alone is not success.
+
+## Update And Rollback
+
+Update an existing Codex installation by refreshing its marketplace snapshot
+before reinstalling:
+
+```bash
+codex plugin marketplace upgrade elnonathan
+codex plugin add semantic-js-mcp@elnonathan
+codex plugin list
+```
+
+Update a global npm installation with:
+
+```bash
+npm install --global semantic-js-mcp@latest
+```
+
+Before updating, record the working version. To roll back a global installation,
+install that exact known version, for example:
+
+```bash
+npm install --global semantic-js-mcp@0.10.1
+```
+
+For a host adapter, restore the previously recorded package version and host
+configuration together. Do not replace or remove unrelated configuration while
+rolling back.
+
+## Removal
+
+For Codex, remove only this plugin:
+
+```bash
+codex plugin remove semantic-js-mcp@elnonathan
+```
+
+Remove the `elnonathan` marketplace only when the user confirms that no other
+installed plugin uses it:
+
+```bash
+codex plugin marketplace remove elnonathan
+```
+
+For a global executable, remove the package and only its `semanticjsmcp` MCP
+entry:
+
+```bash
+npm uninstall --global semantic-js-mcp
+```
+
+Restart the host and confirm the tools are no longer registered.
+
+## Completion Report
+
+Report the detected host, installed or removed version, exact configuration
+entry changed, doctor status when available, tool-discovery result, required
+restart, and any remaining uncertainty. Do not include credentials or unrelated
+configuration values.

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [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
+
+- Publish release tags to npm through a protected GitHub Actions environment using short-lived OIDC credentials and automatic provenance.
+
+### Fixed
+
+- Document and validate marketplace refresh before reinstalling an existing Codex plugin.
+- Install and verify ripgrep in the trusted-publishing runner before executing the release gate.
+
 ## [0.10.0] - 2026-07-17
 
 ### Added

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.
 
+When a user explicitly asks a coding agent to install or configure the package, the agent should follow the [agent setup guide](AGENT_SETUP.md).
+
 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.**
@@ -16,7 +18,7 @@ For each file, it identifies the owning workspace and uses the corresponding Typ
 
 ## Project Status
 
-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.
+Version `0.10.2` 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
 
@@ -31,6 +33,18 @@ 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:
@@ -78,7 +92,7 @@ For an MCP host that accepts a direct stdio configuration, point it at the check
 ```json
 {
   "mcpServers": {
-    "semantic-js-mcp": {
+    "semanticjsmcp": {
       "command": "node",
       "args": ["/absolute/path/to/semantic-js-mcp/server.mjs"]
     }
@@ -93,7 +107,7 @@ When the package executable is available on the host's `PATH`, the equivalent st
 ```json
 {
   "mcpServers": {
-    "semantic-js-mcp": {
+    "semanticjsmcp": {
       "command": "semantic-js-mcp",
       "args": ["serve"]
     }

package/docs/distribution.md

@@ -11,6 +11,16 @@ 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
+```
+
+`plugin add` reinstalls the plugin selected by the refreshed marketplace. Start a new Codex session after the listed version matches the release being installed.
+
 ## Executable
 
 ```bash
@@ -47,6 +57,7 @@ npm run check
 npm run check:runtime
 npm run check:documentation
 npm run smoke:ci
+npm run smoke:publish
 npm run smoke:negative
 npm run smoke:doctor
 npm run smoke
@@ -68,6 +79,14 @@ The local release gate runs every configured source, runtime, semantic, evaluati
 
 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`.
 
+## npm Trusted Publishing
+
+The `publish.yml` workflow publishes tags matching `v*` from a GitHub-hosted Node.js 24 runner. It requires the protected `npm-publish` environment, verifies that the tag exactly matches the package version, runs the complete release gate, and publishes through npm Trusted Publishing with OIDC. No long-lived npm token is used. npm generates provenance automatically for the public package.
+
+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.
+
 ## 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

@@ -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.0",
+  "version": "0.10.2",
   "description": "Semantic understanding of JavaScript codebases for AI agents",
   "keywords": [
     "mcp",
@@ -28,6 +28,7 @@
     ".codex-plugin/",
     ".mcp.json",
     ".prettierrc.json",
+    "AGENT_SETUP.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "ROADMAP.md",
@@ -44,13 +45,14 @@
     "node": ">=22"
   },
   "scripts": {
-    "check": "npm run format:check && node --check protocol.mjs && node --check server.mjs && node --check cli.mjs && node --check lib/runtime.mjs && node --check lib/doctor.mjs && node --check lib/semantic-evidence.mjs && node --check lib/pending-requests.mjs && node --check lib/stable-collection.mjs && node --check scripts/generate-protocol-reference.mjs && node --check scripts/check-protocol-literals.mjs && node --check scripts/check-runtime.mjs && node --check scripts/documentation-contract.mjs && node --check scripts/documentation-gate.mjs && node --check scripts/documentation-gate-smoke.mjs && node --check scripts/semantic-js-mcp-ci.mjs && node --check scripts/ci-smoke.mjs && node --check scripts/negative-verification-smoke.mjs && node --check scripts/doctor-smoke.mjs && node --check scripts/smoke.mjs && node --check scripts/vue-smoke.mjs && node --check scripts/lifecycle-smoke.mjs && node --check scripts/lifecycle-memory-contract.mjs && node --check scripts/lifecycle-memory-observer.mjs && node --check scripts/lifecycle-memory-benchmark.mjs && node --check scripts/benchmark.mjs && node --check scripts/distribution-policy.mjs && node --check scripts/distribution-smoke.mjs && node --check scripts/release-contract.mjs && node --check scripts/release-verify.mjs && node --check scripts/release-smoke.mjs && node --check scripts/postpublication-smoke.mjs && node --check scripts/codex-plugin-verification.mjs && node --check scripts/agent-evaluation-contract.mjs && node --check scripts/agent-evaluation.mjs && node --check scripts/agent-evaluation-smoke.mjs && node --check scripts/repository-matrix-contract.mjs && node --check scripts/repository-matrix.mjs && node --check scripts/repository-matrix-smoke.mjs && node scripts/generate-protocol-reference.mjs --check && node scripts/check-protocol-literals.mjs && node scripts/documentation-gate-smoke.mjs",
+    "check": "npm run format:check && node --check protocol.mjs && node --check server.mjs && node --check cli.mjs && node --check lib/runtime.mjs && node --check lib/doctor.mjs && node --check lib/semantic-evidence.mjs && node --check lib/pending-requests.mjs && node --check lib/stable-collection.mjs && node --check scripts/generate-protocol-reference.mjs && node --check scripts/check-protocol-literals.mjs && node --check scripts/check-runtime.mjs && node --check scripts/documentation-contract.mjs && node --check scripts/documentation-gate.mjs && node --check scripts/documentation-gate-smoke.mjs && node --check scripts/semantic-js-mcp-ci.mjs && node --check scripts/ci-smoke.mjs && node --check scripts/publish-workflow-smoke.mjs && node --check scripts/negative-verification-smoke.mjs && node --check scripts/doctor-smoke.mjs && node --check scripts/smoke.mjs && node --check scripts/vue-smoke.mjs && node --check scripts/lifecycle-smoke.mjs && node --check scripts/lifecycle-memory-contract.mjs && node --check scripts/lifecycle-memory-observer.mjs && node --check scripts/lifecycle-memory-benchmark.mjs && node --check scripts/benchmark.mjs && node --check scripts/distribution-policy.mjs && node --check scripts/distribution-smoke.mjs && node --check scripts/release-contract.mjs && node --check scripts/release-verify.mjs && node --check scripts/release-smoke.mjs && node --check scripts/postpublication-smoke.mjs && node --check scripts/codex-plugin-verification.mjs && node --check scripts/agent-evaluation-contract.mjs && node --check scripts/agent-evaluation.mjs && node --check scripts/agent-evaluation-smoke.mjs && node --check scripts/repository-matrix-contract.mjs && node --check scripts/repository-matrix.mjs && node --check scripts/repository-matrix-smoke.mjs && node scripts/generate-protocol-reference.mjs --check && node scripts/check-protocol-literals.mjs && node scripts/documentation-gate-smoke.mjs",
     "check:runtime": "node scripts/check-runtime.mjs",
     "check:documentation": "node scripts/documentation-gate.mjs",
     "doctor": "node cli.mjs doctor",
     "ci:evaluate": "node scripts/semantic-js-mcp-ci.mjs",
     "smoke": "node scripts/smoke.mjs",
     "smoke:ci": "node scripts/ci-smoke.mjs",
+    "smoke:publish": "node scripts/publish-workflow-smoke.mjs",
     "smoke:negative": "node scripts/negative-verification-smoke.mjs",
     "smoke:doctor": "node scripts/doctor-smoke.mjs",
     "smoke:vue": "node scripts/vue-smoke.mjs",

package/protocol.mjs

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

package/scripts/codex-plugin-verification.mjs

@@ -71,6 +71,25 @@ export async function verifyCodexPlugin({version, workspace, spawn, runCommand})
     ];
   }
 
+  const upgrade = await execute(CODEX_DISTRIBUTION.EXECUTABLE, [
+    CODEX_DISTRIBUTION.PLUGIN_COMMAND,
+    CODEX_DISTRIBUTION.MARKETPLACE_COMMAND,
+    CODEX_DISTRIBUTION.UPGRADE_COMMAND,
+    CODEX_DISTRIBUTION.MARKETPLACE_NAME,
+    CODEX_DISTRIBUTION.JSON_ARGUMENT,
+  ]);
+  if (upgrade.exitCode !== CI_EXIT_CODE.PASS) {
+    const unavailable = upgrade.exitCode === undefined || networkUnavailable(upgrade);
+    return [
+      check(
+        RELEASE_CHECK.CODEX_MARKETPLACE,
+        unavailable ? CI_STATUS.BLOCKED : CI_STATUS.FAIL,
+        unavailable ? RELEASE_REASON.CODEX_MARKETPLACE_UNAVAILABLE : RELEASE_REASON.CODEX_MARKETPLACE_FAILED,
+        {marketplaceRef, message: failureMessage(upgrade)},
+      ),
+    ];
+  }
+
   const checks = [check(RELEASE_CHECK.CODEX_MARKETPLACE, CI_STATUS.PASS, RELEASE_REASON.CHECK_COMPLETED, {marketplaceRef})];
   const installation = await execute(CODEX_DISTRIBUTION.EXECUTABLE, [
     CODEX_DISTRIBUTION.PLUGIN_COMMAND,

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",
+  AGENT_SETUP: "AGENT_SETUP.md",
   LICENSE: "LICENSE",
   CLI: "cli.mjs",
   SERVER: "server.mjs",
@@ -30,6 +31,7 @@ export const CODEX_DISTRIBUTION = Object.freeze({
   PLUGIN_COMMAND: "plugin",
   MARKETPLACE_COMMAND: "marketplace",
   ADD_COMMAND: "add",
+  UPGRADE_COMMAND: "upgrade",
   LIST_COMMAND: "list",
   REF_ARGUMENT: "--ref",
   JSON_ARGUMENT: "--json",

package/scripts/documentation-contract.mjs

@@ -2,28 +2,68 @@ import {DOCTOR_REASON, SEMANTIC_EVIDENCE_FOLLOW_UP_REASON} from "../protocol.mjs
 
 export const DOCUMENTATION_FILE = Object.freeze({
   README: "README.md",
+  AGENT_SETUP: "AGENT_SETUP.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([
+  "AGENT_SETUP.md",
+  "CHANGELOG.md",
+  "CONTRIBUTING.md",
+  "README.md",
+  "ROADMAP.md",
+  "SECURITY.md",
+]);
 
 export const PUBLIC_DOCUMENT_DIRECTORY = Object.freeze(["docs", "skills"]);
 
 export const DOCUMENTATION_REQUIREMENT = Object.freeze({
-  README_HEADINGS: Object.freeze(["Installation", "Runtime", "Verification", "Current Limitations", "Reporting Problems"]),
+  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"]),
   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"]),
+  AGENT_SETUP_HEADINGS: Object.freeze([
+    "Scope",
+    "Safety Boundaries",
+    "Installation Procedure",
+    "Verification",
+    "Update And Rollback",
+    "Removal",
+    "Completion Report",
+  ]),
+  SEMANTIC_NAVIGATION_SKILL_HEADINGS: Object.freeze(["Preserve Combination Invariants"]),
+  README_LINKS: Object.freeze(["AGENT_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]),
+  AGENT_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`",
+  ]),
+  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({

package/scripts/documentation-gate-smoke.mjs

@@ -6,8 +6,10 @@ 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")}`,
+  [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.AGENT_SETUP]: `${headingText(DOCUMENTATION_REQUIREMENT.AGENT_SETUP_HEADINGS)}\n${DOCUMENTATION_REQUIREMENT.AGENT_SETUP_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",
 };
@@ -46,9 +48,98 @@ strictEqual(
   "Missing canonical example literal was accepted",
 );
 
+const missingMarketplaceUpgrade = {
+  ...valid,
+  [DOCUMENTATION_FILE.README]: valid[DOCUMENTATION_FILE.README].replace(DOCUMENTATION_REQUIREMENT.README_LITERALS[0], ""),
+};
+strictEqual(
+  evaluateDocumentation(missingMarketplaceUpgrade).some(
+    (finding) =>
+      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING && finding.literal === DOCUMENTATION_REQUIREMENT.README_LITERALS[0],
+  ),
+  true,
+  "Missing marketplace upgrade guidance was accepted",
+);
+
+const missingAgentSetupLink = {
+  ...valid,
+  [DOCUMENTATION_FILE.README]: valid[DOCUMENTATION_FILE.README].replace(`[doc](${DOCUMENTATION_REQUIREMENT.README_LINKS[0]})`, ""),
+};
+strictEqual(
+  evaluateDocumentation(missingAgentSetupLink).some(
+    (finding) => finding.reason === DOCUMENTATION_REASON.LINK_MISSING && finding.link === DOCUMENTATION_REQUIREMENT.README_LINKS[0],
+  ),
+  true,
+  "Missing agent setup README link was accepted",
+);
+
+const missingAgentSetup = {...valid};
+delete missingAgentSetup[DOCUMENTATION_FILE.AGENT_SETUP];
+strictEqual(
+  evaluateDocumentation(missingAgentSetup).some(
+    (finding) => finding.reason === DOCUMENTATION_REASON.FILE_MISSING && finding.file === DOCUMENTATION_FILE.AGENT_SETUP,
+  ),
+  true,
+  "Missing agent setup guide was accepted",
+);
+
+const missingAgentSafetyBoundary = {
+  ...valid,
+  [DOCUMENTATION_FILE.AGENT_SETUP]: valid[DOCUMENTATION_FILE.AGENT_SETUP].replace(DOCUMENTATION_REQUIREMENT.AGENT_SETUP_LITERALS[2], ""),
+};
+strictEqual(
+  evaluateDocumentation(missingAgentSafetyBoundary).some(
+    (finding) =>
+      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING && finding.literal === DOCUMENTATION_REQUIREMENT.AGENT_SETUP_LITERALS[2],
+  ),
+  true,
+  "Missing agent setup safety boundary was accepted",
+);
+
+const missingGenericServerName = {
+  ...valid,
+  [DOCUMENTATION_FILE.AGENT_SETUP]: valid[DOCUMENTATION_FILE.AGENT_SETUP].replace(DOCUMENTATION_REQUIREMENT.AGENT_SETUP_LITERALS[4], ""),
+};
+strictEqual(
+  evaluateDocumentation(missingGenericServerName).some(
+    (finding) =>
+      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING && finding.literal === DOCUMENTATION_REQUIREMENT.AGENT_SETUP_LITERALS[4],
+  ),
+  true,
+  "Missing generic MCP server name was accepted",
+);
+
+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",
+);
+
 process.stdout.write(
   `${JSON.stringify(
-    {validDocumentation: "pass", missingHeading: "rejected", missingLiteral: "rejected", privateCoordination: "rejected"},
+    {
+      validDocumentation: "pass",
+      missingHeading: "rejected",
+      missingLiteral: "rejected",
+      missingMarketplaceUpgrade: "rejected",
+      missingAgentSetupLink: "rejected",
+      missingAgentSetup: "rejected",
+      missingAgentSafetyBoundary: "rejected",
+      missingGenericServerName: "rejected",
+      missingCombinationInvariant: "rejected",
+      privateCoordination: "rejected",
+    },
     null,
     2,
   )}\n`,

package/scripts/documentation-gate.mjs

@@ -35,7 +35,9 @@ export function evaluateDocumentation(documents) {
 
   const headingRequirements = [
     [DOCUMENTATION_FILE.README, DOCUMENTATION_REQUIREMENT.README_HEADINGS],
+    [DOCUMENTATION_FILE.AGENT_SETUP, DOCUMENTATION_REQUIREMENT.AGENT_SETUP_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;
@@ -52,6 +54,10 @@ export function evaluateDocumentation(documents) {
       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) {
+      if (readme.includes(literal)) continue;
+      findings.push({file: DOCUMENTATION_FILE.README, reason: DOCUMENTATION_REASON.LITERAL_MISSING, literal});
+    }
   }
 
   const gettingStarted = documents[DOCUMENTATION_FILE.GETTING_STARTED];
@@ -62,6 +68,26 @@ export function evaluateDocumentation(documents) {
     }
   }
 
+  const agentSetup = documents[DOCUMENTATION_FILE.AGENT_SETUP];
+  if (agentSetup !== undefined) {
+    for (const literal of DOCUMENTATION_REQUIREMENT.AGENT_SETUP_LITERALS) {
+      if (agentSetup.includes(literal)) continue;
+      findings.push({file: DOCUMENTATION_FILE.AGENT_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,
+      });
+    }
+  }
+
   for (const [file, source] of Object.entries(documents)) {
     if (PRIVATE_COORDINATION_PATTERN.test(source)) {
       findings.push({file, reason: DOCUMENTATION_REASON.PRIVATE_COORDINATION});

package/scripts/publish-workflow-smoke.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+import {deepStrictEqual, strictEqual} from "node:assert";
+import {readFile} from "node:fs/promises";
+import {fileURLToPath} from "node:url";
+import path from "node:path";
+import {parse} from "yaml";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const workflowFile = path.join(root, ".github", "workflows", "publish.yml");
+const workflowText = await readFile(workflowFile, "utf8");
+const workflow = parse(workflowText);
+const publish = workflow.jobs?.publish;
+const steps = publish?.steps || [];
+const setupNode = steps.find((step) => step.uses === "actions/setup-node@v6");
+const commands = steps.flatMap((step) => (typeof step.run === "string" ? [step.run] : []));
+
+deepStrictEqual(Object.keys(workflow.on || {}), ["push"], "Publish workflow must only run from tag pushes");
+deepStrictEqual(workflow.on?.push?.tags, ["v*"], "Publish workflow must run only for release tags");
+deepStrictEqual(
+  workflow.permissions,
+  {contents: "read", "id-token": "write"},
+  "Publish workflow must grant only repository read and OIDC permissions",
+);
+strictEqual(publish?.if, "github.repository == 'elnonathan/semantic-js-mcp'", "Publishing must be restricted to the canonical repository");
+strictEqual(publish?.["runs-on"], "ubuntu-latest", "Publishing must use a GitHub-hosted runner");
+strictEqual(publish?.environment, "npm-publish", "Publishing must use the protected npm environment");
+strictEqual(workflow.concurrency?.["cancel-in-progress"], false, "An active publication must never be cancelled by another tag");
+strictEqual(setupNode?.with?.["node-version"], 24, "Publishing must use Node.js 24");
+strictEqual(setupNode?.with?.["registry-url"], "https://registry.npmjs.org", "Publishing must target npmjs.org");
+strictEqual(setupNode?.with?.["package-manager-cache"], false, "Release builds must not use a package-manager cache");
+strictEqual(
+  commands.includes("sudo apt-get update && sudo apt-get install --yes ripgrep"),
+  true,
+  "Publishing must install the required ripgrep executable",
+);
+strictEqual(commands.includes("rg --version"), true, "Publishing must verify ripgrep before the release gate");
+strictEqual(commands.includes("npm install --global npm@11.17.0"), true, "Publishing must install the verified npm CLI");
+strictEqual(commands.includes("npm ci"), true, "Publishing must install the locked dependency tree");
+strictEqual(commands.includes("npm run release:verify"), true, "Publishing must run the complete release gate");
+strictEqual(commands.includes("npm publish --access public"), true, "Publishing must use the public OIDC publish path");
+strictEqual(
+  commands.some((command) => command.includes("GITHUB_REF_NAME") && command.includes("package.json")),
+  true,
+  "Publishing must reject a tag that differs from the package version",
+);
+strictEqual(workflowText.includes("NODE_AUTH_TOKEN"), false, "OIDC publishing must not use an npm token");
+strictEqual(workflowText.includes("secrets."), false, "OIDC publishing must not read repository secrets");
+
+process.stdout.write(
+  `${JSON.stringify(
+    {
+      workflow: "publish.yml",
+      trigger: "release-tags",
+      authentication: "oidc",
+      environment: publish.environment,
+      tokenSecret: "absent",
+    },
+    null,
+    2,
+  )}\n`,
+);

package/scripts/release-contract.mjs

@@ -10,6 +10,7 @@ export const RELEASE_CHECK = Object.freeze({
   RUNTIME: "runtime",
   DOCUMENTATION: "documentation",
   CI_POLICY: "ci-policy",
+  PUBLISH_WORKFLOW: "publish-workflow",
   NEGATIVE_VERIFICATION: "negative-verification",
   DOCTOR: "doctor",
   TYPESCRIPT_SMOKE: "typescript-smoke",
@@ -57,6 +58,7 @@ export const RELEASE_LOCAL_CHECKS = Object.freeze([
   Object.freeze({name: RELEASE_CHECK.RUNTIME, npmScript: "check:runtime"}),
   Object.freeze({name: RELEASE_CHECK.DOCUMENTATION, npmScript: "check:documentation"}),
   Object.freeze({name: RELEASE_CHECK.CI_POLICY, npmScript: "smoke:ci"}),
+  Object.freeze({name: RELEASE_CHECK.PUBLISH_WORKFLOW, npmScript: "smoke:publish"}),
   Object.freeze({name: RELEASE_CHECK.NEGATIVE_VERIFICATION, npmScript: "smoke:negative"}),
   Object.freeze({name: RELEASE_CHECK.DOCTOR, npmScript: "smoke:doctor"}),
   Object.freeze({name: RELEASE_CHECK.TYPESCRIPT_SMOKE, npmScript: "smoke"}),

package/scripts/release-smoke.mjs

@@ -81,7 +81,11 @@ try {
     calls[0].args.includes(`${CODEX_DISTRIBUTION.VERSION_REF_PREFIX}${version}`),
     "Codex marketplace verification did not use an immutable version ref",
   );
-  assert(calls[1].args.includes(CODEX_DISTRIBUTION.PLUGIN_SELECTOR), "Codex verification used the wrong plugin selector");
+  assert(
+    calls[1].args.includes(CODEX_DISTRIBUTION.UPGRADE_COMMAND) && calls[1].args.includes(CODEX_DISTRIBUTION.MARKETPLACE_NAME),
+    "Codex marketplace verification omitted the configured snapshot refresh",
+  );
+  assert(calls[2].args.includes(CODEX_DISTRIBUTION.PLUGIN_SELECTOR), "Codex verification used the wrong plugin selector");
   assert(
     calls.every((call) => call.options.env[CODEX_DISTRIBUTION.HOME_ENVIRONMENT_VARIABLE].startsWith(codexWorkspace)),
     "Codex verification did not isolate its state under the temporary workspace",
@@ -105,6 +109,22 @@ try {
     networkChecks[0].reason === RELEASE_REASON.CODEX_MARKETPLACE_UNAVAILABLE,
     "Unavailable Codex marketplace network used the wrong reason",
   );
+
+  let upgradeCall = 0;
+  const upgradeNetworkChecks = await verifyCodexPlugin({
+    version,
+    workspace: codexWorkspace,
+    runCommand: async () => {
+      upgradeCall++;
+      if (upgradeCall === 1) return {exitCode: CI_EXIT_CODE.PASS, stdout: "{}", stderr: ""};
+      return {exitCode: CI_EXIT_CODE.FAIL, stdout: "", stderr: "network is unreachable"};
+    },
+  });
+  assert(upgradeNetworkChecks[0].status === CI_STATUS.BLOCKED, "Unavailable marketplace upgrade was not blocked");
+  assert(
+    upgradeNetworkChecks[0].reason === RELEASE_REASON.CODEX_MARKETPLACE_UNAVAILABLE,
+    "Unavailable marketplace upgrade used the wrong reason",
+  );
 } finally {
   await rm(codexWorkspace, {recursive: true, force: true});
 }
@@ -116,6 +136,7 @@ process.stdout.write(
       missingPublishedVersion: "blocked",
       isolatedCodexPluginInstallation: "ok",
       unavailableCodexMarketplace: "blocked",
+      unavailableCodexMarketplaceUpgrade: "blocked",
     },
     null,
     2,

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.0`
+Producer: `semantic-js-mcp` version `0.10.2`
 Display name: `Semantic JS MCP`
 Result schema version: `7`