@msdavid/pi-distro 0.2.0

package/docs/authoring.md

@@ -0,0 +1,238 @@
+# Authoring a Distro
+
+A **distro** is a directory containing a `harness.md` file and an optional `files/`
+directory. Distros are reusable pi configurations that can be deployed into any
+project via `/pi-distro deploy` (from the local catalogue or GitHub), and live
+projects can be snapshotted back into distros via `/pi-distro save`.
+
+## Sharing distros via GitHub
+
+Any GitHub repository containing a `harness.md` (and optional `files/`) at the root
+or under a subpath can be deployed directly:
+
+```
+/pi-distro show owner/repo            # preview before deploying
+/pi-distro deploy owner/repo           # deploy from repo root
+/pi-distro deploy owner/repo/my-distro # deploy from a subpath
+```
+
+The extension shallow-clones the repo (`git clone --depth 1`), displays a security
+warning + full preview, and requires explicit confirmation before proceeding. This
+makes it easy to share distros — just push a repo with a `harness.md` and `files/`.
+
+When authoring a distro intended for GitHub sharing, include a `README.md` so users
+can understand what the distro does before deploying it.
+
+## Directory layout
+
+```
+<name>/
+├── harness.md                  # REQUIRED: frontmatter + directives
+├── README.md                   # RECOMMENDED: extended human-readable description
+└── files/                      # OPTIONAL: bundled files deployed into the target
+    ├── AGENTS.md
+    ├── settings.json           # becomes ./.pi/settings.json (merged, not overwritten)
+    ├── .pi/
+    │   ├── extensions/
+    │   │   └── hooks.ts        # "hooks" are just extensions
+    │   ├── prompts/
+    │   │   └── review.md
+    │   └── skills/
+    │       └── …/SKILL.md
+    └── …
+```
+
+The directory name **must match** the `name` field in the frontmatter.
+
+## README.md (recommended)
+
+Each distro should include a `README.md` alongside `harness.md`. While the frontmatter
+`description` is a one-liner (≤300 chars) shown in selectors and listings, the README is
+the extended human-readable description: a few paragraphs covering what the distro sets
+up, which packages it installs and why, what workflow it targets, and any prerequisites.
+
+The README is for users browsing the catalogue or reading the distro on disk. It is **not**
+consumed by the extension and is **not** copied into the target project on deploy — it
+lives only in the catalogue.
+
+When you run `/pi-distro save`, the agent writes a `README.md` for the new distro as part
+of the authoring flow. If you author a distro by hand, include one too.
+
+## Frontmatter fields
+
+The frontmatter is YAML between `---` fences at the top of `harness.md`.
+
+| Field         | Required | Description                                                        |
+|---------------|----------|--------------------------------------------------------------------|
+| `name`        | Yes      | Unique slug. Lowercase a-z/0-9/hyphens. Must match the directory name. |
+| `title`       | Yes      | Human-readable title (shown in the selector).                     |
+| `description` | Yes      | One-liner shown in the selector. ≤300 characters.                  |
+| `version`     | Yes      | Semantic version (e.g. `1.0.0`, `0.1.0`). Bump on every update (see below). |
+| `author`      | No       | Author name or handle.                                             |
+| `tags`        | No       | Array of tags for categorisation (e.g. `[web, react, node]`).      |
+
+Example:
+
+```yaml
+---
+name: my-distro
+title: My Distro
+description: >
+  A concise description of what this distro configures.
+version: 1.0.0
+author: Jane Doe
+tags: [api, backend]
+---
+```
+
+## Bundled `files/` directory
+
+The `files/` directory contains files that are deployed into the target project
+verbatim. The directory structure inside `files/` mirrors the target project layout:
+
+| Source in `files/`                     | Target in project                |
+|----------------------------------------|----------------------------------|
+| `files/AGENTS.md`                      | `./AGENTS.md`                    |
+| `files/settings.json`                  | `./.pi/settings.json`            |
+| `files/.pi/extensions/hooks.ts`        | `./.pi/extensions/hooks.ts`      |
+| `files/.pi/prompts/review.md`          | `./.pi/prompts/review.md`        |
+| `files/.pi/skills/my-skill/SKILL.md`   | `./.pi/skills/my-skill/SKILL.md` |
+
+The `harness.md` body should include a **Bundled files** section that lists each file
+and its target path, so the agent knows what to deploy.
+
+## Directive conventions
+
+The body of `harness.md` (after the frontmatter) is agent-readable prose instructing
+the agent how to set up the project. Use structured sections:
+
+> **Authoring for `/pi-distro pick`:** since users may pick individual components from your
+> distro, it helps to keep components as independent as possible and to state dependencies
+> explicitly in the directives prose (e.g. "this extension requires the `pi-crew` package
+> for its theme"). The agent uses these notes to warn users during a partial deploy.
+
+### `## Bundled files`
+
+List each bundled file with its target path and any merge instructions. This is the
+manifest the agent uses during `deploy`.
+
+```markdown
+## Bundled files
+- `files/AGENTS.md` → `./AGENTS.md`
+- `files/settings.json` → `./.pi/settings.json` (merge with existing settings)
+```
+
+### `## 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.
+
+```markdown
+## pi packages to install
+- `npm:pi-browse` — for web search and content extraction
+```
+
+### `## Hooks`
+
+Describe extensions/hooks to create under `./.pi/extensions/`. These are bundled as
+files (e.g. `files/.pi/extensions/hooks.ts`) or described as instructions for the agent
+to write.
+
+### `## Context`
+
+Describe what context to write or configure. This may reference the bundled
+`AGENTS.md` or instruct the agent to create project-specific context.
+
+### `## Skills / prompts`
+
+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.
+
+## Merge-don't-clobber expectations
+
+When a distro is deployed via `/pi-distro deploy`, **existing files are never
+silently overwritten**. The agent:
+
+1. Checks if each target file already exists.
+2. If it does, shows the user a diff (or summary of differences).
+3. Asks the user whether to **overwrite**, **keep theirs**, or **merge**.
+4. For JSON files (e.g. `settings.json`): merges field-by-field when the user chooses
+   merge — combining keys from both objects without destroying user customisations.
+5. For `AGENTS.md`: appends bundled content under a delimited section rather than
+   replacing. If the section already exists (re-deploy), replaces only that section.
+
+This ensures distros compose with existing configurations rather than clobbering
+them.
+
+## Provenance file format
+
+Every project that has had a distro applied carries a provenance file at
+`./.pi/harness.md`. This file is itself a valid `harness.md` (the applied distro's
+frontmatter + directives) with a provenance header injected at the top of the body:
+
+```markdown
+<!-- pi-distro provenance
+     appliedHarness: <name>
+     appliedVersion: <version>
+     sourceCatalogue: <user|seed|none>
+     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/`).
+- `lastUpdated`: ISO 8601 timestamp of the last apply/save.
+
+The provenance file is updated automatically by the `deploy`, `save`, and `undeploy`
+commands. When `/pi-distro save` snapshots a project, the provenance file is
+regenerated to reflect the current live config.
+
+## Saving a live config as a distro
+
+To capture your current project's pi configuration as a reusable distro:
+
+1. Run `/pi-distro save` in the project.
+2. The extension captures a live snapshot (tools, skills, context files, raw config
+   files) and asks the agent to draft a `harness.md` that reproduces the configuration.
+3. Review the draft — the agent proposes a `name`, `title`, `description`, and the
+   directive sections. Confirm or request edits.
+4. Choose **save as new** (prompts for a name, creates `~/.pi/harnesses/<name>/`) or
+   **update existing** (selects from your user distros, backs up the old version to
+   `~/.pi/harnesses/.trash/` before overwriting, and **bumps the version** — see below).
+5. The extension writes `harness.md` + `files/` to `~/.pi/harnesses/<name>/` and
+   updates `./.pi/harness.md` provenance.
+
+### Versioning
+
+The `version` field tracks which revision of a distro is applied. Two places use it:
+
+- **On deploy**, the extension compares the incoming version against the project's existing
+  provenance (`appliedVersion`) and includes a version note: **upgrade** (proceed normally),
+  **downgrade** (asks the user to confirm — may regress features), **same version** (asks
+  whether to skip or force re-deploy), or **different distro** (treat as a distro switch).
+- **On save-update**, the agent bumps the version using semver:
+  - **patch** (`0.1.0` → `0.1.1`) — small tweaks, bug fixes, doc updates.
+  - **minor** (`0.1.0` → `0.2.0`) — new capabilities, added packages, config additions.
+  - **major** (`0.1.0` → `1.0.0`) — breaking changes (removed packages, changed conventions,
+    incompatible settings).
+
+Never keep the same version when updating a distro — the version should always reflect
+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.
+
+The saved distro is immediately available in `/pi-distro list` and can be deployed
+into other projects with `/pi-distro deploy`.

package/docs/preview.svg

@@ -0,0 +1,58 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="720" viewBox="0 0 1280 720" font-family="sans-serif">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#15161c"/>
+      <stop offset="1" stop-color="#0c0d12"/>
+    </linearGradient>
+    <linearGradient id="accent" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#7c9eff"/>
+      <stop offset="1" stop-color="#5b7cff"/>
+    </linearGradient>
+  </defs>
+
+  <rect width="1280" height="720" fill="url(#bg)"/>
+
+  <!-- subtle grid -->
+  <g stroke="#ffffff" stroke-opacity="0.03" stroke-width="1">
+    <line x1="0" y1="180" x2="1280" y2="180"/>
+    <line x1="0" y1="360" x2="1280" y2="360"/>
+    <line x1="0" y1="540" x2="1280" y2="540"/>
+    <line x1="320" y1="0" x2="320" y2="720"/>
+    <line x1="640" y1="0" x2="640" y2="720"/>
+    <line x1="960" y1="0" x2="960" y2="720"/>
+  </g>
+
+  <!-- left accent bar -->
+  <rect x="0" y="0" width="8" height="720" fill="url(#accent)"/>
+
+  <!-- pi-package badge -->
+  <g transform="translate(1040,72)">
+    <rect width="168" height="44" rx="22" fill="#ffffff" fill-opacity="0.06" stroke="#ffffff" stroke-opacity="0.12"/>
+    <text x="84" y="29" text-anchor="middle" font-size="18" font-weight="600" fill="#9fb2ff">pi-package</text>
+  </g>
+
+  <!-- title -->
+  <text x="120" y="312" font-size="92" font-weight="700" fill="#f4f5fb" letter-spacing="-2">pi-distro</text>
+
+  <!-- tagline -->
+  <text x="124" y="372" font-size="30" fill="#a6accc">Reusable, composable configurations for the pi coding agent.</text>
+
+  <!-- command chips -->
+  <g font-family="monospace" font-size="24" fill="#d7dcf2">
+    <g transform="translate(120,440)">
+      <rect width="290" height="56" rx="12" fill="#ffffff" fill-opacity="0.05" stroke="#ffffff" stroke-opacity="0.1"/>
+      <text x="20" y="37">/pi-distro deploy</text>
+    </g>
+    <g transform="translate(430,440)">
+      <rect width="250" height="56" rx="12" fill="#ffffff" fill-opacity="0.05" stroke="#ffffff" stroke-opacity="0.1"/>
+      <text x="20" y="37">/pi-distro save</text>
+    </g>
+    <g transform="translate(700,440)">
+      <rect width="250" height="56" rx="12" fill="#ffffff" fill-opacity="0.05" stroke="#ffffff" stroke-opacity="0.1"/>
+      <text x="20" y="37">/pi-distro pick</text>
+    </g>
+  </g>
+
+  <!-- footer hint -->
+  <text x="120" y="640" font-size="20" fill="#6b7088">Seed distros · user snapshots · GitHub sharing · version-aware updates</text>
+</svg>

package/extensions/catalogue.ts

@@ -0,0 +1,221 @@
+/**
+ * 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.
+ */
+
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join, dirname, relative } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { parseFrontmatter, extractBody } from "./frontmatter.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;
+  filesDir?: string;
+}
+
+export interface BundledFile {
+  source: string;
+  target: string;
+}
+
+/** Parse pi package references (npm:...) from a directives body. */
+export function parsePackageList(body: string): string[] {
+  const packages: string[] = [];
+  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]);
+    }
+  }
+  return packages;
+}
+
+export interface Provenance {
+  appliedHarness: string;
+  appliedVersion: string;
+  sourceCatalogue: string;
+  lastUpdated: string;
+}
+
+/** Parse the provenance header from a harness.md content. */
+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). */
+export function getCatalogueNamesSync(): string[] {
+  const names: string[] = [];
+  for (const dir of [getSeedHarnessesDir(), getUserHarnessesDir()]) {
+    if (!existsSync(dir)) continue;
+    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);
+        }
+      }
+    } catch { /* ignore */ }
+  }
+  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.
+ * On name collision, user takes precedence.
+ * Returns sorted: seeds first (alphabetical), then user (alphabetical).
+ */
+export async function readCatalogue(): Promise<HarnessEntry[]> {
+  const seeds = readHarnessesFromDir(getSeedHarnessesDir(), "seed");
+  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));
+
+  // Sort each group alphabetically
+  filteredSeeds.sort((a, b) => a.name.localeCompare(b.name));
+  users.sort((a, b) => a.name.localeCompare(b.name));
+
+  return [...filteredSeeds, ...users];
+}
+
+/** Find a harness by name in the catalogue. */
+export function findHarness(
+  name: string,
+  catalogue: HarnessEntry[],
+): HarnessEntry | undefined {
+  return catalogue.find((h) => h.name === name);
+}
+
+/**
+ * Walk a files/ directory tree and return relative paths.
+ * source = relative path within files/, target = same relative path in the project.
+ */
+export async function listBundledFiles(
+  filesDir: string,
+): Promise<BundledFile[]> {
+  if (!existsSync(filesDir)) return [];
+  const results: BundledFile[] = [];
+  walkDir(filesDir, filesDir, results);
+  return results.sort((a, b) => a.source.localeCompare(b.source));
+}
+
+/** Read the harness.md body (content after frontmatter). */
+export async function readHarnessBody(harnessMdPath: string): Promise<string> {
+  const content = readFileSync(harnessMdPath, "utf-8");
+  return extractBody(content);
+}
+
+/** Read the full harness.md file content. */
+export async function readFullHarnessMd(harnessMdPath: string): Promise<string> {
+  return readFileSync(harnessMdPath, "utf-8");
+}
+
+// --- Internal helpers ---
+
+function readHarnessesFromDir(
+  dir: string,
+  source: "seed" | "user",
+): HarnessEntry[] {
+  if (!existsSync(dir)) return [];
+
+  let entries: string[];
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && e.name !== ".trash")
+      .map((e) => e.name);
+  } catch {
+    return [];
+  }
+
+  const harnesses: HarnessEntry[] = [];
+  for (const name of entries) {
+    const harnessDir = join(dir, name);
+    const harnessMdPath = join(harnessDir, "harness.md");
+    if (!existsSync(harnessMdPath)) continue;
+
+    try {
+      const content = readFileSync(harnessMdPath, "utf-8");
+      const fm = parseFrontmatter(content);
+      if (!fm?.name) continue;
+
+      const filesDir = join(harnessDir, "files");
+      harnesses.push({
+        name: fm.name,
+        title: fm.title ?? fm.name,
+        description: fm.description ?? "",
+        version: fm.version ?? "0.0.0",
+        source,
+        dir: harnessDir,
+        harnessMdPath,
+        filesDir: existsSync(filesDir) ? filesDir : undefined,
+      });
+    } catch {
+      // Skip unparseable harnesses
+    }
+  }
+  return harnesses;
+}
+
+function walkDir(
+  base: string,
+  current: string,
+  results: BundledFile[],
+): void {
+  let entries;
+  try {
+    entries = readdirSync(current, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const fullPath = join(current, entry.name);
+    if (entry.isDirectory()) {
+      walkDir(base, fullPath, results);
+    } else if (entry.isFile()) {
+      const rel = relative(base, fullPath);
+      results.push({ source: rel, target: rel });
+    }
+  }
+}

package/extensions/deploy.ts

@@ -0,0 +1,141 @@
+/**
+ * `/pi-distro deploy` — apply a distro (local name or GitHub ref) to the project.
+ * sendDeployKickoff() is also reused by `/pi-distro update`.
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import { readFileSync, existsSync } from "node:fs";
+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 { resolveDistro } from "./resolve.ts";
+import { buildShowPreview } from "./show.ts";
+import {
+  display,
+  compareVersions,
+  readProjectPackages,
+  MERGE_RULE,
+  USER_INVOLVEMENT_RULE,
+  PACKAGE_CONFLICT_RULE,
+} from "./util.ts";
+
+/** Build and send the deploy kickoff message for a resolved harness. */
+export async function sendDeployKickoff(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  harness: HarnessEntry,
+): Promise<void> {
+  const body = readFileSync(harness.harnessMdPath, "utf-8");
+  const directives = extractBody(body);
+  const files = harness.filesDir ? await listBundledFiles(harness.filesDir) : [];
+  const fileList = files.length > 0
+    ? files.map((f) => `- \`${f.source}\` → \`./${f.target}\``).join("\n")
+    : "_(no bundled files)_";
+  const filesDirNote = harness.filesDir ? `\n\nBundled files are located at: \`${harness.filesDir}\`` : "";
+
+  const snapshot = ctx.getSystemPromptOptions();
+  const activeTools = snapshot.selectedTools?.length
+    ? snapshot.selectedTools.map((t) => `- \`${t}\``).join("\n")
+    : "_(none / default set)_";
+  const pkgs = readProjectPackages(snapshot.cwd);
+  const projectPackages = pkgs.length > 0 ? pkgs.map((p) => `- \`${p}\``).join("\n") : "_(none)_";
+
+  // Version comparison against existing provenance (upgrade / downgrade / same / first deploy)
+  const provenancePath = join(snapshot.cwd, ".pi", "harness.md");
+  let versionNote = "";
+  if (existsSync(provenancePath)) {
+    const prov = parseProvenance(readFileSync(provenancePath, "utf-8"));
+    if (prov) {
+      if (prov.appliedHarness !== harness.name) {
+        versionNote = `### Version note\nThis project currently has distro **${prov.appliedHarness}** (v${prov.appliedVersion}) applied. You are now deploying **${harness.name}** (v${harness.version}) — a different distro. The agent should treat this as a distro switch (merge with existing config; do not assume the new distro's files are a superset of the old).`;
+      } else {
+        const cmp = compareVersions(harness.version, prov.appliedVersion);
+        if (cmp > 0) {
+          versionNote = `### Version note\n**Upgrading** ${prov.appliedHarness}: v${prov.appliedVersion} → v${harness.version}. Re-apply the distro (merge-don't-clobber still applies — existing user customisations should be preserved).`;
+        } else if (cmp < 0) {
+          versionNote = `### Version note\n**Downgrade warning:** the project has v${prov.appliedVersion} of ${harness.name} applied, but you are deploying v${harness.version} (an older version). Ask the user to confirm before proceeding — this may remove features or regress fixes. If they confirm, proceed with merge-don't-clobber.`;
+        } else {
+          versionNote = `### Version note\n**Same version** (v${harness.version}) is already applied. Ask the user whether to (a) skip (no changes — the project already has this exact distro) or (b) force re-deploy (re-run the merge, useful if files were manually edited or the distro was updated in-place). Only proceed if they choose (b).`;
+        }
+      }
+    }
+  } else {
+    versionNote = `### Version note\nFirst deploy of distro **${harness.name}** (v${harness.version}) in this project — no existing provenance found.`;
+  }
+
+  pi.sendUserMessage(`## Deploying distro: ${harness.name} (v${harness.version})
+
+### Directives
+${directives}
+
+### Bundled files manifest
+${fileList}${filesDirNote}
+
+### Current project state (for conflict detection)
+**Already-active tools in this session:**
+${activeTools}
+
+**Packages already in this project's .pi/settings.json:**
+${projectPackages}
+
+(Run \`pi list\` to also see globally-installed packages.)
+
+${versionNote}
+
+### User involvement rule
+${USER_INVOLVEMENT_RULE}
+
+### Merge rule
+${MERGE_RULE}
+
+### Package-conflict rule
+${PACKAGE_CONFLICT_RULE}
+
+### Provenance
+When finished, write or update \`./.pi/harness.md\` provenance with:
+\`\`\`
+<!-- pi-distro provenance
+     appliedHarness: ${harness.name}
+     appliedVersion: ${harness.version}
+     sourceCatalogue: ${harness.source}
+     lastUpdated: ${new Date().toISOString()}
+-->
+\`\`\`
+Place this provenance header at the top of the body, followed by the harness.md directives.
+
+### Post-deploy
+After all files are placed, packages installed, and provenance written, tell the user:
+"Distro **${harness.name}** deployed. **Restart pi** to activate newly-installed packages and extensions." A restart is required because pi loads extensions and packages at startup — newly installed ones are not available until the next session start.`);
+}
+
+export async function handleDeploy(pi: ExtensionAPI, ctx: ExtensionCommandContext, nameArg?: string): Promise<void> {
+  const resolved = await resolveDistro(pi, ctx, nameArg, "deploy");
+  if (!resolved) return;
+  const { entry, cleanup } = resolved;
+
+  // GitHub trust gate (local distros are trusted by being in the catalogue).
+  if (cleanup) {
+    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.`;
+    display(pi, preview + warning);
+    const confirmed = await ctx.ui.confirm(
+      "Deploy from GitHub?",
+      `This will install the distro \`${entry.name}\` from \`${ref.displayRef}\`. It may install packages and write files to your project. Only proceed if you trust this source and have reviewed the preview above.`,
+    );
+    if (!confirmed) {
+      cleanup();
+      ctx.ui.notify("Deploy cancelled.", "info");
+      return;
+    }
+  }
+
+  await sendDeployKickoff(pi, ctx, entry);
+  // GitHub temp dir left in /tmp for the agent to read bundled files (ephemeral).
+}