@msdavid/pi-distro 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # 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`,
+  `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 +95,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

@@ -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 (pi-distro-one = a Claude Code-style multi-agent coder)
-/pi-distro deploy pi-distro-one
+# 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)
@@ -145,7 +201,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 +222,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 +295,35 @@ 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.
+
+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 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 +369,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

@@ -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
@@ -187,14 +257,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`
@@ -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

@@ -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 {
@@ -27,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;
@@ -50,74 +73,86 @@ 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). */
+  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[] = [];
-  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"))) {
-          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();
 }
 
-/**
- * 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 +191,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 +254,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;
+}