semantic-js-mcp 0.10.2 → 0.10.4

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

@@ -56,15 +56,25 @@ Inspect the unresolved candidates and relevant source before making a coverage c
 
 ```yaml
 result:
+  diagnosticUse:
+    currentDocumentDiagnosticsAvailable: false
+    unconfirmedDiagnosticReportAvailable: false
+    usableAsCurrentDocumentDiagnosticEvidence: false
+    guidance: Current-document diagnostics are unavailable. Do not interpret this as a clean file. Run applicable repository-native typecheck, compile, or focused test commands.
   evidence:
     status: untrusted
     reason: language-server-did-not-report-current-document
   diagnosticsForCurrentDocument: null
+  unconfirmedDiagnosticReport:
+    reportReceived: false
 collection:
   status: partial
 ```
 
-An empty unconfirmed report is not a clean diagnostic result.
+When `usableAsCurrentDocumentDiagnosticEvidence` is false, use any unconfirmed
+items only as context. Run the repository's applicable typecheck, compile, or
+focused test commands before making a validation claim. An empty or unavailable
+unconfirmed report is not a clean diagnostic result.
 
 ### Startup Failure
 

package/lib/diagnostic-evidence.mjs

@@ -0,0 +1,26 @@
+import {DIAGNOSTIC_GUIDANCE, DIAGNOSTIC_RESULT_FIELD} from "../protocol.mjs";
+
+export function diagnosticUseSummary({versionConfirmed, reportReceived}) {
+  if (versionConfirmed) {
+    return {
+      [DIAGNOSTIC_RESULT_FIELD.CURRENT_DOCUMENT_DIAGNOSTICS_AVAILABLE]: true,
+      [DIAGNOSTIC_RESULT_FIELD.UNCONFIRMED_DIAGNOSTIC_REPORT_AVAILABLE]: false,
+      [DIAGNOSTIC_RESULT_FIELD.USABLE_AS_CURRENT_DOCUMENT_DIAGNOSTIC_EVIDENCE]: true,
+      [DIAGNOSTIC_RESULT_FIELD.GUIDANCE]: DIAGNOSTIC_GUIDANCE.CURRENT_DOCUMENT_DIAGNOSTICS_AVAILABLE,
+    };
+  }
+  if (reportReceived) {
+    return {
+      [DIAGNOSTIC_RESULT_FIELD.CURRENT_DOCUMENT_DIAGNOSTICS_AVAILABLE]: false,
+      [DIAGNOSTIC_RESULT_FIELD.UNCONFIRMED_DIAGNOSTIC_REPORT_AVAILABLE]: true,
+      [DIAGNOSTIC_RESULT_FIELD.USABLE_AS_CURRENT_DOCUMENT_DIAGNOSTIC_EVIDENCE]: false,
+      [DIAGNOSTIC_RESULT_FIELD.GUIDANCE]: DIAGNOSTIC_GUIDANCE.UNCONFIRMED_DIAGNOSTIC_REPORT_AVAILABLE,
+    };
+  }
+  return {
+    [DIAGNOSTIC_RESULT_FIELD.CURRENT_DOCUMENT_DIAGNOSTICS_AVAILABLE]: false,
+    [DIAGNOSTIC_RESULT_FIELD.UNCONFIRMED_DIAGNOSTIC_REPORT_AVAILABLE]: false,
+    [DIAGNOSTIC_RESULT_FIELD.USABLE_AS_CURRENT_DOCUMENT_DIAGNOSTIC_EVIDENCE]: false,
+    [DIAGNOSTIC_RESULT_FIELD.GUIDANCE]: DIAGNOSTIC_GUIDANCE.CURRENT_DOCUMENT_DIAGNOSTICS_UNAVAILABLE,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "semantic-js-mcp",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "description": "Semantic understanding of JavaScript codebases for AI agents",
   "keywords": [
     "mcp",
@@ -28,7 +28,7 @@
     ".codex-plugin/",
     ".mcp.json",
     ".prettierrc.json",
-    "AGENT_SETUP.md",
+    "SETUP.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "ROADMAP.md",
@@ -45,7 +45,7 @@
     "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/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": "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/diagnostic-evidence.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",
@@ -67,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

@@ -205,7 +205,7 @@ export const TOOL_DESCRIPTION = Object.freeze({
   [TOOL.DEFINITION]: `Resolves definitions for one source position. Use ${TOOL.HOVER} for type information or ${TOOL.COUNT_REFERENCES} for impact scope.`,
   [TOOL.HOVER]: `Returns inferred type information and documentation for one source position. Use ${TOOL.DEFINITION} for declaration identity.`,
   [TOOL.DIAGNOSTICS]:
-    "Returns diagnostics for one file and marks evidence untrusted when the current document snapshot cannot be confirmed.",
+    "Returns diagnostics for one file, separates unconfirmed context, and states whether the result is usable as current-document diagnostic evidence.",
   [TOOL.COUNT_TEXT_MATCHES]: `Counts exact identifier text matches without semantic verification. Use ${TOOL.COUNT_NAMED_SYMBOL} or ${TOOL.AUDIT_NAMED_SYMBOL} to verify identity.`,
   [TOOL.COUNT_NAMED_SYMBOL]: `Returns exact-definition and verified-reference counts plus explicit semantic follow-up status for a symbol name. Use ${TOOL.AUDIT_NAMED_SYMBOL} for identity, signature, or file-hint binding verification and ${TOOL.REFERENCE_PAGE} with a returned referenceSetId for locations.`,
   [TOOL.COUNT_REFERENCES]: `Returns verified-reference counts for the symbol at one source position. Use ${TOOL.AUDIT_SYMBOL} for identity and signature or ${TOOL.REFERENCE_PAGE} with the returned referenceSetId for locations.`,
@@ -301,6 +301,26 @@ export const DIAGNOSTIC_EVIDENCE_REASON = Object.freeze({
   LANGUAGE_SERVER_DID_NOT_REPORT_CURRENT_DOCUMENT: "language-server-did-not-report-current-document",
 });
 
+export const DIAGNOSTIC_RESULT_FIELD = Object.freeze({
+  DIAGNOSTIC_USE: "diagnosticUse",
+  DIAGNOSTICS_FOR_CURRENT_DOCUMENT: "diagnosticsForCurrentDocument",
+  UNCONFIRMED_DIAGNOSTIC_REPORT: "unconfirmedDiagnosticReport",
+  REPORT_RECEIVED: "reportReceived",
+  CURRENT_DOCUMENT_DIAGNOSTICS_AVAILABLE: "currentDocumentDiagnosticsAvailable",
+  UNCONFIRMED_DIAGNOSTIC_REPORT_AVAILABLE: "unconfirmedDiagnosticReportAvailable",
+  USABLE_AS_CURRENT_DOCUMENT_DIAGNOSTIC_EVIDENCE: "usableAsCurrentDocumentDiagnosticEvidence",
+  GUIDANCE: "guidance",
+});
+
+export const DIAGNOSTIC_GUIDANCE = Object.freeze({
+  CURRENT_DOCUMENT_DIAGNOSTICS_AVAILABLE:
+    "Use these as current-document diagnostic evidence, not proof of correctness. Run applicable repository-native checks before claiming correctness.",
+  UNCONFIRMED_DIAGNOSTIC_REPORT_AVAILABLE:
+    "Treat the unconfirmed report as context only. It is not current-document, compile, or type validation. Run applicable repository-native typecheck, compile, or focused test commands.",
+  CURRENT_DOCUMENT_DIAGNOSTICS_UNAVAILABLE:
+    "Current-document diagnostics are unavailable. Do not interpret this as a clean file. Run applicable repository-native typecheck, compile, or focused test commands.",
+});
+
 export const CONTENT_FRESHNESS = Object.freeze({
   VERIFIED_CURRENT: "verified-current-file-content",
   VERIFIED_REPOSITORY_SOURCE_INVENTORY: "verified-current-repository-source-inventory",
@@ -408,7 +428,7 @@ export const RESULT_SCHEMA = Object.freeze({
   VERSION: 7,
 });
 
-export const SERVER_VERSION = "0.10.2";
+export const SERVER_VERSION = "0.10.4";
 
 export const REQUIRED_RUNTIME_COMPONENT = Object.freeze({
   TYPESCRIPT_LANGUAGE_SERVER: "typescript-language-server/lib/cli.mjs",

package/scripts/check-protocol-literals.mjs

@@ -20,9 +20,11 @@ import {
   DEFINITION_SELECTION_STATUS,
   DIAGNOSTIC_EVIDENCE_REASON,
   DIAGNOSTIC_FRESHNESS,
+  DIAGNOSTIC_GUIDANCE,
   DIAGNOSTIC_LANGUAGE,
   DIAGNOSTIC_PROVIDER,
   DIAGNOSTIC_REGION,
+  DIAGNOSTIC_RESULT_FIELD,
   DIAGNOSTIC_SEVERITY,
   DOCTOR_CHECK,
   DOCTOR_DISTRIBUTION_ACCEPTED_STATUS,
@@ -67,7 +69,7 @@ import {
 } from "../protocol.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const runtimeSourceFiles = ["server.mjs", "cli.mjs", "lib/runtime.mjs", "lib/doctor.mjs"];
+const runtimeSourceFiles = ["server.mjs", "cli.mjs", "lib/runtime.mjs", "lib/doctor.mjs", "lib/diagnostic-evidence.mjs"];
 const runtimeSources = await Promise.all(
   runtimeSourceFiles.map(async (file) => ({
     file,
@@ -102,6 +104,8 @@ const groups = [
   DIAGNOSTIC_LANGUAGE,
   DIAGNOSTIC_SEVERITY,
   DIAGNOSTIC_EVIDENCE_REASON,
+  DIAGNOSTIC_RESULT_FIELD,
+  DIAGNOSTIC_GUIDANCE,
   EVIDENCE_STATUS,
   CONTENT_FRESHNESS,
   ERROR_CODE,

package/scripts/distribution-policy.mjs

@@ -2,7 +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",
+  SETUP: "SETUP.md",
   LICENSE: "LICENSE",
   CLI: "cli.mjs",
   SERVER: "server.mjs",

package/scripts/documentation-contract.mjs

@@ -1,8 +1,9 @@
-import {DOCTOR_REASON, SEMANTIC_EVIDENCE_FOLLOW_UP_REASON} from "../protocol.mjs";
+import {DIAGNOSTIC_GUIDANCE, DIAGNOSTIC_RESULT_FIELD, DOCTOR_REASON, SEMANTIC_EVIDENCE_FOLLOW_UP_REASON} from "../protocol.mjs";
 
 export const DOCUMENTATION_FILE = Object.freeze({
   README: "README.md",
-  AGENT_SETUP: "AGENT_SETUP.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",
@@ -10,26 +11,36 @@ export const DOCUMENTATION_FILE = Object.freeze({
 });
 
 export const PUBLIC_ROOT_DOCUMENT = Object.freeze([
-  "AGENT_SETUP.md",
   "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_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",
   ]),
-  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",
@@ -40,29 +51,96 @@ export const DOCUMENTATION_REQUIREMENT = Object.freeze({
     "Untrusted Diagnostics",
     "Startup Failure",
   ]),
-  AGENT_SETUP_HEADINGS: Object.freeze([
-    "Scope",
-    "Safety Boundaries",
-    "Installation Procedure",
-    "Verification",
-    "Update And Rollback",
+  SETUP_HEADINGS: Object.freeze([
+    "Guards",
+    "Prerequisites",
+    "Choose A Version",
+    "Install With Codex",
+    "Install With Another MCP Host",
+    "Verify The Installation",
+    "Troubleshooting",
+    "Update",
+    "Rollback",
     "Removal",
-    "Completion Report",
+    "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(["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([
+  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,
+    DIAGNOSTIC_RESULT_FIELD.USABLE_AS_CURRENT_DOCUMENT_DIAGNOSTIC_EVIDENCE,
+    DIAGNOSTIC_GUIDANCE.CURRENT_DOCUMENT_DIAGNOSTICS_UNAVAILABLE,
+  ]),
+  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.",
+    "Use the language of the user's latest message for explanations, questions,",
+    "Complete Sections 1.1 through 1.4 before invoking any terminal, filesystem, package-manager, or host tool.",
+    "does not authorize a tool call.",
+    "Record exactly one operation: `verification`.",
+    "Use a direct integration only after positive evidence identifies the application running this setup session.",
+    "If no documented direct integration is positively identified, record `generic stdio` and continue without asking the user to identify the agent.",
+    "The host application and the host route are different facts.",
+    "The host route does not identify the server source.",
+    "The application running the agent can also be the MCP host.",
+    "Recommended target host: `<application>` using `generic stdio`.",
+    "Do not repeatedly ask for the application name after positive session evidence already identifies it.",
+    "Do not present direct integrations as a menu.",
+    "The presence of an installed host executable is not positive host evidence.",
+    "continue only with the recorded host route",
+    "and server source for the existing installation.",
+    "Do not use `npx`, `npm exec`, `@latest`, or an npm cache as an installation route.",
+    "Do not pipe JSON-RPC messages",
+    "A manually started server does not prove that the configured host application loaded the MCP tools.",
+    "Source checkout registration is not supported",
+    "When the recorded host route is `Codex direct`, the agent may run the",
+    "I cannot identify the current host application. Which application should I configure?",
+    "record `user` as the command runner.",
+    "low side-effect risk, but they are not sandbox-neutral evidence:",
+    "The agent must not perform even read-only local checks.",
+    "A command name is not enough to infer its argument grammar.",
+    "Do not construct the add command unless Section 5.1 recorded its exact current",
+    "An added-entry message is not enough.",
+    "A host status of `failed` is a failure, not an expected pre-restart state.",
+    "Use `lsp_document_symbols` on that file as the first functional",
+    "global executable checks for a source checkout.",
+    "search the user's home directory or unrelated directories for a checkout.",
+    "A similarly named file is not evidence of a Semantic JS MCP installation.",
+    "Before constructing a removal command, confirm the exact remove subcommand",
+    "do not run the global npm",
+    "Before constructing a source-checkout registration command, confirm the exact",
+    "report that the source checkout is ready and stop.",
+    "pending-restart",
+    "No source-code call is required",
+    "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",
+    `Read \`result.${DIAGNOSTIC_RESULT_FIELD.DIAGNOSTIC_USE}\``,
+    DIAGNOSTIC_RESULT_FIELD.UNCONFIRMED_DIAGNOSTIC_REPORT_AVAILABLE,
   ]),
 });
 
@@ -71,6 +149,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",
 });