@piagent/platform 1.0.1 → 1.1.0

package/scripts/check-published-site.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+
+// Checks that the published documentation site serves the released version from
+// every address it resolves to.
+//
+// Opening the site in a browser is not this check. A domain with several A
+// records answers from whichever one the resolver picked that second, so one
+// address can be dead for a week while every manual look happens to land on a
+// healthy one. This resolves the name, then asks each address directly with the
+// right Host header and SNI, and reports them separately. A partial outage has
+// to read as a failure, not as an average.
+//
+// A redirect from a pinned address back to the same host is reported rather
+// than followed: that is the shape of a loop, and following it would only
+// re-resolve the name and hide which address caused it.
+
+import dns from "node:dns/promises";
+import https from "node:https";
+import path from "node:path";
+import fs from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const REQUEST_TIMEOUT_MS = 15_000;
+const MAX_BODY_BYTES = 4 * 1024 * 1024;
+
+function fail(message) {
+  process.stderr.write(`FAIL: ${message}\n`);
+  process.exit(1);
+}
+
+function parseArguments(values) {
+  const options = { hosts: [], expect: null };
+  for (let index = 0; index < values.length; index += 1) {
+    const option = values[index];
+    if (option === "-h" || option === "--help") {
+      process.stdout.write("Usage: node scripts/check-published-site.mjs [--host <name>]... [--expect <text>]\n");
+      process.stdout.write("Verify every resolved address of the docs site serves the released version.\n");
+      process.stdout.write("Defaults to piagent.io.vn and www.piagent.io.vn, expecting the root package version.\n");
+      process.exit(0);
+    }
+    const value = values[index + 1];
+    if (option === "--host") {
+      if (!value || value.startsWith("--")) fail("--host requires a value");
+      if (!/^[a-z0-9.-]{1,253}$/i.test(value)) fail(`--host value ${JSON.stringify(value)} is not a hostname`);
+      options.hosts.push(value);
+      index += 1;
+      continue;
+    }
+    if (option === "--expect") {
+      if (!value || value.startsWith("--")) fail("--expect requires a value");
+      if (options.expect !== null) fail("duplicate option --expect");
+      options.expect = value;
+      index += 1;
+      continue;
+    }
+    fail(`unknown option ${option}`);
+  }
+  if (options.hosts.length === 0) options.hosts = ["piagent.io.vn", "www.piagent.io.vn"];
+  if (options.expect === null) {
+    const manifest = JSON.parse(fs.readFileSync(path.join(repositoryRoot, "package.json"), "utf8"));
+    options.expect = manifest.version;
+  }
+  return options;
+}
+
+async function resolveAddresses(host) {
+  const addresses = [];
+  for (const [family, resolver] of [[4, dns.resolve4], [6, dns.resolve6]]) {
+    try {
+      for (const address of await resolver(host)) addresses.push({ address, family });
+    } catch (error) {
+      if (error?.code !== "ENODATA" && error?.code !== "ENOTFOUND") throw error;
+    }
+  }
+  return addresses;
+}
+
+function request(host, { address, family }) {
+  return new Promise((resolve) => {
+    const call = https.request(
+      {
+        host: address,
+        family,
+        servername: host,
+        port: 443,
+        path: "/",
+        method: "GET",
+        headers: { Host: host, "User-Agent": "piagent-site-check" },
+        timeout: REQUEST_TIMEOUT_MS
+      },
+      (response) => {
+        let body = "";
+        let bytes = 0;
+        response.setEncoding("utf8");
+        response.on("data", (chunk) => {
+          bytes += Buffer.byteLength(chunk, "utf8");
+          if (bytes > MAX_BODY_BYTES) {
+            response.destroy();
+            return;
+          }
+          body += chunk;
+        });
+        response.on("end", () => resolve({ status: response.statusCode, location: response.headers.location, body }));
+        response.on("error", (error) => resolve({ error: error.message, code: error.code }));
+      }
+    );
+    call.on("timeout", () => {
+      call.destroy();
+      resolve({ error: `no response within ${REQUEST_TIMEOUT_MS}ms` });
+    });
+    call.on("error", (error) => resolve({ error: error.message, code: error.code }));
+    call.end();
+  });
+}
+
+// A redirect is only acceptable when it leaves this host for another name we are
+// also checking. Pointing back at itself is the loop; pointing off the domain
+// means the released page is not what this address serves.
+export function judge(host, hosts, expect, result, family) {
+  // A machine with no route to the address family cannot say anything about the
+  // address. Calling that a site failure would be a false positive, and a gate
+  // that cries wolf gets ignored, so it is reported as unverified instead.
+  if (result.code === "ENETUNREACH" || result.code === "EHOSTUNREACH") {
+    return { unverified: `no route from this machine to IPv${family}: ${result.error}` };
+  }
+  if (result.error) return `unreachable: ${result.error}`;
+  if (result.status >= 300 && result.status < 400) {
+    let target;
+    try {
+      target = new URL(result.location ?? "", `https://${host}/`);
+    } catch {
+      return `HTTP ${result.status} with an unreadable Location header`;
+    }
+    if (target.hostname === host) return `HTTP ${result.status} redirecting to itself at ${target.href}`;
+    if (!hosts.includes(target.hostname)) return `HTTP ${result.status} redirecting off the site to ${target.href}`;
+    return null;
+  }
+  if (result.status !== 200) return `HTTP ${result.status}`;
+  if (!result.body.includes(expect)) return `HTTP 200 but the page does not mention ${expect}`;
+  return null;
+}
+
+async function main() {
+  const options = parseArguments(process.argv.slice(2));
+  const failures = [];
+  const unverified = [];
+  let checked = 0;
+
+  for (const host of options.hosts) {
+    let addresses;
+    try {
+      addresses = await resolveAddresses(host);
+    } catch (error) {
+      fail(`${host} did not resolve: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (addresses.length === 0) fail(`${host} resolved to no addresses`);
+    for (const entry of addresses) {
+      const verdict = judge(host, options.hosts, options.expect, await request(host, entry), entry.family);
+      checked += 1;
+      if (verdict?.unverified) {
+        unverified.push(`${host} at ${entry.address}: ${verdict.unverified}`);
+        process.stdout.write(`  ????  ${host} ${entry.address} — ${verdict.unverified}\n`);
+      } else if (verdict) {
+        failures.push(`${host} at ${entry.address}: ${verdict}`);
+        process.stdout.write(`  FAIL  ${host} ${entry.address} — ${verdict}\n`);
+      } else {
+        process.stdout.write(`  ok    ${host} ${entry.address}\n`);
+      }
+    }
+  }
+
+  for (const entry of unverified) process.stdout.write(`UNVERIFIED: ${entry}\n`);
+
+  if (failures.length > 0) {
+    process.stderr.write(`FAIL: ${failures.length} of ${checked} addresses do not serve ${options.expect}\n`);
+    for (const failure of failures) process.stderr.write(`  ${failure}\n`);
+    process.stderr.write("Each address is a real path users take. Fix the DNS records or the deployment behind them.\n");
+    process.exit(1);
+  }
+
+  const verified = checked - unverified.length;
+  const note = unverified.length > 0 ? ` (${unverified.length} not reachable from this machine)` : "";
+  process.stdout.write(`PASS: ${verified} of ${checked} addresses serve ${options.expect}${note}\n`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await main();
+}

package/scripts/configure-mcp.sh

@@ -211,6 +211,22 @@ const servers = {
   }
 };
 
+// Writing a server definition does not make it usable. What each one still
+// needs from the operator is stated here so it can be printed at the moment the
+// definition is written, rather than living only in a description string that
+// shows up under --list.
+const prerequisites = {
+  context7: ["optional: export CONTEXT7_API_KEY for a higher documentation quota"],
+  "chrome-devtools": ["a local Chrome installation"],
+  github: [
+    "Docker running",
+    "export GITHUB_PERSONAL_ACCESS_TOKEN with the scopes you intend to use"
+  ],
+  playwright: ["browsers installed on first use (npx playwright install)"],
+  figma: ["Figma OAuth, completed from the Pi MCP panel on first use"],
+  "figma-desktop": ["Figma desktop running with Dev Mode MCP enabled"]
+};
+
 const presets = {
   minimal: [],
   docs: ["context7"],
@@ -227,7 +243,10 @@ const presets = {
 if (listOnly) {
   console.log(JSON.stringify({
     presets,
-    servers: Object.fromEntries(Object.entries(servers).map(([name, value]) => [name, value.description]))
+    servers: Object.fromEntries(Object.entries(servers).map(([name, value]) => [
+      name,
+      { description: value.description, requires: prerequisites[name] ?? [] }
+    ]))
   }, null, 2));
   process.exit(0);
 }
@@ -290,6 +309,19 @@ const report = {
   serverCount: Object.keys(current.mcpServers).length
 };
 
+// stdout stays machine-readable; the operator note goes to stderr.
+function reportPrerequisites() {
+  const lines = [];
+  for (const name of presets[presetName]) {
+    for (const item of prerequisites[name] ?? []) lines.push(`  ${name}: ${item}`);
+  }
+  if (lines.length === 0) return;
+  console.error("");
+  console.error("Server definitions are written. Each still needs this before it can connect:");
+  for (const line of lines) console.error(line);
+  console.error("Servers connect lazily, so nothing above is checked until the first call.");
+}
+
 if (dryRun) {
   console.log(JSON.stringify(report, null, 2));
   console.log(output);
@@ -297,5 +329,6 @@ if (dryRun) {
   fs.mkdirSync(path.dirname(configPath), { recursive: true });
   fs.writeFileSync(configPath, output);
   console.log(JSON.stringify(report, null, 2));
+  reportPrerequisites();
 }
 NODE

package/scripts/init-project.sh

@@ -238,6 +238,20 @@ NODE
     fi
   fi
 
+  # Running from an installed package rather than a checkout. The name and
+  # version on disk are exactly what a teammate resolves from the registry, so
+  # they are a portable source; the install path is not, and project settings
+  # are meant to be committed.
+  if [[ "$PLATFORM_ROOT" == */node_modules/* ]]; then
+    local installed_name installed_version
+    installed_name="$(node -e 'const fs=require("node:fs"); process.stdout.write(JSON.parse(fs.readFileSync(process.argv[1], "utf8")).name ?? "");' "$PLATFORM_ROOT/package.json")"
+    installed_version="$(node -e 'const fs=require("node:fs"); process.stdout.write(JSON.parse(fs.readFileSync(process.argv[1], "utf8")).version ?? "");' "$PLATFORM_ROOT/package.json")"
+    if [[ -n "$installed_name" && "$installed_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+([+-][0-9A-Za-z.-]+)?$ ]]; then
+      printf 'npm:%s@%s\n' "$installed_name" "$installed_version"
+      return
+    fi
+  fi
+
   echo "WARN: No exact package source provided." >&2
   echo "WARN: .pi/settings.json will use local platform path; do not commit it for team use." >&2
   printf '%s\n' "$PLATFORM_ROOT"
@@ -365,5 +379,10 @@ echo "  cd \"$PROJECT_PATH\""
 echo "  pi"
 echo "  /login              # first time only"
 echo "  /onboard-project    # first project-read after model selection"
+echo "  /mcp                # MCP servers come from the global install, not from this project"
 echo "  /context-index      # inspect compact project context index"
 echo "  /memory-policy      # inspect project memory policy when needed"
+echo
+echo "Note: .mcp.json and .pi/mcp.json are written empty on purpose. They exist so this"
+echo "project can add its own servers later; the shared baseline lives in the global"
+echo "config written by piagent-setup. An empty file here does not mean MCP is missing."

package/scripts/install-global.sh

@@ -4,7 +4,7 @@ set -euo pipefail
 usage() {
   cat <<'USAGE'
 Usage:
-  scripts/install-global.sh [--stable|--dev|--local|--channel <stable|dev|local>] [--version <tag>] [--resolve-tag] [--package-source <source>] [--dry-run] [--with-mcp] [--mcp-preset <preset>] [--with-subagents] [--subagents-preset <preset>] [--with-web-access] [--with-herdr] [--model-scope <preset>]
+  scripts/install-global.sh [--stable|--dev|--local|--channel <stable|dev|local>] [--version <tag>] [--resolve-tag] [--package-source <source>] [--dry-run] [--with-mcp|--no-mcp] [--mcp-preset <preset>] [--with-subagents] [--subagents-preset <preset>] [--with-web-access] [--with-herdr] [--model-scope <preset>]
 
 Purpose:
   Install the piagent Pi package into the current user's global Pi settings.
@@ -15,7 +15,7 @@ Package source examples:
   # Installs the stable tag after resolving it to a commit SHA.
 
   # Pin a specific release:
-  scripts/install-global.sh --version v1.0.1 --resolve-tag
+  scripts/install-global.sh --version v1.1.0 --resolve-tag
 
   # Preview the planned install/update without changing user config:
   scripts/install-global.sh --stable --dry-run
@@ -35,7 +35,10 @@ Notes:
   - OAuth is intentionally not automated. Run `pi` then `/login`.
   - Model scope is configured with Pi's native `enabledModels` so users choose via `/model`, Ctrl+L, `/scoped-models`, and Ctrl+P.
   - Herdr integration is optional and modifies user-level Herdr/Pi config.
-  - MCP preset defaults to core: Context7 docs, Chrome DevTools, GitHub.
+  - MCP is installed by default with the core preset: Context7 docs, Chrome DevTools, GitHub.
+    Skip it with --no-mcp. Writing the config does not start or authenticate anything:
+    the GitHub server additionally needs Docker running and GITHUB_PERSONAL_ACCESS_TOKEN
+    exported, and Chrome DevTools needs a local Chrome.
   - Subagents preset defaults to safe: compact tool description, bounded concurrency/depth.
   - Web access is optional. Install it only when you want the builtin `researcher` subagent to browse/fetch web sources inside Pi.
 USAGE
@@ -50,8 +53,9 @@ DEFAULT_REPO_REMOTE_URL="https://github.com/Vt-mmm/piagent.git"
 PACKAGE_SOURCE="${PIAGENT_PACKAGE_SOURCE:-}"
 PACKAGE_VERSION="${PIAGENT_PACKAGE_VERSION:-}"
 RELEASE_CHANNEL="${PIAGENT_RELEASE_CHANNEL:-}"
-WITH_MCP=false
+WITH_MCP=true
 MCP_PRESET="core"
+MCP_PRESET_EXPLICIT=false
 WITH_SUBAGENTS=false
 SUBAGENTS_PRESET="safe"
 SUBAGENTS_MODEL_SCOPE="none"
@@ -123,7 +127,7 @@ detect_runtime_surface() {
       printf 'native-windows/%s (not release-gated; terminal helpers require Bash semantics)' "$arch_name"
       ;;
     *)
-      printf '%s/%s (outside v1.0.1 release matrix)' "$os_name" "$arch_name"
+      printf '%s/%s (outside v1.1.0 release matrix)' "$os_name" "$arch_name"
       ;;
   esac
 }
@@ -131,7 +135,7 @@ detect_runtime_surface() {
 warn_runtime_surface_if_needed() {
   local surface="$1"
   case "$surface" in
-    *"supported target"*|*"experimental"*|*"not release-gated"*|*"outside v1.0.1 release matrix"*)
+    *"supported target"*|*"experimental"*|*"not release-gated"*|*"outside v1.1.0 release matrix"*)
       echo "WARN: runtime surface is $surface." >&2
       echo "WARN: For team rollout, run piagent-doctor plus the project smoke/verify suite on this machine before relying on it." >&2
       ;;
@@ -275,9 +279,14 @@ while [[ $# -gt 0 ]]; do
       WITH_MCP=true
       shift
       ;;
+    --no-mcp)
+      WITH_MCP=false
+      shift
+      ;;
     --mcp-preset)
       require_value "$1" "${2:-}"
       MCP_PRESET="$2"
+      MCP_PRESET_EXPLICIT=true
       shift 2
       ;;
     --with-subagents)
@@ -328,6 +337,13 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
+# A preset chosen alongside --no-mcp used to be accepted and then quietly
+# dropped, which reads as "the preset was applied".
+if [[ "$WITH_MCP" == false && "$MCP_PRESET_EXPLICIT" == true ]]; then
+  echo "FAIL: --mcp-preset has no effect with --no-mcp. Drop one of them." >&2
+  exit 2
+fi
+
 require_node_version
 CURRENT_RUNTIME_SURFACE="$(detect_runtime_surface)"
 warn_runtime_surface_if_needed "$CURRENT_RUNTIME_SURFACE"
@@ -438,7 +454,7 @@ if ! command -v pi >/dev/null 2>&1; then
   else
   echo "FAIL: pi is not on PATH." >&2
   echo "Install Pi first, then rerun this script." >&2
-    echo "Expected command on npm-based installs: npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1" >&2
+    echo "Expected command on npm-based installs: npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0" >&2
   exit 1
   fi
 else
@@ -527,6 +543,8 @@ echo "  pi"
 echo "  /login"
 echo "  /model          # or Ctrl+L: select provider/model from Pi selector"
 echo "  /scoped-models  # optional: edit Ctrl+P model cycle scope"
-echo "  /mcp            # inspect MCP servers; authenticate Figma/GitHub only when needed"
+if [[ "$WITH_MCP" == true ]]; then
+  echo "  /mcp            # inspect MCP servers; authenticate Figma/GitHub only when needed"
+fi
 echo "  /subagents-doctor"
 echo "  /task Implement <task>  # parent may auto-delegate scout/planner/reviewer"

package/scripts/piagent-cli.mjs

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 const scriptByCommand = {
   "piagent-setup": "scripts/setup.sh",
   "piagent-install": "scripts/install-global.sh",
+  "piagent-uninstall": "scripts/uninstall-global.sh",
   "piagent-init": "scripts/init-project.sh",
   "piagent-doctor": "scripts/team-doctor.sh",
   "piagent-benchmark": "scripts/quality-benchmark.sh",

package/scripts/setup.sh

@@ -244,6 +244,20 @@ NODE
     fi
   fi
 
+  # Running from an installed package rather than a checkout. The name and
+  # version on disk are exactly what a teammate resolves from the registry, so
+  # they are a portable source; the install path is not, and project settings
+  # are meant to be committed.
+  if [[ "$PLATFORM_ROOT" == */node_modules/* ]]; then
+    local installed_name installed_version
+    installed_name="$(node -e 'const fs=require("node:fs"); process.stdout.write(JSON.parse(fs.readFileSync(process.argv[1], "utf8")).name ?? "");' "$PLATFORM_ROOT/package.json")"
+    installed_version="$(node -e 'const fs=require("node:fs"); process.stdout.write(JSON.parse(fs.readFileSync(process.argv[1], "utf8")).version ?? "");' "$PLATFORM_ROOT/package.json")"
+    if [[ -n "$installed_name" && "$installed_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+([+-][0-9A-Za-z.-]+)?$ ]]; then
+      printf 'npm:%s@%s\n' "$installed_name" "$installed_version"
+      return
+    fi
+  fi
+
   echo "WARN: No exact package source provided." >&2
   echo "WARN: using local platform path; do not commit project .pi/settings.json with this value for team rollout." >&2
   printf '%s\n' "$PLATFORM_ROOT"

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.0.1 support matrix."
+    note: "This runtime is outside the documented v1.1.0 support matrix."
   };
 }
 

package/scripts/uninstall-global.sh

@@ -0,0 +1,231 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Removes what this platform installed, and nothing else.
+#
+# Uninstall is reported before it is performed, for the same reason install is:
+# the two touch shared Pi state that other tools also write to. Anything this
+# script cannot prove it installed is listed for the operator instead of being
+# deleted.
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PI_AGENT_DIR="${PI_CODING_AGENT_DIR:-"${HOME}/.pi/agent"}"
+GLOBAL_SETTINGS="$PI_AGENT_DIR/settings.json"
+
+APPLY=false
+WITH_ADDONS=false
+WITH_HOST=false
+PROJECT_PATH=""
+
+PLATFORM_PACKAGE="@piagent/platform"
+ADDON_PACKAGES=("pi-mcp-adapter" "pi-subagents" "pi-web-access")
+PI_HOST_PACKAGE="@earendil-works/pi-coding-agent"
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  piagent-uninstall [--apply] [--with-addons] [--with-host] [--project <path>]
+
+Removes the Pi package this platform installed from Pi's global settings.
+
+  (default)        Dry run. Reports what would be removed and exits 0.
+  --apply          Perform the removal.
+  --with-addons    Also remove pi-mcp-adapter, pi-subagents, and pi-web-access.
+  --with-host      Also uninstall the global Pi Coding Agent host.
+  --project <path> Also remove this platform's state from a project.
+
+Never removed, at any flag combination: credentials, trust decisions, sessions,
+todos, and project memory. Those are operator data, not platform state.
+USAGE
+}
+
+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
+      PROJECT_PATH="$2"
+      shift 2
+      ;;
+    -h|--help) usage; exit 0 ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+print_cmd() {
+  printf '+'
+  for arg in "$@"; do printf ' %q' "$arg"; done
+  printf '\n'
+}
+
+run_cmd() {
+  print_cmd "$@"
+  if [[ "$APPLY" == true ]]; then
+    "$@"
+  fi
+}
+
+# Reads the package sources Pi has registered, so removal targets what is
+# actually installed rather than what this version happens to install today. An
+# older release registered a different source shape, and it still has to come
+# out.
+platform_sources() {
+  [[ -f "$GLOBAL_SETTINGS" ]] || return 0
+  node --input-type=module - "$GLOBAL_SETTINGS" <<'NODE'
+import fs from "node:fs";
+
+let settings;
+try {
+  settings = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+} catch {
+  process.exit(0);
+}
+const packages = Array.isArray(settings.packages) ? settings.packages : [];
+// Every shape this platform has ever been installed as: the scoped npm
+// package, the Git source, and a local checkout path.
+const owned = /(@piagent\/platform|[/:]piagent(@|$|#)|Vt-mmm\/piagent|pi-company-platform)/;
+for (const entry of packages) {
+  if (typeof entry === "string" && owned.test(entry)) process.stdout.write(`${entry}\n`);
+}
+NODE
+}
+
+addon_sources() {
+  [[ -f "$GLOBAL_SETTINGS" ]] || return 0
+  node --input-type=module - "$GLOBAL_SETTINGS" "${ADDON_PACKAGES[@]}" <<'NODE'
+import fs from "node:fs";
+
+let settings;
+try {
+  settings = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+} catch {
+  process.exit(0);
+}
+const names = process.argv.slice(3);
+const packages = Array.isArray(settings.packages) ? settings.packages : [];
+for (const entry of packages) {
+  if (typeof entry !== "string") continue;
+  if (names.some((name) => entry.includes(name))) process.stdout.write(`${entry}\n`);
+}
+NODE
+}
+
+echo "Pi Agent Platform uninstall"
+echo "  mode: $([[ "$APPLY" == true ]] && echo apply || echo "dry run")"
+echo "  settings: $GLOBAL_SETTINGS"
+echo "  addons: $WITH_ADDONS"
+echo "  host: $WITH_HOST"
+[[ -n "$PROJECT_PATH" ]] && echo "  project: $PROJECT_PATH"
+echo
+
+if ! command -v pi >/dev/null 2>&1; then
+  echo "WARN: pi is not on PATH; skipping Pi package removal." >&2
+  echo "WARN: reinstall the host or remove entries from $GLOBAL_SETTINGS by hand." >&2
+else
+  found=false
+  while IFS= read -r source; do
+    [[ -z "$source" ]] && continue
+    found=true
+    echo "Removing platform package:"
+    run_cmd pi remove "$source"
+  done < <(platform_sources)
+  if [[ "$found" == false ]]; then
+    echo "No platform package found in Pi settings; nothing to remove."
+  fi
+
+  if [[ "$WITH_ADDONS" == true ]]; then
+    addon_found=false
+    while IFS= read -r source; do
+      [[ -z "$source" ]] && continue
+      addon_found=true
+      echo "Removing add-on:"
+      run_cmd pi remove "$source"
+    done < <(addon_sources)
+    if [[ "$addon_found" == false ]]; then
+      echo "No pinned add-on found in Pi settings."
+    fi
+    # The MCP baseline and subagent config are shared files that the operator
+    # may have edited after install, so they are reported rather than reset.
+    # Install writes the shared global scope; the Pi-global file is the override
+    # scope and is listed too, because an operator who used it will look there.
+    echo "Left in place, review by hand if no longer wanted:"
+    echo "  ${XDG_CONFIG_HOME:-"${HOME}/.config"}/mcp/mcp.json   # written by install"
+    echo "  $PI_AGENT_DIR/mcp.json                               # Pi-global override scope, only if you created it"
+    echo "  $PI_AGENT_DIR/extensions/subagent/config.json"
+  fi
+fi
+
+if [[ "$WITH_HOST" == true ]]; then
+  echo
+  if command -v npm >/dev/null 2>&1; then
+    echo "Uninstalling Pi host:"
+    run_cmd npm uninstall -g "$PI_HOST_PACKAGE"
+  else
+    echo "WARN: npm is not on PATH; cannot uninstall $PI_HOST_PACKAGE." >&2
+  fi
+fi
+
+if [[ -n "$PROJECT_PATH" ]]; then
+  echo
+  if [[ ! -d "$PROJECT_PATH" ]]; then
+    echo "FAIL: project path does not exist: $PROJECT_PATH" >&2
+    exit 1
+  fi
+  PROJECT_PATH="$(cd "$PROJECT_PATH" && pwd)"
+  echo "Project state in $PROJECT_PATH:"
+
+  # Files this platform alone writes and owns.
+  for relative in ".pi/piagent-profile.json" ".pi/piagent-profile.lock.json"; do
+    [[ -e "$PROJECT_PATH/$relative" ]] && run_cmd rm -f "$PROJECT_PATH/$relative"
+  done
+  if [[ -d "$PROJECT_PATH/.pi/piagent-state" ]]; then
+    run_cmd rm -rf "$PROJECT_PATH/.pi/piagent-state"
+  fi
+
+  # settings.json belongs to Pi, not to this platform. Only the package entry
+  # pointing here comes out; everything else the operator configured stays.
+  if [[ -f "$PROJECT_PATH/.pi/settings.json" ]]; then
+    echo "+ drop platform package entry from $PROJECT_PATH/.pi/settings.json"
+    if [[ "$APPLY" == true ]]; then
+      node --input-type=module - "$PROJECT_PATH/.pi/settings.json" <<'NODE'
+import fs from "node:fs";
+
+const target = process.argv[2];
+const settings = JSON.parse(fs.readFileSync(target, "utf8"));
+if (Array.isArray(settings.packages)) {
+  const owned = /(@piagent\/platform|[/:]piagent(@|$|#)|Vt-mmm\/piagent|pi-company-platform)/;
+  const kept = settings.packages.filter((entry) => !(typeof entry === "string" && owned.test(entry)));
+  if (kept.length > 0) settings.packages = kept;
+  else delete settings.packages;
+  fs.writeFileSync(target, `${JSON.stringify(settings, null, 2)}\n`);
+}
+NODE
+    fi
+  fi
+
+  # Written from templates at init, then edited by whoever used the project.
+  # Deleting them would take the operator's work with them.
+  echo "Left in place because they carry project content:"
+  for relative in "AGENTS.md" "REVIEW_GUIDELINES.md" ".mcp.json" ".pi/settings.json" ".pi/mcp.json" \
+    ".pi/project-context.md" ".pi/context-index.json" ".pi/tech-stack.json" ".pi/tech-context" ".pi/memory"; do
+    [[ -e "$PROJECT_PATH/$relative" ]] && echo "  $relative"
+  done
+fi
+
+echo
+if [[ "$APPLY" == true ]]; then
+  echo "Uninstall complete."
+  echo "The npm-global helper is separate and stays until you remove it:"
+  echo "  npm uninstall -g $PLATFORM_PACKAGE"
+else
+  echo "Dry run only. Nothing was removed. Re-run with --apply to perform it."
+fi