@msdavid/pi-distro 0.2.0

package/extensions/save.ts

@@ -0,0 +1,217 @@
+/**
+ * `/pi-distro save` — snapshot the current project config as a reusable distro.
+ * Agent-driven; see skills/pi-distro/SKILL.md for the collaborative authoring flow.
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import { readFileSync, statSync, existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { getUserHarnessesDir } from "./catalogue.ts";
+import { display } from "./util.ts";
+
+export async function handleSave(pi: ExtensionAPI, ctx: ExtensionCommandContext): Promise<void> {
+  const snapshot = ctx.getSystemPromptOptions();
+  const cwd = snapshot.cwd;
+
+  // Enumerate ALL project-local config files so nothing is missed — including per-extension/skill
+  // config files, .pi/SYSTEM.md & .pi/APPEND_SYSTEM.md, theme files, subdirectory extensions,
+  // nested skill dirs, pi-crew's project-local agents/teams/workflows, and the cross-tool
+  // .agents/skills/ dir. Data/runtime dirs and our own provenance file are skipped. Ancestor
+  // (parent-dir) AGENTS.md / .agents/skills are out of scope for a single-project distro and
+  // are only surfaced via the snapshot's contextFiles list.
+  // NOTE: .crew/ is handled separately below — it mixes authored config (agents/teams/workflows)
+  // with runtime state (state/artifacts/worktrees/imports/audit/cache/graphs), so only its three
+  // config subdirs are captured, not the whole tree.
+  const SKIP_NAMES = new Set(["npm", "git", "sessions", "state", "tmp", "node_modules"]);
+  const MAX_DUMP_BYTES = 16384;
+  const configFiles: string[] = [];
+  const pushFile = (fp: string) => {
+    let st;
+    try { st = statSync(fp); } catch { return; }
+    if (st.size > MAX_DUMP_BYTES) {
+      configFiles.push(`### ${fp}\n_(${st.size} bytes — read with the \`read\` tool if needed)_`);
+      return;
+    }
+    try {
+      configFiles.push(`### ${fp}\n\`\`\`\n${readFileSync(fp, "utf-8")}\n\`\`\``);
+    } catch { /* unreadable (binary?) — skip */ }
+  };
+  const walk = (dir: string, isPiRoot: boolean) => {
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (isPiRoot && entry.name === "harness.md") continue; // provenance — never bundle
+      const fp = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_NAMES.has(entry.name)) continue;
+        walk(fp, false);
+      } else if (entry.isFile()) {
+        pushFile(fp);
+      }
+    }
+  };
+  // Root context files — pi tries all four variants; only exact AGENTS.md was captured before.
+  for (const name of ["AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"]) {
+    const p = join(cwd, name);
+    if (existsSync(p)) pushFile(p);
+  }
+  // Everything under .pi/: settings.json, SYSTEM.md, APPEND_SYSTEM.md, extensions/ (incl.
+  // subdir extensions), skills/ (incl. nested), prompts/, themes/, and any per-extension/skill
+  // config files (e.g. .pi/<name>.json) that we cannot predict by name.
+  const piDir = join(cwd, ".pi");
+  if (existsSync(piDir)) walk(piDir, true);
+  // Cross-tool skills at project root only (ancestor .agents/skills/ are out of scope).
+  const agentsSkills = join(cwd, ".agents", "skills");
+  if (existsSync(agentsSkills)) walk(agentsSkills, false);
+  // pi-crew project-local authored config: .crew/{agents,teams,workflows}/ (the legacy pi-crew
+  // project root, which projectCrewRoot prefers over .pi/teams/ when it exists). Only these
+  // three config subdirs are captured — the rest of .crew/ is runtime state (state/artifacts/
+  // worktrees/imports/audit/cache/graphs). The .pi/teams/ and .pi/agents/ equivalents are
+  // already captured by the .pi/ walk above. Files that are --copy-builtins copies of pi-crew's
+  // shipped builtins should be deduped by the agent (see procedure) rather than bundled.
+  const crewDir = join(cwd, ".crew");
+  if (existsSync(crewDir)) {
+    for (const sub of ["agents", "teams", "workflows"]) {
+      const subDir = join(crewDir, sub);
+      if (existsSync(subDir)) walk(subDir, false);
+    }
+  }
+
+  // Existing user harnesses (so the agent can offer update-existing)
+  const userDir = getUserHarnessesDir();
+  const existing: string[] = [];
+  if (existsSync(userDir)) {
+    try {
+      for (const entry of readdirSync(userDir, { withFileTypes: true })) {
+        if (entry.isDirectory() && entry.name !== ".trash"
+          && existsSync(join(userDir, entry.name, "harness.md"))) {
+          existing.push(entry.name);
+        }
+      }
+    } catch { /* ignore */ }
+  }
+  existing.sort();
+
+  const tools = snapshot.selectedTools?.join(", ") ?? "(default)";
+  const skillsList = snapshot.skills?.map((s) => `- ${s.name}: ${s.description}`).join("\n") ?? "_(none)_";
+  const contextList = snapshot.contextFiles?.map((c) => `- ${c.path}`).join("\n") ?? "_(none)_";
+  const existingList = existing.length > 0 ? existing.map((n) => `- \`${n}\``).join("\n") : "_(none yet)_";
+
+  pi.sendUserMessage(`## Save current configuration as a distro
+
+A live snapshot of this project's pi configuration follows. Draft a \`harness.md\` that
+reproduces it, confirm with the user, then save it to the catalogue.
+
+### Live snapshot
+- **Working dir:** ${cwd}
+- **Active tools:** ${tools}
+- **Skills:**
+${skillsList}
+- **Context files:**
+${contextList}
+
+### Raw config files
+${configFiles.length > 0 ? configFiles.join("\n\n") : "_(none found)_"}
+
+### Existing user distros in the catalogue
+${existingList}
+
+Catalogue dir: \`${userDir}\`
+
+### Procedure (follow exactly, collaborating with the user)
+
+**1. Draft.** Analyse the snapshot and write a \`harness.md\` that reproduces this
+configuration. Frontmatter MUST include: \`name\` (slug: lowercase a-z/0-9/hyphens, no
+leading/trailing/consecutive hyphens), \`title\` (human-readable), \`description\`
+(one-liner, <=300 chars), \`version\` (semver). Optionally \`author\` and \`tags\`.
+The body should have directive sections (Bundled files, pi packages to install, System
+prompt/SYSTEM.md if present, Themes, Context, Skills/prompts, and any per-extension/skill
+config files) mirroring the live config.
+
+**2. Propose & confirm.** Show the user the proposed \`name\`, \`title\`, \`description\`,
+and the full draft. Ask for confirmation or edits. Do NOT proceed until the user confirms.
+
+**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
+    \`~/.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
+    \`~/.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
+    semver: **patch** (\`0.1.0\` -> \`0.1.1\`) for small tweaks/bug fixes, **minor**
+    (\`0.1.0\` -> \`0.2.0\`) for new capabilities or config additions, **major**
+    (\`0.1.0\` -> \`1.0.0\`) for breaking changes (removed packages, changed conventions). Never
+    keep the same version when updating — a distro's version should always reflect that
+    something changed. Propose the bumped version to the user and let them confirm or adjust.
+
+**4. Write the harness.** Write \`~/.pi/harnesses/<name>/harness.md\` with the confirmed
+frontmatter + directives. Then copy the project's config files into
+\`~/.pi/harnesses/<name>/files/\` so the harness is self-contained and reproducible. Copy
+EVERY file listed under "Raw config files" above, preserving its path relative to the
+project root:
+  - root context (\`AGENTS.md\` / \`CLAUDE.md\` / case variants) -> \`files/<name>\`
+  - \`.pi/settings.json\` -> \`files/.pi/settings.json\`
+  - \`.pi/SYSTEM.md\` / \`.pi/APPEND_SYSTEM.md\` -> \`files/.pi/\` (same name)
+  - \`.pi/extensions/**\` (incl. subdirectory extensions with \`index.ts\`/\`package.json\`)
+    -> \`files/.pi/extensions/\` (preserve structure)
+  - \`.pi/skills/**\` (incl. nested skill dirs) -> \`files/.pi/skills/\`
+  - \`.pi/prompts/**\` -> \`files/.pi/prompts/\`
+  - \`.pi/themes/**\` -> \`files/.pi/themes/\` (see theme dedup below)
+  - \`.agents/skills/**\` (project root only) -> \`files/.agents/skills/\`
+  - \`.crew/{agents,teams,workflows}/**\` (pi-crew project-local authored definitions)
+    -> \`files/.crew/<sub>/\` (preserve structure). Do NOT copy the rest of \`.crew/\`
+    (state/artifacts/worktrees/imports/audit/cache/graphs = runtime data).
+  - any per-extension/skill config files (e.g. \`.pi/<name>.json\`) -> \`files/.pi/\` (same path)
+  Use \`cp -r\` for directory trees. Only copy files that actually exist. Do NOT copy:
+  \`./.pi/harness.md\` (provenance), \`./.pi/npm/\`, \`./.pi/git/\`, \`./.pi/sessions/\`,
+  \`./.pi/state/\`, \`./.pi/tmp/\`, \`./.pi/.crew/\`, or any \`node_modules/\`.
+
+  **Theme dedup:** before bundling a \`.pi/themes/<name>.json\`, check whether that theme
+  name is already provided by an installed package (run \`pi list\`; package themes surface
+  at \`~/.pi/agent/themes/\`). If a package provides it, do NOT bundle the file — reference
+  it via the package install directive instead (a bundled copy would collide on deploy,
+  exactly like the pi-crew \`crew-*\` themes). Only bundle genuinely custom themes not
+  available from any package.
+
+  **pi-crew agents/teams/workflows dedup:** \`.crew/agents/foo.md\` (or \`.pi/teams/agents/\`,
+  \`.pi/agents/\`) may be a \`--copy-builtins\` copy of a pi-crew shipped builtin rather than
+  custom-authored. Before bundling, compare against pi-crew's package builtins at
+  \`<pkg>/agents/\` (and \`teams/\`, \`workflows/\`). If a file is an unmodified builtin copy,
+  do NOT bundle it — the \`pi-crew\` install directive already provides it. Bundle only
+  genuinely custom/authored definitions.
+
+  **Extension/skill config:** some extensions or skills read their own config file (e.g.
+  \`.pi/<extname>.json\`). These appear in the raw config files above. Bundle any that are
+  project-local authored config; if a file is machine-specific runtime state rather than
+  authored config, skip it and tell the user why.
+
+  **Write a README.md:** also write \`~/.pi/harnesses/<name>/README.md\` — a
+  human-readable description of the distro (a few paragraphs: what it sets up, which
+  packages it installs and why, what workflow it targets, and any prerequisites). This is
+  the extended description that complements the one-liner \`description\` in the
+  frontmatter. The README is not consumed by the extension; it is for users browsing the
+  catalogue or reading the distro on disk. Do NOT copy it into the target project on
+  deploy — it lives only in the catalogue.
+
+**5. Update provenance.** Update \`./.pi/harness.md\` in the project to reflect the saved
+harness. The provenance file is a valid \`harness.md\` (the saved frontmatter + directives)
+with this header at the top of the body:
+\`\`\`
+<!-- pi-distro provenance
+     appliedHarness: <name>
+     appliedVersion: <version>
+     sourceCatalogue: user
+     lastUpdated: <ISO8601 now>
+-->
+\`\`\`
+
+**6. Report.** Tell the user: "Saved distro '<name>'. Run \`/pi-distro deploy\` elsewhere to
+deploy it."`);
+}

package/extensions/show.ts

@@ -0,0 +1,96 @@
+/**
+ * `/pi-distro show` — dry-run preview of a distro (local or GitHub).
+ * Also exports buildShowPreview(), reused by deploy/pick/update.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { readFullHarnessMd, listBundledFiles, readCatalogue, findHarness, parsePackageList } from "./catalogue.ts";
+import type { HarnessEntry } from "./catalogue.ts";
+import { parseFrontmatter, extractBody } from "./frontmatter.ts";
+import { looksLikeGithubRef, parseGithubRef, fetchGithubDistro } from "./github.ts";
+import { display } from "./util.ts";
+
+/** Build the dry-run preview for a harness (used by local and GitHub show). */
+export async function buildShowPreview(harness: HarnessEntry): Promise<string> {
+  const fullMd = await readFullHarnessMd(harness.harnessMdPath);
+  const fm = parseFrontmatter(fullMd);
+  const body = extractBody(fullMd);
+  const packages = parsePackageList(body);
+
+  let settingsPreview = "_(none)_";
+  if (harness.filesDir) {
+    const sp = join(harness.filesDir, "settings.json");
+    if (existsSync(sp)) settingsPreview = "```json\n" + readFileSync(sp, "utf-8") + "\n```";
+  }
+  const files = harness.filesDir ? await listBundledFiles(harness.filesDir) : [];
+  const fileList = files.length > 0
+    ? files.map((f) => `- \`${f.source}\` → \`./${f.target}\``).join("\n")
+    : "_(none)_";
+  const tags = fm?.tags
+    ? Array.isArray(fm.tags) ? fm.tags.join(", ") : String(fm.tags)
+    : "_(none)_";
+
+  return `## Distro preview: ${harness.name}
+
+### Frontmatter
+- **Name:** ${fm?.name ?? harness.name}
+- **Title:** ${fm?.title ?? harness.title}
+- **Description:** ${fm?.description ?? harness.description}
+- **Version:** ${fm?.version ?? harness.version}
+- **Tags:** ${tags}
+- **Source:** ${harness.source}
+
+### pi packages to install
+${packages.length > 0 ? packages.map((p) => `- \`${p}\``).join("\n") : "_(none)_"}
+
+### Settings (would be merged)
+${settingsPreview}
+
+### Bundled files (target paths)
+${fileList}
+
+### Full directives
+${body}
+
+---
+Nothing is applied. Run \`/pi-distro deploy\` to apply.`;
+}
+
+export async function handleShow(pi: ExtensionAPI, name?: string): Promise<void> {
+  if (!name) {
+    display(pi, "Usage: \`/pi-distro show <name|gh-repo>\`\n\nExamples:\n  /pi-distro show minimal\n  /pi-distro show owner/repo\n  /pi-distro show owner/repo/subpath");
+    return;
+  }
+
+  // GitHub ref?
+  if (looksLikeGithubRef(name)) {
+    const ref = parseGithubRef(name)!;
+    pi.sendMessage({ customType: "pi-distro", content: `Fetching \`${ref.displayRef}\` from GitHub…`, display: true });
+    let fetched;
+    try {
+      fetched = fetchGithubDistro(ref);
+    } catch (err) {
+      display(pi, `**Error:** ${err instanceof Error ? err.message : String(err)}`);
+      return;
+    }
+    try {
+      display(pi, await buildShowPreview(fetched.entry));
+    } finally {
+      fetched.cleanup();
+    }
+    return;
+  }
+
+  // Local catalogue
+  const catalogue = await readCatalogue();
+  const harness = findHarness(name, catalogue);
+  if (!harness) {
+    const available = catalogue.map((h) => h.name).join(", ") || "(none)";
+    display(pi, `Distro '${name}' not found. Available: ${available}`);
+    return;
+  }
+  display(pi, await buildShowPreview(harness));
+}

package/extensions/undeploy.ts

@@ -0,0 +1,124 @@
+/**
+ * `/pi-distro undeploy` — remove an applied distro from the current project
+ * (the reverse of deploy).
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { parseProvenance, parsePackageList } from "./catalogue.ts";
+import { extractBody } from "./frontmatter.ts";
+import { readProjectPackages, USER_INVOLVEMENT_RULE } from "./util.ts";
+
+export async function handleUndeploy(pi: ExtensionAPI, ctx: ExtensionCommandContext): Promise<void> {
+  const snapshot = ctx.getSystemPromptOptions();
+  const cwd = snapshot.cwd;
+  const provenancePath = join(cwd, ".pi", "harness.md");
+  if (!existsSync(provenancePath)) {
+    ctx.ui.notify("No distro applied in this project. (Nothing to undeploy.)", "warning");
+    return;
+  }
+  const provContent = readFileSync(provenancePath, "utf-8");
+  const prov = parseProvenance(provContent);
+  if (!prov) {
+    ctx.ui.notify("Could not parse provenance in .pi/harness.md.", "error");
+    return;
+  }
+
+  // The provenance file contains the full directives body (after the provenance header).
+  // Reuse it to identify what the distro intended to install.
+  const directives = extractBody(provContent);
+  const packages = parsePackageList(directives);
+
+  // Read current project state to compare against the distro's directives.
+  const installedPackages = readProjectPackages(cwd);
+
+  // Which of the distro's packages are still installed?
+  const distroPackagesInstalled = packages.filter((p) => installedPackages.includes(p));
+  const distroPackagesMissing = packages.filter((p) => !installedPackages.includes(p));
+
+  // Check for the AGENTS.md delimited section.
+  const agentsMdPath = join(cwd, "AGENTS.md");
+  let agentsMdSection = "not present";
+  if (existsSync(agentsMdPath)) {
+    const content = readFileSync(agentsMdPath, "utf-8");
+    if (content.includes(`<!-- pi-distro: ${prov.appliedHarness} -->`)) {
+      agentsMdSection = "present";
+    } else {
+      agentsMdSection = "not found (already removed or never added)";
+    }
+  }
+
+  const activeTools = snapshot.selectedTools?.length
+    ? snapshot.selectedTools.map((t) => `- \`${t}\``).join("\n")
+    : "_(none / default set)_";
+
+  const packageList = distroPackagesInstalled.length > 0
+    ? distroPackagesInstalled.map((p) => `- \`${p}\` — installed (can be removed with \`pi remove -l\`)`).join("\n")
+    : "_(none of the distro's packages are currently installed)_";
+  const missingNote = distroPackagesMissing.length > 0
+    ? `\n\n**Packages from this distro not currently installed (already removed):**\n${distroPackagesMissing.map((p) => `- \`${p}\``).join("\n")}`
+    : "";
+
+  pi.sendUserMessage(`## Undeploying distro: ${prov.appliedHarness} (v${prov.appliedVersion})
+
+The user wants to **remove** the applied distro from this project. This is the reverse of
+\`/pi-distro deploy\`. Walk them through removing each component, asking at every step —
+never silently delete anything. Provenance records the distro's *intentions* (directives),
+not the exact outcome of the interactive deploy, so you must compare the directives against
+the *current* project state and let the user decide what to remove.
+
+### Distro directives (for reference — what was intended to be applied)
+${directives}
+
+### Current project state
+**Distro packages still installed in this project (${distroPackagesInstalled.length} of ${packages.length}):**
+${packageList}${missingNote}
+
+**AGENTS.md delimited section:** ${agentsMdSection}
+
+**Active tools in this session:**
+${activeTools}
+
+**Installed packages in .pi/settings.json:**
+${installedPackages.length > 0 ? installedPackages.map((p) => `- \`${p}\``).join("\n") : "_(none)_"}
+
+### Removal procedure (follow exactly, collaborating with the user)
+
+**0. User involvement rule** — ${USER_INVOLVEMENT_RULE} This is especially critical here:
+removal is destructive. Never silently delete a file, remove a package, or strip a settings
+key. The user may have customized files after deploy, or may want to keep some components.
+
+**1. Walk the user through each removal category, one at a time:**
+
+   **(a) Packages** — for each distro package still installed, offer to remove it with
+   \`pi remove -l <pkg>\`. **Ask per package** — the user may want to keep some. Warn if
+   removing a package that other components depend on (e.g. if an extension relies on a
+   package's theme). If the user skips a package, note it.
+
+   **(b) Bundled files** — the directives list bundled files (e.g. \`AGENTS.md\`,
+   \`settings.json\`, \`extensions/claude-statusline.ts\`). For each, check if the file exists
+   in the project. If it does, **show the user the file (or a summary) before removing** —
+   they may have customized it and want to keep it. Offer: remove / keep. Never silently
+   delete. For \`settings.json\`, offer to remove specific keys the distro merged (e.g.
+   \`theme\`, \`defaultThinkingLevel\`) rather than deleting the whole file — and warn about
+   user customizations.
+
+   **(c) AGENTS.md delimited section** — if the \`<!-- pi-distro: ${prov.appliedHarness} -->\` ...
+   \`<!-- /pi-distro: ${prov.appliedHarness} -->\` block exists, offer to remove it. If the
+   user has a standalone (non-delimited) AGENTS.md that wasn't added by the distro, leave it.
+
+   **(d) Extensions / skills / prompts / themes** — if the directives describe these and they
+   exist in the project, offer to remove each (with the same show-before-delete rule).
+
+**2. Remove provenance last.** Only after the user has confirmed the component removals,
+   remove \`./.pi/harness.md\` (the provenance file). Confirm with the user before deleting it.
+
+**3. Report and recommend a restart.** Summarise what was removed and what was kept (the user
+   may have chosen to keep some components). Tell the user to **restart pi** — removed packages
+   and extensions won't fully unload until the next session start.`);
+}

package/extensions/update.ts

@@ -0,0 +1,109 @@
+/**
+ * `/pi-distro update` — upgrade the applied distro if a newer version exists.
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { parseProvenance } from "./catalogue.ts";
+import type { HarnessEntry } from "./catalogue.ts";
+import { parseGithubRef, fetchGithubDistro } from "./github.ts";
+import { resolveCatalogueEntry } from "./resolve.ts";
+import { buildShowPreview } from "./show.ts";
+import { sendDeployKickoff } from "./deploy.ts";
+import { display, compareVersions } from "./util.ts";
+
+export async function handleUpdate(pi: ExtensionAPI, ctx: ExtensionCommandContext): Promise<void> {
+  // 1. Read provenance to find the applied distro.
+  const snapshot = ctx.getSystemPromptOptions();
+  const cwd = snapshot.cwd;
+  const provenancePath = join(cwd, ".pi", "harness.md");
+  if (!existsSync(provenancePath)) {
+    ctx.ui.notify("No distro applied in this project. Run /pi-distro deploy <name> first.", "warning");
+    return;
+  }
+  const prov = parseProvenance(readFileSync(provenancePath, "utf-8"));
+  if (!prov) {
+    ctx.ui.notify("Could not parse provenance in .pi/harness.md.", "error");
+    return;
+  }
+
+  // 2. Resolve the current version from the source.
+  const source = prov.sourceCatalogue;
+  let current: HarnessEntry | undefined;
+  let fetchedCleanup: (() => void) | undefined;
+
+  if (source.startsWith("github:")) {
+    // GitHub source: re-fetch to get the latest.
+    const refStr = source.slice("github:".length);
+    const ref = parseGithubRef(refStr);
+    if (!ref) {
+      ctx.ui.notify(`Could not parse GitHub source '${refStr}' from provenance.`, "error");
+      return;
+    }
+    ctx.ui.notify(`Fetching ${ref.displayRef} from GitHub to check for updates…`, "info");
+    try {
+      const fetched = fetchGithubDistro(ref);
+      current = fetched.entry;
+      fetchedCleanup = fetched.cleanup;
+    } catch (err) {
+      ctx.ui.notify(err instanceof Error ? err.message : String(err), "error");
+      return;
+    }
+  } else {
+    // Local catalogue (seed or user).
+    current = await resolveCatalogueEntry(prov.appliedHarness);
+    if (!current) {
+      ctx.ui.notify(
+        `Distro '${prov.appliedHarness}' is no longer in the catalogue (it may have been removed or renamed). Applied version was v${prov.appliedVersion}.`,
+        "warning",
+      );
+      return;
+    }
+  }
+
+  // 3. Compare versions.
+  const cmp = compareVersions(current.version, prov.appliedVersion);
+  if (cmp === 0) {
+    if (fetchedCleanup) fetchedCleanup();
+    ctx.ui.notify(
+      `Already up to date: ${prov.appliedHarness} v${prov.appliedVersion}. To force a re-deploy, run /pi-distro deploy ${prov.appliedHarness}.`,
+      "info",
+    );
+    return;
+  }
+
+  const direction = cmp > 0 ? "upgrade" : "downgrade";
+  if (direction === "downgrade") {
+    if (fetchedCleanup) fetchedCleanup();
+    ctx.ui.notify(
+      `Downgrade warning: ${prov.appliedHarness} is at v${prov.appliedVersion} in this project, but the catalogue has v${current.version} (older). Updates are for moving to a newer version. To downgrade, run /pi-distro deploy ${prov.appliedHarness} and confirm.`,
+      "warning",
+    );
+    return;
+  }
+
+  // 4. Upgrade available — surface it and ask the user before proceeding.
+  const preview = await buildShowPreview(current);
+  display(pi, `## Update available
+
+${preview}`);
+
+  const confirmed = await ctx.ui.confirm(
+    "Apply the update?",
+    `An update is available for ${prov.appliedHarness}: v${prov.appliedVersion} → v${current!.version}. This will re-deploy the distro (merge-don't-clobber; your existing config and customisations are preserved). Proceed?`,
+  );
+  if (!confirmed) {
+    if (fetchedCleanup) fetchedCleanup();
+    ctx.ui.notify("Update cancelled.", "info");
+    return;
+  }
+
+  // 5. Run the standard deploy (carries the version note, merge rule, user-involvement rule, etc.).
+  await sendDeployKickoff(pi, ctx, current!);
+  // GitHub temp dir left in /tmp for the agent to read bundled files (ephemeral).
+}

package/extensions/util.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared helpers and rule strings for the pi-distro command handlers.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+/** Display markdown content in the TUI as a custom message (no LLM turn). */
+export function display(pi: ExtensionAPI, content: string): void {
+  pi.sendMessage({ customType: "pi-distro", content, display: true });
+}
+
+/** Compare two semver-ish version strings. Returns >0 if a>b, <0 if a<b, 0 if equal. */
+export function compareVersions(a: string, b: string): number {
+  const pa = (a || "0").split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = (b || "0").split(".").map((n) => parseInt(n, 10) || 0);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const va = pa[i] ?? 0;
+    const vb = pb[i] ?? 0;
+    if (va !== vb) return va - vb;
+  }
+  return 0;
+}
+
+/** Read the packages array from <cwd>/.pi/settings.json, normalised to source strings. */
+export function readProjectPackages(cwd: string): string[] {
+  const settingsPath = join(cwd, ".pi", "settings.json");
+  if (!existsSync(settingsPath)) return [];
+  try {
+    const s = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    if (!Array.isArray(s.packages)) return [];
+    return s.packages.map((p: string | { source: string }) => (typeof p === "string" ? p : p.source));
+  } catch {
+    return [];
+  }
+}
+
+export const MERGE_RULE = `**Merge, don't clobber.** For any target file that already exists, do not overwrite silently — show a diff and ask the user whether to overwrite, keep theirs, or merge. Merge JSON settings field-by-field. Append AGENTS.md content under a delimited section. Install pi packages with \`pi install -l\` (project-local) only after confirming with the user; do NOT pre-add packages to ./.pi/settings.json by hand — \`pi install -l\` registers them on success (and leaves settings untouched on failure).`;
+
+export const USER_INVOLVEMENT_RULE = `**The user is in the loop for every decision.** pi-distro is a collaborative, agent-driven tool — never make a state-changing decision for the user. Before overwriting a file, installing a package, skipping a step, replacing a tool, applying an upgrade, or resolving any conflict (merge, redundancy, version downgrade, etc.), the agent must (1) surface the decision clearly (what it's about to do and why), (2) present the available options, and (3) wait for the user's explicit choice. Never silently skip, silently overwrite, silently substitute, or proceed on assumption. If a decision is ambiguous or the user is unsure, explain the tradeoffs and let them choose. The agent proposes; the user disposes.`;
+
+export const PACKAGE_CONFLICT_RULE = `**Evaluate tool redundancy/conflicts before installing.** When you install a distro's packages, some may provide tools that overlap with already-active tools — either an **exact name collision** (two tools with the same name) or **semantic redundancy** (different names, but doing very similar things, e.g. two web-search tools, two browser tools, two todo tools). pi handles exact name collisions by load order (project-local tools shadow global ones; the conflict is a non-fatal diagnostic, not a fatal error — pi still starts), but redundancy leaves the user with duplicate capability and a confusing tool set. Before installing each package, the **agent must evaluate** whether its purpose overlaps an already-active tool (read the already-active tools and project packages above, and run \`pi list\` to see globally-installed packages). If redundancy or a conflict is detected, do NOT install blindly — present the user a choice: (a) **skip** installing it (the capability already exists); (b) **replace** — \`pi remove -l <old>\` the overlapping package then \`pi install -l <new>\`; (c) **keep both** — install it anyway (e.g. the user prefers the new tool, or they serve subtly different purposes); (d) **cancel**. Only proceed with the user's choice.`;

package/harnesses/minimal/README.md

@@ -0,0 +1,21 @@
+# minimal
+
+A clean starting point for any project. Drops in a basic `AGENTS.md` and a sensible
+`.pi/settings.json` — nothing more, nothing less.
+
+## What it sets up
+
+- **`AGENTS.md`** — a minimal explore-before-acting methodology: investigate before
+  implementing, make surgical changes, keep solutions simple.
+- **`.pi/settings.json`** — a sensible default thinking level (pi's default
+  one-at-a-time steering already applies).
+
+No pi packages are installed. Use this as a blank canvas — tailor the `AGENTS.md` to your
+project's build/test commands and conventions, then layer on packages and skills as you go.
+
+## When to use
+
+- You want a clean baseline without opinions about which packages to install.
+- You're starting a new project and just want the agent oriented with good defaults.
+- You want to build your own distro from a minimal starting point (deploy this, then
+  `/pi-distro save` after customizing).

package/harnesses/minimal/files/AGENTS.md

@@ -0,0 +1,20 @@
+# Project Instructions
+
+Brief guidance for working in this project. Add your own rules below.
+
+## Build & Test Commands
+
+<!-- e.g. npm run build, npm test, npm run lint -->
+- Build:
+- Test:
+- Lint:
+
+## Code Style
+
+<!-- e.g. use TypeScript, 2-space indent, prefer named exports -->
+-
+
+## Project Structure Notes
+
+<!-- e.g. src/ for source, tests/ for tests, docs/ for documentation -->
+-

package/harnesses/minimal/files/settings.json

@@ -0,0 +1,4 @@
+{
+  "packages": [],
+  "defaultThinkingLevel": "medium"
+}

package/harnesses/minimal/harness.md

@@ -0,0 +1,24 @@
+---
+name: minimal
+title: Minimal
+description: Clean starting point: a basic AGENTS.md and .pi/settings.json.
+version: 0.1.0
+---
+
+# Minimal
+
+## Bundled files
+The following bundled files are provided under `files/` and should be placed into the
+target project. For any path that already exists, do NOT overwrite — show the user a diff
+and ask whether to overwrite, keep theirs, or merge. Merge JSON settings objects field by
+field. Append (not replace) `AGENTS.md` content under a clearly-delimited section.
+
+- `files/AGENTS.md` → `./AGENTS.md`
+- `files/settings.json` → `./.pi/settings.json` (merge with existing settings)
+
+## Context
+This harness provides a minimal starting point for any project. After placing the bundled
+files, ensure the `AGENTS.md` is tailored to the project's actual build/test commands and
+conventions. The `settings.json` sets a sensible default thinking level — adjust as needed.
+
+No additional pi packages are required for this harness.