@piagent/platform 1.2.2 → 1.2.4

package/packages/piagent-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/core",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "type": "module",
   "private": true,
   "license": "MIT",

package/packages/piagent-core/prompts/be-to-fe.md

@@ -20,11 +20,11 @@ Use this for tasks like:
 
 Mandatory flow:
 
-0. Call `piagent_context_preflight` with `workflow=be-to-fe`. If it recommends `fresh-session`, stop loading context in this session and tell the user to use `/fresh-be-to-fe <request>` unless this command already runs in a fresh session.
+0. Call `piagent_context_preflight` with `workflow=be-to-fe`. If it recommends `fresh-session`, stop loading context in this session and tell the user to use `/piagent-session fresh be-to-fe <request>` unless this command already runs in a fresh session.
 1. Call `piagent_context` with `detail=full` and confirm profile/protected backend paths.
 2. Call `piagent_orchestration_policy`; keep the workflow solo-first unless bounded BE/FE scouting or review is worth the extra token/tool cost.
 3. Call `piagent_memory_status`; search memory or Field Guide for prior BE/FE mapping decisions if relevant, record citations with `piagent_memory_citation_record`, then verify against current BE/FE files.
-4. Read `.pi/project-context.md`. If pending, stop and ask for `/onboard-project`.
+4. Read `.pi/project-context.md`. If pending, stop and ask for `/onboard-project run`.
 5. Read required context from the active profile and call `piagent_context_budget` for BE/FE files that look large.
 6. Classify the task:
    - BE scout: read-only.
@@ -67,7 +67,7 @@ Mandatory flow:
 
 For generic projects, use profile `be-readonly-fe` when the repo policy is “BE scout only, FE write allowed”.
 
-Do not ask the user to paste the mandatory flow. The platform prompt already contains it. If the user asks only for scout/audit, stay read-only and prefer `/scout` or `/fresh-scout`.
+Do not ask the user to paste the mandatory flow. The platform prompt already contains it. If the user asks only for scout/audit, stay read-only and prefer `/workflow scout` or `/piagent-session fresh scout`.
 
 Final output:
 

package/packages/piagent-core/prompts/discuss.md

@@ -13,7 +13,7 @@ Operating rules:
 
 1. Call `piagent_context` first when available.
 2. Call `piagent_memory_status`; use memory only to avoid repeated context questions, not as authority.
-3. Read `.pi/project-context.md` if available; if it is still pending, recommend `/onboard-project` before implementation.
+3. Read `.pi/project-context.md` if available; if it is still pending, recommend `/onboard-project run` before implementation.
 4. Inspect relevant files/docs before asking; do not ask what can be answered from the project.
 5. Identify the next unresolved decision, dependency, constraint, or risk.
 6. Ask at most 3 focused questions per round.
@@ -32,4 +32,4 @@ Final output when clear:
 - implementation approach
 - required context
 - verify commands
-- recommended next command: `/plan` or `/task`
+- recommended next command: `/workflow plan` or `/workflow task`

package/packages/piagent-core/prompts/plan.md

@@ -14,7 +14,7 @@ Rules:
 1. Call `piagent_context`.
 2. Call `piagent_orchestration_policy`; default to solo-first and choose review lenses/model roles before considering subagents.
 3. Call `piagent_memory_status`; search memory or Field Guide if it can reduce re-scouting, but treat it as advisory.
-4. Read `.pi/project-context.md`; if it is missing or still pending, recommend `/onboard-project` before implementation.
+4. Read `.pi/project-context.md`; if it is missing or still pending, recommend `/onboard-project run` before implementation.
 5. Read required context.
 6. Identify protected paths and external/high-risk actions.
 7. Decide whether subagents are useful enough to justify extra token/tool cost. If the bundled `pi-subagents` parent skill is available, use it for delegation patterns and safety boundaries. If `pi-subagents`/`subagent(...)` is available, use `piagent-scout` for independent read-only repo/spec mapping before medium/large plans. Use builtin `context-builder` when the task needs a handoff context/meta-prompt. Use `piagent-oracle` for architecture/risk challenge when the decision is non-obvious. Continue single-agent for tiny plans or unavailable subagent tooling.

package/packages/piagent-core/prompts/platform-improve.md

@@ -23,7 +23,7 @@ Mandatory flow:
 1. Call `piagent_context` with `detail=full` and inspect the active project profile.
 2. Call `piagent_orchestration_policy`; keep the platform change solo-first unless bounded scout/planning/review lanes are useful.
 3. Call `piagent_memory_status`; if prior decisions or Field Guide notes are relevant, search memory and record citations with `piagent_memory_citation_record`.
-4. Read `.pi/project-context.md`. If pending, stop and ask the user to run `/onboard-project`.
+4. Read `.pi/project-context.md`. If pending, stop and ask the user to run `/onboard-project run`.
 5. Read the required context declared by the active profile. Before loading large files, call `piagent_context_budget`.
 6. Classify the task risk lane and create a task contract with `piagent_task_start`, including review lenses and a compact workPlan, before source edits.
 7. Decide whether bounded subagents are useful enough to justify extra token/tool cost:

package/packages/piagent-core/prompts/pr.md

@@ -16,7 +16,7 @@ Rules:
 1. Do not merge. Do not publish, release, deploy, or tag.
 2. Use normal shell Git/GitHub commands so the piagent guard and confirmation gates remain active.
 3. Start with `git status --short`, `git branch --show-current`, and `git remote -v`.
-4. If there are uncommitted changes, stop and ask the operator to run `/commit` first, unless the operator explicitly asks this command to include a commit.
+4. If there are uncommitted changes, stop and ask the operator to run `/workflow commit` first, unless the operator explicitly asks this command to include a commit.
 5. Run the relevant verification command before opening the PR. At minimum use `git diff --check`; for source or policy changes, run the project verify/test/typecheck commands that apply.
 6. If the branch is not pushed, ask for explicit operator confirmation before `git push -u origin <branch>`.
 7. Create the PR only after the operator explicitly confirms the external GitHub action. Prefer `gh pr create --draft` with a clear title/body derived from the current diff and commits, unless the operator explicitly asks for a ready-for-review PR.

package/packages/piagent-core/prompts/review.md

@@ -11,7 +11,7 @@ $ARGUMENTS
 
 Rules:
 
-0. Call `piagent_context_preflight` with `workflow=review` for large diffs or long requests. If it recommends `fresh-session`, prefer `/fresh-scout` for read-only evidence gathering or ask the user to resume in a fresh session.
+0. Call `piagent_context_preflight` with `workflow=review` for large diffs or long requests. If it recommends `fresh-session`, prefer `/piagent-session fresh scout` for read-only evidence gathering or ask the user to resume in a fresh session.
 1. Call `piagent_context`.
 2. Call `piagent_orchestration_policy` and select explicit review lenses before reading the diff deeply.
 3. Read `.pi/project-context.md` if available.

package/packages/piagent-core/prompts/scout.md

@@ -14,11 +14,11 @@ Use this when the user needs evidence before deciding whether to implement. Do n
 Preflight first:
 
 1. Call `piagent_context_preflight` with `workflow=scout`.
-2. If it recommends `fresh-session`, stop loading context in this session and tell the user to use `/fresh-scout <request>` unless this command already runs in a fresh session.
+2. If it recommends `fresh-session`, stop loading context in this session and tell the user to use `/piagent-session fresh scout <request>` unless this command already runs in a fresh session.
 3. Call `piagent_context` with `detail=full`.
 4. Call `piagent_orchestration_policy`; keep scout solo-first unless independent read-only lanes are useful.
 5. Call `piagent_memory_status`; cite relevant memory or Field Guide only with `piagent_memory_citation_record`, then verify against current repo files.
-6. Read `.pi/project-context.md`; if pending, stop and ask for `/onboard-project`.
+6. Read `.pi/project-context.md`; if pending, stop and ask for `/onboard-project run`.
 7. Create a read-only task contract with `piagent_task_start` before broad scouting:
    - risk lane;
    - expected output;

package/packages/piagent-core/prompts/task.md

@@ -11,11 +11,11 @@ $ARGUMENTS
 
 Mandatory flow:
 
-0. Call `piagent_context_preflight` with `workflow=task`. If it recommends `fresh-session`, stop loading context in this session and tell the user to use `/fresh-task <request>` unless this command already runs in a fresh session.
+0. Call `piagent_context_preflight` with `workflow=task`. If it recommends `fresh-session`, stop loading context in this session and tell the user to use `/piagent-session fresh task <request>` unless this command already runs in a fresh session.
 1. Call `piagent_context` and read the project profile/runtime policy.
 2. Call `piagent_orchestration_policy` and keep the task solo-first unless the policy and task shape make bounded subagents clearly useful.
 3. Call `piagent_memory_status`. If memory or the Field Guide is enabled and relevant to the task, search/read it as advisory context, record citations with `piagent_memory_citation_record`, then verify against current repo files.
-4. Call `piagent_context_index_status` when available, then read `.pi/project-context.md`. If `.pi/project-context.md` is missing or still says `Generated: not yet`, stop and ask the user to run `/onboard-project` after login/model selection before implementation.
+4. Call `piagent_context_index_status` when available, then read `.pi/project-context.md`. If `.pi/project-context.md` is missing or still says `Generated: not yet`, stop and ask the user to run `/onboard-project run` after login/model selection before implementation.
    - Use `piagent_context_index_search` for navigation hints when the task touches an unfamiliar module/tech/risk area.
    - Treat context-index hits as advisory; open and verify cited files before editing.
 5. Build a Task Implementation Contract with `piagent_task_start` before editing:

package/scripts/init-project.sh

@@ -315,10 +315,11 @@ echo "Next:"
 echo "  cd \"$PROJECT_PATH\""
 echo "  pi"
 echo "  /login              # first time only"
-echo "  /onboard-project    # first project-read after model selection"
+echo "  /onboard    # open onboarding menu/status"
+echo "  /onboard run # 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 "  /context index # inspect compact project context index"
+echo "  /memory     # 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"

package/scripts/install-global.sh

@@ -178,6 +178,50 @@ run_cmd() {
   fi
 }
 
+resolve_user_package_path() {
+  local source="$1"
+  local pi_agent_dir="${PI_CODING_AGENT_DIR:-"${HOME}/.pi/agent"}"
+  node --input-type=module - "$pi_agent_dir" "$source" <<'NODE'
+import path from "node:path";
+
+const base = process.argv[2];
+const source = process.argv[3];
+console.log(path.resolve(base, source));
+NODE
+}
+
+is_piagent_platform_source() {
+  local source="$1"
+  case "$source" in
+    git:github.com/Vt-mmm/piagent|git:github.com/Vt-mmm/piagent@*|https://github.com/Vt-mmm/piagent*|npm:@piagent/platform|npm:@piagent/platform@*)
+      return 0
+      ;;
+    npm:*|git:*|http:*|https:*)
+      return 1
+      ;;
+  esac
+
+  local resolved_source
+  resolved_source="$(resolve_user_package_path "$source" 2>/dev/null || true)"
+  [[ "$resolved_source" == "$PLATFORM_ROOT" ]]
+}
+
+remove_existing_piagent_platform_sources() {
+  local source
+  while IFS= read -r source; do
+    [[ -n "$source" ]] || continue
+    if is_piagent_platform_source "$source"; then
+      run_cmd pi remove "$source"
+    fi
+  done < <(
+    pi list --approve 2>/dev/null | awk '
+      $0 == "User packages:" { in_user = 1; next }
+      $0 == "Project packages:" { in_user = 0; next }
+      in_user && $0 ~ /^  [^ ]/ { sub(/^  /, ""); print }
+    '
+  )
+}
+
 verify_npm_integrity() {
   local source="$1"
   local expected="$2"
@@ -496,6 +540,8 @@ if [[ -n "$RESOLVED_PACKAGE_COMMIT" ]]; then
   echo "  resolvedCommit: $RESOLVED_PACKAGE_COMMIT"
 fi
 echo "  source: $PACKAGE_SOURCE"
+echo "Removing previous Pi Agent Platform package registrations:"
+remove_existing_piagent_platform_sources
 run_cmd pi install "$PACKAGE_SOURCE"
 
 if [[ "$WITH_MCP" == true ]]; then
@@ -562,4 +608,4 @@ 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"
+echo "  /workflow task Implement <task>  # parent may auto-delegate scout/planner/reviewer"

package/scripts/profile-doctor.sh

@@ -198,7 +198,7 @@ if (contextIndex.enabled && contextIndex.writePolicy !== "off") {
   if (relativeIndexPath.startsWith("..") || path.isAbsolute(relativeIndexPath)) {
     errors.push(`contextIndex.path escapes project root: ${contextIndex.path}`);
   } else if (!fs.existsSync(indexPath)) {
-    warnings.push(`context index missing: ${contextIndex.path}; run /onboard-project or record piagent_context_index_record`);
+    warnings.push(`context index missing: ${contextIndex.path}; run /onboard run or record piagent_context_index_record`);
   }
 }
 

package/scripts/setup.sh

@@ -452,12 +452,13 @@ if [[ "$DO_PROJECT" == true ]]; then
   echo "  /scoped-models     # optional: edit Ctrl+P model cycle scope"
   echo "  /mcp               # inspect MCP servers; run /mcp setup for guided changes"
   echo "  /subagents-doctor  # inspect subagent setup"
-  echo "  /onboard-project   # first project-read snapshot before implementation"
-  echo "  /memory-policy     # inspect project memory policy when needed"
+  echo "  /onboard   # open onboarding menu/status"
+  echo "  /onboard run # first project-read snapshot before implementation"
+  echo "  /memory    # inspect project memory policy when needed"
 fi
 echo
 echo "Daily flow after setup:"
 echo "  herdr    # optional"
 echo "  cd <project>"
 echo "  pi"
-echo "  /task Implement <task>  # parent may auto-delegate scout/planner/reviewer"
+echo "  /workflow task Implement <task>  # parent may auto-delegate scout/planner/reviewer"

package/scripts/team-doctor.sh

@@ -149,8 +149,6 @@ if (!runtime.teamRolloutReady) {
 for (const rel of [
   "package.json",
   "packages/piagent-core/extensions/piagent-guard.ts",
-  "packages/piagent-core/prompts/onboard-project.md",
-  "packages/piagent-core/prompts/memory-policy.md",
   "packages/piagent-core/prompts/platform-improve.md",
   "packages/piagent-core/prompts/be-to-fe.md",
   "packages/piagent-core/prompts/task.md",
@@ -374,10 +372,10 @@ const projectContextPath = path.join(projectPath, ".pi", "project-context.md");
 if (fs.existsSync(projectContextPath)) {
   const projectContext = fs.readFileSync(projectContextPath, "utf8");
   if (/Generated:\s*not yet/i.test(projectContext)) {
-    warnings.push("project onboarding snapshot is still pending; run /onboard-project in Pi after login/model selection");
+    warnings.push("project onboarding snapshot is still pending; run /onboard run in Pi after login/model selection");
   }
 } else {
-  warnings.push("project has no .pi/project-context.md; run setup/init or /onboard-project");
+  warnings.push("project has no .pi/project-context.md; run setup/init or /onboard run");
 }
 
 const contextIndexConfig = projectProfile && typeof projectProfile.contextIndex === "object" && !Array.isArray(projectProfile.contextIndex)
@@ -402,8 +400,8 @@ if (contextIndexEscapes) {
     const edges = Array.isArray(contextIndex.edges) ? contextIndex.edges : [];
     const citations = Array.isArray(contextIndex.citations) ? contextIndex.citations : [];
     if (contextIndex.schemaVersion !== 1) warnings.push("project context index schemaVersion should be 1");
-    if (contextIndex.summary === "Pending. Run /onboard-project after login/model selection to generate the compact project context index.") {
-      warnings.push("project context index is still pending; run /onboard-project after login/model selection");
+    if (/Pending\.\s+Run \/onboard(?: run)? after login\/model selection/i.test(String(contextIndex.summary ?? ""))) {
+      warnings.push("project context index is still pending; run /onboard run after login/model selection");
     }
     if (nodes.length === 0) warnings.push("project context index has no nodes yet");
     if (contextIndex?.policy?.requireCitations !== false && citations.length === 0) warnings.push("project context index has no citations yet");
@@ -411,13 +409,13 @@ if (contextIndexEscapes) {
     if (edges.length > (contextIndex?.policy?.maxEdges ?? 240)) warnings.push("project context index has more edges than policy maxEdges");
   }
 } else {
-  warnings.push(`project has no ${contextIndexRelativePath}; run setup/init or /onboard-project`);
+  warnings.push(`project has no ${contextIndexRelativePath}; run setup/init or /onboard run`);
 }
 
 const memorySummaryPath = path.join(projectPath, ".pi", "memory", "memory_summary.md");
 const memoryHandbookPath = path.join(projectPath, ".pi", "memory", "MEMORY.md");
 if (!fs.existsSync(memorySummaryPath) || !fs.existsSync(memoryHandbookPath)) {
-  warnings.push("project has no .pi/memory scaffold; run setup/init or use /memory-policy before relying on project memory");
+  warnings.push("project has no .pi/memory scaffold; run setup/init or use /memory before relying on project memory");
 }
 
 if (strictShare) {

package/scripts/update-global.mjs

@@ -17,6 +17,7 @@
 // it asked for.
 
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
@@ -39,13 +40,18 @@ Options:
   --dry-run               Print every command that would run, change nothing
   --version <x.y.z>       Update to an exact helper version instead of latest
   --force                 Reinstall even when already on the target version
-  --project <path>        Run the team doctor against this project afterwards
+  --project <path>        Optional: after the global update, migrate and doctor this project
   --no-host               Do not touch the Pi host
   --no-package            Do not reinstall the Pi package
+  --no-migrate            With --project, skip project state migration
+  --npm-prefix <path>     Use this npm global prefix for host/helper installs
   -h, --help              Show this help
 
 Anything after -- is passed through to piagent-install, for example:
   piagent-update -- --no-mcp
+
+Bootstrap a machine that does not have piagent-update yet:
+  npm exec -y --package @piagent/platform@X.Y.Z -- piagent-update --version X.Y.Z --force
 `;
 }
 
@@ -81,6 +87,8 @@ function parseArguments(argv) {
     project: undefined,
     host: true,
     package: true,
+    migrate: true,
+    npmPrefix: undefined,
     passthrough: []
   };
 
@@ -111,6 +119,15 @@ function parseArguments(argv) {
       case "--no-package":
         options.package = false;
         break;
+      case "--no-migrate":
+        options.migrate = false;
+        break;
+      case "--npm-prefix": {
+        const value = argv[index += 1];
+        if (!value) fail("--npm-prefix needs a path", EXIT_USAGE);
+        options.npmPrefix = value;
+        break;
+      }
       case "--version": {
         const value = normalizeVersion(argv[index += 1]);
         if (!isReleaseVersion(value)) fail(`--version needs an exact release such as 1.1.4, got ${argv[index] ?? "nothing"}`, EXIT_USAGE);
@@ -140,6 +157,167 @@ function run(command, args, { capture = false } = {}) {
   return { ok: result.status === 0, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
 }
 
+function expandHome(value) {
+  if (value === "~") return os.homedir();
+  if (value?.startsWith("~/")) return path.join(os.homedir(), value.slice(2));
+  return value;
+}
+
+function configuredNpmPrefix() {
+  const result = run("npm", ["config", "get", "prefix"], { capture: true });
+  if (!result.ok) return undefined;
+  const prefix = result.stdout.trim();
+  return prefix && prefix !== "undefined" && prefix !== "null" ? path.resolve(expandHome(prefix)) : undefined;
+}
+
+function fallbackNpmRoot(prefix) {
+  return process.platform === "win32"
+    ? path.join(prefix, "node_modules")
+    : path.join(prefix, "lib", "node_modules");
+}
+
+function npmRoot(prefix) {
+  const args = ["root", "-g"];
+  if (prefix) args.push("--prefix", prefix);
+  const result = run("npm", args, { capture: true });
+  if (result.ok && result.stdout.trim()) return path.resolve(expandHome(result.stdout.trim()));
+  return prefix ? fallbackNpmRoot(prefix) : undefined;
+}
+
+function nearestExistingPath(target) {
+  let current = target;
+  while (current && !fs.existsSync(current)) {
+    const parent = path.dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+  return current || undefined;
+}
+
+function canWriteOrCreate(target) {
+  const nearest = nearestExistingPath(target);
+  if (!nearest) return false;
+  try {
+    fs.accessSync(nearest, fs.constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function userNpmPrefix() {
+  return path.join(os.homedir(), ".pi", "npm-global");
+}
+
+function binForPrefix(prefix) {
+  return process.platform === "win32" ? prefix : path.join(prefix, "bin");
+}
+
+function prependPath(directory) {
+  process.env.PATH = `${directory}${path.delimiter}${process.env.PATH ?? ""}`;
+}
+
+function resolveNpmInstallTarget(options, needsGlobalInstall) {
+  const explicitPrefix = options.npmPrefix ? path.resolve(expandHome(options.npmPrefix)) : undefined;
+  if (explicitPrefix) {
+    if (!options.dryRun) fs.mkdirSync(explicitPrefix, { recursive: true });
+    return {
+      prefix: explicitPrefix,
+      root: npmRoot(explicitPrefix),
+      bin: binForPrefix(explicitPrefix),
+      reason: "explicit"
+    };
+  }
+
+  const defaultPrefix = configuredNpmPrefix();
+  const defaultRoot = npmRoot(defaultPrefix);
+  if (!needsGlobalInstall || (defaultRoot && canWriteOrCreate(defaultRoot))) {
+    return { prefix: undefined, root: defaultRoot, bin: undefined, reason: "default" };
+  }
+
+  const prefix = userNpmPrefix();
+  if (!options.dryRun) fs.mkdirSync(prefix, { recursive: true });
+  return {
+    prefix,
+    root: npmRoot(prefix),
+    bin: binForPrefix(prefix),
+    reason: "user-prefix",
+    blockedRoot: defaultRoot
+  };
+}
+
+function npmInstallArgs(specifier, npmTarget) {
+  const args = ["install", "-g", "--ignore-scripts"];
+  if (npmTarget.prefix) args.push("--prefix", npmTarget.prefix);
+  args.push(specifier);
+  return args;
+}
+
+function helperRootFromNpmTarget(npmTarget) {
+  return npmTarget.root ? path.join(npmTarget.root, "@piagent", "platform") : undefined;
+}
+
+function helperVersionAt(root) {
+  return root ? readJson(path.join(root, "package.json"))?.version : undefined;
+}
+
+function resolveInstalledHelperRoot(targetHelper, npmTarget) {
+  const npmHelperRoot = helperRootFromNpmTarget(npmTarget);
+  if (helperVersionAt(npmHelperRoot) === targetHelper) return npmHelperRoot;
+  if (helperVersionAt(platformRoot) === targetHelper) return platformRoot;
+  const checked = [];
+  for (const root of [npmHelperRoot, platformRoot]) {
+    if (!root || checked.some((entry) => entry.root === root)) continue;
+    checked.push({ root, version: helperVersionAt(root) ?? "nothing" });
+  }
+  const details = checked.map((entry) => `${entry.root} reports ${entry.version}`).join("; ");
+  fail(`installed ${HELPER_PACKAGE}@${targetHelper}, but ${details || "the helper paths did not report that version"}. `
+    + "The Pi package was left untouched; rerun once the helper is correct.");
+}
+
+function parseJsonOutput(result, label) {
+  try {
+    return JSON.parse(result.stdout.trim() || "{}");
+  } catch {
+    fail(`${label} did not return valid JSON:\n${result.stdout.trim()}`);
+  }
+}
+
+function summarizeMigration(report, dryRun) {
+  const renamed = report.renamed?.length ?? 0;
+  const removed = report.removedOld?.length ?? 0;
+  const rewrote = report.rewrote?.length ?? report.wouldRewrite?.length ?? 0;
+  const wouldRename = report.wouldRename?.length ?? 0;
+  const alreadyMigrated = report.alreadyMigrated?.length ?? 0;
+
+  if (dryRun) {
+    const planned = wouldRename + rewrote + alreadyMigrated;
+    return planned > 0
+      ? `project migration: would update legacy layout (${wouldRename} rename, ${rewrote} rewrite, ${alreadyMigrated} already copied)`
+      : "project migration: already current";
+  }
+  if (report.migrated === false) return "project migration: already current";
+  return `project migration: applied (${renamed} rename, ${rewrote} rewrite, ${removed} old path removed)`;
+}
+
+function runProjectMigration(project, options, activePlatformRoot) {
+  const migrator = path.join(activePlatformRoot, "scripts/migrate-project-state.mjs");
+  if (!options.dryRun && !fs.existsSync(migrator)) {
+    fail(`the updated helper has no project migrator at ${migrator}`);
+  }
+  const args = options.dryRun
+    ? [migrator, project]
+    : [migrator, project, "--apply", "--remove-old"];
+  describeStep(options.dryRun, process.execPath, args);
+  const result = run(process.execPath, args, { capture: true });
+  if (!result.ok) fail(`project migration failed:\n${result.stderr.trim() || result.stdout.trim()}`);
+  const report = parseJsonOutput(result, "project migration");
+  if ((report.skipped?.length ?? 0) > 0) {
+    fail(`project migration skipped protected entries: ${report.skipped.map((entry) => `${entry.path} (${entry.reason})`).join(", ")}`);
+  }
+  console.log(`  ${summarizeMigration(report, options.dryRun)}`);
+}
+
 function npmView(specifier, field) {
   const result = run("npm", ["view", specifier, field, "--json"], { capture: true });
   if (!result.ok) return undefined;
@@ -196,6 +374,9 @@ function main() {
   console.log(`  helper:  ${currentHelper} -> ${targetHelper}${helperNeedsChange ? "" : " (already current)"}`);
   console.log(`  host:    ${currentHost ?? "not installed"} -> ${targetHost}${hostNeedsChange ? "" : " (already current)"}`);
   console.log(`  package: reinstalled from v${targetHelper} as a resolved commit${options.package ? "" : " (skipped)"}`);
+  if (options.project) {
+    console.log(`  project: ${path.resolve(options.project)} (${options.migrate ? "migrate + doctor" : "doctor only"})`);
+  }
 
   if (options.check) {
     const pending = [helperNeedsChange && "helper", hostNeedsChange && "host"].filter(Boolean);
@@ -203,7 +384,7 @@ function main() {
     return;
   }
 
-  if (!helperNeedsChange && !hostNeedsChange && !options.package) {
+  if (!helperNeedsChange && !hostNeedsChange && !options.package && !options.project) {
     console.log("\nNothing to do.");
     return;
   }
@@ -215,33 +396,38 @@ function main() {
       + `  bash ${path.join(platformRoot, "scripts/install-global.sh")} --local`);
   }
 
+  let activePlatformRoot = platformRoot;
+  const npmTarget = resolveNpmInstallTarget(options, hostNeedsChange || helperNeedsChange);
+  if (npmTarget.bin) prependPath(npmTarget.bin);
+  if (npmTarget.reason === "user-prefix") {
+    console.log(`  npm:     default global root is not writable (${npmTarget.blockedRoot ?? "unknown"}); using ${npmTarget.prefix}`);
+  } else if (npmTarget.reason === "explicit") {
+    console.log(`  npm:     using explicit global prefix ${npmTarget.prefix}`);
+  }
+
   // Host first: piagent-install refuses to run against a host that does not match
   // the version its package.json pins, so a helper installed ahead of the host
   // would fail on its very next step.
   if (hostNeedsChange) {
-    const args = ["install", "-g", "--ignore-scripts", `${HOST_PACKAGE}@${targetHost}`];
+    const args = npmInstallArgs(`${HOST_PACKAGE}@${targetHost}`, npmTarget);
     describeStep(options.dryRun, "npm", args);
     if (!options.dryRun && !run("npm", args).ok) fail(`could not install ${HOST_PACKAGE}@${targetHost}`);
   }
 
   if (helperNeedsChange) {
-    const args = ["install", "-g", "--ignore-scripts", `${HELPER_PACKAGE}@${targetHelper}`];
+    const args = npmInstallArgs(`${HELPER_PACKAGE}@${targetHelper}`, npmTarget);
     describeStep(options.dryRun, "npm", args);
     if (!options.dryRun) {
       if (!run("npm", args).ok) fail(`could not install ${HELPER_PACKAGE}@${targetHelper}`);
       // The helper has just replaced itself on disk. Everything after this point
       // runs the newly installed scripts, so confirm they are the ones asked for
       // rather than trusting that npm did what it said.
-      const landed = readJson(path.join(platformRoot, "package.json"))?.version;
-      if (landed !== targetHelper) {
-        fail(`installed ${HELPER_PACKAGE}@${targetHelper} but ${platformRoot} reports ${landed ?? "nothing"}. `
-          + "The Pi package was left untouched; rerun once the helper is correct.");
-      }
+      activePlatformRoot = resolveInstalledHelperRoot(targetHelper, npmTarget);
     }
   }
 
   if (options.package) {
-    const installer = path.join(platformRoot, "scripts/install-global.sh");
+    const installer = path.join(activePlatformRoot, "scripts/install-global.sh");
     if (!options.dryRun && !fs.existsSync(installer)) {
       fail(`the updated helper has no installer at ${installer}`);
     }
@@ -251,12 +437,22 @@ function main() {
   }
 
   if (options.project) {
-    const doctor = path.join(platformRoot, "scripts/team-doctor.sh");
+    if (options.migrate) {
+      runProjectMigration(options.project, options, activePlatformRoot);
+    } else {
+      console.log("  project migration: skipped");
+    }
+    const doctor = path.join(activePlatformRoot, "scripts/team-doctor.sh");
     const args = [doctor, options.project, "--strict-share"];
     describeStep(options.dryRun, "bash", args);
     if (!options.dryRun && !run("bash", args).ok) fail("the team doctor reported a problem");
   }
 
+  if (npmTarget.reason === "user-prefix") {
+    console.log(`\nPATH note: add this once if your shell cannot find piagent-* commands later:`);
+    console.log(`  export PATH="${npmTarget.bin}:$PATH"`);
+  }
+
   console.log(options.dryRun
     ? `\nDRY RUN: nothing was installed. Rerun without --dry-run to apply v${targetHelper}.`
     : `\nPASS: updated to v${targetHelper}.`);