@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/scripts/check-ai-context.js

@@ -0,0 +1,963 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs"
+import { basename, join, posix } from "node:path"
+import {
+  AI_CONTEXT_FILES,
+  CLAUDE_MARKETPLACE,
+  RUNTIME_PLUGIN_MANIFESTS,
+} from "./ai-context-files.js"
+import { fencedLines } from "./lib/markdown-fences.mjs"
+import { LANE_PACKAGES } from "./release-tag.mjs"
+import { REMOVED_V3_NAMES } from "./removed-v3-names.js"
+
+const rootDir = process.cwd()
+
+// The packages of the release lane (scripts/release-tag.mjs): each one
+// publishes, at the lane's version.
+const versionChecks = LANE_PACKAGES.map((packageDir) => ({
+  packageName: `@ic-reactor/${packageDir}`,
+  packageDir,
+}))
+
+// The one consumer guide of the 4.x line: core ships `packages/core/llms.txt`
+// in its npm tarball, and it must open with an "Applies to
+// `@ic-reactor/core` <version>." line. A pointer guide in another package
+// (react's, once DX3 adds it) is stamped the same way, so a `llms.txt` that
+// ships names the release it was written for.
+const requiredPackageLlms = ["core"]
+const optionalPackageLlms = versionChecks
+  .map(({ packageDir }) => packageDir)
+  .filter(
+    (packageDir) =>
+      !requiredPackageLlms.includes(packageDir) &&
+      existsSync(join(rootDir, "packages", packageDir, "llms.txt"))
+  )
+const packageGuides = [...requiredPackageLlms, ...optionalPackageLlms]
+
+/**
+ * Files whose `https://ic-reactor.b3pay.net/...` links must resolve: the
+ * AI-context files, plus the READMEs npm shows, the changelog and the
+ * contributing guide. linkinator (`pnpm docs:check-links`) skips absolute
+ * links to the site, so without this a renamed page left these dangling.
+ */
+const docsLinkFiles = [
+  ...AI_CONTEXT_FILES,
+  "README.md",
+  "CHANGELOG.md",
+  "CONTRIBUTING.md",
+  ...versionChecks.map(({ packageDir }) => `packages/${packageDir}/README.md`),
+]
+
+/**
+ * Files whose whole purpose is to orient an AI agent. They are the "package
+ * surface" source of truth, so a stale version here steers agents (and the
+ * humans reading their output) at a release that is no longer current.
+ *
+ * Until this check covered them, only the version table in the root llms.txt was
+ * validated, so a release could bump every manifest and leave all of these
+ * claiming the previous version with the gate still green.
+ */
+const aiContextFiles = AI_CONTEXT_FILES
+
+/**
+ * The base the docs site in this tree is served under, read from
+ * docs/astro.config.mjs so the check follows the branch: `/v3/` on the 3.x
+ * line (v3), `/v4/` on the 4.x line (main). Links under it are resolved against
+ * this tree's pages.
+ */
+const DOCS_BASE = (() => {
+  const config = readFileSync(join(rootDir, "docs", "astro.config.mjs"), "utf8")
+  const base = config.match(/^\s*base:\s*["'](.+?)["']/m)?.[1]
+  if (!base) {
+    console.error(
+      "check-ai-context: could not read `base` from docs/astro.config.mjs"
+    )
+    process.exit(1)
+  }
+  return `/${base.replace(/^\/|\/$/g, "")}/`
+})()
+
+/**
+ * Every versioned base the site publishes (.github/workflows/docs.yml): the
+ * static 2.x docs, the 3.x line built from the v3 branch and the 4.x line
+ * built from main. A link to a base outside this set 404s. A link under a base
+ * other than DOCS_BASE is served from another line's tree, so only its base
+ * is checked here.
+ */
+const PUBLISHED_DOCS_BASES = new Set(["/v2/", "/v3/", "/v4/"])
+
+/**
+ * Versions that legitimately appear in the AI-context files without belonging to
+ * an @ic-reactor package (a documented Node or pnpm version, for example).
+ *
+ * Deliberately starts empty: every version-like token in these files today is an
+ * @ic-reactor version, so anything else is drift until someone says otherwise.
+ * Adding an entry here is the explicit way to say "this one is not ours".
+ */
+const ALLOWED_EXTERNAL_VERSIONS = new Set([])
+
+const failures = []
+
+// ── Current package versions ─────────────────────────────────────────────────
+const currentVersions = new Map()
+for (const { packageName, packageDir } of versionChecks) {
+  const pkgPath = join(rootDir, "packages", packageDir, "package.json")
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"))
+  currentVersions.set(packageName, pkg.version)
+}
+const validVersions = new Set(currentVersions.values())
+
+// ── 1. (3.x only) The version lists of the root llms.txt and llms-full.txt ───
+// The 4.x line has no root guides in the tree: the docs deploy serves
+// packages/core/llms.txt (checked below) as the site's /llms.txt, and
+// /llms-full.txt is the 3.x line's, frozen on the v3 branch
+// (.github/workflows/docs.yml, scripts/assemble-docs-site.mjs).
+
+// ── 2. The package guide is stamped with its package's version ───────────────
+// The stamp tells an agent reading node_modules/@ic-reactor/<dir>/llms.txt
+// which release the guide describes. The generic version check below accepts
+// any version some package is at, so it would not notice a stamp naming
+// another lane's version; this compares against the package's own.
+for (const packageDir of packageGuides) {
+  const relPath = `packages/${packageDir}/llms.txt`
+  const packageLlmsPath = join(rootDir, relPath)
+  if (!existsSync(packageLlmsPath)) {
+    failures.push(`Missing package AI guide: ${relPath}`)
+    continue
+  }
+  const packageName = `@ic-reactor/${packageDir}`
+  const version = currentVersions.get(packageName)
+  const expectedStamp = `Applies to \`${packageName}\` ${version}.`
+  const stamp = readFileSync(packageLlmsPath, "utf8")
+    .split("\n")
+    .find((line) => line.startsWith(`Applies to \`${packageName}\``))
+
+  if (stamp === undefined) {
+    failures.push(
+      `${relPath} has no version stamp. Expected line: ${expectedStamp}`
+    )
+  } else if (stamp.trim() !== expectedStamp) {
+    failures.push(
+      `${relPath} is stamped "${stamp.trim()}" but ${packageName} is at ${version}. Expected line: ${expectedStamp}`
+    )
+  }
+}
+
+// ── 3. No stale version anywhere in the AI-context files ─────────────────────
+// Matches every semver-shaped token regardless of how it is written: backticked,
+// `v`-prefixed, or bare in prose. An earlier version of this check only matched
+// the first two forms, so a stale bare "3.7.0" in a sentence passed silently --
+// which defeats the point, since prose is exactly where these versions rot.
+//
+// The lookarounds keep it from matching a fragment of a longer dotted number
+// (1.2.3.4) while still allowing a version at the end of a sentence ("v3.8.0.").
+// A prerelease tag (4.0.0-alpha.0) is part of the version, so it is compared
+// whole; a sentence's closing period is not taken into it.
+const SEMVER =
+  /(?<![\d.])v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?)(?![\d.]\d)/g
+
+// Any /vN/ path segment, not just one inside markdown link syntax -- the same
+// narrowness bug as above.
+const VERSIONED_DOC_PATH = /\/v\d+\//g
+
+for (const relPath of aiContextFiles) {
+  const absPath = join(rootDir, relPath)
+  if (!existsSync(absPath)) {
+    failures.push(`Missing AI-context file: ${relPath}`)
+    continue
+  }
+  const text = readFileSync(absPath, "utf8")
+
+  text.split("\n").forEach((line, i) => {
+    for (const [, version] of line.matchAll(SEMVER)) {
+      if (validVersions.has(version)) continue
+      if (ALLOWED_EXTERNAL_VERSIONS.has(version)) continue
+
+      failures.push(
+        `${relPath}:${i + 1} refers to version ${version}, which no @ic-reactor package is at. ` +
+          `Current: ${[...currentVersions].map(([n, v]) => `${n}@${v}`).join(", ")}. ` +
+          `If this version is not an @ic-reactor package, add it to ` +
+          `ALLOWED_EXTERNAL_VERSIONS in scripts/check-ai-context.js.`
+      )
+    }
+
+    // 4. Doc links must use a base the site publishes.
+    for (const seg of line.match(VERSIONED_DOC_PATH) ?? []) {
+      if (!PUBLISHED_DOCS_BASES.has(seg)) {
+        failures.push(
+          `${relPath}:${i + 1} references ${seg} but the docs site publishes only ${[...PUBLISHED_DOCS_BASES].join(", ")}`
+        )
+      }
+    }
+  })
+}
+
+// ── 5. Links to the docs site resolve ────────────────────────────────────────
+// The site serves each page twice under DOCS_BASE: as a route, lowercased by
+// Starlight (`/v3/reference/clientmanager/`), and as the Markdown companion
+// starlight-page-actions writes at the SOURCE-cased path
+// (`/v3/reference/ClientManager.md`, and `/v3/packages/candid.md` for
+// `packages/candid/index.mdx`). The host is case-sensitive, so each form is
+// matched exactly. A `#fragment` must name a heading of the page.
+const DOCS_SITE = "https://ic-reactor.b3pay.net"
+const DOCS_CONTENT = join(rootDir, "docs", "src", "content", "docs")
+/** Published at the site root by .github/workflows/docs.yml. */
+const SITE_ROOT_FILES = new Set(["", "llms.txt", "llms-full.txt"])
+
+function* docsSources(dir, rel = "") {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const entryRel = rel ? `${rel}/${entry.name}` : entry.name
+    // TypeDoc output, generated by docs:build and not in the repository.
+    if (entry.isDirectory() && entryRel !== "libs") {
+      yield* docsSources(join(dir, entry.name), entryRel)
+    } else if (entry.isFile() && /\.mdx?$/.test(entry.name)) {
+      yield entryRel
+    }
+  }
+}
+
+const sourcePages = new Set(docsSources(DOCS_CONTENT))
+/** Route (lowercased, no trailing slash, "" for the home page) -> source file. */
+const sourceByRoute = new Map()
+for (const page of sourcePages) {
+  const route = page
+    .replace(/\.mdx?$/, "")
+    .replace(/(^|\/)index$/, "")
+    .toLowerCase()
+  sourceByRoute.set(route, page)
+}
+
+/** The source page a path under DOCS_BASE names, or undefined. */
+function resolveDocsPath(path) {
+  if (path.endsWith(".md")) {
+    const key = path.slice(0, -".md".length)
+    // `packages/candid/index.md` is not published; `packages/candid.md` is.
+    if (key.endsWith("/index")) return undefined
+    return [
+      `${key}.mdx`,
+      `${key}.md`,
+      `${key}/index.mdx`,
+      `${key}/index.md`,
+    ].find((candidate) => sourcePages.has(candidate))
+  }
+  const route = path.replace(/\/$/, "")
+  const page = sourceByRoute.get(route.toLowerCase())
+  // Starlight lowercases routes; a mixed-case route 404s on the host.
+  return page !== undefined && route === route.toLowerCase() ? page : undefined
+}
+
+/** github-slugger's rule, which Starlight uses for heading ids. */
+function slugify(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^\p{L}\p{M}\p{N}\p{Pc} -]/gu, "")
+    .replace(/ /g, "-")
+}
+
+/**
+ * A heading's text without inline HTML or JSX tags. The pattern runs until
+ * nothing changes, so a tag that one pass would leave behind (`<<b>b>`) goes
+ * too, and a lone "<" is dropped, as the slug drops it anyway.
+ */
+function withoutTags(text) {
+  let previous
+  let current = text
+  do {
+    previous = current
+    current = current.replace(/<[^<>]*>/g, "")
+  } while (current !== previous)
+  return current.replace(/</g, "")
+}
+
+const headingIdsCache = new Map()
+function headingIds(page) {
+  if (headingIdsCache.has(page)) return headingIdsCache.get(page)
+  const ids = new Set(["_top"])
+  const seen = new Map()
+  const fenced = fencedLines()
+  for (const line of readFileSync(join(DOCS_CONTENT, page), "utf8").split(
+    "\n"
+  )) {
+    if (fenced(line)) continue
+    // A heading may open a list item, as the steps of a <Steps> block do.
+    const heading = line.match(
+      /^\s*(?:(?:\d+\.|[-*+])\s+)?#{1,6}\s+(.+?)\s*#*\s*$/
+    )
+    if (!heading) continue
+    const text = withoutTags(
+      heading[1].replace(/\[([^\]]*)\]\([^)]*\)/g, "$1") // [text](url) -> text
+    ).replace(/[`*]/g, "")
+    const base = slugify(text)
+    const count = seen.get(base) ?? 0
+    seen.set(base, count + 1)
+    ids.add(count === 0 ? base : `${base}-${count}`)
+  }
+  headingIdsCache.set(page, ids)
+  return ids
+}
+
+const SITE_LINK = /https:\/\/ic-reactor\.b3pay\.net(\/[^\s)\]`>"'<]*)?/g
+
+for (const relPath of docsLinkFiles) {
+  const absPath = join(rootDir, relPath)
+  if (!existsSync(absPath)) continue // a missing AI-context file is reported above
+  readFileSync(absPath, "utf8")
+    .split("\n")
+    .forEach((line, i) => {
+      for (const match of line.matchAll(SITE_LINK)) {
+        const url = match[0].replace(/[.,;:]+$/, "")
+        const [pathAndQuery, fragment] = url.slice(DOCS_SITE.length).split("#")
+        const path = pathAndQuery.split("?")[0].replace(/^\//, "")
+        const where = `${relPath}:${i + 1}`
+
+        if (SITE_ROOT_FILES.has(path)) continue
+        const base = DOCS_BASE.replace(/^\/|\/$/g, "") // "v4"
+        if (path !== base && !path.startsWith(`${base}/`)) {
+          // Served from another line's tree (DOCS_BASE's doc comment); a base
+          // the site does not publish is reported by check 4 above.
+          const other = path.match(/^(v\d+)(\/|$)/)?.[1]
+          if (other && PUBLISHED_DOCS_BASES.has(`/${other}/`)) continue
+          failures.push(
+            `${where} links ${url}, which is neither under ${DOCS_BASE} nor one of the files published at the site root`
+          )
+          continue
+        }
+        const docsPath = path === base ? "" : path.slice(base.length + 1)
+        if (docsPath.startsWith("libs/")) continue // TypeDoc pages are generated
+
+        const page = resolveDocsPath(docsPath)
+        if (page === undefined) {
+          failures.push(
+            `${where} links ${url}, but no page in docs/src/content/docs serves it. ` +
+              `Use the lowercase route (${DOCS_BASE}guides/error-handling) or the source-cased ` +
+              `Markdown path (${DOCS_BASE}guides/error-handling.md).`
+          )
+        } else if (fragment && !headingIds(page).has(fragment)) {
+          failures.push(
+            `${where} links ${url}, but docs/src/content/docs/${page} has no heading with the id "${fragment}"`
+          )
+        }
+      }
+    })
+}
+
+// ── 6. Agent skills ──────────────────────────────────────────────────────────
+// Every `skill-packages/<name>/SKILL.md`, and every skill a plugin in the
+// marketplace installs, must load in the tools that read the Agent Skills
+// format (https://agentskills.io/specification): YAML frontmatter with a
+// `name` equal to its folder and a `description` of at most 1024 characters,
+// and no key outside the spec, which claude.ai uploads and the Skills API
+// reject.
+const SKILLS_DIR = "skill-packages"
+// Absent only in a tree with no skill, such as this script's tests.
+const skillEntries = existsSync(join(rootDir, SKILLS_DIR))
+  ? readdirSync(join(rootDir, SKILLS_DIR), { withFileTypes: true })
+  : []
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+const SKILL_KEYS = new Set([
+  "name",
+  "description",
+  "license",
+  "compatibility",
+  "metadata",
+  "allowed-tools",
+])
+
+/**
+ * The top-level keys of a SKILL.md's YAML frontmatter, or null when it has
+ * none. Enough YAML for skill frontmatter: plain, quoted and multi-line plain
+ * scalars, `>`/`|` block scalars (folded or kept), and one level of nested
+ * mapping for `metadata`. Anything else is reported rather than guessed at.
+ */
+function parseFrontmatter(text) {
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/)
+  if (!match) return null
+  const lines = match[1].split(/\r?\n/)
+  const fields = {}
+  let i = 0
+  while (i < lines.length) {
+    const line = lines[i]
+    if (line.trim() === "" || line.trimStart().startsWith("#")) {
+      i++
+      continue
+    }
+    const keyMatch = line.match(/^([A-Za-z][\w-]*):(?:[ \t]+(.*))?$/)
+    if (!keyMatch) throw new Error(`cannot read frontmatter line "${line}"`)
+    const key = keyMatch[1]
+    const inline = (keyMatch[2] ?? "").trim()
+    i++
+    const block = []
+    while (
+      i < lines.length &&
+      (lines[i].trim() === "" || /^\s/.test(lines[i]))
+    ) {
+      block.push(lines[i])
+      i++
+    }
+    while (block.length > 0 && block[block.length - 1].trim() === "")
+      block.pop()
+
+    if (/^[>|][+-]?$/.test(inline)) {
+      const indent = Math.min(
+        ...block.filter((l) => l.trim()).map((l) => l.match(/^\s*/)[0].length)
+      )
+      const body = block.map((l) => l.slice(indent))
+      fields[key] =
+        inline[0] === "|"
+          ? body.join("\n")
+          : body
+              .join("\n")
+              .replace(/([^\n])\n(?=[^\n])/g, "$1 ")
+              .replace(/\n\n/g, "\n")
+    } else if (inline === "" && block.length > 0) {
+      fields[key] = Object.fromEntries(
+        block
+          .filter((l) => l.trim())
+          .map((l) => {
+            const entry = l.trim().match(/^([\w-]+):\s*(.*)$/)
+            if (!entry) throw new Error(`cannot read "${l.trim()}" in ${key}`)
+            return [entry[1], entry[2].replace(/^(["'])(.*)\1$/, "$2")]
+          })
+      )
+    } else {
+      const value = [inline, ...block.map((l) => l.trim())]
+        .filter(Boolean)
+        .join(" ")
+      fields[key] = value.replace(/^(["'])(.*)\1$/s, "$2")
+    }
+  }
+  return fields
+}
+
+function checkSkill(relSkillMd) {
+  const absPath = join(rootDir, relSkillMd)
+  let fields
+  try {
+    fields = parseFrontmatter(readFileSync(absPath, "utf8"))
+  } catch (error) {
+    failures.push(`${relSkillMd}: ${error.message}`)
+    return
+  }
+  if (fields === null) {
+    failures.push(
+      `${relSkillMd} has no YAML frontmatter; it must open with ---, name: and description:`
+    )
+    return
+  }
+  const folder = basename(posix.dirname(relSkillMd))
+  const { name, description } = fields
+  if (typeof name !== "string" || !SKILL_NAME.test(name) || name.length > 64) {
+    failures.push(
+      `${relSkillMd}: name must be 1-64 lowercase letters, digits and single hyphens (got ${JSON.stringify(name)})`
+    )
+  } else if (name !== folder) {
+    failures.push(
+      `${relSkillMd}: name "${name}" must match its folder "${folder}"`
+    )
+  }
+  if (typeof description !== "string" || description.trim() === "") {
+    failures.push(`${relSkillMd}: description is missing`)
+  } else if (description.length > 1024) {
+    failures.push(
+      `${relSkillMd}: description is ${description.length} characters; the limit is 1024`
+    )
+  }
+  for (const key of Object.keys(fields)) {
+    if (!SKILL_KEYS.has(key)) {
+      failures.push(
+        `${relSkillMd}: frontmatter key "${key}" is not in the Agent Skills spec (${[...SKILL_KEYS].join(", ")})`
+      )
+    }
+  }
+}
+
+/** Markdown files of a skill folder, relative to the repository root. */
+function* skillMarkdown(relDir) {
+  for (const entry of readdirSync(join(rootDir, relDir), {
+    withFileTypes: true,
+  })) {
+    const rel = `${relDir}/${entry.name}`
+    if (entry.isDirectory() && !entry.name.startsWith(".")) {
+      yield* skillMarkdown(rel)
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      yield rel
+    }
+  }
+}
+
+const checkedSkills = new Set()
+for (const entry of skillEntries) {
+  if (!entry.isDirectory()) continue
+  const relSkillMd = `${SKILLS_DIR}/${entry.name}/SKILL.md`
+  if (!existsSync(join(rootDir, relSkillMd))) {
+    failures.push(`${SKILLS_DIR}/${entry.name}/ has no SKILL.md`)
+    continue
+  }
+  checkSkill(relSkillMd)
+  checkedSkills.add(relSkillMd)
+  // What a skill tells an agent must be version- and link-checked like the
+  // other AI files, so a new reference file cannot slip past this script.
+  for (const relMd of skillMarkdown(`${SKILLS_DIR}/${entry.name}`)) {
+    if (/\/(SKILL\.md|references\/[^/]+\.md)$/.test(relMd)) {
+      if (!AI_CONTEXT_FILES.includes(relMd)) {
+        failures.push(
+          `${relMd} is not listed in scripts/ai-context-files.js, so its versions and links go unchecked and releases do not update it`
+        )
+      }
+    }
+  }
+}
+
+// ── 7. The Claude Code plugin marketplace ────────────────────────────────────
+// `/plugin marketplace add B3Pay/ic-reactor` reads CLAUDE_MARKETPLACE from the
+// default branch; each relative `source` is a plugin directory holding
+// `.claude-plugin/plugin.json` and its skills. `claude plugin validate .`
+// checks the same shape, but it is not installed in CI.
+const currentReact = currentVersions.get("@ic-reactor/react")
+/** Folders whose skills an app installs: every text an agent loads from them
+ * must stand on the published packages alone. They are the folder of every
+ * skill under SKILLS_DIR, which `npx skills add` installs from this repository
+ * whether or not a marketplace lists it (#970), and of each skill of a
+ * marketplace plugin below. So a contributor skill does not go under
+ * SKILLS_DIR. */
+const consumerSkillDirs = [...checkedSkills].map((rel) => posix.dirname(rel))
+
+function readJson(relPath) {
+  try {
+    return JSON.parse(readFileSync(join(rootDir, relPath), "utf8"))
+  } catch (error) {
+    failures.push(`${relPath} is not valid JSON: ${error.message}`)
+    return undefined
+  }
+}
+
+const isDirectory = (relPath) =>
+  existsSync(join(rootDir, relPath)) &&
+  statSync(join(rootDir, relPath)).isDirectory()
+
+// Optional: v4 has no marketplace (DX3 added the skill without one), so the
+// consumer rules of section 8 do not depend on this file.
+if (existsSync(join(rootDir, CLAUDE_MARKETPLACE))) {
+  const marketplace = readJson(CLAUDE_MARKETPLACE)
+  if (marketplace !== undefined) {
+    if (
+      typeof marketplace.name !== "string" ||
+      !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(marketplace.name)
+    ) {
+      failures.push(
+        `${CLAUDE_MARKETPLACE}: name must be letters, digits, ".", "_" and "-", starting with a letter or digit`
+      )
+    }
+    if (typeof marketplace.owner?.name !== "string") {
+      failures.push(`${CLAUDE_MARKETPLACE}: owner.name is required`)
+    }
+    if (
+      !Array.isArray(marketplace.plugins) ||
+      marketplace.plugins.length === 0
+    ) {
+      failures.push(
+        `${CLAUDE_MARKETPLACE}: plugins must list at least one plugin`
+      )
+    }
+    for (const [i, entry] of (marketplace.plugins ?? []).entries()) {
+      const where = `${CLAUDE_MARKETPLACE} plugins[${i}]`
+      const { source } = entry
+      if (typeof entry.name !== "string" || /\s/.test(entry.name)) {
+        failures.push(`${where}: name is required and has no spaces`)
+      }
+      if (
+        typeof source !== "string" ||
+        !source.startsWith("./") ||
+        source.split("/").includes("..")
+      ) {
+        failures.push(
+          `${where}: source must be a "./" path inside the repository (got ${JSON.stringify(source)})`
+        )
+        continue
+      }
+      const pluginDir = posix.normalize(source).replace(/\/$/, "")
+      if (!isDirectory(pluginDir)) {
+        failures.push(`${where}: source ${source} is not a directory`)
+        continue
+      }
+      if ("version" in entry) {
+        failures.push(
+          `${where}: set version in ${pluginDir}/.claude-plugin/plugin.json only; Claude Code ignores the entry's when both are set`
+        )
+      }
+      const manifestPath = `${pluginDir}/.claude-plugin/plugin.json`
+      if (!existsSync(join(rootDir, manifestPath))) {
+        failures.push(`${where}: ${manifestPath} is missing`)
+        continue
+      }
+      const manifest = readJson(manifestPath)
+      if (manifest === undefined) continue
+      if (manifest.name !== entry.name) {
+        failures.push(
+          `${manifestPath}: name "${manifest.name}" must equal the marketplace entry's "${entry.name}", or installing by one name fails`
+        )
+      }
+      if (typeof manifest.description !== "string") {
+        failures.push(`${manifestPath}: description is required`)
+      }
+      if (typeof manifest.author?.name !== "string") {
+        failures.push(`${manifestPath}: author.name is required`)
+      }
+      if (manifest.version !== undefined) {
+        if (!RUNTIME_PLUGIN_MANIFESTS.includes(manifestPath)) {
+          failures.push(
+            `${manifestPath} sets a version but is not in RUNTIME_PLUGIN_MANIFESTS (scripts/ai-context-files.js), so no release would update it`
+          )
+        } else if (manifest.version !== currentReact) {
+          failures.push(
+            `${manifestPath} is at version ${manifest.version} but @ic-reactor/react is at ${currentReact}; installed copies update only when it changes`
+          )
+        }
+      }
+
+      // Its skills: SKILL.md at the plugin root, or skills/<name>/SKILL.md.
+      const skillFiles = []
+      if (existsSync(join(rootDir, pluginDir, "SKILL.md"))) {
+        skillFiles.push(`${pluginDir}/SKILL.md`)
+      }
+      if (isDirectory(`${pluginDir}/skills`)) {
+        for (const dir of readdirSync(join(rootDir, pluginDir, "skills"))) {
+          const rel = `${pluginDir}/skills/${dir}/SKILL.md`
+          if (existsSync(join(rootDir, rel))) skillFiles.push(rel)
+        }
+      }
+      if (skillFiles.length === 0) {
+        failures.push(
+          `${where}: ${pluginDir} holds no SKILL.md at its root or under skills/<name>/`
+        )
+      }
+      for (const rel of skillFiles) {
+        if (!checkedSkills.has(rel)) checkSkill(rel)
+        const skillDir = posix.dirname(rel)
+        if (!consumerSkillDirs.includes(skillDir)) {
+          consumerSkillDirs.push(skillDir)
+        }
+      }
+    }
+  }
+}
+
+for (const relPath of RUNTIME_PLUGIN_MANIFESTS) {
+  if (!existsSync(join(rootDir, relPath))) {
+    failures.push(
+      `RUNTIME_PLUGIN_MANIFESTS names ${relPath}, which does not exist`
+    )
+  }
+}
+
+// ── 8. Consumer skills stand on the published packages ───────────────────────
+// A consumer skill runs in an app's repository, where `packages/react/src` or
+// `examples/...` do not exist; it may point only at the public API, the docs
+// site and node_modules/@ic-reactor/*/llms.txt. It must also state the version
+// of each package it describes, as `- \`@ic-reactor/<pkg>\`: \`<version>\``,
+// the line shape the release scripts rewrite.
+const REPO_PATH =
+  /(?<![\w@/.-])(?:packages|examples|skill-packages|scripts|e2e|docs\/src)\/[\w.-][\w./-]*/
+const VERSION_LINE = /^- `(@ic-reactor\/[\w-]+)`: `([^`]+)`\s*$/
+
+for (const skillDir of consumerSkillDirs) {
+  for (const relMd of skillMarkdown(skillDir)) {
+    // What the agent loads: SKILL.md and its references. README.md is for
+    // people browsing the repository.
+    if (!/\/(SKILL\.md|references\/[^/]+\.md)$/.test(relMd)) continue
+    readFileSync(join(rootDir, relMd), "utf8")
+      .split("\n")
+      .forEach((line, i) => {
+        const found = line.match(REPO_PATH)
+        if (found) {
+          failures.push(
+            `${relMd}:${i + 1} names the repository path "${found[0]}", which an app does not have; link the docs site or node_modules/@ic-reactor/<package>/llms.txt instead`
+          )
+        }
+      })
+  }
+
+  const skillMd = `${skillDir}/SKILL.md`
+  const listed = readFileSync(join(rootDir, skillMd), "utf8")
+    .split("\n")
+    .map((line) => line.match(VERSION_LINE))
+    .filter(Boolean)
+  if (!listed.some(([, name]) => name === "@ic-reactor/react")) {
+    failures.push(
+      `${skillMd} must list the versions it describes, one line per package, such as: - \`@ic-reactor/react\`: \`${currentReact}\``
+    )
+  }
+  for (const [line, name, version] of listed) {
+    const current = currentVersions.get(name)
+    if (current === undefined) {
+      failures.push(`${skillMd}: "${line.trim()}" names no @ic-reactor package`)
+    } else if (version !== current) {
+      failures.push(`${skillMd}: "${line.trim()}" but ${name} is at ${current}`)
+    }
+  }
+}
+
+// ── 9. No removed 3.x name outside a "Removed in 4.0" section ────────────────
+// The guides, the contributor files and the skill are what an agent reads to
+// learn the 4 API. A 3.x name left in one (`ClientManager` in a snippet, a
+// `createQuery` in a sentence about caching) teaches an API that is gone,
+// and the agent writes it. The 34 names of the migration table
+// (scripts/removed-v3-names.js) may appear only under a heading that begins
+// "Removed in 4.0", which is where the guide says what replaced them; the
+// section runs to the next heading of the same or a higher level. Headings are
+// read outside code fences only, so a `# Removed in 4.0` comment in a snippet
+// opens nothing.
+//
+// What counts as a mention: the name as a whole word, in prose, a code span
+// or a snippet alike. Two names get a narrower rule, stated in
+// removed-v3-names.js: the product name "IC Reactor" is not `Reactor`, and
+// `skipToken` is stale only when imported from, or named beside, an
+// `@ic-reactor/*` package, since `@tanstack/react-query` still exports it.
+const REMOVED_NAME = new RegExp(
+  `(?<![\\w$])(${[...REMOVED_V3_NAMES]
+    .sort((a, b) => b.name.length - a.name.length)
+    .map(({ name }) => name)
+    .join("|")})(?![\\w$])`,
+  "g"
+)
+const removedByName = new Map(
+  REMOVED_V3_NAMES.map((entry) => [entry.name, entry])
+)
+const REMOVED_HEADING = /^removed in 4\.0\b/i
+const PRODUCT_NAME = /\bIC Reactor\b/g
+const IC_REACTOR_IMPORT =
+  /\bimport\s+(?:type\s+)?\{[^}]*\}\s*from\s*["']@ic-reactor\/[^"']*["']/g
+
+/**
+ * Every mention of a removed name outside a "Removed in 4.0" section, or every
+ * mention at all when `exempt` is `false`.
+ *
+ * @param {string} text
+ * @param {{ exempt?: boolean }} [options] - `exempt: false` ignores the
+ *   "Removed in 4.0" headings
+ * @returns {{ line: number, name: string }[]} `line` is 1-based
+ */
+function staleNameMentions(text, { exempt = true } = {}) {
+  const lines = text.split("\n")
+  const starts = []
+  let offset = 0
+  for (const line of lines) {
+    starts.push(offset)
+    offset += line.length + 1
+  }
+  // An import's braces may span lines, so its extent is found in the whole text.
+  const icImports = [...text.matchAll(IC_REACTOR_IMPORT)].map((m) => [
+    m.index,
+    m.index + m[0].length,
+  ])
+  const found = []
+  const fenced = fencedLines()
+  let exemptLevel = null
+  lines.forEach((line, i) => {
+    if (!fenced(line)) {
+      const heading = line.match(/^ {0,3}(#{1,6})\s+(.*?)\s*#*\s*$/)
+      if (heading) {
+        const level = heading[1].length
+        const title = heading[2].replace(/[`*_]/g, "")
+        if (exempt && REMOVED_HEADING.test(title)) exemptLevel = level
+        else if (exemptLevel !== null && level <= exemptLevel)
+          exemptLevel = null
+      }
+    }
+    if (exemptLevel !== null) return
+    const prose = line.replace(PRODUCT_NAME, (m) => " ".repeat(m.length))
+    for (const match of prose.matchAll(REMOVED_NAME)) {
+      const { name, fromTanStack } = removedByName.get(match[1])
+      if (
+        fromTanStack &&
+        !line.includes("@ic-reactor/") &&
+        !icImports.some(
+          ([from, to]) =>
+            starts[i] + match.index >= from && starts[i] + match.index < to
+        )
+      ) {
+        continue
+      }
+      found.push({ line: i + 1, name })
+    }
+  })
+  return found
+}
+
+for (const relPath of aiContextFiles) {
+  const absPath = join(rootDir, relPath)
+  if (!existsSync(absPath)) continue // reported above
+  for (const { line, name } of staleNameMentions(
+    readFileSync(absPath, "utf8")
+  )) {
+    failures.push(
+      `${relPath}:${line} mentions ${name}, which 4.0 removed (use ${removedByName.get(name).use}). ` +
+        `Remove it, or move the mention under a heading that begins "Removed in 4.0".`
+    )
+  }
+}
+
+// ── 10. The 4 docs pages teach no removed name and link no 3.x page ──────────
+// The pages of docs/src/content/docs are what a person reads once they have
+// found the site, so they follow check 9 as the AI-context files do: a removed
+// name appears only under a heading that begins "Removed in 4.0", and only on
+// the migration page (V3_LINK_PAGE). Another page gets no exemption for such a
+// heading, so the table of removed names stays in one place. They are not
+// in AI_CONTEXT_FILES, which would also apply check 3 and let the release
+// script rewrite them: a page names versions of other packages (a peer range,
+// a TanStack Query release) that check 3 refuses. The generated API reference
+// (`libs/`) is not a page of the tree and is left out, as in check 5.
+//
+// Versions get a rule of their own. A page names no @ic-reactor version (the
+// site follows the branch, so a release would leave one stale), and every
+// prerelease version it names, such as the `--save-exact` install of
+// `@meantjs/schema`, is the exact pin some packages/*/package.json has,
+// so an install line moves with the pin. A stable version is held to the pin
+// when the page names it with its package, as `@meantjs/schema@0.6.0`: a
+// package that packages/*/package.json pins exactly is installed at that pin.
+//
+// The pages also keep out of the 3.x docs: one page, the migration guide,
+// links `/v3/`, and every other page reaches the 3.x docs through it. A link
+// is an absolute URL of the site's `/v3/`, or a link, `href` or reference
+// definition that starts with `/v3` (the site's own path, which leaves the
+// 4 docs). The whole page is read, code fences included, since a reader
+// copies a URL from a fence as well.
+const V3_LINK_PAGE = "migrating-from-3.mdx"
+const V3_LINK =
+  /ic-reactor\.b3pay\.net\/v3(?![\w-])|(?:\]\(\s*<?|href=\s*["']|^\s*\[[^\]]+\]:\s*<?)\/v3(?![\w-])/g
+
+/** Exact prerelease pins (such as `0.3.0-beta.1`) of the packages' dependencies. */
+const exactPins = new Set()
+/** Every exact pin of the packages' dependencies, stable ones included, by package. */
+const exactPinsByName = new Map()
+for (const { packageDir } of versionChecks) {
+  const pkg = JSON.parse(
+    readFileSync(join(rootDir, "packages", packageDir, "package.json"), "utf8")
+  )
+  for (const field of ["dependencies", "peerDependencies", "devDependencies"]) {
+    for (const [name, range] of Object.entries(pkg[field] ?? {})) {
+      if (/^\d+\.\d+\.\d+-[0-9A-Za-z.-]+$/.test(range)) exactPins.add(range)
+      if (/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(range)) {
+        if (!exactPinsByName.has(name)) exactPinsByName.set(name, new Set())
+        exactPinsByName.get(name).add(range)
+      }
+    }
+  }
+}
+const PRERELEASE =
+  /(?<![\d.])v?(\d+\.\d+\.\d+-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)(?![\d.]\d)/g
+/** A scoped package named with a version, as an install line names it: `@scope/name@1.2.3`. */
+const NAMED_VERSION =
+  /(?<![\w@/.-])(@[a-z0-9][\w.-]*\/[a-z0-9][\w.-]*)@(\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?)(?![\w.-]*\d)/g
+
+for (const page of [...sourcePages].sort()) {
+  const relPath = `docs/src/content/docs/${page}`
+  const text = readFileSync(join(rootDir, relPath), "utf8")
+  text.split("\n").forEach((line, i) => {
+    for (const [, name, version] of line.matchAll(NAMED_VERSION)) {
+      const pins = exactPinsByName.get(name)
+      // A prerelease is held to the pins by the rule below.
+      if (!pins || version.includes("-") || pins.has(version)) continue
+      failures.push(
+        `${relPath}:${i + 1} names ${name}@${version}, which packages/*/package.json pins exactly at ` +
+          `${[...pins].join(", ")}. Name the pin.`
+      )
+    }
+    for (const [, version] of line.matchAll(PRERELEASE)) {
+      if (exactPins.has(version)) continue
+      failures.push(
+        validVersions.has(version)
+          ? `${relPath}:${i + 1} names the @ic-reactor version ${version}. A docs page names none: ` +
+              `the site follows main, which can be ahead of the latest release, so install without a version instead.`
+          : `${relPath}:${i + 1} names version ${version}, which no package pins exactly ` +
+              `(pins: ${[...exactPins].join(", ") || "none"}). Name the pin of packages/*/package.json.`
+      )
+    }
+  })
+  for (const { line, name } of staleNameMentions(text, {
+    exempt: page === V3_LINK_PAGE,
+  })) {
+    failures.push(
+      `${relPath}:${line} mentions ${name}, which 4.0 removed (use ${removedByName.get(name).use}). ` +
+        `Remove it, or move it to ${V3_LINK_PAGE}, under a heading that begins "Removed in 4.0".`
+    )
+  }
+  if (page === V3_LINK_PAGE) continue
+  text.split("\n").forEach((line, i) => {
+    for (const match of line.matchAll(V3_LINK)) {
+      failures.push(
+        `${relPath}:${i + 1} links the 3.x docs (${match[0].trim()}). ` +
+          `Only ${V3_LINK_PAGE} may; link to /v4/${V3_LINK_PAGE.replace(/\.mdx$/, "")}/ instead.`
+      )
+    }
+  })
+}
+
+// ── 11. Each package's homepage is its own page of the 4 docs ───────────────
+// npm shows `homepage` as the package's link, so it names the package's page
+// (`https://ic-reactor.b3pay.net/v4/packages/core/`), and that page must exist.
+// Every package of the lane publishes, so a missing `homepage` fails too: npm
+// would fall back to the repository's README.
+for (const { packageName, packageDir } of versionChecks) {
+  const relPath = `packages/${packageDir}/package.json`
+  const { homepage } = JSON.parse(readFileSync(join(rootDir, relPath), "utf8"))
+  const expected = `${DOCS_SITE}${DOCS_BASE}packages/${packageDir}/`
+  if (homepage === undefined) {
+    failures.push(
+      `${relPath} has no homepage; ${packageName}'s is its page, ${expected}`
+    )
+  } else if (homepage !== expected) {
+    failures.push(
+      `${relPath} has homepage ${homepage}; ${packageName}'s is its page, ${expected}`
+    )
+  } else if (resolveDocsPath(`packages/${packageDir}/`) === undefined) {
+    failures.push(
+      `${relPath} has homepage ${homepage}, but docs/src/content/docs has no packages/${packageDir} page`
+    )
+  }
+}
+
+// ── 12. No link to the retired v4 branch ─────────────────────────────────────
+// ic-reactor 4 lives on `main` since the 4.0 GA flip, and the `v4` branch is
+// deleted after a window, so a GitHub, raw or sandbox link to it would 404.
+// A tag (`tree/v4.0.0`) is not a branch and is allowed. Checked in the files
+// whose site links are checked, the docs pages and the docs config (its edit
+// link).
+const V4_BRANCH_LINK =
+  /(?:github\.com\/b3pay\/ic-reactor\/(?:tree|blob|edit|raw|commits)\/|raw\.githubusercontent\.com\/b3pay\/ic-reactor\/|stackblitz\.com\/github\/b3pay\/ic-reactor\/tree\/|codesandbox\.io\/p\/github\/b3pay\/ic-reactor\/)v4(?![\w.-])/gi
+for (const relPath of [
+  ...new Set([
+    ...docsLinkFiles,
+    "docs/astro.config.mjs",
+    ...[...sourcePages].sort().map((page) => `docs/src/content/docs/${page}`),
+  ]),
+]) {
+  const absPath = join(rootDir, relPath)
+  if (!existsSync(absPath)) continue
+  readFileSync(absPath, "utf8")
+    .split("\n")
+    .forEach((line, i) => {
+      for (const match of line.matchAll(V4_BRANCH_LINK)) {
+        failures.push(
+          `${relPath}:${i + 1} links the v4 branch (${match[0]}). ic-reactor 4 is on main: link main instead.`
+        )
+      }
+    })
+}
+
+if (failures.length > 0) {
+  console.error("AI context check failed:\n")
+  for (const failure of failures) {
+    console.error(`- ${failure}`)
+  }
+  // Not process.exit(): on a pipe it can cut off output still being written,
+  // and a long list of failures is the output most worth reading in full.
+  process.exitCode = 1
+} else {
+  console.log(
+    `AI context check passed (${aiContextFiles.length} files, ${packageGuides.length} package guides, ` +
+      `${checkedSkills.size} skills, ${consumerSkillDirs.length} consumer skill(s), ` +
+      `docs links in ${docsLinkFiles.length} files, ${sourcePages.size} docs pages, versions: ${[...validVersions].join(", ")}).`
+  )
+}