@msdavid/pi-distro 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.4.0 - 2026-07-13
+
+- **Install scope: local vs global.** Every component of a distro can now be installed
+  **project-locally** (default, `./.pi/`) or **globally** (`~/.pi/agent/`, opt-in). At
+  deploy/pick time the agent builds a deployment plan and offers three presets
+  (accept-defaults / all-global-where-safe / customize), with safety guards for dangerous
+  types (settings.json, SYSTEM.md/APPEND_SYSTEM.md, AGENTS.md). Authors can suggest a
+  global default per package with a `(global)` marker. `status`/`undeploy` detect where
+  each component actually landed by checking both scopes; `save` captures global config
+  too (marked `(global)`).
+- **Offline/rate-limit awareness**: when the official catalogue can't be fetched from
+  GitHub, `list`, `status`, and the selectors now say so explicitly instead of implying
+  distros don't exist or were removed.
+- **Official distro names in tab-completion**: the last successful catalogue listing is
+  cached to `~/.pi/harnesses/.official-cache.json`, so `deploy`/`show`/`pick` completion
+  offers official names, not just local ones.
+- **Robustness fixes**: provenance header parsing is now field-order-independent;
+  `compareVersions` handles `v` prefixes and prerelease suffixes (`1.0.0-beta < 1.0.0`);
+  the `(global)` scope marker is only honored between the package ref and the description
+  dash (prose mentions no longer count); an h1 heading now also terminates the
+  `## pi packages` section; `status` renders object-form package entries correctly.
+- **Save snapshot hygiene**: skips `.pi/loops/` runtime state, detects binary files
+  instead of inlining garbage, and caps the total inlined snapshot at 256 KB (per-file
+  cap unchanged; omitted files are listed by path).
+- **GitHub temp clones cleaned up**: deploy/pick kickoffs now instruct the agent to
+  remove the temporary clone after copying bundled files.
+- **CLI polish**: extra arguments are warned about instead of silently ignored; the
+  command description lists all subcommands.
+- **Distro fixes**: `web-fullstack` 0.2.0 — removed the non-functional `tools` key from
+  bundled settings (pi restricts tools via the `--tools` launch flag, now documented in
+  the directives); `minimal` 0.1.1 — removed the empty `packages` array from bundled
+  settings (merge hazard); `trip-planner` 0.3.0 — statusline now provided by
+  `npm:pi-cc-status` (bundled extension removed), supi post-install aligned with
+  cc-knockoff's config-file flow, description shortened to the ≤300-char limit;
+  `cc-knockoff` 1.2.1 — README global-settings path corrected to
+  `~/.pi/agent/settings.json`.
+- **New test suite for shipped distros** (`tests/harnesses.test.ts`): validates
+  frontmatter rules (name/dir match, plain semver, description length), README presence,
+  and that the bundled-files manifest matches `files/` on disk in both directions.
+
 ## 0.3.0 - 2026-07-10
 
 - **Dynamic official distros from GitHub**: official distros (`minimal`, `web-fullstack`,

package/README.md

@@ -23,11 +23,13 @@ existing setup — nothing is silently overwritten.
 ## Get a fully-configured coder in 60 seconds
 
 ```bash
-# 1. Install the package
+# 1. Install the package (in your shell)
 pi install npm:@msdavid/pi-distro
 
-# 2. Deploy a distro (cc-knockoff = a Claude Code-style multi-agent coder)
-/pi-distro deploy cc-knockoff
+# 2. Start pi, then deploy a distro from inside the session
+#    (cc-knockoff = a Claude Code-style multi-agent coder)
+pi
+> /pi-distro deploy cc-knockoff
 
 # 3. Restart pi — done.
 ```
@@ -46,7 +48,10 @@ explore-before-acting methodology — all configured and ready to go.
   substitutes, or chooses. Every state-changing decision (file merge, package install, tool
   conflict, upgrade) is surfaced with options, and the agent waits for your explicit choice
 - 📦 **Project-local by default** — each project gets its own isolated configuration, so
-  different projects can use different harnesses (coding, research, automation, trading…)
+  different projects can use different harnesses (coding, research, automation, trading…).
+  Need a component everywhere? **Install globally** — at deploy time, choose
+  accept-defaults / all-global / customize per component (with safety guards for
+  machine-wide changes)
 - 🔄 **Round-trip** — snapshot your live config back into a reusable distro with `/pi-distro save`
 - 🐙 **GitHub distros** — deploy distros straight from any GitHub repo, so your personal
   config follows you to any machine (`/pi-distro deploy owner/repo`)
@@ -110,6 +115,57 @@ Other advantages:
 You can still use global packages and settings alongside project-level ones — pi merges
 them. But the distro itself lives at the project level.
 
+## Installing locally vs globally
+
+Although pi-distro defaults to **project-local** installation (so each project gets its own
+isolated harness), you can choose to install any component **globally** — shared across
+every project and session on your machine. This is an opt-in choice made at deploy time; the
+project-local default is never changed silently.
+
+When you run `/pi-distro deploy` (or `/pi-distro pick`), the agent builds a **deployment
+plan** listing every component with its default scope, then offers three presets:
+
+- **Accept defaults** — keep each component at its default scope (recommended). Most things
+  go project-local; themes default to global (they're user-wide by nature).
+- **All-global (where safe)** — install every safe component globally. Dangerous types
+  (settings, `SYSTEM.md`, `AGENTS.md`) stay project-local with a surfaced warning, because
+  their blast radius is machine-wide.
+- **Customize** — walk components one at a time and pick `local` / `global` / `skip` for each.
+
+### What can go global
+
+| Component | Default | Global? |
+|---|---|---|
+| Packages | local | ✅ |
+| Extensions | local | ✅ |
+| Skills | local | ✅ |
+| Prompts | local | ✅ |
+| Themes | **global** | ✅ |
+| `settings.json` merge | local | ⚠️ guarded (explicit confirm) |
+| `SYSTEM.md` / `APPEND_SYSTEM.md` | local | ⚠️ double-confirm |
+| `AGENTS.md` | local | ⚠️ guarded (explicit confirm) |
+
+Global placement writes to `~/.pi/agent/` (packages via `pi install` →
+`~/.pi/agent/settings.json`; extensions/themes/skills/prompts into `~/.pi/agent/<type>/`).
+Project-local writes to `./.pi/` (packages via `pi install -l`). pi merges the two;
+project-local shadows global on conflict.
+
+### Tracking global installs
+
+Provenance (`./.pi/harness.md`) records the distro's directives — it does **not** record
+scope. So `/pi-distro status` and `/pi-distro undeploy` detect where each component
+actually landed by checking **both** `./.pi/...` and `~/.pi/agent/...` (plus `pi list` for
+packages). When you undeploy, the agent offers the right removal command per location
+(`pi remove -l` for local, `pi remove` for global). `/pi-distro save` captures
+globally-installed config too (marked `(global)` in the snapshot), so saved distros stay
+reproducible.
+
+### Authoring a distro with a global hint
+
+Distro authors can suggest a global default for a package with the `(global)` marker — see
+[docs/authoring.md](docs/authoring.md). The hint is a suggested default; the user's
+preset still governs at deploy time.
+
 ## Workflows
 
 ### Global setup (install once, use everywhere)
@@ -256,6 +312,10 @@ Selectors and `/pi-distro list` show each distro's source clearly: **Official**
 `msdavid/pi-distro` repo), **Local** (your `~/.pi/harnesses/`), or **GitHub (<owner>/<repo>)**
 for distros from other repos.
 
+If GitHub is unreachable (offline, or the unauthenticated API rate limit is hit), the
+catalogue degrades to local-only and `/pi-distro list`, `/pi-distro status`, and the
+selectors say so explicitly — official distros are temporarily hidden, not gone.
+
 On a name collision, the **user distro takes precedence** — save a distro with the same
 name as an official distro to override it. Official distros come from a trusted repo (the
 package's own repo), so they skip the GitHub security confirmation that other-repo

package/docs/authoring.md

@@ -125,25 +125,45 @@ manifest the agent uses during `deploy`.
 ### `## pi packages to install`
 
 List pi packages the distro depends on. The agent installs these with `pi install -l`
-(**project-local** — writes to `./.pi/settings.json`, not global) **only after confirming
-with the user** AND after a **redundancy/conflict evaluation**: the agent compares each
-package's stated purpose against the project's already-active tools (and `pi list`),
-checking for both exact tool-name collisions and semantic redundancy (different names,
-similar function). If overlap is detected, it offers the user **skip / replace / keep both /
-cancel** instead of installing blindly. (Exact name collisions are non-fatal in pi —
-project-local tools shadow global ones — but redundancy leaves a confusing duplicate tool
-set, so the agent surfaces it for the user to decide.)
-
-**Do not list these packages in the bundled `settings.json` `packages` array.** `pi install -l`
-is the single mechanism that registers a package: it installs the package AND appends the
-source to `./.pi/settings.json` on success, and leaves settings untouched on failure. This
-way a failed install never leaves a dangling, unresolvable entry in settings.
+(**project-local** — writes to `./.pi/settings.json`) **or** `pi install` (**global** — writes
+to `~/.pi/agent/settings.json`, shared across every project) per the user's deploy-time
+scope choice, **only after confirming with the user** AND after a
+**redundancy/conflict evaluation**: the agent compares each package's stated purpose against
+the project's already-active tools and installed packages (both local and global, via
+`pi list`), checking for both exact tool-name collisions and semantic redundancy (different
+names, similar function). If overlap is detected, it offers the user **skip / replace /
+keep both / cancel** instead of installing blindly. (Exact name collisions are non-fatal in
+pi — project-local tools shadow global ones — but redundancy leaves a confusing duplicate
+tool set, so the agent surfaces it for the user to decide.)
+
+**Do not list these packages in the bundled `settings.json` `packages` array.**
+`pi install -l` / `pi install` are the single mechanisms that register a package: each
+installs the package AND appends the source to the corresponding settings file on success,
+and leaves settings untouched on failure. This way a failed install never leaves a dangling,
+unresolvable entry in settings.
+
+#### Scope hint: `(global)`
+
+By default, a package is suggested for **project-local** install. To suggest **global** as
+the author-intended default, suffix the entry with `(global)`:
 
 ```markdown
 ## pi packages to install
 - `npm:pi-browse` — for web search and content extraction
+- `npm:my-shared-tool` (global) — a tool the user wants in every project
 ```
 
+The hint is a **suggested default** for the deployment plan — it does not force global
+install. At deploy time the user picks a preset (accept-defaults / all-global-where-safe /
+customize) which governs the final scope. Use `(global)` for packages that are genuinely
+user-wide (a favorite status-line, a shared utility); leave it off for project-specific
+dependencies.
+
+> **Marker placement:** the `(global)` / `(local)` marker must appear **between the
+> package reference and the description dash** (as in the example above). A `(global)`
+> that appears inside the description prose after the `—` dash is intentionally ignored,
+> so descriptions can mention the word without changing the scope.
+
 ### `## Hooks`
 
 Describe extensions/hooks to create under `./.pi/extensions/`. These are bundled as
@@ -161,6 +181,56 @@ Reference bundled skills (under `files/.pi/skills/`) and prompts (under
 `files/.pi/prompts/`) that should be deployed, or describe skills/prompts the agent
 should create.
 
+## Install scope: local vs global
+
+Every component a distro installs can be placed either **project-local** (the default,
+under `./.pi/` — scoped to this project) or **global** (under `~/.pi/agent/` — shared
+across every project and session on the machine). pi merges the two; project-local
+shadows global on conflict. pi-distro's default philosophy is **project-local**, because
+different projects need different harnesses — global is an opt-in choice the user makes at
+deploy time.
+
+### Per-type default scopes
+
+| Component type | Default scope | Global allowed? |
+|---|---|---|
+| Packages | local | yes |
+| Extensions | local | yes |
+| Skills | local | yes |
+| Prompts | local | yes |
+| Themes | **global** | yes |
+| settings.json merge | local | guarded (explicit confirm) |
+| SYSTEM.md / APPEND_SYSTEM.md | local | double-confirm |
+| AGENTS.md | local | guarded (explicit confirm) |
+
+At deploy (and `/pi-distro pick`), the agent builds a **deployment plan** from the
+directives — grouping every component with its default scope — and offers the user three
+presets:
+
+- **(a) Accept defaults** — keep each component at its default scope (recommended).
+- **(b) All-global (where safe)** — flip every global-allowed component to global;
+  dangerous types (settings, SYSTEM.md, AGENTS.md) stay local with a surfaced warning.
+- **(c) Customize** — walk items one at a time, offering `local` / `global` / `skip`.
+
+When a dangerous type's final scope is global, the agent surfaces the blast radius
+("affects every project/session on this machine") and requires explicit confirmation
+(double-confirm for SYSTEM.md/APPEND_SYSTEM.md).
+
+### `## Global deployment notes`
+
+If your distro is intended to place some bundled files **globally** (e.g. an extension that
+should live at `~/.pi/agent/extensions/` rather than `./.pi/extensions/`), add a `## Global
+deployment notes` section listing which file targets should go global:
+
+```markdown
+## Global deployment notes
+- `.pi/extensions/my-shared-ext.ts` → deploy globally to `~/.pi/agent/extensions/my-shared-ext.ts`
+- `.pi/themes/shared-theme.json` → deploy globally to `~/.pi/agent/themes/shared-theme.json`
+```
+
+The agent reads this note and places those files at the global path per the user's scope
+choice. For packages, prefer the `(global)` marker in `## pi packages to install` instead.
+
 ## Merge-don't-clobber expectations
 
 When a distro is deployed via `/pi-distro deploy`, **existing files are never
@@ -234,5 +304,9 @@ Never keep the same version when updating a distro — the version should always
 that something changed. When authoring a distro by hand, pick a starting version (e.g.
 `0.1.0`) and bump it on each meaningful change.
 
+Write versions as plain `MAJOR.MINOR.PATCH` — no `v` prefix. Prerelease suffixes
+(`1.0.0-beta`) are tolerated and sort before their release, but plain releases are
+recommended for distros.
+
 The saved distro is immediately available in `/pi-distro list` and can be deployed
 into other projects with `/pi-distro deploy`.

package/extensions/catalogue.ts

@@ -32,17 +32,35 @@ export interface BundledFile {
   target: string;
 }
 
+export interface PackageEntry {
+  source: string;
+  scope: "local" | "global";  // author hint; the user's deploy-time preset still governs
+}
+
 /** Parse pi package references (npm:...) from a directives body. */
 export function parsePackageList(body: string): string[] {
-  const packages: string[] = [];
+  return parsePackageListWithScope(body).map((p) => p.source);
+}
+
+/** Parse pi package references with their author-specified scope hint.
+ *  A package may be suffixed with `(global)` to suggest global install; otherwise
+ *  the default scope is `local`. The hint is a *default* — the user's deploy-time
+ *  preset (accept-defaults / all-global / customize) still governs the final scope. */
+export function parsePackageListWithScope(body: string): PackageEntry[] {
+  const packages: PackageEntry[] = [];
   let inSection = false;
   for (const line of body.split("\n")) {
     const t = line.trim();
     if (/^##\s+pi\s*packages/i.test(t)) { inSection = true; continue; }
     if (inSection) {
-      if (/^##\s/.test(t)) { inSection = false; continue; }
-      const m = t.match(/^-\s+`(npm:[^`]+)`/);
-      if (m) packages.push(m[1]);
+      if (/^#{1,2}\s/.test(t)) { inSection = false; continue; } // any h1/h2 ends the section
+      const m = t.match(/^-\s+`(npm:[^`]+)`([^—–]*)/);
+      if (m) {
+        // The scope marker must appear between the package ref and the
+        // description dash — "(global)" inside description prose is ignored.
+        const scopeM = m[2].match(/\((global|local)\)/);
+        packages.push({ source: m[1], scope: scopeM?.[1] === "global" ? "global" : "local" });
+      }
     }
   }
   return packages;
@@ -55,35 +73,53 @@ export interface Provenance {
   lastUpdated: string;
 }
 
-/** Parse the provenance header from a harness.md content. */
+/** Parse the provenance header from a harness.md content. Fields are matched
+ *  independently within the provenance comment block, so their order (and any
+ *  extra fields an agent may have added) doesn't matter. */
 export function parseProvenance(content: string): Provenance | null {
-  const m = content.match(
-    /appliedHarness:\s*(.+?)\s*\n\s*appliedVersion:\s*(.+?)\s*\n\s*sourceCatalogue:\s*(.+?)\s*\n\s*lastUpdated:\s*(.+?)\s*\n/,
-  );
-  if (!m) return null;
-  return {
-    appliedHarness: m[1].trim(),
-    appliedVersion: m[2].trim(),
-    sourceCatalogue: m[3].trim(),
-    lastUpdated: m[4].trim(),
-  };
-}
-
-/** Synchronous catalogue name read for autocomplete (best-effort, local only).
- *  Official distros live on GitHub and aren't available to synchronous
- *  tab-completion — they appear once a command runs and reads the catalogue. */
+  const block = content.match(/<!--\s*pi-distro provenance([\s\S]*?)-->/);
+  if (!block) return null;
+  const field = (name: string): string | undefined =>
+    block[1].match(new RegExp(`${name}:[ \\t]*(.+)`))?.[1].trim();
+  const appliedHarness = field("appliedHarness");
+  const appliedVersion = field("appliedVersion");
+  const sourceCatalogue = field("sourceCatalogue");
+  const lastUpdated = field("lastUpdated");
+  if (!appliedHarness || !appliedVersion || !sourceCatalogue || !lastUpdated) return null;
+  return { appliedHarness, appliedVersion, sourceCatalogue, lastUpdated };
+}
+
+/** Synchronous catalogue name read for autocomplete (best-effort).
+ *  User distros are read from disk (by frontmatter name, falling back to the
+ *  directory name). Official distros live on GitHub and can't be fetched
+ *  synchronously — but the last successful async listing is cached to
+ *  `.official-cache.json` (see github.ts), so their names complete too once
+ *  any command has read the catalogue. */
 export function getCatalogueNamesSync(): string[] {
   const dir = getUserHarnessesDir();
   const names: string[] = [];
   if (existsSync(dir)) {
     try {
       for (const entry of readdirSync(dir, { withFileTypes: true })) {
-        if (entry.isDirectory() && entry.name !== ".trash" && existsSync(join(dir, entry.name, "harness.md"))) {
-          names.push(entry.name);
+        if (entry.isDirectory() && entry.name !== ".trash") {
+          const harnessMdPath = join(dir, entry.name, "harness.md");
+          if (!existsSync(harnessMdPath)) continue;
+          try {
+            const fm = parseFrontmatter(readFileSync(harnessMdPath, "utf-8"));
+            names.push(fm?.name ?? entry.name);
+          } catch {
+            names.push(entry.name);
+          }
         }
       }
     } catch { /* ignore */ }
   }
+  try {
+    const cached = JSON.parse(readFileSync(join(dir, ".official-cache.json"), "utf-8"));
+    if (Array.isArray(cached)) {
+      for (const n of cached) if (typeof n === "string") names.push(n);
+    }
+  } catch { /* no cache yet — officials appear after the first catalogue read */ }
   return [...new Set(names)].sort();
 }
 

package/extensions/deploy.ts

@@ -10,17 +10,19 @@ import type {
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 
-import { listBundledFiles, parseProvenance } from "./catalogue.ts";
+import { listBundledFiles, parseProvenance, parsePackageListWithScope } from "./catalogue.ts";
 import type { HarnessEntry } 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,
   compareVersions,
   readProjectPackages,
+  readGlobalPackages,
   MERGE_RULE,
+  SCOPE_RULE,
   USER_INVOLVEMENT_RULE,
   PACKAGE_CONFLICT_RULE,
 } from "./util.ts";
@@ -37,7 +39,11 @@ export async function sendDeployKickoff(
   const fileList = files.length > 0
     ? files.map((f) => `- \`${f.source}\` → \`./${f.target}\``).join("\n")
     : "_(no bundled files)_";
-  const filesDirNote = harness.filesDir ? `\n\nBundled files are located at: \`${harness.filesDir}\`` : "";
+  const cloneRoot = harness.dir ? tempCloneRoot(harness.dir) : undefined;
+  const cloneCleanupNote = cloneRoot
+    ? `\n\nThe distro was fetched to a temporary GitHub clone. After all bundled files have been copied into the project, remove the clone: \`rm -rf ${cloneRoot}\``
+    : "";
+  const filesDirNote = (harness.filesDir ? `\n\nBundled files are located at: \`${harness.filesDir}\`` : "") + cloneCleanupNote;
 
   const snapshot = ctx.getSystemPromptOptions();
   const activeTools = snapshot.selectedTools?.length
@@ -45,6 +51,15 @@ export async function sendDeployKickoff(
     : "_(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)_";
+
+  // Author-specified scope hints (a package may be marked `(global)` in the directives).
+  // These are *defaults* for the deployment plan — the user's preset still governs.
+  const scopedPackages = parsePackageListWithScope(directives);
+  const packagePlan = scopedPackages.length > 0
+    ? scopedPackages.map((p) => `- \`${p.source}\` [${p.scope}]`).join("\n")
+    : "_(none)_";
 
   // Version comparison against existing provenance (upgrade / downgrade / same / first deploy)
   const provenancePath = join(snapshot.cwd, ".pi", "harness.md");
@@ -77,20 +92,31 @@ ${directives}
 ### Bundled files manifest
 ${fileList}${filesDirNote}
 
+### Packages with author scope hints
+${packagePlan}
+
+(\`[local]\` / \`[global]\` are the distro author's suggested default scope. The user's deploy-time preset — see the scope rule below — governs the final scope.)
+
 ### Current project state (for conflict detection)
 **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.)
 
 ${versionNote}
 
 ### User involvement rule
 ${USER_INVOLVEMENT_RULE}
 
+### Scope rule (install locally or globally)
+${SCOPE_RULE}
+
 ### Merge rule
 ${MERGE_RULE}
 
@@ -138,5 +164,6 @@ export async function handleDeploy(pi: ExtensionAPI, ctx: ExtensionCommandContex
   }
 
   await sendDeployKickoff(pi, ctx, entry);
-  // 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/github.ts

@@ -11,9 +11,9 @@
  */
 
 import { execSync } from "node:child_process";
-import { existsSync, mkdtempSync, rmSync, readFileSync } from "node:fs";
+import { existsSync, mkdtempSync, mkdirSync, rmSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { tmpdir } from "node:os";
+import { tmpdir, homedir } from "node:os";
 import { parseFrontmatter } from "./frontmatter.ts";
 import type { HarnessEntry } from "./catalogue.ts";
 
@@ -152,6 +152,21 @@ export function fetchGithubDistro(
 let officialListCache: { entries: HarnessEntry[]; fetchedAt: number } | null = null;
 const OFFICIAL_LIST_TTL_MS = 5 * 60 * 1000; // 5 minutes
 
+/** Whether the last official-catalogue fetch failed (network down, GitHub API
+ *  rate limit, …). Lets callers tell "GitHub unreachable" apart from "distro
+ *  genuinely doesn't exist" in their messaging. */
+let officialUnavailable = false;
+
+/** True if the most recent official-catalogue fetch failed. */
+export function isOfficialCatalogueUnavailable(): boolean {
+  return officialUnavailable;
+}
+
+/** On-disk cache of official distro names, for synchronous autocomplete. */
+function officialNamesCachePath(): string {
+  return join(homedir(), ".pi", "harnesses", ".official-cache.json");
+}
+
 /**
  * List official distros from OFFICIAL_REPO's `harnesses/` directory via the GitHub
  * Contents API (one call) + a raw frontmatter fetch per distro.
@@ -179,10 +194,11 @@ async function listOfficialDistrosUncached(): Promise<HarnessEntry[]> {
     const resp = await fetch(contentsUrl, {
       headers: { "Accept": "application/vnd.github+json", "User-Agent": "pi-distro" },
     });
-    if (!resp.ok) return [];
+    if (!resp.ok) { officialUnavailable = true; return []; }
     const listing = (await resp.json()) as Array<{ name: string; type: string }>;
     dirs = listing.filter((e) => e.type === "dir").map((e) => e.name);
   } catch {
+    officialUnavailable = true;
     return [];
   }
 
@@ -209,9 +225,30 @@ async function listOfficialDistrosUncached(): Promise<HarnessEntry[]> {
     }
   }));
   entries.sort((a, b) => a.name.localeCompare(b.name));
+  // The raw fetches all failing (with a non-empty dir listing) is also "unavailable".
+  officialUnavailable = dirs.length > 0 && entries.length === 0;
+  if (!officialUnavailable) {
+    try {
+      mkdirSync(join(homedir(), ".pi", "harnesses"), { recursive: true });
+      writeFileSync(officialNamesCachePath(), JSON.stringify(entries.map((e) => e.name)));
+    } catch { /* cache is best-effort */ }
+  }
   return entries;
 }
 
+/**
+ * For a directory inside one of our temp GitHub clones, return the clone root
+ * (the `pi-distro-gh-*` mkdtemp dir), or undefined if the dir is not a temp
+ * clone. Used to tell the deploying agent which directory to remove once the
+ * bundled files have been copied.
+ */
+export function tempCloneRoot(dir: string): string | undefined {
+  const prefix = join(tmpdir(), "pi-distro-gh-");
+  if (!dir.startsWith(prefix)) return undefined;
+  const first = dir.slice(tmpdir().length + 1).split(/[\\/]/)[0];
+  return join(tmpdir(), first);
+}
+
 /** Invalidate the official-list cache (used by tests / explicit refresh). */
 export function clearOfficialListCache(): void {
   officialListCache = null;

package/extensions/index.ts

@@ -35,11 +35,14 @@ const SUBCOMMANDS = [
 
 export default function (pi: ExtensionAPI): void {
   pi.registerCommand("pi-distro", {
-    description: "Manage pi distros (deploy, save, list, show, status, remove)",
+    description: "Manage pi distros (deploy, undeploy, pick, update, save, list, show, status, remove)",
     handler: async (args: string, ctx: ExtensionCommandContext) => {
       const parts = args.trim().split(/\s+/).filter(Boolean);
       const sub = parts[0] ?? "";
       const nameArg = parts[1];
+      if (parts.length > 2) {
+        ctx.ui.notify(`Ignoring extra arguments: ${parts.slice(2).join(" ")}`, "warning");
+      }
       switch (sub) {
         case "": await handleHelp(pi); break;
         case "deploy": await handleDeploy(pi, ctx, nameArg); break;

package/extensions/info.ts

@@ -18,14 +18,25 @@ import {
   sourceLabel,
 } from "./catalogue.ts";
 import { resolveCatalogueEntry } from "./resolve.ts";
-import { isOfficialSource, officialNameFromSource, listOfficialDistros } from "./github.ts";
-import { display, compareVersions } from "./util.ts";
+import {
+  isOfficialSource,
+  officialNameFromSource,
+  listOfficialDistros,
+  isOfficialCatalogueUnavailable,
+} from "./github.ts";
+import { display, compareVersions, readProjectPackages, readGlobalPackages } from "./util.ts";
 
 // --- list ---
 
 export async function handleList(pi: ExtensionAPI): Promise<void> {
   const catalogue = await readCatalogue();
-  if (catalogue.length === 0) { display(pi, "No distros found in the catalogue."); return; }
+  const offlineNote = isOfficialCatalogueUnavailable()
+    ? "\n\n⚠️ Official distros could not be fetched from GitHub (offline or rate-limited?) — showing local distros only. Try again later."
+    : "";
+  if (catalogue.length === 0) {
+    display(pi, `No distros found in the catalogue.${offlineNote}`);
+    return;
+  }
   const rows = catalogue.map((h) => {
     const desc = h.description.length > 50 ? h.description.slice(0, 47) + "..." : h.description;
     return `| ${h.name} | ${h.title} | ${h.version} | ${sourceLabel(h.source)} | ${desc} |`;
@@ -39,7 +50,7 @@ export async function handleList(pi: ExtensionAPI): Promise<void> {
 |------|-------|---------|--------|-------------|
 ${rows.join("\n")}
 
-_Official: ${officialCount} (GitHub) · Local: ${localCount}${otherGhCount > 0 ? ` · Other GitHub: ${otherGhCount}` : ""} · Total: ${catalogue.length}_`);
+_Official: ${officialCount} (GitHub) · Local: ${localCount}${otherGhCount > 0 ? ` · Other GitHub: ${otherGhCount}` : ""} · Total: ${catalogue.length}_${offlineNote}`);
 }
 
 // --- status ---
@@ -67,6 +78,8 @@ export async function handleStatus(pi: ExtensionAPI, ctx: ExtensionCommandContex
           } else if (cmp < 0) {
             updateSection = `### Version note\nApplied v${prov.appliedVersion} is newer than the official catalogue's v${current.version} (downgrade).`;
           } // same version → no section
+        } else if (isOfficialCatalogueUnavailable()) {
+          updateSection = `### Update check\nCould not check for updates: the official catalogue is unreachable (offline or GitHub rate limit?). Try again later.`;
         } else {
           updateSection = `### Update check\nOfficial distro '${prov.appliedHarness}' is no longer in the catalogue (removed or renamed).`;
         }
@@ -97,16 +110,10 @@ export async function handleStatus(pi: ExtensionAPI, ctx: ExtensionCommandContex
   const skillsList = snapshot.skills?.map((s) => `- ${s.name}`).join("\n") ?? "_(none)_";
   const contextList = snapshot.contextFiles?.map((c) => `- ${c.path}`).join("\n") ?? "_(none)_";
 
-  let packages = "_(none)_";
-  const settingsPath = join(cwd, ".pi", "settings.json");
-  if (existsSync(settingsPath)) {
-    try {
-      const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
-      if (Array.isArray(settings.packages) && settings.packages.length > 0) {
-        packages = settings.packages.map((p: string) => `- \`${p}\``).join("\n");
-      }
-    } catch { /* ignore */ }
-  }
+  const lpkgs = readProjectPackages(cwd);
+  const localPackages = lpkgs.length > 0 ? lpkgs.map((p) => `- \`${p}\``).join("\n") : "_(none)_";
+  const gpkgs = readGlobalPackages();
+  const globalPackages = gpkgs.length > 0 ? gpkgs.map((p) => `- \`${p}\``).join("\n") : "_(none)_";
 
   display(pi, `## Project distro status
 
@@ -119,8 +126,10 @@ ${updateSection}
 ${skillsList}
 - **Context files:**
 ${contextList}
-- **Installed packages:**
-${packages}`);
+- **Installed packages (project-local, ./.pi/settings.json):**
+${localPackages}
+- **Installed packages (global, ~/.pi/agent/settings.json):**
+${globalPackages}`);
 }
 
 // --- remove ---