@msdavid/pi-distro 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.3.0 - 2026-07-10
+
+- **Dynamic official distros from GitHub**: official distros (`minimal`, `web-fullstack`,
+  `cc-knockoff`) are no longer bundled inside the npm package. The catalogue fetches them
+  dynamically from the [`msdavid/pi-distro`](https://github.com/msdavid/pi-distro) repo's
+  `harnesses/` directory via the GitHub Contents API (listed cheaply, cloned on demand
+  when selected). Publishing a new official distro now only requires pushing to the repo —
+  no npm release needed. Selectors and `/pi-distro list` label each distro's source
+  clearly: **Official**, **Local**, or **GitHub (<owner>/<repo>)**. Official distros come
+  from the trusted package repo and skip the GitHub security confirmation that other-repo
+  distros require. Network failures degrade gracefully (local-only catalogue).
+- **`harnesses/` removed from the npm tarball**: `package.json` `files` no longer includes
+  `harnesses/`. The directory remains in the repo as the GitHub source of truth.
+- **`/pi-distro status` update check** now also checks official (GitHub) sources for
+  updates via the cached listing, instead of only local sources.
+- **Renamed `pi-distro-one` → `cc-knockoff`**: the distro formerly known as `pi-distro-one`
+  is renamed `cc-knockoff` everywhere (directory, frontmatter, docs). Projects with
+  `appliedHarness: pi-distro-one` provenance will show "no longer in the catalogue" —
+  redeploy as `cc-knockoff` to migrate. No automatic migration is performed.
+
 ## 0.2.0 - 2026-07-08
 
 - **`/pi-distro undeploy`**: the reverse of `deploy` — removes an applied distro from the
@@ -35,7 +55,7 @@
 - **Semantic redundancy check**: the package-conflict check now evaluates semantic overlap
   (different tool names, similar function), not just exact name collisions. Offers
   skip / replace / keep both / cancel.
-- **Auto-expand tool outputs**: pi-distro-one's status-line extension now auto-expands
+- **Auto-expand tool outputs**: cc-knockoff's status-line extension now auto-expands
   tool output on session start (the Ctrl+O effect), while keeping thinking blocks hidden.
 - **Per-distro README.md**: saved distros now include a `README.md` with an extended
   human-readable description. All seed distros ship one too.

package/README.md

@@ -26,8 +26,8 @@ existing setup — nothing is silently overwritten.
 # 1. Install the package
 pi install npm:@msdavid/pi-distro
 
-# 2. Deploy a distro (pi-distro-one = a Claude Code-style multi-agent coder)
-/pi-distro deploy pi-distro-one
+# 2. Deploy a distro (cc-knockoff = a Claude Code-style multi-agent coder)
+/pi-distro deploy cc-knockoff
 
 # 3. Restart pi — done.
 ```
@@ -145,7 +145,7 @@ to apply — just the packages you want, or a single extension, or a subset of t
 This is how you combine pieces from different distros to build your own:
 
 ```bash
-/pi-distro pick pi-distro-one     # pick, say, just pi-subagents + the statusline
+/pi-distro pick cc-knockoff     # pick, say, just pi-subagents + the statusline
 /pi-distro pick web-fullstack      # then add web research from another distro
 /pi-distro save                    # snapshot the combination as your own distro
 ```
@@ -166,7 +166,7 @@ doesn't write provenance (it's a custom config, not an applied distro) — run
 ```bash
 /pi-distro status              # shows the applied distro + live config
 /pi-distro list                # lists all available distros
-/pi-distro show pi-distro-one  # dry-run preview of what a distro would do
+/pi-distro show cc-knockoff  # dry-run preview of what a distro would do
 ```
 
 ### Bring your config to any machine
@@ -239,22 +239,31 @@ All interaction happens through a single slash command — there is no standalon
 
 The effective catalogue is the union of:
 
-- **Package seeds** — shipped with `@msdavid/pi-distro` under `harnesses/`. Read straight
-  from the installed package at runtime. Currently:
+- **Official distros** — fetched dynamically from the [`msdavid/pi-distro`](https://github.com/msdavid/pi-distro)
+  repo's `harnesses/` directory on GitHub (no longer bundled inside the npm package, so
+  new official distros ship by pushing to the repo — no npm release needed). The catalogue
+  is listed via the GitHub Contents API and each distro is cloned on demand when you
+  select it. Currently:
   - **minimal** — clean starting point: basic `AGENTS.md` + `.pi/settings.json`.
   - **web-fullstack** — React/Node project with web research, review skills, restricted tools.
-  - **pi-distro-one** — a Claude Code–style multi-agent coder (see below).
+  - **cc-knockoff** — a Claude Code–style multi-agent coder (see below).
 - **User distros** — saved by you to `~/.pi/harnesses/<name>/` via `/pi-distro save`.
-- **GitHub distros** — fetched on-demand from any GitHub repo.
+- **GitHub distros** — fetched on-demand from any GitHub repo (`/pi-distro deploy owner/repo`).
 - **Partial/combined configs** — built from `/pi-distro pick` across multiple distros, then
   saved as a user distro.
 
+Selectors and `/pi-distro list` show each distro's source clearly: **Official** (the
+`msdavid/pi-distro` repo), **Local** (your `~/.pi/harnesses/`), or **GitHub (<owner>/<repo>)**
+for distros from other repos.
+
 On a name collision, the **user distro takes precedence** — save a distro with the same
-name as a seed to override it.
+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
+distros require.
 
-### pi-distro-one
+### cc-knockoff
 
-`pi-distro-one` is the author's draft shot at using the most popular pi coding packages to
+`cc-knockoff` is the author's draft shot at using the most popular pi coding packages to
 closely resemble the capabilities of Claude Code. It's opinionated — spawning and
 coordinating autonomous sub-agents is the primary capability, with web research, browser
 automation, live shell, model routing, and task management integrated in support. It
@@ -300,7 +309,9 @@ it's saved to `~/.pi/harnesses/<name>/` with a `README.md` describing the distro
 
 ### Author a distro by hand
 
-Create a directory under `~/.pi/harnesses/<name>/` (or contribute a seed to the package)
+Create a directory under `~/.pi/harnesses/<name>/` (or contribute an official distro via a
+PR to the [`msdavid/pi-distro`](https://github.com/msdavid/pi-distro) repo's `harnesses/`
+dir)
 with a `harness.md` and optional `files/`. See
 [docs/authoring.md](docs/authoring.md) for the complete format reference — frontmatter
 fields, bundled file conventions, directive sections, and merge-don't-clobber

package/docs/authoring.md

@@ -187,14 +187,14 @@ frontmatter + directives) with a provenance header injected at the top of the bo
 <!-- pi-distro provenance
      appliedHarness: <name>
      appliedVersion: <version>
-     sourceCatalogue: <user|seed|none>
+     sourceCatalogue: <user|github:owner/repo[/subpath]>
      lastUpdated: <ISO8601>
 -->
 ```
 
 - `appliedHarness`: the name of the distro that was deployed.
 - `appliedVersion`: the version from the distro frontmatter.
-- `sourceCatalogue`: `seed` (from the package) or `user` (from `~/.pi/harnesses/`).
+- `sourceCatalogue`: `user` (from `~/.pi/harnesses/`) or `github:owner/repo[/subpath]` (official distros are `github:msdavid/pi-distro/harnesses/<name>`).
 - `lastUpdated`: ISO 8601 timestamp of the last apply/save.
 
 The provenance file is updated automatically by the `deploy`, `save`, and `undeploy`

package/extensions/catalogue.ts

@@ -1,25 +1,30 @@
 /**
  * Catalogue reading logic for pi-distro.
  *
- * Reads seed harnesses from the installed package dir and user harnesses
- * from ~/.pi/harnesses/. On name collision, user takes precedence.
+ * The effective catalogue is the union of:
+ *   - **Official distros** — fetched dynamically from `msdavid/pi-distro`'s
+ *     `harnesses/` directory on GitHub (no longer bundled in the npm package).
+ *   - **User distros** — saved locally to `~/.pi/harnesses/`.
+ * On a name collision, the user distro takes precedence (so a user can override
+ * an official distro by saving one with the same name).
  */
 
 import { readdirSync, readFileSync, existsSync } from "node:fs";
-import { join, dirname, relative } from "node:path";
+import { join, relative } from "node:path";
 import { homedir } from "node:os";
-import { fileURLToPath } from "node:url";
 import { parseFrontmatter, extractBody } from "./frontmatter.ts";
+import { listOfficialDistros, isOfficialSource } from "./github.ts";
 
 export interface HarnessEntry {
   name: string;
   title: string;
   description: string;
   version: string;
-  source: string;  // "seed", "user", or "github:<owner>/<repo>[/subpath]"
-  dir: string;
-  harnessMdPath: string;
+  source: string;  // "user", "github:owner/repo[/subpath]", or official "github:msdavid/pi-distro/harnesses/<name>"
+  dir?: string;            // on-disk dir (user distros, or a fetched GitHub clone). Absent for official *listing* entries.
+  harnessMdPath?: string;  // path to harness.md. Absent for official *listing* entries (fetched on selection).
   filesDir?: string;
+  needsFetch?: boolean;    // true for official listing entries — must fetchGithubDistro before use
 }
 
 export interface BundledFile {
@@ -64,11 +69,13 @@ export function parseProvenance(content: string): Provenance | null {
   };
 }
 
-/** Synchronous catalogue name read for autocomplete (best-effort). */
+/** 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. */
 export function getCatalogueNamesSync(): string[] {
+  const dir = getUserHarnessesDir();
   const names: string[] = [];
-  for (const dir of [getSeedHarnessesDir(), getUserHarnessesDir()]) {
-    if (!existsSync(dir)) continue;
+  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"))) {
@@ -80,44 +87,36 @@ export function getCatalogueNamesSync(): string[] {
   return [...new Set(names)].sort();
 }
 
-/**
- * Resolve the package root directory (the dir containing package.json).
- * Uses import.meta.url — in extensions/index.ts this resolves to the
- * extensions/ dir, so the package dir is one level up.
- */
-export function getPackageDir(): string {
-  const extensionsDir = dirname(fileURLToPath(import.meta.url));
-  return dirname(extensionsDir);
-}
-
-/** Directory containing seed harnesses shipped with the package. */
-export function getSeedHarnessesDir(): string {
-  return join(getPackageDir(), "harnesses");
-}
-
 /** Directory containing user-saved harnesses (~/.pi/harnesses/). */
 export function getUserHarnessesDir(): string {
   return join(homedir(), ".pi", "harnesses");
 }
 
 /**
- * Read the effective catalogue: seeds ∪ user harnesses.
+ * Read the effective catalogue: official distros (GitHub, dynamic) ∪ user harnesses.
  * On name collision, user takes precedence.
- * Returns sorted: seeds first (alphabetical), then user (alphabetical).
+ * Returns sorted: official first (alphabetical), then user (alphabetical).
+ * Never throws on network failure — official distros are simply omitted and the
+ * catalogue degrades to local-only.
  */
 export async function readCatalogue(): Promise<HarnessEntry[]> {
-  const seeds = readHarnessesFromDir(getSeedHarnessesDir(), "seed");
+  const official = await listOfficialDistros();
   const users = readHarnessesFromDir(getUserHarnessesDir(), "user");
 
   // User takes precedence on collision
   const userNames = new Set(users.map((u) => u.name));
-  const filteredSeeds = seeds.filter((s) => !userNames.has(s.name));
+  const filteredOfficial = official.filter((o) => !userNames.has(o.name));
 
-  // Sort each group alphabetically
-  filteredSeeds.sort((a, b) => a.name.localeCompare(b.name));
+  filteredOfficial.sort((a, b) => a.name.localeCompare(b.name));
   users.sort((a, b) => a.name.localeCompare(b.name));
 
-  return [...filteredSeeds, ...users];
+  return [...filteredOfficial, ...users];
+}
+
+/** Read only local (user) harnesses — no network. Used by update/status local
+ *  resolution and anywhere a network call is undesirable. */
+export function readLocalCatalogue(): HarnessEntry[] {
+  return readHarnessesFromDir(getUserHarnessesDir(), "user");
 }
 
 /** Find a harness by name in the catalogue. */
@@ -156,7 +155,7 @@ export async function readFullHarnessMd(harnessMdPath: string): Promise<string>
 
 function readHarnessesFromDir(
   dir: string,
-  source: "seed" | "user",
+  source: "user",
 ): HarnessEntry[] {
   if (!existsSync(dir)) return [];
 
@@ -219,3 +218,13 @@ function walkDir(
     }
   }
 }
+
+// --- Source labelling (for selectors / list / status) ---
+
+/** A short human label for a distro source, shown in selectors and lists. */
+export function sourceLabel(source: string): string {
+  if (isOfficialSource(source)) return "Official";
+  if (source === "user") return "Local";
+  if (source.startsWith("github:")) return `GitHub (${source.slice("github:".length)})`;
+  return source;
+}

package/extensions/deploy.ts

@@ -13,7 +13,7 @@ import { join } from "node:path";
 import { listBundledFiles, parseProvenance } from "./catalogue.ts";
 import type { HarnessEntry } from "./catalogue.ts";
 import { extractBody } from "./frontmatter.ts";
-import { parseGithubRef } from "./github.ts";
+import { parseGithubRef, isOfficialSource } from "./github.ts";
 import { resolveDistro } from "./resolve.ts";
 import { buildShowPreview } from "./show.ts";
 import {
@@ -31,7 +31,7 @@ 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
@@ -119,8 +119,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.`;

package/extensions/github.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,90 @@ 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
+
+/**
+ * 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) return [];
+    const listing = (await resp.json()) as Array<{ name: string; type: string }>;
+    dirs = listing.filter((e) => e.type === "dir").map((e) => e.name);
+  } catch {
+    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));
+  return entries;
+}
+
+/** 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/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,8 +15,10 @@ import {
   findHarness,
   parseProvenance,
   getUserHarnessesDir,
+  sourceLabel,
 } from "./catalogue.ts";
 import { resolveCatalogueEntry } from "./resolve.ts";
+import { isOfficialSource, officialNameFromSource, listOfficialDistros } from "./github.ts";
 import { display, compareVersions } from "./util.ts";
 
 // --- list ---
@@ -26,17 +28,18 @@ export async function handleList(pi: ExtensionAPI): Promise<void> {
   if (catalogue.length === 0) { display(pi, "No distros found in the catalogue."); 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}_`);
 }
 
 // --- status ---
@@ -51,9 +54,24 @@ 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 {
+          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);
@@ -116,8 +134,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 +145,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

@@ -11,7 +11,7 @@ import { join } from "node:path";
 
 import { listBundledFiles, parsePackageList } from "./catalogue.ts";
 import { extractBody } from "./frontmatter.ts";
-import { parseGithubRef } from "./github.ts";
+import { parseGithubRef, isOfficialSource } from "./github.ts";
 import { resolveDistro } from "./resolve.ts";
 import { buildShowPreview } from "./show.ts";
 import {
@@ -27,8 +27,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,7 +46,7 @@ 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 files = entry.filesDir ? await listBundledFiles(entry.filesDir) : [];

package/extensions/resolve.ts

@@ -9,10 +9,12 @@ 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 } from "./github.ts";
 
 /**
  * Resolve a distro from a name argument (GitHub ref or local catalogue name).
@@ -52,19 +54,44 @@ export async function resolveDistro(
       ctx.ui.notify(`Distro '${nameArg}' not found. Available: ${available}`, "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);
 }

package/extensions/save.ts

@@ -137,11 +137,12 @@ and the full draft. Ask for confirmation or edits. Do NOT proceed until the user
 
 **3. Choose save target.** Ask the user whether to:
   - **(a) Save as a new distro** — ask for a name (validate the slug; if it collides with an
-    existing user distro or a seed name, warn and ask whether to overwrite), then create
+    existing user distro or an official distro name (fetched from GitHub), warn and ask
+    whether to overwrite), then create
     \`~/.pi/harnesses/<name>/\`.
   - **(b) Update an existing distro** — let the user pick from the existing user distros
-    above. Refuse to update a name that is NOT in the existing-user list (those are package
-    seeds and are read-only). Before overwriting, back the old distro up: copy
+    above. Refuse to update a name that is NOT in the existing-user list (official distros
+    live on GitHub and are read-only locally). Before overwriting, back the old distro up: copy
     \`~/.pi/harnesses/<name>/\` to
     \`~/.pi/harnesses/.trash/<name>-<timestamp>/\` (create \`.trash/\` if needed).
     **Bump the version:** read the old distro's \`version\` field and increment it using