claude-plan-review 0.1.0 → 0.2.0

package/README.md

@@ -24,6 +24,9 @@ Git worktrees are scoped separately automatically.
 - 🔀 **Diff** current vs any previous version — **side-by-side or unified** (toggle)
 - ✅ **Approve / request-changes** straight from the UI, fed back to Claude
 - 🗂 Per-worktree scoping; per-project opt-in (only runs where you enable the hook)
+- 📤 **Save a plan to a storage channel** — push the plan markdown to a secret
+  **GitHub Gist** (one gist per project, overwritten on each save; GitHub keeps
+  the gist's revision history). More channels can be added later.
 - ⚡ Tiny, zero-framework UI; Bun server; one dependency (`marked`)
 
 ## Requirements
@@ -32,6 +35,9 @@ Git worktrees are scoped separately automatically.
   tool is plain ESM JavaScript and runs unchanged on both. `init` auto-detects which
   you have (preferring Bun) and writes the matching hook command; override with `--runtime`.
 - Claude Code ≥ 2.1 (verified against 2.1.185)
+- *(Optional, only for saving to a Gist)* the [GitHub CLI](https://cli.github.com)
+  `gh`, logged in (`gh auth login`) with the `gist` scope. The tool reuses your
+  existing `gh` session — it never asks for or stores a token of its own.
 
 ## Setup
 
@@ -54,13 +60,25 @@ any machine — nothing to keep in your repo but the one settings entry.
 ### Option B — from a local clone (for hacking on it)
 
 ```bash
-git clone https://github.com/pavlo-petrychenko/claude-plan-preview-local
+git clone https://github.com/pavlo-petrychenko/claude-plan-review
 cd claude-plan-review
 bun install                                  # or: npm install
 bun  src/cli.js init /path/to/your/project   # …or…
 node src/cli.js init /path/to/your/project   # writes an absolute-path hook command
 ```
 
+### All projects at once (global)
+
+Install once, enable everywhere — the hook goes in your user-level `~/.claude/settings.json`:
+
+```bash
+npm install -g claude-plan-review     # or: bun add -g claude-plan-review
+claude-plan-review init --global
+```
+
+This fires the review for plans in **every** project, with no per-project setup. Don't also
+run a per-project `init` in the same project, or the hook will fire twice.
+
 ### Either way
 
 **Reopen the `/hooks` menu once (or restart Claude Code)** in that project so the
@@ -76,6 +94,7 @@ Use `bun` or `node` interchangeably (or `bunx`/`npx claude-plan-review …` when
 | `… cli.js init [dir] [--local] [--published] [--runtime bun\|node]` | Wire the `ExitPlanMode` hook into a project |
 | `… cli.js serve [port]` | Start the review server manually (default `4607`) |
 | `… cli.js stop` | Stop the running server |
+| `… cli.js channels` | Show storage-channel readiness (is `gh` installed / authed / `gist`-scoped?) |
 
 The server auto-starts on the first plan and stays up, so you can browse history
 anytime at `http://localhost:4607`.
@@ -90,6 +109,28 @@ anytime at `http://localhost:4607`.
 
 > The hook entry sets `timeout: 1800` so Claude Code waits while you review.
 
+## Storage channels (save a plan out of the local store)
+
+Each plan version lives only on your machine by default. A **storage channel**
+lets you push the plan markdown somewhere shareable. Today there's one channel —
+**GitHub Gist** — and the registry is built so more can be added later.
+
+Click **Save to gist** in the header. The first save asks for a description and
+file name and creates a **secret** (unlisted) gist from the version you're
+viewing. There's **one gist per project**: saving any later version overwrites
+that same gist (GitHub keeps the gist's own revision history), and you can rename
+the description/file name on any save. The header then shows a link to the gist
+and which version it currently holds.
+
+Auth is delegated entirely to the GitHub CLI — if you've run `gh auth login`,
+nothing else is needed and **no token is ever stored by this tool**. If `gh`
+isn't installed, isn't logged in, or its token lacks the `gist` scope, the save
+dialog tells you the exact command to fix it (e.g. `gh auth refresh -s gist`).
+Run `claude-plan-review channels` to check readiness from the terminal.
+
+> Note: the Gist API requires a **classic** `gh` token scope (`gist`);
+> fine-grained tokens don't support gists. `gh auth login` handles this for you.
+
 ## How it works
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plan-review",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Review, comment on, and approve/reject Claude Code plans in a local GitHub-style web UI — with persistent comments, version history, and diffs.",
   "type": "module",
   "bin": {
@@ -32,13 +32,13 @@
     "hooks",
     "exitplanmode"
   ],
-  "homepage": "https://github.com/pavlo-petrychenko/claude-plan-preview-local#readme",
+  "homepage": "https://github.com/pavlo-petrychenko/claude-plan-review#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/pavlo-petrychenko/claude-plan-preview-local.git"
+    "url": "git+https://github.com/pavlo-petrychenko/claude-plan-review.git"
   },
   "bugs": {
-    "url": "https://github.com/pavlo-petrychenko/claude-plan-preview-local/issues"
+    "url": "https://github.com/pavlo-petrychenko/claude-plan-review/issues"
   },
   "author": "pavlo.p@mate.academy",
   "license": "MIT"

package/src/channels/gh.js

@@ -0,0 +1,84 @@
+/**
+ * Thin wrapper around the GitHub CLI (`gh`). Runs on Bun or Node ≥18.
+ *
+ * We shell out to `gh` rather than holding our own token: if the user has
+ * already `gh auth login`'d, we store no secrets at all. All request bodies are
+ * piped via STDIN (never argv), so plan content / descriptions can't break
+ * argument parsing.
+ */
+import { spawnSync } from "node:child_process";
+
+function run(args, { input } = {}) {
+  try {
+    const r = spawnSync("gh", args, {
+      input: input ?? undefined,
+      encoding: "utf8",
+      // gh writes `auth status` to stderr; capture both streams.
+    });
+    return {
+      ok: r.status === 0,
+      status: r.status,
+      stdout: r.stdout || "",
+      stderr: r.stderr || "",
+      spawnError: r.error || null,
+    };
+  } catch (e) {
+    return { ok: false, status: null, stdout: "", stderr: "", spawnError: e };
+  }
+}
+
+/** Is `gh` on PATH at all? */
+export function installed() {
+  return run(["--version"]).ok;
+}
+
+/**
+ * Readiness probe: { installed, authed, scopes:[...] }.
+ * `gh auth status` exits non-zero when not logged in; its human output (on
+ * stderr) carries a "Token scopes: 'gist', 'repo', …" line we parse.
+ */
+export function status() {
+  if (!installed()) return { installed: false, authed: false, scopes: [] };
+  const r = run(["auth", "status"]);
+  const text = `${r.stdout}\n${r.stderr}`;
+  const authed = r.ok || /Logged in to/i.test(text);
+  let scopes = [];
+  const m = text.match(/Token scopes:\s*(.+)/i);
+  if (m) {
+    scopes = m[1]
+      .split(",")
+      .map((s) => s.trim().replace(/^['"]|['"]$/g, ""))
+      .filter(Boolean);
+  }
+  return { installed: true, authed, scopes };
+}
+
+/**
+ * Call the GitHub REST API through gh, sending `body` as JSON on stdin.
+ * Returns { ok, data, error, needsGistScope }.
+ */
+export function api(method, path, body) {
+  const args = ["api", "-X", method.toUpperCase(), path];
+  let input;
+  if (body !== undefined) {
+    args.push("--input", "-");
+    input = JSON.stringify(body);
+  }
+  const r = run(args, { input });
+  if (r.ok) {
+    try {
+      return { ok: true, data: JSON.parse(r.stdout || "null") };
+    } catch {
+      return { ok: true, data: null };
+    }
+  }
+  const errText = `${r.stderr}${r.stdout}`.trim();
+  // gh surfaces a "(HTTP 404)"/"(HTTP 403)" + scope hint when the token can't touch gists
+  const needsGistScope =
+    /gist/i.test(errText) && /(scope|HTTP 40[34]|Not Found|requires)/i.test(errText);
+  return {
+    ok: false,
+    error: errText || (r.spawnError ? String(r.spawnError.message || r.spawnError) : "gh failed"),
+    needsGistScope,
+  };
+}

package/src/channels/gist.js

@@ -0,0 +1,97 @@
+/**
+ * GitHub Gist storage channel. Stores the plan markdown (only) in a secret
+ * gist owned by the user's `gh`-authenticated account. One gist per project:
+ * the first save creates it, later saves PATCH the same gist (GitHub keeps the
+ * gist's own revision history automatically).
+ */
+import * as gh from "./gh.js";
+
+export const id = "gist";
+export const label = "GitHub Gist";
+
+const REFRESH_CMD = "gh auth refresh -s gist";
+const LOGIN_CMD = "gh auth login";
+
+/** Readiness for the UI: can we create a gist right now, and if not, how to fix it. */
+export function available() {
+  const s = gh.status();
+  if (!s.installed)
+    return {
+      ready: false,
+      installed: false,
+      authed: false,
+      hasGistScope: false,
+      reason: "GitHub CLI (gh) is not installed.",
+      fixCommand: null,
+      fixUrl: "https://cli.github.com",
+    };
+  if (!s.authed)
+    return {
+      ready: false,
+      installed: true,
+      authed: false,
+      hasGistScope: false,
+      reason: "Not logged in to GitHub.",
+      fixCommand: LOGIN_CMD,
+    };
+  const hasGistScope = s.scopes.includes("gist");
+  return {
+    ready: hasGistScope,
+    installed: true,
+    authed: true,
+    hasGistScope,
+    reason: hasGistScope ? null : "Your gh token is missing the 'gist' scope.",
+    fixCommand: hasGistScope ? null : REFRESH_CMD,
+    scopes: s.scopes,
+  };
+}
+
+function ghError(res) {
+  const e = new Error(
+    res.needsGistScope
+      ? `GitHub rejected the gist write — your gh token likely lacks the 'gist' scope. Run: ${REFRESH_CMD}`
+      : res.error || "gh request failed",
+  );
+  e.fixCommand = res.needsGistScope ? REFRESH_CMD : null;
+  return e;
+}
+
+/** Create a new secret gist. Returns the binding info we persist. */
+export function create({ markdown, description, filename }) {
+  const file = filename || "plan.md";
+  const res = gh.api("POST", "/gists", {
+    description: description || "",
+    public: false,
+    files: { [file]: { content: markdown || "\n" } },
+  });
+  if (!res.ok) throw ghError(res);
+  return {
+    id: res.data.id,
+    htmlUrl: res.data.html_url,
+    filename: file,
+    description: description || "",
+  };
+}
+
+/**
+ * Overwrite an existing gist with new content (and optionally a new
+ * description / filename). `oldFilename` is the name currently in the gist so
+ * we can rename rather than orphan it.
+ */
+export function update({ id: gistId, markdown, description, filename, oldFilename }) {
+  const newName = filename || oldFilename || "plan.md";
+  const fileKey = oldFilename || newName;
+  const filePatch = { content: markdown || "\n" };
+  if (newName !== fileKey) filePatch.filename = newName;
+  const res = gh.api("PATCH", `/gists/${gistId}`, {
+    description: description ?? "",
+    files: { [fileKey]: filePatch },
+  });
+  if (!res.ok) throw ghError(res);
+  return {
+    id: res.data.id,
+    htmlUrl: res.data.html_url,
+    filename: newName,
+    description: res.data.description ?? description ?? "",
+  };
+}

package/src/channels/index.js

@@ -0,0 +1,24 @@
+/**
+ * Storage-channel registry. A channel lets the user push a plan out of the
+ * local store into some shareable location. Gist is the only channel today;
+ * the registry keeps adding more (S3, Drive, …) a matter of dropping in a
+ * module with the same shape.
+ *
+ * Channel contract:
+ *   id, label                         — identity
+ *   available() → { ready, ...flags } — can we use it now, and how to fix it
+ *   create({markdown, description, filename})              → binding info
+ *   update({id, markdown, description, filename, oldFilename}) → binding info
+ */
+import * as gist from "./gist.js";
+
+export const channels = { [gist.id]: gist };
+
+export function getChannel(id) {
+  return channels[id] || null;
+}
+
+/** Readiness of every channel, for the picker / verify UI. */
+export function listChannelStatus() {
+  return Object.values(channels).map((ch) => ({ id: ch.id, label: ch.label, ...ch.available() }));
+}

package/src/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { DEFAULT_PORT, SERVER_FILE } from "./paths.js";
@@ -34,6 +35,14 @@ function chooseRuntime(args) {
 
 function hookCommand(args) {
   const runtime = chooseRuntime(args);
+  // global install → use the bare `claude-plan-review` command (resolved via PATH at hook time).
+  // We intentionally do NOT hardcode an absolute path: version managers like fnm/nvm expose
+  // bins via per-shell paths that don't persist across sessions.
+  if (args.includes("--global")) {
+    if (canRun("claude-plan-review")) return "claude-plan-review hook";
+    // not on PATH → fall back to the package runner
+    return runtime === "node" ? "npx claude-plan-review hook" : "bunx claude-plan-review hook";
+  }
   if (args.includes("--published") || args.includes("--bunx")) {
     // portable command using the runtime's package runner
     return runtime === "node" ? "npx claude-plan-review hook" : "bunx claude-plan-review hook";
@@ -50,10 +59,12 @@ function readJSON(path, fallback) {
 }
 
 function cmdInit(args) {
+  const global = args.includes("--global");
   const local = args.includes("--local");
   const dirArg = args.find((a) => !a.startsWith("--") && a !== chooseRuntime(args));
-  const projectDir = resolve(dirArg || process.cwd());
-  const settingsFile = join(projectDir, ".claude", local ? "settings.local.json" : "settings.json");
+  const settingsFile = global
+    ? join(homedir(), ".claude", "settings.json")
+    : join(resolve(dirArg || process.cwd()), ".claude", local ? "settings.local.json" : "settings.json");
   mkdirSync(dirname(settingsFile), { recursive: true });
 
   const settings = readJSON(settingsFile, {});
@@ -79,7 +90,7 @@ function cmdInit(args) {
   }
   console.log(`\nRuntime: ${chooseRuntime(args)}\nCommand: ${command}`);
   console.log(
-    `\nReopen the /hooks menu once (or restart Claude Code) in this project so the new hook is picked up.\n` +
+    `\nReopen the /hooks menu once (or restart Claude Code) ${global ? "in any project" : "in this project"} so the new hook is picked up.\n` +
       `Then finish a plan in plan mode — your browser will open the review.`,
   );
 }
@@ -91,6 +102,27 @@ async function cmdServe(args) {
   console.log(`Open http://localhost:${port}  (Ctrl+C to stop)`);
 }
 
+async function cmdChannels() {
+  const { listChannelStatus } = await import("./channels/index.js");
+  const list = listChannelStatus();
+  if (!list.length) {
+    console.log("No storage channels registered.");
+    return;
+  }
+  console.log("Storage channels:\n");
+  for (const c of list) {
+    const mark = c.ready ? "✓" : "✗";
+    console.log(`  ${mark} ${c.label} (${c.id})`);
+    if (!c.ready) {
+      if (c.reason) console.log(`      ${c.reason}`);
+      if (c.fixCommand) console.log(`      fix: ${c.fixCommand}`);
+      else if (c.fixUrl) console.log(`      see: ${c.fixUrl}`);
+    } else if (c.scopes) {
+      console.log(`      gh scopes: ${c.scopes.join(", ")}`);
+    }
+  }
+}
+
 function cmdStop() {
   const info = readJSON(SERVER_FILE, null);
   if (!info?.pid) {
@@ -110,14 +142,16 @@ function usage() {
   console.log(`claude-plan-review — review Claude Code plans in your browser (runs on Bun or Node ≥18)
 
 Usage:
-  claude-plan-review init [dir] [--local] [--published] [--runtime bun|node]
-                                  Wire the ExitPlanMode hook into a project.
+  claude-plan-review init [dir] [--global] [--local] [--published] [--runtime bun|node]
+                                  Wire the ExitPlanMode hook into a project (or all projects).
                                   Runtime auto-detects (Bun if installed, else Node).
+                                  --global     → ~/.claude/settings.json (applies to ALL projects)
                                   --local      → .claude/settings.local.json
                                   --published  → portable bunx/npx command (after npm publish)
                                   --runtime    → force a runtime
   claude-plan-review serve [port] Start the review server (default ${DEFAULT_PORT})
   claude-plan-review stop         Stop the running server
+  claude-plan-review channels     Show storage-channel readiness (e.g. gh / gist)
   claude-plan-review hook         (internal) the PreToolUse hook entry
 `);
 }
@@ -133,6 +167,9 @@ switch (sub) {
   case "stop":
     cmdStop();
     break;
+  case "channels":
+    await cmdChannels();
+    break;
   case "hook":
     await import("./hook.js");
     break;

package/src/server.js

@@ -9,6 +9,7 @@ import {
   deleteComment,
   getProjectMeta,
   getReview,
+  getStorage,
   getVersion,
   listComments,
   listProjects,
@@ -16,7 +17,9 @@ import {
   listVersions,
   pruneResolvedReviews,
   resolveReview,
+  setStorage,
 } from "./store.js";
+import { getChannel, listChannelStatus } from "./channels/index.js";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const UI_DIR = join(HERE, "ui");
@@ -115,6 +118,7 @@ async function handleApi(req, res, seg, url) {
 
   if (a === "health") return sendJSON(res, { ok: true });
   if (a === "version") return sendJSON(res, { version: pkg.version });
+  if (a === "channels" && !b) return sendJSON(res, listChannelStatus());
 
   if (a === "projects" && !b) return sendJSON(res, listProjects());
 
@@ -134,6 +138,11 @@ async function handleApi(req, res, seg, url) {
     });
   }
 
+  // /api/projects/:key/storage  → current channel bindings
+  if (a === "projects" && b && c === "storage" && !d) {
+    return sendJSON(res, getStorage(b));
+  }
+
   // /api/projects/:key/versions/:n ...
   if (a === "projects" && b && c === "versions" && d) {
     const key = b;
@@ -162,6 +171,10 @@ async function handleApi(req, res, seg, url) {
     if (e === "comments" && seg[5] && method === "DELETE") {
       return sendJSON(res, { ok: deleteComment(key, n, seg[5]) });
     }
+    // /api/projects/:key/versions/:n/save  (POST) → push this version to a storage channel
+    if (e === "save" && method === "POST") {
+      return await handleSave(req, res, key, n);
+    }
   }
 
   // /api/reviews ...
@@ -181,6 +194,47 @@ async function handleApi(req, res, seg, url) {
   return sendJSON(res, { error: "unknown endpoint" }, 404);
 }
 
+/** POST /api/projects/:key/versions/:n/save — create or overwrite the channel's store. */
+async function handleSave(req, res, key, n) {
+  const body = JSON.parse((await readBody(req)) || "{}");
+  const channelId = body.channel || "gist";
+  const channel = getChannel(channelId);
+  if (!channel) return sendJSON(res, { error: `unknown channel: ${channelId}` }, 400);
+
+  const v = getVersion(key, n);
+  if (!v) return sendJSON(res, { error: "no such version" }, 404);
+
+  const ready = channel.available();
+  if (!ready.ready) {
+    return sendJSON(
+      res,
+      { error: ready.reason || "channel not ready", fixCommand: ready.fixCommand ?? null },
+      409,
+    );
+  }
+
+  const existing = getStorage(key)[channelId];
+  try {
+    const info = existing?.id
+      ? channel.update({
+          id: existing.id,
+          markdown: v.markdown,
+          description: body.description ?? existing.description ?? "",
+          filename: body.filename ?? existing.filename,
+          oldFilename: existing.filename,
+        })
+      : channel.create({
+          markdown: v.markdown,
+          description: body.description ?? "",
+          filename: body.filename,
+        });
+    const saved = setStorage(key, channelId, { ...info, savedVersion: n });
+    return sendJSON(res, { channel: channelId, savedVersion: n, ...saved });
+  } catch (e) {
+    return sendJSON(res, { error: String(e?.message || e), fixCommand: e?.fixCommand ?? null }, 502);
+  }
+}
+
 // run directly: `node src/server.js [port]` (or bun)
 const invokedDirectly =
   process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));

package/src/store.js

@@ -42,6 +42,23 @@ export function getProjectMeta(key) {
   return existsSync(metaPath(key)) ? readJSON(metaPath(key), null) : null;
 }
 
+// ---------- storage-channel bindings ----------
+/** All channel bindings for a project, e.g. { gist: { id, htmlUrl, … } }. */
+export function getStorage(key) {
+  return getProjectMeta(key)?.storage ?? {};
+}
+
+/** Persist (or update) the binding for one channel on a project. */
+export function setStorage(key, channelId, info) {
+  const meta = getProjectMeta(key);
+  if (!meta) return null;
+  meta.storage ??= {};
+  meta.storage[channelId] = { ...meta.storage[channelId], ...info, savedAt: now() };
+  meta.updatedAt = now();
+  writeFileSync(metaPath(key), enc(meta));
+  return meta.storage[channelId];
+}
+
 /**
  * Record a freshly-presented plan. De-dupes by content hash: an identical
  * re-presentation reuses the existing version (and keeps its comments),
@@ -82,6 +99,8 @@ export function recordPlan(opts) {
       updatedAt: now(),
       currentVersion: version,
       latestHash: hash,
+      // carry forward storage-channel bindings — they outlive individual versions
+      storage: meta?.storage ?? {},
     };
   }
   writeFileSync(metaPath(key), enc(meta));

package/src/ui/app.js

@@ -6,7 +6,12 @@ const esc = (s) =>
 
 async function api(path, opts) {
   const res = await fetch(path, opts);
-  if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error || res.statusText);
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    const err = new Error(body.error || res.statusText);
+    err.fixCommand = body.fixCommand ?? null;
+    throw err;
+  }
   return res.status === 204 ? null : res.json();
 }
 
@@ -23,6 +28,8 @@ const state = {
   diffMode: "split",
   sel: { anchor: null, start: null, end: null }, // source line-range selection
   dragging: false,
+  storage: {}, // channel bindings for the current project, e.g. { gist: {...} }
+  channels: [], // channel readiness (loaded when the save modal opens)
 };
 
 function toast(msg) {
@@ -60,6 +67,7 @@ function showEmpty(msg) {
   $("panel-preview").classList.add("active");
   $("preview").innerHTML = `<div class="empty">${esc(msg)}</div>`;
   $("reviewActions").hidden = true;
+  $("saveActions").hidden = true;
 }
 
 async function loadProjects() {
@@ -80,6 +88,7 @@ async function selectProject(key, wantV) {
   $("projectSel").value = key;
   const { versions } = await api(`/api/projects/${encodeURIComponent(key)}`);
   state.versions = versions;
+  state.storage = await api(`/api/projects/${encodeURIComponent(key)}/storage`).catch(() => ({}));
   if (!versions.length) {
     showEmpty("This project has no plan versions yet.");
     return;
@@ -111,6 +120,7 @@ async function loadVersion(n) {
   renderSource();
   renderGeneral();
   updateCommentCount();
+  refreshSaveUI();
   await refreshReview();
   if (state.tab === "diff") loadDiff();
 }
@@ -358,6 +368,112 @@ async function resolve(decision) {
   toast(decision === "approve" ? "Plan approved — Claude will proceed." : "Sent back to Claude with your comments.");
 }
 
+// ---------- storage / save ----------
+function projectName() {
+  return state.projects?.find((p) => p.key === state.key)?.name || "plan";
+}
+
+function refreshSaveUI() {
+  const box = $("saveActions");
+  if (!state.version) {
+    box.hidden = true;
+    return;
+  }
+  box.hidden = false;
+  const g = state.storage?.gist;
+  const btn = $("saveBtn");
+  const link = $("savedLink");
+  if (g?.id) {
+    btn.textContent = state.version === g.savedVersion ? "Update gist" : `Save v${state.version} → gist`;
+    link.hidden = false;
+    link.href = g.htmlUrl;
+    link.textContent = `gist · holds v${g.savedVersion}`;
+  } else {
+    btn.textContent = "Save to gist";
+    link.hidden = true;
+  }
+}
+
+function renderChannelStatus(ch) {
+  const box = $("channelStatus");
+  const confirm = $("saveConfirm");
+  if (!ch) {
+    box.className = "channelStatus warn";
+    box.textContent = "Could not read channel status.";
+    confirm.disabled = true;
+    return;
+  }
+  if (ch.ready) {
+    box.className = "channelStatus ok";
+    box.textContent = "✓ GitHub CLI ready — gist scope present.";
+    confirm.disabled = false;
+  } else {
+    box.className = "channelStatus warn";
+    const cmd = ch.fixCommand ? ` Run:  ${ch.fixCommand}` : ch.fixUrl ? ` See ${ch.fixUrl}` : "";
+    box.textContent = `⚠ ${ch.reason || "Channel not ready."}${cmd}`;
+    confirm.disabled = true;
+  }
+}
+
+async function openSaveModal() {
+  const g = state.storage?.gist;
+  $("saveTitle").textContent = g?.id ? "Update gist" : "Save plan to a gist";
+  $("saveDesc").value = g?.description ?? `${projectName()} — plan`;
+  $("saveFilename").value = g?.filename ?? "plan.md";
+  $("saveHint").textContent = g?.id
+    ? `Overwrites your secret gist (currently holds v${g.savedVersion}) with v${state.version}. GitHub keeps the gist's revision history.`
+    : `Creates a secret (unlisted) gist with v${state.version}'s markdown. Only people with the link can see it.`;
+  $("saveModal").hidden = false;
+
+  const sel = $("saveChannel");
+  $("channelStatus").textContent = "Checking GitHub CLI…";
+  $("channelStatus").className = "channelStatus";
+  $("saveConfirm").disabled = true;
+  try {
+    state.channels = await api("/api/channels");
+  } catch {
+    state.channels = [];
+  }
+  sel.innerHTML = state.channels.map((c) => `<option value="${esc(c.id)}">${esc(c.label)}</option>`).join("");
+  const current = state.channels.find((c) => c.id === (sel.value || "gist")) || state.channels[0];
+  if (current) sel.value = current.id;
+  renderChannelStatus(current);
+}
+
+function closeSaveModal() {
+  $("saveModal").hidden = true;
+}
+
+async function doSave() {
+  const channel = $("saveChannel").value || "gist";
+  const description = $("saveDesc").value.trim();
+  const filename = $("saveFilename").value.trim() || "plan.md";
+  const btn = $("saveConfirm");
+  btn.disabled = true;
+  const prev = btn.textContent;
+  btn.textContent = "Saving…";
+  try {
+    const r = await api(
+      `/api/projects/${encodeURIComponent(state.key)}/versions/${state.version}/save`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ channel, description, filename }),
+      },
+    );
+    state.storage[channel] = r;
+    closeSaveModal();
+    refreshSaveUI();
+    toast(`Saved v${state.version} to ${channel}.`);
+  } catch (e) {
+    // surface the remediation command if the channel handed one back
+    renderChannelStatus({ ready: false, reason: e.message, fixCommand: e.fixCommand });
+  } finally {
+    btn.textContent = prev;
+    btn.disabled = false;
+  }
+}
+
 // ---------- polling (reflect external resolution) ----------
 function pollLoop() {
   setInterval(async () => {
@@ -469,6 +585,12 @@ function wireUI() {
     $("generalInput").value = "";
   };
 
+  $("saveBtn").onclick = () => openSaveModal();
+  $("saveCancel").onclick = () => closeSaveModal();
+  $("saveConfirm").onclick = () => doSave();
+  $("saveChannel").onchange = () =>
+    renderChannelStatus(state.channels.find((c) => c.id === $("saveChannel").value));
+
   $("approveBtn").onclick = () => resolve("approve");
   $("rejectBtn").onclick = () => ($("rejectModal").hidden = false);
   $("rejectCancel").onclick = () => ($("rejectModal").hidden = true);

package/src/ui/index.html

@@ -25,6 +25,10 @@
         <select id="versionSel"></select>
       </label>
     </div>
+    <div class="saveActions" id="saveActions" hidden>
+      <button class="btn" id="saveBtn">Save to gist</button>
+      <a class="savedlink" id="savedLink" href="#" target="_blank" rel="noopener" hidden></a>
+    </div>
     <div class="reviewActions" id="reviewActions" hidden>
       <span class="pill pending" id="reviewPill">● review pending</span>
       <button class="btn approve" id="approveBtn">Approve plan</button>
@@ -87,6 +91,27 @@
     </div>
   </div>
 
+  <div class="saveModal" id="saveModal" hidden>
+    <div class="box">
+      <h3 id="saveTitle">Save plan to a gist</h3>
+      <div class="channelStatus" id="channelStatus"></div>
+      <label class="field">Storage channel
+        <select id="saveChannel"></select>
+      </label>
+      <label class="field">Gist description
+        <input type="text" id="saveDesc" placeholder="Short description shown in your gist list" />
+      </label>
+      <label class="field">File name
+        <input type="text" id="saveFilename" placeholder="plan.md" />
+      </label>
+      <p class="hint" id="saveHint"></p>
+      <div class="row">
+        <button class="btn" id="saveCancel">Cancel</button>
+        <button class="btn primary" id="saveConfirm">Save</button>
+      </div>
+    </div>
+  </div>
+
   <div class="toast" id="toast" hidden></div>
 </div>
 <script src="/app.js"></script>

package/src/ui/style.css

@@ -173,6 +173,25 @@ textarea {
 .rejectModal textarea { width: 100%; min-height: 80px; }
 .rejectModal .row { display: flex; justify-content: flex-end; gap: 10px; margin-top: 12px; }
 
+/* save-to-channel control + modal */
+.saveActions { display: flex; align-items: center; gap: 8px; }
+.savedlink { font-size: 11px; color: var(--fg-muted); font-family: var(--mono); text-decoration: none; white-space: nowrap; }
+.savedlink:hover { color: var(--accent); text-decoration: underline; }
+
+.saveModal { position: fixed; inset: 0; background: #00000066; display: flex; align-items: center; justify-content: center; z-index: 50; }
+.saveModal .box { background: var(--bg); border: 1px solid var(--border); border-radius: 10px; padding: 20px; width: 480px; max-width: 92vw; }
+.saveModal h3 { margin-top: 0; }
+.saveModal .field { display: flex; flex-direction: column; gap: 4px; font-size: 12px; color: var(--fg-muted); margin-bottom: 12px; }
+.saveModal .field input, .saveModal .field select { font-family: var(--sans); font-size: 13px; padding: 6px 8px; border: 1px solid var(--border); border-radius: 6px; background: var(--bg); color: var(--fg); }
+.saveModal .hint { color: var(--fg-muted); font-size: 12px; margin: 4px 0 0; }
+.saveModal .row { display: flex; justify-content: flex-end; gap: 10px; margin-top: 16px; }
+.saveModal .btn.primary { background: var(--accent); border-color: var(--accent); color: #fff; }
+.saveModal .btn.primary:hover { filter: brightness(1.08); }
+.saveModal .btn:disabled { opacity: .5; cursor: not-allowed; filter: none; }
+.channelStatus { font-size: 12px; padding: 8px 10px; border-radius: 6px; margin-bottom: 14px; white-space: pre-wrap; word-break: break-word; }
+.channelStatus.ok { background: var(--green-bg); color: var(--green); }
+.channelStatus.warn { background: #fff8c5; color: #7d4e00; font-family: var(--mono); }
+
 .toast { position: fixed; bottom: 22px; left: 50%; transform: translateX(-50%); background: var(--fg); color: var(--bg);
   padding: 10px 18px; border-radius: 8px; font-size: 13px; z-index: 60; box-shadow: 0 4px 16px #0004; }