@msdavid/pi-distro 0.3.0 → 0.4.0

package/extensions/pick.ts

@@ -9,15 +9,17 @@ import type {
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import { listBundledFiles, parsePackageList } from "./catalogue.ts";
+import { listBundledFiles, parsePackageListWithScope } from "./catalogue.ts";
 import { extractBody } from "./frontmatter.ts";
-import { parseGithubRef, isOfficialSource } from "./github.ts";
+import { parseGithubRef, isOfficialSource, tempCloneRoot } from "./github.ts";
 import { resolveDistro } from "./resolve.ts";
 import { buildShowPreview } from "./show.ts";
 import {
   display,
   readProjectPackages,
+  readGlobalPackages,
   MERGE_RULE,
+  SCOPE_RULE,
   USER_INVOLVEMENT_RULE,
   PACKAGE_CONFLICT_RULE,
 } from "./util.ts";
@@ -48,9 +50,13 @@ export async function handlePick(pi: ExtensionAPI, ctx: ExtensionCommandContext,
   // Parse the distro into selectable components.
   const fullMd = readFileSync(entry.harnessMdPath!, "utf-8");
   const directives = extractBody(fullMd);
-  const packages = parsePackageList(directives);
+  const packages = parsePackageListWithScope(directives);
   const files = entry.filesDir ? await listBundledFiles(entry.filesDir) : [];
-  const filesDirNote = entry.filesDir ? `\n\nBundled files are located at: \`${entry.filesDir}\`` : "";
+  const cloneRoot = entry.dir ? tempCloneRoot(entry.dir) : undefined;
+  const cloneCleanupNote = cloneRoot
+    ? `\n\nThe distro was fetched to a temporary GitHub clone. After the selected bundled files have been copied into the project, remove the clone: \`rm -rf ${cloneRoot}\``
+    : "";
+  const filesDirNote = (entry.filesDir ? `\n\nBundled files are located at: \`${entry.filesDir}\`` : "") + cloneCleanupNote;
 
   const snapshot = ctx.getSystemPromptOptions();
   const activeTools = snapshot.selectedTools?.length
@@ -58,9 +64,11 @@ export async function handlePick(pi: ExtensionAPI, ctx: ExtensionCommandContext,
     : "_(none / default set)_";
   const pkgs = readProjectPackages(snapshot.cwd);
   const projectPackages = pkgs.length > 0 ? pkgs.map((p) => `- \`${p}\``).join("\n") : "_(none)_";
+  const gpkgs = readGlobalPackages();
+  const globalPackages = gpkgs.length > 0 ? gpkgs.map((p) => `- \`${p}\``).join("\n") : "_(none)_";
 
   const packageList = packages.length > 0
-    ? packages.map((p) => `- \`${p}\``).join("\n")
+    ? packages.map((p) => `- \`${p.source}\` [${p.scope}]`).join("\n")
     : "_(none)_";
   const fileList = files.length > 0
     ? files.map((f) => `- \`${f.source}\` → \`./${f.target}\``).join("\n")
@@ -89,19 +97,25 @@ extensions, themes, prompts, skills) — treat each as individually selectable t
 **Already-active tools in this session:**
 ${activeTools}
 
-**Packages already in this project's .pi/settings.json:**
+**Packages already in this project's .pi/settings.json (project-local):**
 ${projectPackages}
 
-(Run \`pi list\` to also see globally-installed packages.)
+**Packages already in ~/.pi/agent/settings.json (global, every project):**
+${globalPackages}
+
+(Run \`pi list\` to see both local and global packages in one view.)
 
 ### Selection procedure (follow exactly, collaborating with the user)
 
 **0. User involvement rule** — ${USER_INVOLVEMENT_RULE}
 
+**0a. Scope rule** — ${SCOPE_RULE} Apply the deployment-plan + preset flow to the items the user selects to apply (not the whole distro). Build the plan from only the selected components, offer the three presets (accept-defaults / all-global-where-safe / customize), apply the scope-safety guard for dangerous types, then install/place at the chosen scope.
+
 **1. Walk the user through each category, one at a time.** For each category (packages, then
    bundled files, then any other components described in the directives), use
    \`ctx.ui.select\`/\`ctx.ui.confirm\` to let the user pick which to apply. Present the items
-   with their one-line purpose (from the directives). Let the user select any subset —
+   with their one-line purpose (from the directives) and their author scope hint
+   (\`[local]\`/\`[global]\`). Let the user select any subset —
    including none (skip the category entirely).
 
 **2. Surface dependencies.** As the user selects, **evaluate cross-component dependencies**
@@ -115,7 +129,7 @@ ${projectPackages}
 **3. Apply only the selected components**, with the same rules as a full deploy:
    - **Merge-don't-clobber** — ${MERGE_RULE}
    - **Package-redundancy check** — ${PACKAGE_CONFLICT_RULE}
-   - For each selected package: \`pi install -l\` after confirming (do NOT pre-add to
+   - For each selected package: install at the chosen scope (\`pi install -l\` for local, \`pi install\` for global) after confirming (do NOT pre-add to
      settings.json by hand).
    - For each selected bundled file: copy/merge as the user chooses (overwrite / keep theirs /
      merge).
@@ -129,5 +143,6 @@ ${projectPackages}
 
 **5. Recommend a restart** if any packages or extensions were installed — they load at
    startup.`);
-  // GitHub temp dir left in /tmp for the agent to read bundled files (ephemeral).
+  // GitHub temp dir is left in place so the agent can read the bundled files;
+  // the kickoff instructs the agent to remove it after copying them.
 }

package/extensions/resolve.ts

@@ -14,7 +14,13 @@ import {
   sourceLabel,
 } from "./catalogue.ts";
 import type { HarnessEntry } from "./catalogue.ts";
-import { looksLikeGithubRef, parseGithubRef, fetchGithubDistro, fetchOfficialDistro } from "./github.ts";
+import {
+  looksLikeGithubRef,
+  parseGithubRef,
+  fetchGithubDistro,
+  fetchOfficialDistro,
+  isOfficialCatalogueUnavailable,
+} from "./github.ts";
 
 /**
  * Resolve a distro from a name argument (GitHub ref or local catalogue name).
@@ -43,15 +49,23 @@ export async function resolveDistro(
 
   // Local catalogue
   const catalogue = await readCatalogue();
+  const offlineNote = isOfficialCatalogueUnavailable()
+    ? " (Official distros could not be fetched from GitHub — offline or rate-limited? Try again later.)"
+    : "";
   if (catalogue.length === 0) {
-    ctx.ui.notify("No distros found. Run /pi-distro save to create one.", "warning");
+    ctx.ui.notify(
+      isOfficialCatalogueUnavailable()
+        ? "Could not reach GitHub to list official distros (offline or rate-limited?), and no local distros exist. Retry later, or run /pi-distro save to create one."
+        : "No distros found. Run /pi-distro save to create one.",
+      "warning",
+    );
     return undefined;
   }
   if (nameArg) {
     const harness = findHarness(nameArg, catalogue);
     if (!harness) {
       const available = catalogue.map((h) => h.name).join(", ") || "(none)";
-      ctx.ui.notify(`Distro '${nameArg}' not found. Available: ${available}`, "error");
+      ctx.ui.notify(`Distro '${nameArg}' not found. Available: ${available}${offlineNote}`, "error");
       return undefined;
     }
     return resolveEntry(harness, ctx);

package/extensions/save.ts

@@ -9,9 +9,10 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import { readFileSync, statSync, existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
+import { homedir } from "node:os";
 
 import { getUserHarnessesDir } from "./catalogue.ts";
-import { display } from "./util.ts";
+import { display, readGlobalPackages } from "./util.ts";
 
 export async function handleSave(pi: ExtensionAPI, ctx: ExtensionCommandContext): Promise<void> {
   const snapshot = ctx.getSystemPromptOptions();
@@ -26,20 +27,33 @@ export async function handleSave(pi: ExtensionAPI, ctx: ExtensionCommandContext)
   // NOTE: .crew/ is handled separately below — it mixes authored config (agents/teams/workflows)
   // with runtime state (state/artifacts/worktrees/imports/audit/cache/graphs), so only its three
   // config subdirs are captured, not the whole tree.
-  const SKIP_NAMES = new Set(["npm", "git", "sessions", "state", "tmp", "node_modules"]);
+  const SKIP_NAMES = new Set(["npm", "git", "sessions", "state", "tmp", "node_modules", "loops"]);
   const MAX_DUMP_BYTES = 16384;
-  const configFiles: string[] = [];
-  const pushFile = (fp: string) => {
+  const MAX_TOTAL_DUMP_BYTES = 262144; // cap the whole inlined snapshot, not just per-file
+  let totalInlined = 0;
+  const makePush = (sink: string[], label: string) => (fp: string) => {
     let st;
     try { st = statSync(fp); } catch { return; }
     if (st.size > MAX_DUMP_BYTES) {
-      configFiles.push(`### ${fp}\n_(${st.size} bytes — read with the \`read\` tool if needed)_`);
+      sink.push(`### ${fp}${label}\n_(${st.size} bytes — read with the \`read\` tool if needed)_`);
+      return;
+    }
+    if (totalInlined + st.size > MAX_TOTAL_DUMP_BYTES) {
+      sink.push(`### ${fp}${label}\n_(omitted — snapshot size cap reached; read with the \`read\` tool if needed)_`);
       return;
     }
     try {
-      configFiles.push(`### ${fp}\n\`\`\`\n${readFileSync(fp, "utf-8")}\n\`\`\``);
-    } catch { /* unreadable (binary?) — skip */ }
+      const buf = readFileSync(fp);
+      if (buf.includes(0)) {
+        sink.push(`### ${fp}${label}\n_(binary file, ${st.size} bytes — not inlined; copy it as-is if bundling)_`);
+        return;
+      }
+      totalInlined += st.size;
+      sink.push(`### ${fp}${label}\n\`\`\`\n${buf.toString("utf-8")}\n\`\`\``);
+    } catch { /* unreadable — skip */ }
   };
+  const configFiles: string[] = [];
+  const pushFile = makePush(configFiles, "");
   const walk = (dir: string, isPiRoot: boolean) => {
     let entries;
     try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
@@ -81,6 +95,40 @@ export async function handleSave(pi: ExtensionAPI, ctx: ExtensionCommandContext)
     }
   }
 
+  // Global (user-level) config at ~/.pi/agent/ — capture alongside project-local so that
+  // components the user installed GLOBALLY (via `pi install` with no -l, or files placed in
+  // ~/.pi/agent/) are reproduced by the saved distro. These are marked as global in the
+  // snapshot (absolute path under ~/.pi/agent/). The agent must emit `(global)` markers for
+  // global packages and note global file placement in the directives so a re-deploy installs
+  // them at the global scope, not project-local. Skip runtime/data dirs (npm/, sessions/,
+  // state/, tmp/, bin/, supi/, cc-status/) and auth/models/trust (machine-specific). Only the
+  // authored config is captured: settings.json, AGENTS.md, extensions/, themes/, skills/,
+  // prompts/. An ancestor or unrelated global file the user added by hand is also captured.
+  const globalAgentDir = join(homedir(), ".pi", "agent");
+  const globalFiles: string[] = [];
+  const GLOBAL_SKIP_NAMES = new Set(["npm", "sessions", "state", "tmp", "bin", "supi", "cc-status", "loops"]);
+  const pushGlobalFile = makePush(globalFiles, " (global)");
+  const walkGlobal = (dir: string) => {
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const fp = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (GLOBAL_SKIP_NAMES.has(entry.name)) continue;
+        walkGlobal(fp);
+      } else if (entry.isFile()) {
+        // skip machine-specific runtime files
+        if (["auth.json", "models.json", "trust.json"].includes(entry.name)) continue;
+        pushGlobalFile(fp);
+      }
+    }
+  };
+  if (existsSync(globalAgentDir)) walkGlobal(globalAgentDir);
+  const gpkgs = readGlobalPackages();
+  const globalPackagesList = gpkgs.length > 0
+    ? gpkgs.map((p) => `- \`${p}\` (global)`).join("\n")
+    : "_(none)_";
+
   // Existing user harnesses (so the agent can offer update-existing)
   const userDir = getUserHarnessesDir();
   const existing: string[] = [];
@@ -132,6 +180,28 @@ The body should have directive sections (Bundled files, pi packages to install,
 prompt/SYSTEM.md if present, Themes, Context, Skills/prompts, and any per-extension/skill
 config files) mirroring the live config.
 
+**Scope handling (local vs global):** the snapshot above separates **project-local** files
+(under \`./.pi/\` and \`./\`) from **global** files (under \`~/.pi/agent/\`, marked \`(global)\`),
+and lists global packages with \`(global)\`. Reproduce each component at the scope it was
+captured at:
+  - For a **global package**: list it in the \`## pi packages to install\` section with the
+    \`(global)\` marker (e.g. - npm:foo (global) — reason, written as a list item with
+    the marker suffix). At
+    deploy, the user's preset still governs, but the marker is the author-suggested default.
+  - For a **project-local package**: list it without the marker (default local).
+  - For a **global bundled file** (e.g. \`~/.pi/agent/extensions/foo.ts\`): copy it into the
+    distro's \`files/\` mirror preserving structure, AND add a note in a
+    \`## Global deployment notes\` directive section listing which file targets should be
+    placed globally (e.g. "\`.pi/extensions/foo.ts\` -> deploy globally to
+    \`~/.pi/agent/extensions/foo.ts\`"). The agent reads this note at deploy and places
+    those files at the global path per the user's scope choice.
+  - For a **global settings.json merge** or **global SYSTEM.md/AGENTS.md**: these are the
+    dangerous guarded types — note in \`## Global deployment notes\` that they target
+    \`~/.pi/agent/settings.json\` / \`~/.pi/agent/SYSTEM.md\` / \`~/.pi/agent/AGENTS.md\`, so the
+    deploy-time scope-safety guard will surface their blast radius.
+If the user does not want a global component reproduced, they may ask to drop it or convert
+it to local — confirm with them during the draft step.
+
 **2. Propose & confirm.** Show the user the proposed \`name\`, \`title\`, \`description\`,
 and the full draft. Ask for confirmation or edits. Do NOT proceed until the user confirms.
 
@@ -172,7 +242,7 @@ project root:
   - any per-extension/skill config files (e.g. \`.pi/<name>.json\`) -> \`files/.pi/\` (same path)
   Use \`cp -r\` for directory trees. Only copy files that actually exist. Do NOT copy:
   \`./.pi/harness.md\` (provenance), \`./.pi/npm/\`, \`./.pi/git/\`, \`./.pi/sessions/\`,
-  \`./.pi/state/\`, \`./.pi/tmp/\`, \`./.pi/.crew/\`, or any \`node_modules/\`.
+  \`./.pi/state/\`, \`./.pi/tmp/\`, \`./.pi/loops/\`, \`./.pi/.crew/\`, or any \`node_modules/\`.
 
   **Theme dedup:** before bundling a \`.pi/themes/<name>.json\`, check whether that theme
   name is already provided by an installed package (run \`pi list\`; package themes surface

package/extensions/show.ts

@@ -7,7 +7,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 
-import { readFullHarnessMd, listBundledFiles, readCatalogue, findHarness, parsePackageList, sourceLabel } from "./catalogue.ts";
+import { readFullHarnessMd, listBundledFiles, readCatalogue, findHarness, parsePackageListWithScope, sourceLabel } from "./catalogue.ts";
 import type { HarnessEntry } from "./catalogue.ts";
 import { parseFrontmatter, extractBody } from "./frontmatter.ts";
 import { looksLikeGithubRef, parseGithubRef, fetchGithubDistro, fetchOfficialDistro } from "./github.ts";
@@ -18,7 +18,7 @@ export async function buildShowPreview(harness: HarnessEntry): Promise<string> {
   const fullMd = await readFullHarnessMd(harness.harnessMdPath!);
   const fm = parseFrontmatter(fullMd);
   const body = extractBody(fullMd);
-  const packages = parsePackageList(body);
+  const packages = parsePackageListWithScope(body);
 
   let settingsPreview = "_(none)_";
   if (harness.filesDir) {
@@ -44,7 +44,9 @@ export async function buildShowPreview(harness: HarnessEntry): Promise<string> {
 - **Source:** ${sourceLabel(harness.source)}
 
 ### pi packages to install
-${packages.length > 0 ? packages.map((p) => `- \`${p}\``).join("\n") : "_(none)_"}
+${packages.length > 0 ? packages.map((p) => `- \`${p.source}\` [${p.scope}]`).join("\n") : "_(none)_"}
+
+(\`[local]\`/\`[global]\` = author-suggested default scope; the user's deploy-time preset governs the final scope.)
 
 ### Settings (would be merged)
 ${settingsPreview}
@@ -52,6 +54,10 @@ ${settingsPreview}
 ### Bundled files (target paths)
 ${fileList}
 
+> **Scope:** by default, bundled files deploy project-locally (\`./<target>\`), except
+> themes which default to global (\`~/.pi/agent/themes/\`). At deploy time the user picks a
+> preset (accept-defaults / all-global-where-safe / customize).
+
 ### Full directives
 ${body}
 

package/extensions/undeploy.ts

@@ -12,7 +12,8 @@ import { join } from "node:path";
 
 import { parseProvenance, parsePackageList } from "./catalogue.ts";
 import { extractBody } from "./frontmatter.ts";
-import { readProjectPackages, USER_INVOLVEMENT_RULE } from "./util.ts";
+import { readProjectPackages, readGlobalPackages, USER_INVOLVEMENT_RULE } from "./util.ts";
+import { homedir } from "node:os";
 
 export async function handleUndeploy(pi: ExtensionAPI, ctx: ExtensionCommandContext): Promise<void> {
   const snapshot = ctx.getSystemPromptOptions();
@@ -34,34 +35,57 @@ export async function handleUndeploy(pi: ExtensionAPI, ctx: ExtensionCommandCont
   const directives = extractBody(provContent);
   const packages = parsePackageList(directives);
 
-  // Read current project state to compare against the distro's directives.
-  const installedPackages = readProjectPackages(cwd);
-
-  // Which of the distro's packages are still installed?
-  const distroPackagesInstalled = packages.filter((p) => installedPackages.includes(p));
-  const distroPackagesMissing = packages.filter((p) => !installedPackages.includes(p));
-
-  // Check for the AGENTS.md delimited section.
-  const agentsMdPath = join(cwd, "AGENTS.md");
-  let agentsMdSection = "not present";
-  if (existsSync(agentsMdPath)) {
-    const content = readFileSync(agentsMdPath, "utf-8");
-    if (content.includes(`<!-- pi-distro: ${prov.appliedHarness} -->`)) {
-      agentsMdSection = "present";
-    } else {
-      agentsMdSection = "not found (already removed or never added)";
-    }
-  }
+  // Read current project state to compare against the distro's directives. A distro may
+  // have installed packages/files either project-locally or globally — provenance records
+  // the directives (intentions), not scope, so we detect placement at runtime by checking
+  // BOTH ./.pi/settings.json and ~/.pi/agent/settings.json (and both file trees).
+  const installedLocal = readProjectPackages(cwd);
+  const installedGlobal = readGlobalPackages();
+
+  // Classify each distro package by where it actually landed.
+  type Placement = "local" | "global" | "both" | "missing";
+  const placement = (src: string): Placement => {
+    const inLocal = installedLocal.includes(src);
+    const inGlobal = installedGlobal.includes(src);
+    if (inLocal && inGlobal) return "both";
+    if (inLocal) return "local";
+    if (inGlobal) return "global";
+    return "missing";
+  };
+  const removeHint = (pl: Placement): string =>
+    pl === "local" ? "remove with `pi remove -l <pkg>`"
+    : pl === "global" ? "remove with `pi remove <pkg>` (global — affects every project)"
+    : pl === "both" ? "remove from both: `pi remove -l <pkg>` AND `pi remove <pkg>`"
+    : "";
+  const distroPackages = packages.map((p) => ({ pkg: p, pl: placement(p) }));
+  const distroPackagesInstalled = distroPackages.filter((d) => d.pl !== "missing");
+  const distroPackagesMissing = distroPackages.filter((d) => d.pl === "missing");
+
+  // Check for the AGENTS.md delimited section at BOTH the project root and the global
+  // ~/.pi/agent/AGENTS.md (a distro may have deployed it at either scope).
+  const checkAgentsSection = (path: string): boolean => {
+    if (!existsSync(path)) return false;
+    return readFileSync(path, "utf-8").includes(`<!-- pi-distro: ${prov.appliedHarness} -->`);
+  };
+  const localAgentsMdPath = join(cwd, "AGENTS.md");
+  const globalAgentsMdPath = join(homedir(), ".pi", "agent", "AGENTS.md");
+  const localAgentsPresent = checkAgentsSection(localAgentsMdPath);
+  const globalAgentsPresent = checkAgentsSection(globalAgentsMdPath);
+  let agentsMdSection: string;
+  if (localAgentsPresent && globalAgentsPresent) agentsMdSection = "present in BOTH ./AGENTS.md and ~/.pi/agent/AGENTS.md";
+  else if (localAgentsPresent) agentsMdSection = "present in ./AGENTS.md (project-local)";
+  else if (globalAgentsPresent) agentsMdSection = "present in ~/.pi/agent/AGENTS.md (global — affects every session)";
+  else agentsMdSection = "not found (already removed or never added)";
 
   const activeTools = snapshot.selectedTools?.length
     ? snapshot.selectedTools.map((t) => `- \`${t}\``).join("\n")
     : "_(none / default set)_";
 
   const packageList = distroPackagesInstalled.length > 0
-    ? distroPackagesInstalled.map((p) => `- \`${p}\` — installed (can be removed with \`pi remove -l\`)`).join("\n")
+    ? distroPackagesInstalled.map((d) => `- \`${d.pkg}\` — [${d.pl}] ${removeHint(d.pl)}`).join("\n")
     : "_(none of the distro's packages are currently installed)_";
   const missingNote = distroPackagesMissing.length > 0
-    ? `\n\n**Packages from this distro not currently installed (already removed):**\n${distroPackagesMissing.map((p) => `- \`${p}\``).join("\n")}`
+    ? `\n\n**Packages from this distro not currently installed (already removed):**\n${distroPackagesMissing.map((d) => `- \`${d.pkg}\``).join("\n")}`
     : "";
 
   pi.sendUserMessage(`## Undeploying distro: ${prov.appliedHarness} (v${prov.appliedVersion})
@@ -76,7 +100,7 @@ the *current* project state and let the user decide what to remove.
 ${directives}
 
 ### Current project state
-**Distro packages still installed in this project (${distroPackagesInstalled.length} of ${packages.length}):**
+**Distro packages still installed (${distroPackagesInstalled.length} of ${packages.length}; [local] = ./.pi, [global] = ~/.pi/agent, [both] = both):**
 ${packageList}${missingNote}
 
 **AGENTS.md delimited section:** ${agentsMdSection}
@@ -84,8 +108,11 @@ ${packageList}${missingNote}
 **Active tools in this session:**
 ${activeTools}
 
-**Installed packages in .pi/settings.json:**
-${installedPackages.length > 0 ? installedPackages.map((p) => `- \`${p}\``).join("\n") : "_(none)_"}
+**Installed packages in .pi/settings.json (project-local):**
+${installedLocal.length > 0 ? installedLocal.map((p) => `- \`${p}\``).join("\n") : "_(none)_"}
+
+**Installed packages in ~/.pi/agent/settings.json (global):**
+${installedGlobal.length > 0 ? installedGlobal.map((p) => `- \`${p}\``).join("\n") : "_(none)_"}
 
 ### Removal procedure (follow exactly, collaborating with the user)
 
@@ -95,25 +122,35 @@ key. The user may have customized files after deploy, or may want to keep some c
 
 **1. Walk the user through each removal category, one at a time:**
 
-   **(a) Packages** — for each distro package still installed, offer to remove it with
-   \`pi remove -l <pkg>\`. **Ask per package** — the user may want to keep some. Warn if
-   removing a package that other components depend on (e.g. if an extension relies on a
-   package's theme). If the user skips a package, note it.
+   **(a) Packages** — for each distro package still installed, remove it from wherever it
+   was placed. Use the [placement] shown above: \`pi remove -l <pkg>\` for [local],
+   \`pi remove <pkg>\` for [global] (note: global removal affects EVERY project on this
+   machine — say so and get explicit confirmation), and BOTH commands for [both]. **Ask per
+   package** — the user may want to keep some. Warn if removing a package that other
+   components depend on (e.g. if an extension relies on a package's theme). If the user
+   skips a package, note it.
 
    **(b) Bundled files** — the directives list bundled files (e.g. \`AGENTS.md\`,
-   \`settings.json\`, \`extensions/claude-statusline.ts\`). For each, check if the file exists
-   in the project. If it does, **show the user the file (or a summary) before removing** —
-   they may have customized it and want to keep it. Offer: remove / keep. Never silently
-   delete. For \`settings.json\`, offer to remove specific keys the distro merged (e.g.
-   \`theme\`, \`defaultThinkingLevel\`) rather than deleting the whole file — and warn about
-   user customizations.
-
-   **(c) AGENTS.md delimited section** — if the \`<!-- pi-distro: ${prov.appliedHarness} -->\` ...
-   \`<!-- /pi-distro: ${prov.appliedHarness} -->\` block exists, offer to remove it. If the
-   user has a standalone (non-delimited) AGENTS.md that wasn't added by the distro, leave it.
-
-   **(d) Extensions / skills / prompts / themes** — if the directives describe these and they
-   exist in the project, offer to remove each (with the same show-before-delete rule).
+   \`settings.json\`, \`extensions/claude-statusline.ts\`). A file may have been placed at
+   EITHER scope: check for it at both \`./<path>\` (project-local) AND
+   \`~/.pi/agent/<equivalent>\` (global). For each that exists, **show the user the file (or
+   a summary) before removing** — they may have customized it and want to keep it. Offer:
+   remove / keep, per location. Never silently delete. For \`settings.json\` (local at
+   \`./.pi/settings.json\`, global at \`~/.pi/agent/settings.json\`), offer to remove specific
+   keys the distro merged (e.g. \`theme\`, \`defaultThinkingLevel\`) rather than deleting the
+   whole file — and warn about user customizations. Warn that global settings removal
+   affects every project.
+
+   **(c) AGENTS.md delimited section** — the \`<!-- pi-distro: ${prov.appliedHarness} -->\` ...
+   \`<!-- /pi-distro: ${prov.appliedHarness} -->\` block may exist at \`./AGENTS.md\`
+   (project-local) and/or \`~/.pi/agent/AGENTS.md\` (global). Offer to remove it from each
+   location it was found (see the AGENTS.md status above). Warn that removing the global one
+   affects every session. If the user has a standalone (non-delimited) AGENTS.md that wasn't
+   added by the distro, leave it.
+
+   **(d) Extensions / skills / prompts / themes** — if the directives describe these, check
+   for them in BOTH \`./.pi/<type>/\` (local) and \`~/.pi/agent/<type>/\` (global). Offer to
+   remove each (with the same show-before-delete rule), per location.
 
 **2. Remove provenance last.** Only after the user has confirmed the component removals,
    remove \`./.pi/harness.md\` (the provenance file). Confirm with the user before deleting it.

package/extensions/util.ts

@@ -5,28 +5,44 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
+import { homedir } from "node:os";
 
 /** Display markdown content in the TUI as a custom message (no LLM turn). */
 export function display(pi: ExtensionAPI, content: string): void {
   pi.sendMessage({ customType: "pi-distro", content, display: true });
 }
 
-/** Compare two semver-ish version strings. Returns >0 if a>b, <0 if a<b, 0 if equal. */
+/** Compare two semver-ish version strings (tolerates a leading `v` and a
+ *  `-prerelease` suffix; a prerelease sorts before its release, e.g.
+ *  1.0.0-beta < 1.0.0). Returns >0 if a>b, <0 if a<b, 0 if equal. */
 export function compareVersions(a: string, b: string): number {
-  const pa = (a || "0").split(".").map((n) => parseInt(n, 10) || 0);
-  const pb = (b || "0").split(".").map((n) => parseInt(n, 10) || 0);
-  const len = Math.max(pa.length, pb.length);
+  const parse = (v: string): { nums: number[]; pre: string } => {
+    const s = (v || "0").trim().replace(/^[vV]/, "");
+    const [core, ...preParts] = s.split("-");
+    return {
+      nums: core.split(".").map((n) => parseInt(n, 10) || 0),
+      pre: preParts.join("-"),
+    };
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  const len = Math.max(pa.nums.length, pb.nums.length);
   for (let i = 0; i < len; i++) {
-    const va = pa[i] ?? 0;
-    const vb = pb[i] ?? 0;
+    const va = pa.nums[i] ?? 0;
+    const vb = pb.nums[i] ?? 0;
     if (va !== vb) return va - vb;
   }
+  if (pa.pre !== pb.pre) {
+    if (!pa.pre) return 1; // release > its own prerelease
+    if (!pb.pre) return -1;
+    return pa.pre < pb.pre ? -1 : 1;
+  }
   return 0;
 }
 
-/** Read the packages array from <cwd>/.pi/settings.json, normalised to source strings. */
-export function readProjectPackages(cwd: string): string[] {
-  const settingsPath = join(cwd, ".pi", "settings.json");
+/** Read the packages array from a pi settings.json, normalised to source strings
+ *  (pi allows both string and `{ source, ... }` object entries). */
+function readPackagesFile(settingsPath: string): string[] {
   if (!existsSync(settingsPath)) return [];
   try {
     const s = JSON.parse(readFileSync(settingsPath, "utf-8"));
@@ -37,8 +53,62 @@ export function readProjectPackages(cwd: string): string[] {
   }
 }
 
-export const MERGE_RULE = `**Merge, don't clobber.** For any target file that already exists, do not overwrite silently — show a diff and ask the user whether to overwrite, keep theirs, or merge. Merge JSON settings field-by-field. Append AGENTS.md content under a delimited section. Install pi packages with \`pi install -l\` (project-local) only after confirming with the user; do NOT pre-add packages to ./.pi/settings.json by hand — \`pi install -l\` registers them on success (and leaves settings untouched on failure).`;
+/** Read the packages array from <cwd>/.pi/settings.json, normalised to source strings. */
+export function readProjectPackages(cwd: string): string[] {
+  return readPackagesFile(join(cwd, ".pi", "settings.json"));
+}
+
+/** Read the packages array from ~/.pi/agent/settings.json (globally-installed
+ *  packages), normalised to source strings. These are packages installed via
+ *  `pi install <pkg>` (no `-l`), shared across every project on this machine. */
+export function readGlobalPackages(): string[] {
+  return readPackagesFile(join(homedir(), ".pi", "agent", "settings.json"));
+}
+
+export const SCOPE_RULE = `**Choose install scope per component — local vs global.** pi supports two install scopes, and the user chooses which to use for each component of this distro:
+
+- **Project-local** (default) — writes to \`./.pi/\` (packages via \`pi install -l\` → \`./.pi/settings.json\`; extensions/skills/prompts/themes into \`./.pi/<type>/\`; settings into \`./.pi/settings.json\`; AGENTS.md at \`./AGENTS.md\`). Scoped to this project only. This is pi-distro's default philosophy — different projects get different harnesses.
+- **Global** — writes to \`~/.pi/agent/\` (packages via \`pi install\` → \`~/.pi/agent/settings.json\`; extensions/skills/prompts/themes into \`~/.pi/agent/<type>/\`; settings into \`~/.pi/agent/settings.json\`; AGENTS.md at \`~/.pi/agent/AGENTS.md\`). Shared across **every project and session on this machine**. Opt-in, never the default.
+
+pi merges global and project-local (project-local shadows global on conflict). Both coexist.
+
+### Per-type default scopes (use these in the deployment plan unless the distro's directives mark a component \`(global)\`)
+| Component type | Default scope | Global allowed? | Notes |
+|---|---|---|---|
+| Packages | local | ✅ | the headline global option |
+| Extensions | local | ✅ | |
+| Skills | local | ✅ | |
+| Prompts | local | ✅ | |
+| Themes | **global** | ✅ | themes are user-wide by nature; default global |
+| settings.json merge | local | ⚠️ guarded | global settings affect every project — surface blast radius, require explicit confirm |
+| SYSTEM.md / APPEND_SYSTEM.md | local | ⚠️ double-confirm | global = overrides the system prompt in EVERY session — very dangerous; require a second explicit confirmation |
+| AGENTS.md | local | ⚠️ guarded | \`~/.pi/agent/AGENTS.md\` applies to all sessions — surface blast radius, require explicit confirm |
+
+### Deployment-plan procedure (follow exactly)
+**1. Build a deployment plan** before touching anything. Group every installable component from the directives by type, each with its default scope (per the table above, or the author's \`(global)\` hint if present). Render it as markdown so the user can see the whole picture at a glance, e.g.:
+\`\`\`
+📦 Packages (default: local)
+  - npm:pi-crew              [local]
+  - npm:pi-web-access        [local]
+🎨 Themes (default: global)
+  - my-theme.json            [global]
+⚙️ settings.json            [local]   (merge 3 keys)
+📝 SYSTEM.md                [local]   (global: guarded — affects all sessions)
+\`\`\`
+
+**2. Offer the user three presets** (use \`ctx.ui.select\`):
+  - **(a) Accept defaults** — keep every component at its default scope (today's project-local behaviour for most things; themes go global). This is the fast path and the recommended option.
+  - **(b) All-global (where safe)** — flip every *global-allowed* component to global. **Dangerous types** (settings.json, SYSTEM.md/APPEND_SYSTEM.md, AGENTS.md) stay local and you surface a warning explaining they were not flipped because their blast radius is machine-wide. Themes and any \`(global)\`-hinted items stay global.
+  - **(c) Customize** — walk the user through components one at a time (\`ctx.ui.select\` is single-select, so go item by item), offering \`local\` / \`global\` / \`skip\` for each. Use the default scope as the highlighted option. \`ctx.ui.select\` returns undefined on cancel — treat that as \`skip\` for that item and continue.
+
+**3. Apply the scope-safety guard.** Whenever the final scope for a **dangerous type** (settings.json, SYSTEM.md/APPEND_SYSTEM.md, AGENTS.md) is **global**, you MUST first surface the blast radius clearly and get an explicit confirmation: "This writes to \`~/.pi/agent/<file>\` and affects **every project and session on this machine**, not just this one. Confirm?" For SYSTEM.md/APPEND_SYSTEM.md global, require a **second** explicit confirmation — global system-prompt overrides are the most dangerous thing a distro can do. If the user declines, fall that component back to local (or skip if they prefer).
+
+**4. Install/place per the chosen scope.** For packages: \`pi install -l <pkg>\` for local, \`pi install <pkg>\` for global — only after the redundancy/conflict check and user confirmation. For bundled files: write to the local path (\`./.pi/...\`, \`./AGENTS.md\`) or the global path (\`~/.pi/agent/...\`, \`~/.pi/agent/AGENTS.md\`) per the chosen scope, applying merge-don't-clobber at whichever target. **Never pre-add packages to settings.json by hand** — \`pi install\`/\`pi install -l\` registers them on success and leaves settings untouched on failure.
+
+**5. Remember the scope for provenance & removal.** pi-distro does not record scope in provenance (provenance keeps the distro's directives). At \`undeploy\`/\`status\` time, the extension detects where each component actually landed by checking both \`./.pi/...\` and \`~/.pi/agent/...\` (and \`pi list\` for packages). So when you place a component globally, just note in your final report which components went global — the user can \`pi remove <pkg>\` (global) or delete from \`~/.pi/agent/...\` later, and \`/pi-distro undeploy\` will find them there.`;
+
+export const MERGE_RULE = `**Merge, don't clobber.** For any target file that already exists (at whichever scope the user chose — \`./.pi/...\` for local or \`~/.pi/agent/...\` for global), do not overwrite silently — show a diff and ask the user whether to overwrite, keep theirs, or merge. Merge JSON settings field-by-field. Append AGENTS.md content under a delimited section. Install pi packages with \`pi install -l\` (project-local) or \`pi install\` (global) per the chosen scope, only after confirming with the user; do NOT pre-add packages to settings.json by hand — \`pi install\`/\`pi install -l\` registers them on success (and leaves settings untouched on failure).`;
 
 export const USER_INVOLVEMENT_RULE = `**The user is in the loop for every decision.** pi-distro is a collaborative, agent-driven tool — never make a state-changing decision for the user. Before overwriting a file, installing a package, skipping a step, replacing a tool, applying an upgrade, or resolving any conflict (merge, redundancy, version downgrade, etc.), the agent must (1) surface the decision clearly (what it's about to do and why), (2) present the available options, and (3) wait for the user's explicit choice. Never silently skip, silently overwrite, silently substitute, or proceed on assumption. If a decision is ambiguous or the user is unsure, explain the tradeoffs and let them choose. The agent proposes; the user disposes.`;
 
-export const PACKAGE_CONFLICT_RULE = `**Evaluate tool redundancy/conflicts before installing.** When you install a distro's packages, some may provide tools that overlap with already-active tools — either an **exact name collision** (two tools with the same name) or **semantic redundancy** (different names, but doing very similar things, e.g. two web-search tools, two browser tools, two todo tools). pi handles exact name collisions by load order (project-local tools shadow global ones; the conflict is a non-fatal diagnostic, not a fatal error — pi still starts), but redundancy leaves the user with duplicate capability and a confusing tool set. Before installing each package, the **agent must evaluate** whether its purpose overlaps an already-active tool (read the already-active tools and project packages above, and run \`pi list\` to see globally-installed packages). If redundancy or a conflict is detected, do NOT install blindly — present the user a choice: (a) **skip** installing it (the capability already exists); (b) **replace** — \`pi remove -l <old>\` the overlapping package then \`pi install -l <new>\`; (c) **keep both** — install it anyway (e.g. the user prefers the new tool, or they serve subtly different purposes); (d) **cancel**. Only proceed with the user's choice.`;
+export const PACKAGE_CONFLICT_RULE = `**Evaluate tool redundancy/conflicts before installing.** When you install a distro's packages, some may provide tools that overlap with already-active tools — either an **exact name collision** (two tools with the same name) or **semantic redundancy** (different names, but doing very similar things, e.g. two web-search tools, two browser tools, two todo tools). pi handles exact name collisions by load order (project-local tools shadow global ones; the conflict is a non-fatal diagnostic, not a fatal error — pi still starts), but redundancy leaves the user with duplicate capability and a confusing tool set. Before installing each package, the **agent must evaluate** whether its purpose overlaps an already-active tool (read the already-active tools, the project packages, and the global packages listed above; also run \`pi list\` if you need a fresh view). If redundancy or a conflict is detected, do NOT install blindly — present the user a choice: (a) **skip** installing it (the capability already exists); (b) **replace** — remove the overlapping package from wherever it lives (\`pi remove -l <old>\` if project-local, \`pi remove <old>\` if global) then install the new one at the chosen scope (\`pi install -l <new>\` or \`pi install <new>\`); (c) **keep both** — install it anyway (e.g. the user prefers the new tool, or they serve subtly different purposes); (d) **cancel**. Only proceed with the user's choice.`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@msdavid/pi-distro",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Reusable, composable configurations for the pi coding agent — seed distros, project snapshots, and GitHub sharing with version-aware updates.",
   "type": "module",
   "license": "MIT",