@piagent/platform 1.1.9 → 1.2.1

package/scripts/preview-docs-site.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Serves docs-site/ locally the way Vercel serves it.
+//
+// The deployed site runs with `cleanUrls: true`, so every internal link points
+// at /quickstart rather than /quickstart.html. A plain static file server
+// answers 404 for all of them, which makes a local preview useless for
+// checking navigation. This resolves the extensionless path the same way.
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const siteRoot = path.join(repoRoot, "docs-site");
+
+const CONTENT_TYPES = {
+  ".css": "text/css; charset=utf-8",
+  ".html": "text/html; charset=utf-8",
+  ".ico": "image/x-icon",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".txt": "text/plain; charset=utf-8",
+  ".webmanifest": "application/manifest+json"
+};
+
+function portFromArgs(argv) {
+  const flag = argv.indexOf("--port");
+  const raw = flag >= 0 ? argv[flag + 1] : process.env.PORT;
+  if (!raw) return 4321;
+  const port = Number.parseInt(raw, 10);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`invalid port: ${raw}`);
+  }
+  return port;
+}
+
+/** Resolve a request path to a file inside the site root, or undefined. */
+function resolveFile(urlPath) {
+  const requested = urlPath === "/" ? "/index.html" : urlPath;
+  const candidate = path.resolve(siteRoot, `.${requested}`);
+  // A traversal such as /../../.ssh/id_rsa escapes the site root; refuse it
+  // rather than reading whatever it lands on.
+  if (candidate !== siteRoot && !candidate.startsWith(siteRoot + path.sep)) return undefined;
+  for (const file of [candidate, `${candidate}.html`, path.join(candidate, "index.html")]) {
+    if (fs.existsSync(file) && fs.statSync(file).isFile()) return file;
+  }
+  return undefined;
+}
+
+const port = portFromArgs(process.argv.slice(2));
+
+const server = http.createServer((req, res) => {
+  if (req.method !== "GET" && req.method !== "HEAD") {
+    res.writeHead(405, { allow: "GET, HEAD" });
+    res.end();
+    return;
+  }
+  let urlPath;
+  try {
+    urlPath = decodeURIComponent(new URL(req.url, `http://localhost:${port}`).pathname);
+  } catch {
+    res.writeHead(400, { "content-type": "text/plain; charset=utf-8" });
+    res.end("bad request\n");
+    return;
+  }
+  const file = resolveFile(urlPath);
+  if (!file) {
+    res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+    res.end(`not found: ${urlPath}\n`);
+    return;
+  }
+  const body = fs.readFileSync(file);
+  res.writeHead(200, {
+    "content-type": CONTENT_TYPES[path.extname(file)] ?? "application/octet-stream",
+    "content-length": body.length,
+    "cache-control": "no-store"
+  });
+  res.end(req.method === "HEAD" ? undefined : body);
+});
+
+// Loopback only: this serves local files and has no business being reachable
+// from the network.
+server.listen(port, "127.0.0.1", () => {
+  process.stdout.write(`docs-site preview on http://localhost:${port} (Ctrl+C to stop)\n`);
+});

package/scripts/quality-benchmark.sh

@@ -31,6 +31,14 @@ if [[ -z "$PROJECT_PATH" ]]; then
   usage
   exit 2
 fi
+# The project path is positional and comes first, so omitting it hands the first
+# flag to `cd` and the run dies somewhere further down complaining about an
+# option. Say what is actually wrong instead.
+if [[ "$PROJECT_PATH" == -* ]]; then
+  echo "FAIL: the project path comes first, before any flag; received: $PROJECT_PATH" >&2
+  usage >&2
+  exit 2
+fi
 shift || true
 
 PROJECT_PATH="$(cd "$PROJECT_PATH" && pwd)"
@@ -45,6 +53,17 @@ COST=""
 DURATION=""
 NOTES=""
 
+# A flag left without a value otherwise consumes the next flag as its value, and
+# the run continues on a record that says something nobody typed.
+require_value() {
+  local option="$1"
+  local value="${2:-}"
+  if [[ -z "$value" || "$value" == --* ]]; then
+    echo "Missing value for $option" >&2
+    exit 2
+  fi
+}
+
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --init)
@@ -56,39 +75,48 @@ while [[ $# -gt 0 ]]; do
       shift
       ;;
     --scenario)
-      SCENARIO="${2:-}"
+      require_value "$1" "${2:-}"
+      SCENARIO="$2"
       shift 2
       ;;
     --surface|--agent)
-      SURFACE="${2:-}"
+      require_value "$1" "${2:-}"
+      SURFACE="$2"
       shift 2
       ;;
     --result)
-      RESULT="${2:-}"
+      require_value "$1" "${2:-}"
+      RESULT="$2"
       shift 2
       ;;
     --task-file)
-      TASK_FILE="${2:-}"
+      require_value "$1" "${2:-}"
+      TASK_FILE="$2"
       shift 2
       ;;
     --verify)
-      VERIFY_CMD="${2:-}"
+      require_value "$1" "${2:-}"
+      VERIFY_CMD="$2"
       shift 2
       ;;
     --tokens)
-      TOKENS="${2:-}"
+      require_value "$1" "${2:-}"
+      TOKENS="$2"
       shift 2
       ;;
     --cost)
-      COST="${2:-}"
+      require_value "$1" "${2:-}"
+      COST="$2"
       shift 2
       ;;
     --duration)
-      DURATION="${2:-}"
+      require_value "$1" "${2:-}"
+      DURATION="$2"
       shift 2
       ;;
     --notes)
-      NOTES="${2:-}"
+      require_value "$1" "${2:-}"
+      NOTES="$2"
       shift 2
       ;;
     -h|--help)

package/scripts/setup.sh

@@ -28,11 +28,11 @@ Options:
                                   Install/skip pi-subagents during global install (default: install)
   --subagents-preset <minimal|safe|async|parallel>
                                   Configure pi-subagents runtime baseline (default: safe)
-  --subagents-model-scope <none|piagent|codex|claude>
+  --subagents-model-scope <none|piagent|codex|claude>   model family for subagents
                                   Optional subagent model allowlist (default: none)
   --with-web-access               Install pi-web-access for builtin `researcher` subagent (default: skip)
   --with-herdr / --no-herdr      Install/skip Herdr Pi integration if herdr exists (default: install)
-  --model-scope <full|codex|claude>
+  --model-scope <full|codex|claude>   model families to enable
                                   Configure Pi enabledModels for selector/cycling (default: full)
   --default-model <provider/model[:thinking]>
                                   Configure default provider/model/thinking (default: openai-codex/gpt-5.5:xhigh)
@@ -85,21 +85,24 @@ SKIP_AGENTS=false
 SKIP_REVIEW=false
 DRY_RUN=false
 
+require_value() {
+  local option="$1"
+  local value="${2:-}"
+  if [[ -z "$value" || "$value" == --* ]]; then
+    echo "Missing value for $option" >&2
+    exit 2
+  fi
+}
+
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --profile)
-      if [[ $# -lt 2 ]]; then
-        echo "Missing value for --profile" >&2
-        exit 2
-      fi
+      require_value "$1" "${2:-}"
       PROFILE_INPUT="$2"
       shift 2
       ;;
     --package-source)
-      if [[ $# -lt 2 ]]; then
-        echo "Missing value for --package-source" >&2
-        exit 2
-      fi
+      require_value "$1" "${2:-}"
       PACKAGE_SOURCE="$2"
       shift 2
       ;;
@@ -124,7 +127,8 @@ while [[ $# -gt 0 ]]; do
       shift
       ;;
     --mcp-preset)
-      MCP_PRESET="${2:-}"
+      require_value "$1" "${2:-}"
+      MCP_PRESET="$2"
       MCP_PRESET_EXPLICIT=true
       shift 2
       ;;
@@ -137,11 +141,13 @@ while [[ $# -gt 0 ]]; do
       shift
       ;;
     --subagents-preset)
-      SUBAGENTS_PRESET="${2:-}"
+      require_value "$1" "${2:-}"
+      SUBAGENTS_PRESET="$2"
       shift 2
       ;;
     --subagents-model-scope)
-      SUBAGENTS_MODEL_SCOPE="${2:-}"
+      require_value "$1" "${2:-}"
+      SUBAGENTS_MODEL_SCOPE="$2"
       shift 2
       ;;
     --with-web-access)
@@ -157,11 +163,13 @@ while [[ $# -gt 0 ]]; do
       shift
       ;;
     --model-scope)
-      MODEL_SCOPE_PRESET="${2:-}"
+      require_value "$1" "${2:-}"
+      MODEL_SCOPE_PRESET="$2"
       shift 2
       ;;
     --default-model)
-      DEFAULT_MODEL="${2:-}"
+      require_value "$1" "${2:-}"
+      DEFAULT_MODEL="$2"
       shift 2
       ;;
     --no-model-scope)

package/scripts/team-doctor.sh

@@ -137,7 +137,7 @@ function runtimeMatrixStatus() {
     surface: `${platform}/${arch}`,
     status: "outside-release-matrix",
     teamRolloutReady: false,
-    note: "This runtime is outside the documented v1.1.9 support matrix."
+    note: "This runtime is outside the documented v1.2.0 support matrix."
   };
 }
 
@@ -169,7 +169,7 @@ for (const rel of [
   "templates/project/.pi/memory/memory_summary.md",
   "templates/project/.pi/memory/MEMORY.md",
   "scripts/setup.sh",
-  "scripts/configure-mcp.sh",
+  "scripts/mcp-manage.mjs",
   "scripts/configure-subagents.sh"
 ]) {
   if (!exists(rel)) errors.push(`missing platform file: ${rel}`);
@@ -247,6 +247,22 @@ if (piHasMcpAdapter && totalMcpServers === 0) {
   warnings.push("Pi MCP adapter is installed but no MCP servers are configured; run `piagent-mcp --preset core --scope global` or `/mcp setup`");
 }
 
+// Counting servers says nothing about whether any of them can answer. A server
+// whose token is not exported, or which this repository defines and nobody
+// approved, is configured and unusable, and finding that out when a call fails
+// is the thing this check exists to prevent.
+try {
+  const { collectServers } = await import(pathToFileURL(path.join(platformRoot, "packages", "piagent-core", "mcp", "mcp-config-layers.js")).href);
+  const { evaluateServerReadiness, BLOCKING_STATES } = await import(pathToFileURL(path.join(platformRoot, "packages", "piagent-core", "mcp", "mcp-auth-readiness.js")).href);
+  for (const server of collectServers({ projectPath })) {
+    const readiness = evaluateServerReadiness(server, { projectPath });
+    if (!BLOCKING_STATES.has(readiness.state)) continue;
+    warnings.push(`MCP server ${server.name} (${server.scope}) is configured but not usable: ${readiness.detail}${readiness.remedy ? `; ${readiness.remedy}` : ""}`);
+  }
+} catch (error) {
+  warnings.push(`MCP readiness check could not run: ${error instanceof Error ? error.message : String(error)}`);
+}
+
 const subagentConfigPath = path.join(process.env.PI_CODING_AGENT_DIR || path.join(process.env.HOME || "", ".pi", "agent"), "extensions", "subagent", "config.json");
 const subagentConfig = readJsonIfPresent(subagentConfigPath);
 if (piHasSubagents && !subagentConfig) {

package/scripts/uninstall-global.sh

@@ -39,16 +39,22 @@ todos, and project memory. Those are operator data, not platform state.
 USAGE
 }
 
+require_value() {
+  local option="$1"
+  local value="${2:-}"
+  if [[ -z "$value" || "$value" == --* ]]; then
+    echo "Missing value for $option" >&2
+    exit 2
+  fi
+}
+
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --apply) APPLY=true; shift ;;
     --with-addons) WITH_ADDONS=true; shift ;;
     --with-host) WITH_HOST=true; shift ;;
     --project)
-      if [[ $# -lt 2 || -z "${2:-}" ]]; then
-        echo "Missing value for --project" >&2
-        exit 2
-      fi
+      require_value "$1" "${2:-}"
       PROJECT_PATH="$2"
       shift 2
       ;;

package/scripts/verify-local.sh

@@ -126,9 +126,16 @@ required_files=(
   "$ROOT/docs/capability-packs.md"
   "$ROOT/docs/runtime-policy-design.md"
   "$ROOT/docs-site/index.html"
+  "$ROOT/docs-site/mcp.html"
   "$ROOT/docs-site/favicon.svg"
   "$ROOT/docs-site/assets/piagent-logo.svg"
+  "$ROOT/docs-site/assets/docs.css"
+  "$ROOT/docs-site/assets/docs.js"
+  "$ROOT/docs-site/content/index.html"
+  "$ROOT/docs-site/content/mcp.html"
   "$ROOT/docs-site/vercel.json"
+  "$ROOT/scripts/build-docs-site.mjs"
+  "$ROOT/scripts/preview-docs-site.mjs"
   "$ROOT/schemas/project-profile.schema.json"
   "$ROOT/schemas/task-contract.schema.json"
   "$ROOT/schemas/capability-pack.schema.json"
@@ -157,10 +164,11 @@ required_files=(
   "$ROOT/scripts/quality-benchmark.sh"
   "$ROOT/scripts/runtime-policy-smoke.sh"
   "$ROOT/scripts/pi-session-stats.sh"
+  "$ROOT/scripts/pi-usage-history.mjs"
   "$ROOT/scripts/pi-auto.sh"
   "$ROOT/scripts/pi-model-catalog.sh"
   "$ROOT/scripts/configure-model-scope.sh"
-  "$ROOT/scripts/configure-mcp.sh"
+  "$ROOT/scripts/mcp-manage.mjs"
   "$ROOT/scripts/configure-subagents.sh"
   "$ROOT/scripts/capability-catalog.mjs"
   "$ROOT/scripts/migrate-project-state.mjs"
@@ -182,6 +190,9 @@ required_files=(
   "$ROOT/tests/document-intake.test.mjs"
   "$ROOT/tests/runtime-advisories.test.mjs"
   "$ROOT/scripts/check-runtime-advisories.mjs"
+  "$ROOT/packages/piagent-core/mcp/mcp-session-view.js"
+  "$ROOT/packages/piagent-core/mcp/mcp-command-actions.js"
+  "$ROOT/tests/mcp-session-command.test.mjs"
   "$ROOT/tests/migrate-project-state.test.mjs"
   "$ROOT/tests/uninstall-global.test.mjs"
   "$ROOT/tests/import-agent-instructions.test.mjs"
@@ -413,33 +424,33 @@ require_documented "gpt-5.6" "$ROOT/README.md" "$ROOT/docs/model-options.md" "$R
 require_documented "claude-fable-5" "$ROOT/README.md" "$ROOT/docs/model-options.md" "$ROOT/packages/piagent-core/prompts/model-options.md"
 require_documented "piagent-models" "$ROOT/README.md" "$ROOT/docs/model-options.md"
 require_documented "enabledModels" "$ROOT/templates/global/settings.json" "$ROOT/docs/model-options.md" "$ROOT/scripts/configure-model-scope.sh"
-require_documented "piagent-mcp" "$ROOT/README.md" "$ROOT/docs/mcp-and-tools.md" "$ROOT/scripts/configure-mcp.sh"
+require_documented "piagent-mcp" "$ROOT/README.md" "$ROOT/docs/mcp-and-tools.md" "$ROOT/scripts/mcp-manage.mjs"
 require_documented "pi-mcp-adapter" "$ROOT/README.md" "$ROOT/docs/mcp-and-tools.md" "$ROOT/scripts/install-global.sh"
 require_documented "piagent-subagents" "$ROOT/README.md" "$ROOT/docs/subagents-and-multiagent.md" "$ROOT/scripts/configure-subagents.sh"
 require_documented "subagents-fleet" "$ROOT/docs/command-reference-vietnamese.md" "$ROOT/docs/subagents-and-multiagent.md" "$ROOT/README.md"
 require_documented "health check" "$ROOT/docs/command-reference-vietnamese.md" "$ROOT/docs/subagents-and-multiagent.md" "$ROOT/README.md"
 require_documented "pi-subagents" "$ROOT/README.md" "$ROOT/docs/subagents-and-multiagent.md" "$ROOT/scripts/install-global.sh" "$ROOT/scripts/setup.sh"
 require_documented "piagent-scout" "$ROOT/README.md" "$ROOT/docs/subagents-and-multiagent.md" "$ROOT/packages/piagent-core/subagents"
-grep -F "@upstash/context7-mcp@3.2.4" "$ROOT/scripts/configure-mcp.sh" >/dev/null
+grep -F "@upstash/context7-mcp@3.2.4" "$ROOT/packages/piagent-core/mcp/mcp-server-catalog.js" >/dev/null
 grep -F "@upstash/context7-mcp@3.2.4" "$ROOT/docs/mcp-and-tools.md" >/dev/null
-grep -F "chrome-devtools-mcp@1.6.0" "$ROOT/scripts/configure-mcp.sh" >/dev/null
+grep -F "chrome-devtools-mcp@1.6.0" "$ROOT/packages/piagent-core/mcp/mcp-server-catalog.js" >/dev/null
 grep -F "chrome-devtools-mcp@1.6.0" "$ROOT/docs/mcp-and-tools.md" >/dev/null
-grep -F "@playwright/mcp@0.0.78" "$ROOT/scripts/configure-mcp.sh" >/dev/null
+grep -F "@playwright/mcp@0.0.78" "$ROOT/packages/piagent-core/mcp/mcp-server-catalog.js" >/dev/null
 grep -F "@playwright/mcp@0.0.78" "$ROOT/docs/mcp-and-tools.md" >/dev/null
-require_documented "https://mcp.figma.com/mcp" "$ROOT/scripts/configure-mcp.sh" "$ROOT/docs/mcp-and-tools.md"
-grep -F "ghcr.io/github/github-mcp-server@sha256:2b0c48b070f61e9d3969269ead600f62d00fb237b60ac849ef3d166ee7de9ad3" "$ROOT/scripts/configure-mcp.sh" >/dev/null
+require_documented "https://mcp.figma.com/mcp" "$ROOT/packages/piagent-core/mcp/mcp-server-catalog.js" "$ROOT/docs/mcp-and-tools.md"
+grep -F "ghcr.io/github/github-mcp-server@sha256:2b0c48b070f61e9d3969269ead600f62d00fb237b60ac849ef3d166ee7de9ad3" "$ROOT/packages/piagent-core/mcp/mcp-server-catalog.js" >/dev/null
 grep -F "ghcr.io/github/github-mcp-server@sha256:2b0c48b070f61e9d3969269ead600f62d00fb237b60ac849ef3d166ee7de9ad3" "$ROOT/docs/mcp-and-tools.md" >/dev/null
-grep -F '"GITHUB_READ_ONLY=1"' "$ROOT/scripts/configure-mcp.sh" >/dev/null
+grep -F '"GITHUB_READ_ONLY=1"' "$ROOT/packages/piagent-core/mcp/mcp-server-catalog.js" >/dev/null
 grep -F '"GITHUB_READ_ONLY=1"' "$ROOT/docs/mcp-and-tools.md" >/dev/null
-grep -F '"GITHUB_LOCKDOWN_MODE=1"' "$ROOT/scripts/configure-mcp.sh" >/dev/null
+grep -F '"GITHUB_LOCKDOWN_MODE=1"' "$ROOT/packages/piagent-core/mcp/mcp-server-catalog.js" >/dev/null
 grep -F '"GITHUB_LOCKDOWN_MODE=1"' "$ROOT/docs/mcp-and-tools.md" >/dev/null
-grep -F 'CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: "1"' "$ROOT/scripts/configure-mcp.sh" >/dev/null
+grep -F 'CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: "1"' "$ROOT/packages/piagent-core/mcp/mcp-server-catalog.js" >/dev/null
 grep -F '"CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS": "1"' "$ROOT/docs/mcp-and-tools.md" >/dev/null
-grep -F 'CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS: "1"' "$ROOT/scripts/configure-mcp.sh" >/dev/null
+grep -F 'CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS: "1"' "$ROOT/packages/piagent-core/mcp/mcp-server-catalog.js" >/dev/null
 grep -F '"CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS": "1"' "$ROOT/docs/mcp-and-tools.md" >/dev/null
-grep -F 'configure-mcp.sh" --scope global --preset "$MCP_PRESET" --replace' "$ROOT/scripts/install-global.sh" >/dev/null
-grep -F 'piagent-mcp --preset core --scope global --replace' "$ROOT/scripts/configure-mcp.sh" >/dev/null
-if grep -E '@latest|"@upstash/context7-mcp"|"chrome-devtools-mcp"|"@playwright/mcp"|"ghcr\.io/github/github-mcp-server"' "$ROOT/scripts/configure-mcp.sh" >/dev/null; then
+grep -F 'mcp-manage.mjs" --scope global --preset "$MCP_PRESET" --replace' "$ROOT/scripts/install-global.sh" >/dev/null
+grep -F 'piagent-mcp --preset core --scope global --replace' "$ROOT/scripts/mcp-manage.mjs" >/dev/null
+if grep -E '@latest|"@upstash/context7-mcp"|"chrome-devtools-mcp"|"@playwright/mcp"|"ghcr\.io/github/github-mcp-server"' "$ROOT/packages/piagent-core/mcp/mcp-server-catalog.js" >/dev/null; then
   echo "MCP production presets contain a mutable dependency source"
   exit 1
 fi
@@ -459,6 +470,23 @@ require_documented "piagent-capabilities" "$ROOT/README.md" "$ROOT/docs/capabili
 require_documented ".pi-subagents/" "$ROOT/.gitignore" "$ROOT/docs/subagents-and-multiagent.md" "$ROOT/docs/distribution-standard.md" "$ROOT/scripts/init-project.sh"
 test -s "$ROOT/tests/policy-core.test.mjs"
 
+# Every gate below this line is a grep, and grep skips a file it decides is
+# binary. One control byte written into a string literal — a NUL used as a key
+# separator is the easy way to do it by accident — takes the whole file out of
+# every one of them, and out of the diff a reviewer reads on a pull request. The
+# file still runs, so nothing else notices. Escapes carry the same bytes and keep
+# the file readable.
+non_text_sources="$(
+  cd "$ROOT" && git ls-files -z -- '*.js' '*.mjs' '*.ts' '*.json' '*.md' '*.sh' '*.html' '*.css' \
+    | LC_ALL=C xargs -0 -I{} sh -c 'grep -qI "" "{}" 2>/dev/null || echo "{}"'
+)"
+if [[ -n "$non_text_sources" ]]; then
+  echo "Source files contain control bytes, so grep-based gates and diffs skip them:"
+  echo "$non_text_sources" | sed 's/^/  /'
+  echo "Write the byte as an escape (\\u0000, \\x03) instead of embedding it."
+  exit 1
+fi
+
 public_wording_pattern="$(
   node --input-type=module <<'NODE'
 const terms = [
@@ -471,6 +499,9 @@ const terms = [
   ["mit", "suhiko"].join(""),
   ["Cod", "ex CLI"].join(""),
   ["Claude", " CLI"].join(""),
+  ["Claude", " Code"].join(""),
+  ["claude", " mcp"].join(""),
+  ["codex", " mcp"].join(""),
   ["Cod", "ex-inspired"].join(""),
   ["Cod", "ex-grade"].join(""),
   ["Pi vs ", "Codex"].join(""),
@@ -485,12 +516,21 @@ console.log(terms.map(escapeRegex).join("|"));
 NODE
 )"
 
+# Every surface an outsider reads: the published docs, the site, and the strings
+# the runtime prints back at an operator. The site is checked at its source,
+# since `build-docs-site.mjs --check` separately proves the committed pages match
+# it; the builder itself is listed too, because navigation labels and page titles
+# live there rather than in a content fragment.
 if grep -R -E -i \
   "$public_wording_pattern" \
   "$ROOT/README.md" \
   "$ROOT/docs" \
+  "$ROOT/docs-site/content" \
+  "$ROOT/scripts/build-docs-site.mjs" \
   "$ROOT/packages/piagent-core/README.md" \
   "$ROOT/packages/piagent-core/prompts" \
+  "$ROOT/packages/piagent-core/mcp" \
+  "$ROOT/packages/piagent-core/extensions" \
   "$ROOT/templates/project/AGENTS.md" >/dev/null; then
   echo "Public docs contain non-neutral platform wording"
   exit 1
@@ -505,10 +545,13 @@ node --check "$ROOT/packages/piagent-core/capabilities/capability-core.js" >/dev
 node --check "$ROOT/packages/piagent-core/capabilities/capability-sources.js" >/dev/null
 node --check "$ROOT/scripts/capability-catalog.mjs" >/dev/null
 node --check "$ROOT/scripts/piagent-cli.mjs" >/dev/null
+node --check "$ROOT/scripts/pi-usage-history.mjs" >/dev/null
 node --check "$ROOT/scripts/migrate-project-state.mjs" >/dev/null
 node --check "$ROOT/scripts/import-agent-instructions.mjs" >/dev/null
 node --check "$ROOT/scripts/check-runtime-advisories.mjs" >/dev/null
 node --check "$ROOT/scripts/check-published-site.mjs" >/dev/null
+node --check "$ROOT/scripts/build-docs-site.mjs" >/dev/null
+node --check "$ROOT/scripts/preview-docs-site.mjs" >/dev/null
 run_quietly "npm test" npm test
 if [[ -x "$ROOT/node_modules/.bin/tsc" ]]; then
   run_quietly "npm run typecheck" npm run typecheck
@@ -519,7 +562,9 @@ bash -n "$ROOT/scripts/pi-session-stats.sh"
 bash -n "$ROOT/scripts/pi-auto.sh"
 bash -n "$ROOT/scripts/pi-model-catalog.sh"
 bash -n "$ROOT/scripts/configure-model-scope.sh"
-bash -n "$ROOT/scripts/configure-mcp.sh"
+node --check "$ROOT/scripts/mcp-manage.mjs"
+node --check "$ROOT/packages/piagent-core/mcp/mcp-session-view.js"
+node --check "$ROOT/packages/piagent-core/mcp/mcp-command-actions.js"
 bash -n "$ROOT/scripts/configure-subagents.sh"
 bash -n "$ROOT/scripts/install-global.sh"
 bash -n "$ROOT/scripts/init-project.sh"
@@ -531,8 +576,8 @@ else
   bash "$ROOT/scripts/pi-model-catalog.sh" --json >/dev/null
 fi
 bash "$ROOT/scripts/configure-model-scope.sh" --dry-run --preset full --default-model openai-codex/gpt-5.5:xhigh >/dev/null
-bash "$ROOT/scripts/configure-mcp.sh" --list >/dev/null
-bash "$ROOT/scripts/configure-mcp.sh" --dry-run --preset popular --scope project --project "$ROOT" >/dev/null
+node "$ROOT/scripts/mcp-manage.mjs" --list >/dev/null
+node "$ROOT/scripts/mcp-manage.mjs" --dry-run --preset popular --scope project --project "$ROOT" >/dev/null
 node --input-type=module - "$ROOT" <<'NODE'
 import assert from "node:assert/strict";
 import { execFileSync } from "node:child_process";
@@ -553,8 +598,8 @@ try {
       internal: { url: "https://mcp.example.invalid/api" }
     }
   }, null, 2)}\n`);
-  execFileSync("bash", [
-    path.join(root, "scripts", "configure-mcp.sh"),
+  execFileSync(process.execPath, [
+    path.join(root, "scripts", "mcp-manage.mjs"),
     "--config", configPath,
     "--preset", "popular",
     "--replace"
@@ -577,6 +622,7 @@ bash "$ROOT/scripts/configure-subagents.sh" --list >/dev/null
 bash "$ROOT/scripts/configure-subagents.sh" --dry-run --preset safe >/dev/null
 bash "$ROOT/scripts/runtime-policy-smoke.sh" >/dev/null
 
+node "$ROOT/scripts/build-docs-site.mjs" --check >/dev/null
 node "$ROOT/scripts/capability-catalog.mjs" catalog --check >/dev/null
 node "$ROOT/scripts/capability-catalog.mjs" doctor --profile "$ROOT/.pi/piagent-profile.json" --lock "$ROOT/.pi/piagent-profile.lock.json" >/dev/null
 node "$ROOT/scripts/capability-catalog.mjs" doctor --profile "$ROOT/adapters/generic/profile.json" >/dev/null

package/scripts/verify-release-identity.mjs

@@ -71,8 +71,43 @@ if (capabilityLock.core?.packageVersion !== version) fail("capability lock packa
 const changelog = fs.readFileSync(path.join(root, "CHANGELOG.md"), "utf8");
 if (!changelog.includes(`## ${expectedTag} -`)) fail(`CHANGELOG.md has no ${expectedTag} release section`);
 
-const docsSite = fs.readFileSync(path.join(root, "docs-site/index.html"), "utf8");
-if (!docsSite.includes(`${expectedTag} docs`)) fail(`docs-site version badge does not identify ${expectedTag}`);
+// The badge is generated onto every page, so a stale build shows up as one page
+// still carrying the previous version rather than as a single missed edit.
+const docsPages = fs.readdirSync(path.join(root, "docs-site")).filter((name) => name.endsWith(".html"));
+if (docsPages.length === 0) fail("docs-site has no generated pages");
+for (const page of docsPages) {
+  const html = fs.readFileSync(path.join(root, "docs-site", page), "utf8");
+  if (!html.includes(`${expectedTag} docs`)) fail(`docs-site/${page} version badge does not identify ${expectedTag}`);
+}
+
+// A version written into an install command does not come from the build, so it
+// goes stale silently and keeps telling readers to install the previous release.
+// The badge check above cannot see these: they are sentences, not generated
+// markup.
+//
+// Only the command shapes are matched, not every version-looking string. Prose
+// naming an old release is usually saying something true about history — when a
+// behaviour arrived, which release a mistake shipped in — and rewriting those to
+// the current number would make them false. Files that exist to list past
+// versions are exempt outright.
+const VERSION_HISTORY_FILES = new Set(["CHANGELOG.md", "docs/publishing-for-teams.md"]);
+const RELEASE_TAG_MENTION = /(?:@piagent\/platform@|Vt-mmm\/piagent@v?|--version )(\d+\.\d+\.\d+)/g;
+
+function proseFiles() {
+  const files = fs.readdirSync(path.join(root, "docs")).filter((name) => name.endsWith(".md")).map((name) => `docs/${name}`);
+  files.push("README.md");
+  for (const name of fs.readdirSync(path.join(root, "docs-site", "content"))) {
+    if (name.endsWith(".html")) files.push(`docs-site/content/${name}`);
+  }
+  return files.filter((file) => !VERSION_HISTORY_FILES.has(file));
+}
+
+for (const file of proseFiles()) {
+  const text = fs.readFileSync(path.join(root, file), "utf8");
+  for (const [mention, named] of text.matchAll(RELEASE_TAG_MENTION)) {
+    if (named !== version) fail(`${file} tells the reader to install ${named} (${mention.trim()}), but this release is ${version}`);
+  }
+}
 
 if (options.tag) {
   if (options.tag !== expectedTag) fail(`release tag ${options.tag} does not match package version ${expectedTag}`);