@msdavid/pi-distro 0.2.0 → 0.4.0

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 } 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";
@@ -31,13 +33,17 @@ export async function sendDeployKickoff(
   ctx: ExtensionCommandContext,
   harness: HarnessEntry,
 ): Promise<void> {
-  const body = readFileSync(harness.harnessMdPath, "utf-8");
+  const body = readFileSync(harness.harnessMdPath!, "utf-8");
   const directives = extractBody(body);
   const files = harness.filesDir ? await listBundledFiles(harness.filesDir) : [];
   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}
 
@@ -119,8 +145,9 @@ export async function handleDeploy(pi: ExtensionAPI, ctx: ExtensionCommandContex
   if (!resolved) return;
   const { entry, cleanup } = resolved;
 
-  // GitHub trust gate (local distros are trusted by being in the catalogue).
-  if (cleanup) {
+  // GitHub trust gate — official distros (msdavid/pi-distro) are trusted and skip
+  // the warning; other GitHub refs require explicit user confirmation.
+  if (cleanup && !isOfficialSource(entry.source)) {
     const ref = parseGithubRef(nameArg!)!;
     const preview = await buildShowPreview(entry);
     const warning = `\n\n---\n\n⚠️ **Security warning:** This distro was fetched from \`${ref.displayRef}\` on GitHub. Installing unknown distros is **dangerous** — they can install arbitrary packages, write extensions that execute code, and inject agent instructions. Review everything above carefully before proceeding. You are responsible for what you install.`;
@@ -137,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";
 
@@ -24,6 +24,43 @@ export interface GithubRef {
   displayRef: string; // "owner/repo" or "owner/repo/subpath"
 }
 
+/**
+ * The official distros repo: `msdavid/pi-distro`, with distros under `harnesses/`.
+ * Official distros are a special case of GitHub distros — they live here and are
+ * fetched on demand (the npm package no longer ships bundled seeds).
+ */
+export const OFFICIAL_REPO = {
+  owner: "msdavid",
+  repo: "pi-distro",
+  path: "harnesses",
+  ref: "main",
+} as const;
+
+/** Official distro source prefix: `github:msdavid/pi-distro/harnesses/<name>`. */
+export const OFFICIAL_SOURCE_PREFIX = `github:${OFFICIAL_REPO.owner}/${OFFICIAL_REPO.repo}/${OFFICIAL_REPO.path}/`;
+
+/** Whether a HarnessEntry.source / provenance sourceCatalogue is the official repo. */
+export function isOfficialSource(source: string): boolean {
+  return source.startsWith(OFFICIAL_SOURCE_PREFIX) ||
+    source === `github:${OFFICIAL_REPO.owner}/${OFFICIAL_REPO.repo}/${OFFICIAL_REPO.path}`;
+}
+
+/** Build the official source string for a distro name. */
+export function officialSource(name: string): string {
+  return `${OFFICIAL_SOURCE_PREFIX}${name}`;
+}
+
+/** Parse an official source string back into the distro name, or undefined. */
+export function officialNameFromSource(source: string): string | undefined {
+  if (source.startsWith(OFFICIAL_SOURCE_PREFIX)) {
+    return source.slice(OFFICIAL_SOURCE_PREFIX.length);
+  }
+  if (source === `github:${OFFICIAL_REPO.owner}/${OFFICIAL_REPO.repo}/${OFFICIAL_REPO.path}`) {
+    return ""; // the bare harnesses path (shouldn't normally happen)
+  }
+  return undefined;
+}
+
 /**
  * Parse a GitHub reference: `owner/repo[/subpath]` or a full GitHub URL.
  * Returns undefined if the string doesn't look like a valid GitHub ref.
@@ -108,3 +145,127 @@ export function fetchGithubDistro(
 
   return { entry, cleanup: () => rmSync(tmp, { recursive: true, force: true }) };
 }
+
+// --- Official distros (dynamic, from OFFICIAL_REPO on GitHub) ---
+
+/** In-memory cache for listOfficialDistros() to avoid repeat API calls in a session. */
+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.
+ *
+ * Returns *listing* entries: `needsFetch: true`, no `dir`/`filesDir` (those are
+ * populated by `fetchOfficialDistro()` when the user actually selects one).
+ *
+ * Never throws — on any network/parse failure returns [] (caller degrades to
+ * local-only catalogue). Results are cached for OFFICIAL_LIST_TTL_MS.
+ */
+export async function listOfficialDistros(): Promise<HarnessEntry[]> {
+  if (officialListCache && Date.now() - officialListCache.fetchedAt < OFFICIAL_LIST_TTL_MS) {
+    return officialListCache.entries;
+  }
+  const entries = await listOfficialDistrosUncached();
+  officialListCache = { entries, fetchedAt: Date.now() };
+  return entries;
+}
+
+async function listOfficialDistrosUncached(): Promise<HarnessEntry[]> {
+  // 1. List `harnesses/` subdirs via the Contents API.
+  const contentsUrl = `https://api.github.com/repos/${OFFICIAL_REPO.owner}/${OFFICIAL_REPO.repo}/contents/${OFFICIAL_REPO.path}?ref=${OFFICIAL_REPO.ref}`;
+  let dirs: string[];
+  try {
+    const resp = await fetch(contentsUrl, {
+      headers: { "Accept": "application/vnd.github+json", "User-Agent": "pi-distro" },
+    });
+    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 [];
+  }
+
+  // 2. Fetch each distro's harness.md frontmatter (raw, unauthenticated).
+  const entries: HarnessEntry[] = [];
+  await Promise.all(dirs.map(async (name) => {
+    const rawUrl = `https://raw.githubusercontent.com/${OFFICIAL_REPO.owner}/${OFFICIAL_REPO.repo}/${OFFICIAL_REPO.ref}/${OFFICIAL_REPO.path}/${name}/harness.md`;
+    try {
+      const resp = await fetch(rawUrl, { headers: { "User-Agent": "pi-distro" } });
+      if (!resp.ok) return;
+      const content = await resp.text();
+      const fm = parseFrontmatter(content);
+      if (!fm?.name) return;
+      entries.push({
+        name: fm.name,
+        title: fm.title ?? fm.name,
+        description: fm.description ?? "",
+        version: fm.version ?? "0.0.0",
+        source: officialSource(fm.name),
+        needsFetch: true,
+      });
+    } catch {
+      // skip this distro
+    }
+  }));
+  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;
+}
+
+/**
+ * Fetch an official distro by name: shallow-clones OFFICIAL_REPO and points at
+ * `harnesses/<name>/`. Returns { entry, cleanup } like fetchGithubDistro.
+ * Throws on clone failure or if the distro/harness.md is missing.
+ */
+export function fetchOfficialDistro(
+  name: string,
+): { entry: HarnessEntry; cleanup: () => void } {
+  return fetchGithubDistro({
+    owner: OFFICIAL_REPO.owner,
+    repo: OFFICIAL_REPO.repo,
+    subPath: `${OFFICIAL_REPO.path}/${name}`,
+    displayRef: `${OFFICIAL_REPO.owner}/${OFFICIAL_REPO.repo}/${OFFICIAL_REPO.path}/${name}`,
+  });
+}

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

@@ -7,7 +7,7 @@ import type {
   ExtensionAPI,
   ExtensionCommandContext,
 } from "@earendil-works/pi-coding-agent";
-import { readFileSync, existsSync, readdirSync, mkdirSync, cpSync, rmSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync, cpSync, rmSync } from "node:fs";
 import { join } from "node:path";
 
 import {
@@ -15,28 +15,42 @@ import {
   findHarness,
   parseProvenance,
   getUserHarnessesDir,
+  sourceLabel,
 } from "./catalogue.ts";
 import { resolveCatalogueEntry } from "./resolve.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} | ${h.source} | ${desc} |`;
+    return `| ${h.name} | ${h.title} | ${h.version} | ${sourceLabel(h.source)} | ${desc} |`;
   });
-  const seedCount = catalogue.filter((h) => h.source === "seed").length;
-  const userCount = catalogue.filter((h) => h.source === "user").length;
+  const officialCount = catalogue.filter((h) => isOfficialSource(h.source)).length;
+  const localCount = catalogue.filter((h) => h.source === "user").length;
+  const otherGhCount = catalogue.length - officialCount - localCount;
   display(pi, `## Distro catalogue
 
 | NAME | TITLE | VERSION | SOURCE | DESCRIPTION |
 |------|-------|---------|--------|-------------|
 ${rows.join("\n")}
 
-_Seeds: ${seedCount} · User: ${userCount} · Total: ${catalogue.length}_`);
+_Official: ${officialCount} (GitHub) · Local: ${localCount}${otherGhCount > 0 ? ` · Other GitHub: ${otherGhCount}` : ""} · Total: ${catalogue.length}_${offlineNote}`);
 }
 
 // --- status ---
@@ -51,9 +65,26 @@ export async function handleStatus(pi: ExtensionAPI, ctx: ExtensionCommandContex
   if (existsSync(provenancePath)) {
     const prov = parseProvenance(readFileSync(provenancePath, "utf-8"));
     if (prov) {
-      provenanceSection = `### Applied distro\n- **Name:** ${prov.appliedHarness}\n- **Version:** ${prov.appliedVersion}\n- **Source:** ${prov.sourceCatalogue}\n- **Last updated:** ${prov.lastUpdated}`;
-      // Check for updates (local catalogue only; GitHub sources are not auto-fetched on status).
-      if (!prov.sourceCatalogue.startsWith("github:")) {
+      provenanceSection = `### Applied distro\n- **Name:** ${prov.appliedHarness}\n- **Version:** ${prov.appliedVersion}\n- **Source:** ${sourceLabel(prov.sourceCatalogue)}\n- **Last updated:** ${prov.lastUpdated}`;
+      // Check for updates.
+      if (isOfficialSource(prov.sourceCatalogue)) {
+        // Official: cheap version check via the cached GitHub listing (no clone).
+        const officialName = officialNameFromSource(prov.sourceCatalogue);
+        const current = (await listOfficialDistros()).find((h) => h.name === officialName);
+        if (current) {
+          const cmp = compareVersions(current.version, prov.appliedVersion);
+          if (cmp > 0) {
+            updateSection = `### Update available\n**${prov.appliedHarness}** v${prov.appliedVersion} → v${current.version}. Run \`/pi-distro update\` to apply.`;
+          } 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).`;
+        }
+      } else if (!prov.sourceCatalogue.startsWith("github:")) {
+        // Local (user) catalogue.
         const current = await resolveCatalogueEntry(prov.appliedHarness);
         if (current) {
           const cmp = compareVersions(current.version, prov.appliedVersion);
@@ -79,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
 
@@ -101,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 ---
@@ -116,8 +143,8 @@ export async function handleRemove(pi: ExtensionAPI, ctx: ExtensionCommandContex
     ctx.ui.notify(`Distro '${name}' not found. Available: ${available}`, "error");
     return;
   }
-  if (harness.source === "seed") {
-    ctx.ui.notify(`'${name}' is a package seed and cannot be removed.`, "error");
+  if (harness.source.startsWith("github:")) {
+    ctx.ui.notify(`'${name}' is a GitHub distro (${sourceLabel(harness.source)}) and cannot be removed locally. Only user-saved distros in ~/.pi/harnesses/ can be removed.`, "error");
     return;
   }
   const confirmed = await ctx.ui.confirm("Remove harness?", `This deletes '~/.pi/harnesses/${name}/'. A backup will be saved to .trash/.`);
@@ -127,7 +154,7 @@ export async function handleRemove(pi: ExtensionAPI, ctx: ExtensionCommandContex
   const userDir = getUserHarnessesDir();
   const trashDir = join(userDir, ".trash", `${name}-${Date.now()}`);
   mkdirSync(trashDir, { recursive: true });
-  cpSync(harness.dir, join(trashDir, name), { recursive: true });
-  rmSync(harness.dir, { recursive: true, force: true });
+  cpSync(harness.dir!, join(trashDir, name), { recursive: true });
+  rmSync(harness.dir!, { recursive: true, force: true });
   ctx.ui.notify(`Removed distro '${name}'. (Backup in ~/.pi/harnesses/.trash/)`, "info");
 }

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 } 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";
@@ -27,8 +29,9 @@ export async function handlePick(pi: ExtensionAPI, ctx: ExtensionCommandContext,
   if (!resolved) return;
   const { entry, cleanup } = resolved;
 
-  // GitHub trust gate (same as deploy — the user must confirm before anything is applied).
-  if (cleanup) {
+  // GitHub trust gate — official distros are trusted and skip the warning;
+  // other GitHub refs require explicit user confirmation.
+  if (cleanup && !isOfficialSource(entry.source)) {
     const ref = parseGithubRef(nameArg!)!;
     const preview = await buildShowPreview(entry);
     const warning = `\n\n---\n\n⚠️ **Security warning:** This distro was fetched from \`${ref.displayRef}\` on GitHub. Picking components from an unknown distro is still **dangerous** — packages can execute code, extensions run at startup, and directives inject agent instructions. Review everything above carefully. You are responsible for what you install.`;
@@ -45,11 +48,15 @@ export async function handlePick(pi: ExtensionAPI, ctx: ExtensionCommandContext,
   }
 
   // Parse the distro into selectable components.
-  const fullMd = readFileSync(entry.harnessMdPath, "utf-8");
+  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
@@ -57,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")
@@ -88,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**
@@ -114,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).
@@ -128,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

@@ -9,10 +9,18 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import {
   readCatalogue,
+  readLocalCatalogue,
   findHarness,
+  sourceLabel,
 } from "./catalogue.ts";
 import type { HarnessEntry } from "./catalogue.ts";
-import { looksLikeGithubRef, parseGithubRef, fetchGithubDistro } 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).
@@ -41,30 +49,63 @@ 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 { entry: harness };
+    return resolveEntry(harness, ctx);
   }
   // No nameArg → interactive selector
   const theme = ctx.ui.theme;
-  const labels = catalogue.map((h) => `${theme.bold(h.name)} — ${h.description}`);
+  const labels = catalogue.map((h) => `${theme.bold(h.name)} — ${h.description}  [${sourceLabel(h.source)}]`);
   const selected = await ctx.ui.select(`Select a distro to ${verb}:`, labels);
   if (selected === undefined) return undefined;
   const harness = catalogue[labels.indexOf(selected)];
-  return harness ? { entry: harness } : undefined;
+  return harness ? resolveEntry(harness, ctx) : undefined;
 }
 
-/** Resolve the current catalogue entry for a distro by name (local catalogue only). */
+/**
+ * Resolve a catalogue entry to a usable { entry, cleanup? }.
+ * Official listing entries (needsFetch) are fetched from GitHub here — the actual
+ * clone happens at selection time, not at catalogue read. Local entries are
+ * returned as-is (no cleanup).
+ */
+async function resolveEntry(
+  harness: HarnessEntry,
+  ctx: ExtensionCommandContext,
+): Promise<{ entry: HarnessEntry; cleanup?: () => void } | undefined> {
+  if (harness.needsFetch) {
+    ctx.ui.notify(`Fetching official distro '${harness.name}' from GitHub…`, "info");
+    try {
+      const fetched = fetchOfficialDistro(harness.name);
+      return { entry: fetched.entry, cleanup: fetched.cleanup };
+    } catch (err) {
+      ctx.ui.notify(err instanceof Error ? err.message : String(err), "error");
+      return undefined;
+    }
+  }
+  return { entry: harness };
+}
+
+/** Resolve the current catalogue entry for a distro by name (local/user catalogue only —
+ *  no network). Only called for non-GitHub provenance sources; GitHub sources
+ *  are re-fetched directly by the update command. */
 export async function resolveCatalogueEntry(name: string): Promise<HarnessEntry | undefined> {
-  const catalogue = await readCatalogue();
+  const catalogue = readLocalCatalogue();
   return findHarness(name, catalogue);
 }