semantic-js-mcp 0.10.2 → 0.10.3

package/scripts/documentation-contract.mjs

@@ -2,7 +2,8 @@ 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",
+  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,24 +51,48 @@ 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"]),
+  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]),
-  AGENT_SETUP_LITERALS: Object.freeze([
+  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",
@@ -71,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,8 +6,9 @@ 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.AGENT_SETUP]: `${headingText(DOCUMENTATION_REQUIREMENT.AGENT_SETUP_HEADINGS)}\n${DOCUMENTATION_REQUIREMENT.AGENT_SETUP_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",
@@ -16,6 +17,105 @@ const valid = {
 
 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),
@@ -48,96 +148,137 @@ strictEqual(
   "Missing canonical example literal was accepted",
 );
 
-const missingMarketplaceUpgrade = {
+const missingSetupLink = {
   ...valid,
-  [DOCUMENTATION_FILE.README]: valid[DOCUMENTATION_FILE.README].replace(DOCUMENTATION_REQUIREMENT.README_LITERALS[0], ""),
+  [DOCUMENTATION_FILE.README]: valid[DOCUMENTATION_FILE.README].replaceAll(
+    `](${DOCUMENTATION_REQUIREMENT.README_LINKS[0]})`,
+    "](missing-setup.md)",
+  ),
 };
 strictEqual(
-  evaluateDocumentation(missingMarketplaceUpgrade).some(
-    (finding) =>
-      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING && finding.literal === DOCUMENTATION_REQUIREMENT.README_LITERALS[0],
+  evaluateDocumentation(missingSetupLink).some(
+    (finding) => finding.reason === DOCUMENTATION_REASON.LINK_MISSING && finding.link === DOCUMENTATION_REQUIREMENT.README_LINKS[0],
   ),
   true,
-  "Missing marketplace upgrade guidance was accepted",
+  "Missing setup README link was accepted",
 );
 
-const missingAgentSetupLink = {
+const missingSetupEntryInstruction = {
   ...valid,
-  [DOCUMENTATION_FILE.README]: valid[DOCUMENTATION_FILE.README].replace(`[doc](${DOCUMENTATION_REQUIREMENT.README_LINKS[0]})`, ""),
+  [DOCUMENTATION_FILE.README]: valid[DOCUMENTATION_FILE.README].replace(DOCUMENTATION_REQUIREMENT.README_SETUP_ENTRY_LITERALS[0], ""),
 };
 strictEqual(
-  evaluateDocumentation(missingAgentSetupLink).some(
-    (finding) => finding.reason === DOCUMENTATION_REASON.LINK_MISSING && finding.link === DOCUMENTATION_REQUIREMENT.README_LINKS[0],
+  evaluateDocumentation(missingSetupEntryInstruction).some(
+    (finding) =>
+      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING &&
+      finding.literal === DOCUMENTATION_REQUIREMENT.README_SETUP_ENTRY_LITERALS[0],
   ),
   true,
-  "Missing agent setup README link was accepted",
+  "Missing README setup instruction was accepted",
 );
 
-const missingAgentSetup = {...valid};
-delete missingAgentSetup[DOCUMENTATION_FILE.AGENT_SETUP];
+const missingSetup = {...valid};
+delete missingSetup[DOCUMENTATION_FILE.SETUP];
 strictEqual(
-  evaluateDocumentation(missingAgentSetup).some(
-    (finding) => finding.reason === DOCUMENTATION_REASON.FILE_MISSING && finding.file === DOCUMENTATION_FILE.AGENT_SETUP,
+  evaluateDocumentation(missingSetup).some(
+    (finding) => finding.reason === DOCUMENTATION_REASON.FILE_MISSING && finding.file === DOCUMENTATION_FILE.SETUP,
   ),
   true,
-  "Missing agent setup guide was accepted",
+  "Missing setup guide was accepted",
 );
 
-const missingAgentSafetyBoundary = {
+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.AGENT_SETUP]: valid[DOCUMENTATION_FILE.AGENT_SETUP].replace(DOCUMENTATION_REQUIREMENT.AGENT_SETUP_LITERALS[2], ""),
+  [DOCUMENTATION_FILE.SEMANTIC_NAVIGATION_SKILL]: valid[DOCUMENTATION_FILE.SEMANTIC_NAVIGATION_SKILL].replace(
+    DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_LITERALS[1],
+    "",
+  ),
 };
 strictEqual(
-  evaluateDocumentation(missingAgentSafetyBoundary).some(
+  evaluateDocumentation(missingCombinationInvariant).some(
     (finding) =>
-      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING && finding.literal === DOCUMENTATION_REQUIREMENT.AGENT_SETUP_LITERALS[2],
+      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING &&
+      finding.literal === DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_LITERALS[1],
   ),
   true,
-  "Missing agent setup safety boundary was accepted",
+  "Missing combination-invariant guidance was accepted",
 );
 
-const missingGenericServerName = {
+const missingTrustedPublishingPolicy = {
   ...valid,
-  [DOCUMENTATION_FILE.AGENT_SETUP]: valid[DOCUMENTATION_FILE.AGENT_SETUP].replace(DOCUMENTATION_REQUIREMENT.AGENT_SETUP_LITERALS[4], ""),
+  [DOCUMENTATION_FILE.DISTRIBUTION]: valid[DOCUMENTATION_FILE.DISTRIBUTION].replace(DOCUMENTATION_REQUIREMENT.DISTRIBUTION_LITERALS[2], ""),
 };
 strictEqual(
-  evaluateDocumentation(missingGenericServerName).some(
+  evaluateDocumentation(missingTrustedPublishingPolicy).some(
     (finding) =>
-      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING && finding.literal === DOCUMENTATION_REQUIREMENT.AGENT_SETUP_LITERALS[4],
+      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING && finding.literal === DOCUMENTATION_REQUIREMENT.DISTRIBUTION_LITERALS[2],
   ),
   true,
-  "Missing generic MCP server name was accepted",
+  "Missing trusted-publishing policy was accepted",
 );
 
-const missingCombinationInvariant = {
+const missingPostpublicationOrder = {
   ...valid,
-  [DOCUMENTATION_FILE.SEMANTIC_NAVIGATION_SKILL]: valid[DOCUMENTATION_FILE.SEMANTIC_NAVIGATION_SKILL].replace(
-    DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_LITERALS[1],
-    "",
-  ),
+  [DOCUMENTATION_FILE.DISTRIBUTION]: valid[DOCUMENTATION_FILE.DISTRIBUTION].replace(DOCUMENTATION_REQUIREMENT.DISTRIBUTION_LITERALS[5], ""),
 };
 strictEqual(
-  evaluateDocumentation(missingCombinationInvariant).some(
+  evaluateDocumentation(missingPostpublicationOrder).some(
     (finding) =>
-      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING &&
-      finding.literal === DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_LITERALS[1],
+      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING && finding.literal === DOCUMENTATION_REQUIREMENT.DISTRIBUTION_LITERALS[5],
   ),
   true,
-  "Missing combination-invariant 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",
-      missingAgentSetupLink: "rejected",
-      missingAgentSetup: "rejected",
-      missingAgentSafetyBoundary: "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,8 @@ export function evaluateDocumentation(documents) {
 
   const headingRequirements = [
     [DOCUMENTATION_FILE.README, DOCUMENTATION_REQUIREMENT.README_HEADINGS],
-    [DOCUMENTATION_FILE.AGENT_SETUP, DOCUMENTATION_REQUIREMENT.AGENT_SETUP_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],
   ];
@@ -50,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];
@@ -68,11 +119,32 @@ 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 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});
     }
   }
 
@@ -88,6 +160,18 @@ export function evaluateDocumentation(documents) {
     }
   }
 
+  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/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.2`
+Producer: `semantic-js-mcp` version `0.10.3`
 Display name: `Semantic JS MCP`
 Result schema version: `7`