@plannotator/pi-extension 0.27.5 → 0.27.7

package/server/serverAnnotate-live.test.ts

@@ -0,0 +1,273 @@
+/**
+ * Annotate server (Pi/Node): live app mode (annotate-app)
+ *
+ * Node mirror of packages/server/annotate.test.ts's "live app mode" describe
+ * block — the same session contract (live /api/plan payload, composed bridge
+ * served by the loopback proxy, per-target draft identity, no version
+ * history, guarded shutdown) over apps/pi-extension/server/serverAnnotate.ts
+ * and the vendored Node live-proxy transport, plus the remote hard-off that
+ * Pi enforces server-side.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { startAnnotateServer } from "./serverAnnotate.ts";
+import { liveAppDraftIdentity } from "../generated/live-proxy-core.ts";
+
+const MINIMAL_HTML = "<html><body>editor</body></html>";
+
+describe("pi annotate server: live app mode (annotate-app)", () => {
+	let savedPort: string | undefined;
+	let savedRemote: string | undefined;
+
+	beforeEach(() => {
+		savedPort = process.env.PLANNOTATOR_PORT;
+		savedRemote = process.env.PLANNOTATOR_REMOTE;
+		delete process.env.PLANNOTATOR_PORT;
+		process.env.PLANNOTATOR_REMOTE = "0";
+	});
+
+	afterEach(() => {
+		if (savedPort === undefined) delete process.env.PLANNOTATOR_PORT;
+		else process.env.PLANNOTATOR_PORT = savedPort;
+		if (savedRemote === undefined) delete process.env.PLANNOTATOR_REMOTE;
+		else process.env.PLANNOTATOR_REMOTE = savedRemote;
+	});
+
+	function startFakeApp() {
+		return Bun.serve({
+			hostname: "127.0.0.1",
+			port: 0,
+			fetch: () =>
+				new Response("<html><head><title>app</title></head><body>app</body></html>", {
+					headers: { "Content-Type": "text/html" },
+				}),
+		});
+	}
+
+	async function startLiveServer(targetUrl: string) {
+		return startAnnotateServer({
+			markdown: "",
+			filePath: targetUrl,
+			htmlContent: MINIMAL_HTML,
+			mode: "annotate-app",
+			sourceInfo: targetUrl,
+			sharingEnabled: false,
+			liveApp: {
+				targetUrl,
+				bridgeScript: "/* bridge body */",
+				bridgeBootstrap: "/* bootstrap body */",
+				annotationCss: ".pn-live {}",
+			},
+		});
+	}
+
+	test("/api/plan returns the live payload and the proxy serves the composed bridge", async () => {
+		const app = startFakeApp();
+		const targetUrl = `http://127.0.0.1:${app.port}`;
+		const server = await startLiveServer(targetUrl);
+
+		try {
+			const plan = (await (await fetch(`${server.url}/api/plan`)).json()) as Record<string, unknown>;
+			expect(plan.mode).toBe("annotate-app");
+			expect(plan.origin).toBe("pi");
+			expect(plan.filePath).toBe(targetUrl);
+			expect(plan.targetUrl).toBe(targetUrl);
+			expect(plan.liveToken).toMatch(/^[0-9a-f]{32}$/);
+			expect(plan.sharingEnabled).toBe(false);
+			expect(plan.convertHtml).toBe(false);
+			// appUrl is the live loopback proxy under its LOCALHOST spelling (so
+			// the framed app is same-site with the editor and shares the dev
+			// app's host-only localhost cookies), never an advertised-host URL.
+			expect(plan.appUrl).toMatch(/^http:\/\/localhost:\d+\/$/);
+			// No srcdoc payloads, no version fields.
+			expect(plan.rawHtml).toBeUndefined();
+			expect(plan.renderAs).toBeUndefined();
+			expect(plan.previousPlan).toBeUndefined();
+			expect(plan.versionInfo).toBeUndefined();
+			expect(plan.diffCurrent).toBeUndefined();
+			// Agent terminal stays unavailable for live sessions.
+			expect((plan.agentTerminal as { enabled: boolean }).enabled).toBe(false);
+
+			// The proxy serves the composed bridge body: config prelude with the
+			// session token and both editor origin forms (localhost first), then
+			// bootstrap, then bridge.
+			const appUrl = plan.appUrl as string;
+			const bridge = await (await fetch(`${appUrl}__plannotator__/bridge.js`)).text();
+			expect(bridge).toContain(String(plan.liveToken));
+			const localhostAt = bridge.indexOf(`http://localhost:${server.port}`);
+			const loopbackAt = bridge.indexOf(`http://127.0.0.1:${server.port}`);
+			expect(localhostAt).toBeGreaterThanOrEqual(0);
+			expect(loopbackAt).toBeGreaterThan(localhostAt);
+			expect(bridge).toContain(".pn-live {}");
+			expect(bridge.indexOf("/* bootstrap body */")).toBeLessThan(bridge.indexOf("/* bridge body */"));
+
+			// The proxied page carries the injected bridge script tag.
+			const page = await (await fetch(appUrl)).text();
+			expect(page).toContain('<script src="/__plannotator__/bridge.js"></script>');
+		} finally {
+			server.stop();
+			app.stop(true);
+		}
+	});
+
+	test("a pathful target URL keeps its path and query in appUrl", async () => {
+		// Annotating http://localhost:5173/admin/settings must open that page,
+		// not the app root.
+		const app = startFakeApp();
+		const targetUrl = `http://127.0.0.1:${app.port}/admin/settings?tab=2`;
+		const server = await startLiveServer(targetUrl);
+		try {
+			const plan = (await (await fetch(`${server.url}/api/plan`)).json()) as { appUrl: string };
+			expect(plan.appUrl).toMatch(/^http:\/\/localhost:\d+\/admin\/settings\?tab=2$/);
+			// The advertised page is reachable through the proxy under the
+			// localhost Host spelling.
+			const res = await fetch(plan.appUrl);
+			expect(res.status).toBe(200);
+		} finally {
+			server.stop();
+			app.stop(true);
+		}
+	});
+
+	test("version endpoints report no history for live sessions", async () => {
+		const app = startFakeApp();
+		const server = await startLiveServer(`http://127.0.0.1:${app.port}`);
+		try {
+			const versions = (await (await fetch(`${server.url}/api/plan/versions`)).json()) as {
+				slug: string | null;
+				versions: unknown[];
+			};
+			expect(versions.slug).toBeNull();
+			expect(versions.versions).toEqual([]);
+			const version = await fetch(`${server.url}/api/plan/version?v=1`);
+			expect(version.status).toBe(404);
+		} finally {
+			server.stop();
+			app.stop(true);
+		}
+	});
+
+	test("stop() closes the proxy port with the server", async () => {
+		const app = startFakeApp();
+		const server = await startLiveServer(`http://127.0.0.1:${app.port}`);
+		const plan = (await (await fetch(`${server.url}/api/plan`)).json()) as { appUrl: string };
+		// Reachable while running.
+		expect((await fetch(plan.appUrl)).status).toBe(200);
+		server.stop();
+		await Bun.sleep(50);
+		let closed = false;
+		try {
+			await fetch(plan.appUrl, { signal: AbortSignal.timeout(1000) });
+		} catch {
+			closed = true;
+		}
+		expect(closed).toBe(true);
+		app.stop(true);
+	});
+
+	test("remote sessions refuse live app mode outright", async () => {
+		// Defense in depth behind the command-side check: a live proxy relays
+		// the user's authenticated dev app, and a remote Pi session is
+		// reachable beyond loopback. No override env var exists on purpose.
+		const app = startFakeApp();
+		process.env.PLANNOTATOR_REMOTE = "1";
+		try {
+			await expect(startLiveServer(`http://127.0.0.1:${app.port}`)).rejects.toThrow(
+				"Live app annotation is unavailable in remote mode",
+			);
+		} finally {
+			process.env.PLANNOTATOR_REMOTE = "0";
+			app.stop(true);
+		}
+	});
+
+	describe("draft isolation between live sessions", () => {
+		// A live session holds no document text (markdown is "" by
+		// construction), so keying its draft by content would give every live
+		// session on the machine the one hash of the empty string. The target
+		// is the identity, shared with the Bun server via liveAppDraftIdentity.
+		const savedDataDir = process.env.PLANNOTATOR_DATA_DIR;
+		let draftDataDir: string;
+
+		beforeEach(() => {
+			draftDataDir = mkdtempSync(join(tmpdir(), "plannotator-pi-live-draft-"));
+			process.env.PLANNOTATOR_DATA_DIR = draftDataDir;
+		});
+
+		afterEach(() => {
+			if (savedDataDir === undefined) delete process.env.PLANNOTATOR_DATA_DIR;
+			else process.env.PLANNOTATOR_DATA_DIR = savedDataDir;
+			rmSync(draftDataDir, { recursive: true, force: true });
+		});
+
+		async function saveDraft(server: { url: string }, feedback: string): Promise<void> {
+			const res = await fetch(`${server.url}/api/draft`, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({ feedback, annotations: [] }),
+			});
+			expect(res.status).toBe(200);
+		}
+
+		async function loadDraft(server: { url: string }): Promise<{ feedback?: string } | null> {
+			const res = await fetch(`${server.url}/api/draft`);
+			if (res.status === 404) return null;
+			expect(res.status).toBe(200);
+			return (await res.json()) as { feedback?: string };
+		}
+
+		test("two live sessions on different targets keep independent drafts", async () => {
+			const appX = startFakeApp();
+			const appY = startFakeApp();
+			const serverX = await startLiveServer(`http://127.0.0.1:${appX.port}`);
+			const serverY = await startLiveServer(`http://127.0.0.1:${appY.port}`);
+			try {
+				await saveDraft(serverX, "notes for X");
+				await saveDraft(serverY, "notes for Y");
+
+				// Neither session sees the other's text, in either direction.
+				expect((await loadDraft(serverX))?.feedback).toBe("notes for X");
+				expect((await loadDraft(serverY))?.feedback).toBe("notes for Y");
+				expect(readdirSync(join(draftDataDir, "drafts")).length).toBe(2);
+			} finally {
+				serverX.stop();
+				serverY.stop();
+				appX.stop(true);
+				appY.stop(true);
+			}
+		});
+
+		test("the same target recovers its draft after a restart", async () => {
+			const app = startFakeApp();
+			const targetUrl = `http://127.0.0.1:${app.port}`;
+			const first = await startLiveServer(targetUrl);
+			try {
+				await saveDraft(first, "survives the crash");
+			} finally {
+				first.stop();
+			}
+			// Same target, spelled with a trailing slash the way a browser would
+			// hand it back: the draft is the point of the key, so it must survive.
+			const second = await startLiveServer(`${targetUrl}/`);
+			try {
+				expect((await loadDraft(second))?.feedback).toBe("survives the crash");
+			} finally {
+				second.stop();
+				app.stop(true);
+			}
+		});
+
+		test("the vendored identity matches the Bun server's normalization", () => {
+			const a = liveAppDraftIdentity("http://127.0.0.1:5173");
+			expect(liveAppDraftIdentity("http://127.0.0.1:5173/")).toBe(a);
+			expect(liveAppDraftIdentity("http://127.0.0.1:5174")).not.toBe(a);
+			expect(liveAppDraftIdentity("http://127.0.0.1:5173/admin/")).toBe(
+				liveAppDraftIdentity("http://127.0.0.1:5173/admin"),
+			);
+			expect(liveAppDraftIdentity("not a url")).toBe("not a url");
+		});
+	});
+});

package/server/serverAnnotate.ts

@@ -2,7 +2,16 @@ import { createServer } from "node:http";
 import type { IncomingMessage } from "node:http";
 import { dirname, resolve as resolvePath } from "node:path";
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { randomUUID } from "node:crypto";
+import { randomBytes, randomUUID } from "node:crypto";
+
+import {
+	buildLiveAppUrl,
+	buildLiveEditorOrigins,
+	composeLiveBridgeJs,
+	liveAppDraftIdentity,
+} from "../generated/live-proxy-core.ts";
+import { startLiveAppProxyNode } from "../generated/live-proxy-node.ts";
+import type { LiveAppProxy } from "../generated/live-proxy-core.ts";
 
 import { contentHash, deleteDraft } from "../generated/draft.ts";
 import { getPlanVersion, getVersionCount, listVersions } from "../generated/storage.ts";
@@ -224,7 +233,28 @@ export async function startAnnotateServer(options: {
 	agentCwd?: string;
 	/** Project name for keying per-file version history (powers the annotate version diff). */
 	project?: string;
+	/**
+	 * Live local app annotation (mode "annotate-app"): the server starts a
+	 * loopback reverse proxy (node:http transport over the shared core)
+	 * mirroring targetUrl and serves the composed bridge body from it. The
+	 * caller supplies the bridge sources; the server owns the per-session
+	 * token. Refused outright in remote mode.
+	 */
+	liveApp?: {
+		targetUrl: string;
+		bridgeScript: string;
+		bridgeBootstrap: string;
+		annotationCss: string;
+	};
 }): Promise<AnnotateServerResult> {
+	// Remote hard-off, defense in depth behind the command-side check: a live
+	// proxy relays the user's authenticated dev app, so it must never coexist
+	// with a beyond-loopback annotate bind. No override env var exists on
+	// purpose (mirrors packages/server/annotate.ts).
+	if (options.liveApp && isRemoteSession()) {
+		throw new Error("Live app annotation is unavailable in remote mode");
+	}
+
 	const gitUser = detectGitUser();
 	const sharingEnabled =
 		options.sharingEnabled ?? resolveSharingEnabled(loadConfig());
@@ -275,11 +305,19 @@ export async function startAnnotateServer(options: {
 		{ graceMs: clientLeaseGraceMs },
 	);
 
-	// Folder annotation has no stable markdown body, so key drafts by folder path instead.
+	// Draft identity. Content-derived for the modes that HAVE content, and
+	// path-derived for the modes that do not: a live app session resolves
+	// `markdown` to "" by construction (the page lives behind the proxy), so
+	// its target is its identity — hashing the empty body would give every
+	// live session on the machine one shared draft slot. Folder sessions key
+	// by folder path for the same reason. liveAppDraftIdentity is the shared
+	// normalization, so Bun and Pi sessions key the same target identically.
 	const draftSource =
-		options.mode === "annotate-folder" && options.folderPath
-			? `folder:${resolvePath(options.folderPath)}`
-			: options.renderHtml && options.rawHtml ? options.rawHtml : options.markdown;
+		options.mode === "annotate-app" && options.liveApp
+			? `annotate-app\0${liveAppDraftIdentity(options.liveApp.targetUrl)}`
+			: options.mode === "annotate-folder" && options.folderPath
+				? `folder:${resolvePath(options.folderPath)}`
+				: options.renderHtml && options.rawHtml ? options.rawHtml : options.markdown;
 	const draftKey = contentHash(draftSource);
 
 	// Per-file version history → powers the native version diff in annotate mode.
@@ -290,10 +328,13 @@ export async function startAnnotateServer(options: {
 	const annotateProjectName = options.project ?? "_unknown";
 	const annotateHistoryEnabled = resolveAnnotateHistory(loadConfig());
 	// Single local file sessions are the only ones this eager gate covers.
-	// URL and agent-message sessions never write session content to the data
-	// dir. Folder sessions do participate in per-file version history, but
-	// lazily through /api/doc (see computeFolderAnnotateHistory below), not
-	// here. The durable submit records stay single-local-file only.
+	// URL, agent-message, and live-app sessions never write session content to
+	// the data dir. Folder sessions do participate in per-file version history,
+	// but lazily through /api/doc (see computeFolderAnnotateHistory below), not
+	// here. The durable submit records stay single-local-file only. The
+	// mode === "annotate" check is deliberate and explicit: "annotate-app"
+	// (whose filePath is URL-shaped anyway) must never become history-eligible
+	// by accident.
 	const singleFileLocalAnnotate =
 		(options.mode || "annotate") === "annotate" && !/^https?:\/\//i.test(options.filePath);
 	let annotateHistory: AnnotateHistoryResult | null = null;
@@ -499,6 +540,13 @@ export async function startAnnotateServer(options: {
 		initialSingleFileSourcePath,
 	});
 
+	// Live app session state, populated after the annotate port is known (the
+	// editor origins carry the port) and before the URL is returned to the
+	// caller for advertisement.
+	let liveProxy: LiveAppProxy | null = null;
+	let liveSessionToken = "";
+	let liveAppUrl = "";
+
 	const server = createServer(async (req, res) => {
 		const url = requestUrl(req);
 
@@ -541,7 +589,41 @@ export async function startAnnotateServer(options: {
 			return;
 		}
 
-		if (url.pathname === "/api/plan" && req.method === "GET") {
+		if (url.pathname === "/api/plan" && req.method === "GET" && options.mode === "annotate-app" && options.liveApp) {
+			// Live app session: no rawHtml, no renderAs, no version fields,
+			// sharing off. The client frames appUrl (the loopback proxy) and
+			// authenticates the bridge with liveToken. Mirrors the Bun
+			// server's annotate-app payload (packages/server/annotate.ts).
+			json(res, {
+				plan: "",
+				origin: options.origin ?? "pi",
+				mode: options.mode,
+				filePath: options.filePath,
+				sourceInfo: options.sourceInfo ?? options.liveApp.targetUrl,
+				appUrl: liveAppUrl,
+				targetUrl: options.liveApp.targetUrl,
+				liveToken: liveSessionToken,
+				gate: options.gate ?? false,
+				approvalNotesSupported: options.approvalNotesSupported ?? false,
+				clientLease: options.clientLeaseSupported
+					? { enabled: true as const, reconnectGraceMs: clientLeaseGraceMs }
+					: { enabled: false as const },
+				sharingEnabled: false,
+				convertHtml: false,
+				repoInfo,
+				projectRoot: process.cwd(),
+				serverConfig: getServerConfig(gitUser),
+				agentTerminal: agentTerminalCapability,
+				feedbackTemplates: {
+					fileFeedback: getAnnotateFileFeedbackTemplate(
+						(options.origin ?? "pi") as PromptRuntime,
+					),
+					messageFeedback: getAnnotateMessageFeedbackTemplate(
+						(options.origin ?? "pi") as PromptRuntime,
+					),
+				},
+			});
+		} else if (url.pathname === "/api/plan" && req.method === "GET") {
 			const displayRawHtml = options.renderHtml && options.rawHtml
 				? htmlAssets.rewriteHtml(options.rawHtml, options.filePath)
 				: undefined;
@@ -928,6 +1010,55 @@ export async function startAnnotateServer(options: {
 
 	const { port, portSource } = await listenOnPort(server);
 
+	if (options.liveApp) {
+		// Compose the proxy-served bridge body via the shared assembly (config
+		// prelude with the token this server owns, both editor origin forms
+		// with the localhost one first to match the advertised URL, then the
+		// bootstrap that installs the CSS, then the bridge itself). A proxy
+		// startup failure must not leave the annotate listener hanging.
+		try {
+			liveSessionToken = randomBytes(16).toString("hex");
+			const editorOrigins = buildLiveEditorOrigins(port);
+			liveProxy = await startLiveAppProxyNode({
+				targetUrl: options.liveApp.targetUrl,
+				editorOrigins,
+				bridgeJs: composeLiveBridgeJs({
+					token: liveSessionToken,
+					editorOrigins,
+					annotationCss: options.liveApp.annotationCss,
+					bridgeBootstrap: options.liveApp.bridgeBootstrap,
+					bridgeScript: options.liveApp.bridgeScript,
+				}),
+			});
+			// Advertise the proxy under the LOCALHOST spelling, carrying the
+			// target URL's own path and query (see buildLiveAppUrl in the
+			// shared core for the same-site/cookie rationale).
+			// PLANNOTATOR_URL_HOST is never applied here.
+			liveAppUrl = buildLiveAppUrl(liveProxy.port, options.liveApp.targetUrl);
+		} catch (error) {
+			// Same disposal set the normal stop() runs, each step guarded so
+			// the original startup error is what propagates.
+			for (const dispose of [
+				() => closeAllFileBrowserWatchers(),
+				() => {
+					clientLease.cancel();
+					clientLease.closeSessions();
+				},
+				() => aiRuntime?.dispose(),
+				() => agentTerminal.dispose(),
+			]) {
+				try {
+					dispose();
+				} catch {
+					// startup failure cleanup: best effort
+				}
+			}
+			server.close();
+			(server as { closeAllConnections?: () => void }).closeAllConnections?.();
+			throw error;
+		}
+	}
+
 	// Mirror the Bun server: bind first, then warm through the async shared walk.
 	void warmFileListCache(process.cwd(), "code");
 
@@ -954,6 +1085,11 @@ export async function startAnnotateServer(options: {
 				}],
 				["AI runtime", () => aiRuntime?.dispose()],
 				["agent terminal", () => agentTerminal.dispose()],
+				// Live proxy last, mirroring the Bun server's guarded order: a
+				// throw in the historically fragile agent-terminal teardown
+				// (#1314) must never orphan the proxy's listener or its
+				// upstream sockets.
+				["live proxy", () => liveProxy?.stop()],
 			];
 			try {
 				for (const [name, dispose] of disposals) {

package/skills/plannotator/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: plannotator
+description: "Reference for using the Plannotator CLI: plan review, code review, annotating files, URLs, folders, and running local apps, annotating the last assistant message, browsing archived plan decisions, and exporting or sharing Guided Reviews. Invoke when asked to use Plannotator for anything not covered by a more specific plannotator-* skill."
+---
+
+# Plannotator CLI Reference
+
+Plannotator is a local, browser-based review layer for agent workflows: it opens plans, diffs, and documents in an annotation UI, the human marks them up, and the structured feedback comes back to you on stdout. It installs as a single `plannotator` binary plus per-host hooks, so plan review fires automatically when you exit plan mode; every other surface is launched explicitly from the CLI. A session runs on a random localhost port (fixed port 19432 in remote mode) and blocks until the reviewer submits feedback, approves, or closes the tab.
+
+This skill is the knowledge layer. The `plannotator-review`, `plannotator-annotate`, and `plannotator-last` skills are thin launchers for the three most common actions; use this reference when you need to pick the right command or flags yourself.
+
+## Choose the command
+
+| The user wants | Run |
+| --- | --- |
+| Review a plan you produced | Nothing. Plan review opens automatically on plan exit via hooks. Never run bare `plannotator` yourself. |
+| Review current code changes | `plannotator review` |
+| Review a GitHub PR or GitLab MR | `plannotator review <PR_URL>` |
+| Annotate a markdown, text, config, or HTML file | `plannotator annotate <file>` |
+| Annotate a web page | `plannotator annotate <https-url>` |
+| Annotate a running local app (dev server) | `plannotator annotate <http://localhost:PORT/>` |
+| Pick a file to annotate from a folder | `plannotator annotate <folder/>` |
+| Annotate your latest assistant message | `plannotator last` |
+| Browse past plan decisions | `plannotator archive` |
+| Export or share a Guided Review | `plannotator guide export` / `plannotator guide share` |
+| Reopen or list live sessions | `plannotator sessions` |
+
+## Session model
+
+Every review or annotate command starts a local web server, opens the browser, and blocks until the human decides. That can take minutes. Launch it with a long (or no) command timeout, or in the background, then read stdout when the process exits. Do not kill the process to "finish" a review; a session that ends without a decision reads as no feedback.
+
+The stdout contract is the whole interface:
+
+- Plaintext (default): empty output on close, `The user approved.` on approve, otherwise the feedback text. Address returned feedback in the same conversation.
+- `--json`: one JSON record, `{"decision":"approved"|"dismissed"|"annotated","feedback":"..."}`. An approval may still carry notes in `feedback`; treat those as guidance, not a change request.
+- `--hook`: hook-native output for real PostToolUse/Stop hook contexts only. Approve/close emits nothing (hook passes); annotations emit `{"decision":"block","reason":"..."}`. `--hook` implies the gate UI. Never use it for a normal interactive invocation.
+
+`plannotator <command> --help` prints usage without launching anything. Bare `plannotator` is the hook entry point and expects hook JSON on stdin.
+
+## plannotator review
+
+```bash
+plannotator review [--git | --gitbutler] [--local | --no-local] [--tailscale] [PR_URL]
+```
+
+Reviews local VCS changes, or a pull request when a URL is given. Feedback and annotations come back on stdout when the reviewer submits; an approval comes back as an LGTM-style message.
+
+- VCS is auto-detected (JJ, GitButler, Git, and P4 where supported). `--git` forces plain Git; `--gitbutler` forces GitButler (requires the `but` CLI 0.21.0+). Running from a non-VCS parent folder that contains nested repos produces a combined workspace diff.
+- The default diff is "everything a PR would show now": merge-base of the trunk vs the working tree plus untracked files. The reviewer can switch diff types in the UI; you do not control that from the CLI.
+- PR review (`plannotator review https://github.com/owner/repo/pull/123`, GitLab MR URLs too) needs an authenticated `gh` or `glab` CLI. `--local` (the default) builds a local checkout of the PR head in the background for full file access; `--no-local` skips it and reviews the platform diff only.
+- `--tailscale` publishes the loopback session over the user's tailnet via `tailscale serve` (HTTPS, never public) and prints the URL with a QR code. A publish failure exits nonzero instead of leaving the server hanging.
+
+## plannotator annotate
+
+```bash
+plannotator annotate <target> [--markdown] [--no-jina] [--app | --static] [--render-html] [--tailscale] [--gate] [--json] [--hook]
+```
+
+Opens one document, page, or app in the annotation UI and returns the human's annotations on stdout.
+
+Targets:
+
+- Markdown and text files: `.md`, `.mdx`, `.txt`.
+- Plain-text config and data files, rendered as text: `.yaml`, `.yml`, `.json`, `.jsonc`, `.json5`, `.toml`, `.ini`, `.cfg`, `.conf`, `.properties`, `.csv`, `.tsv`, `.log`, `.xml`, `.env.example`. `.env` itself is deliberately refused (it commonly holds secrets, and annotate history copies file contents). Source-code files belong to `plannotator review`, not annotate.
+- HTML files (`.html`, `.htm`): rendered as the raw page by default; `--markdown` converts to markdown instead. `--render-html` is accepted for compatibility; raw rendering is already the default.
+- URLs (`https://...`): fetched and converted via Jina Reader by default; `--no-jina` uses plain fetch plus Turndown instead.
+- Running local apps: a loopback `http://localhost:PORT/` URL whose probe returns HTML opens in live-app mode (annotate the real running page). `--app` forces live mode and fails loudly when it cannot apply; `--static` forces the classic conversion pipeline. Non-loopback URLs always use the conversion pipeline.
+- Folders: `plannotator annotate docs/` opens a file browser over the folder's supported files.
+
+Single files are capped at 2MB. Files are read from disk at stable project paths; keep the reviewed source where it lives.
+
+Argument tolerance: extra words are fine (`plannotator annotate look at notes.md please` opens `notes.md`), but two resolvable targets is an error naming both, and an unrecognized dashed token disables the tolerance so flag typos fail loudly. When nothing resolves in a plain multi-word invocation, the CLI prints an agent-addressed handoff on stdout and exits 0: read it, work out the concrete target, and re-run with that exact path or URL.
+
+### Strict gates and exit codes
+
+For a machine-checkable approval gate, add `--gate --json` plus one or both strict flags:
+
+```bash
+plannotator annotate report.md --gate --json --require-approval --result-file /tmp/decision.json
+```
+
+- `--require-approval`: exit code reports the human outcome.
+- `--result-file <path>`: the stdout decision JSON is also published atomically to `<path>`. The parent directory must exist and the file must not; results resolve from the invocation cwd.
+
+Exit codes under a strict flag (grep convention):
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | Approved. The only success. |
+| 1 | The reviewer did not approve (annotated or dismissed); the decision record was still published. |
+| 2 | The gate itself failed: bad flag combination, startup failure (missing file, unreachable URL, oversized file), or the result file could not be published. Never treat as a reviewer outcome. |
+| 128+n | Killed by signal n. |
+
+Without strict flags, startup failures exit 1 and the exit code carries no decision; parse the output instead. Both strict flags require `--gate --json` and reject `--hook`.
+
+## plannotator annotate-last
+
+```bash
+plannotator annotate-last [--stdin] [--tailscale] [--gate] [--json] [--hook]
+plannotator last
+```
+
+Opens the latest rendered assistant message from the current agent session in the annotation UI (`last` is an alias). The session log is discovered per host automatically; `--stdin` reads the content from stdin instead.
+
+Do not print a commentary or status message immediately before running it: the command targets the latest rendered assistant message, so a preamble becomes the thing being annotated.
+
+## plannotator copilot-last
+
+```bash
+plannotator copilot-last [--gate] [--json] [--hook]
+```
+
+The annotate-last variant for live GitHub Copilot CLI sessions (reads Copilot's session-state events). Normally invoked by the Copilot plugin's /plannotator-last command; use it only inside a Copilot CLI session.
+
+## plannotator archive
+
+```bash
+plannotator archive
+```
+
+Opens a read-only browser over saved plan decisions (approved/denied badges) from the Plannotator data directory. No feedback comes back; the session ends when the user clicks Done.
+
+## plannotator guide
+
+```bash
+plannotator guide list
+plannotator guide export --id <savedGuideId> [--out <file.html>]
+plannotator guide export --guide <guide.json> --patch <diff.patch> [--out <file.html>]
+plannotator guide export --snapshot <snapshot.json> [--out <file.html>]
+plannotator guide share --id <savedGuideId> [--public] [--ttl <7d|24h|30m|3600>] [--json]
+plannotator guide unshare <id> --token <deleteToken>
+```
+
+Guided Reviews are AI-generated walkthroughs of a diff, produced inside the code review UI. The CLI works with saved ones:
+
+- `list` shows guides Plannotator has persisted for the current repo.
+- `export` writes one portable, self-contained HTML file (the viewer loads from guides.show). `--guide` + `--patch` exports a guide you authored yourself against a unified diff (`--patch -` reads stdin; validation is strict and names any file the guide references that the patch lacks). `--out -` writes to stdout. `--viewer-url` overrides the pinned viewer base.
+- `share` uploads the guide and prints a link. Encrypted by default: the key lives only in the URL fragment and the host stores ciphertext. `--public` stores it unencrypted so chat apps can unfurl a preview. `--ttl` sets an expiry; otherwise the link stays until `unshare`. A saved guide records its link, and a second `share --id` refuses rather than orphaning the first link's delete token.
+- `unshare <id> --token <t>` removes a link using the delete token printed at share time.
+
+## plannotator sessions
+
+```bash
+plannotator sessions [--open [N]] [--clean]
+```
+
+Lists active Plannotator server sessions. `--open` reopens session N (default 1) in the browser, useful when a tab was closed mid-review. `--clean` drops stale entries.
+
+## Other subcommands
+
+```bash
+plannotator setup-goal <interview|facts> <bundle.json | -> [--json]
+plannotator uninstall [--purge] [--yes] [--dry-run]
+plannotator improve-context
+```
+
+- `setup-goal` opens the interview or facts-acceptance UI for /goal workflows; it is driven by the `plannotator-setup-goal` skill and takes a bundle JSON (`-` reads stdin). Do not hand-build bundles.
+- `uninstall` removes Plannotator-installed components (`--purge` also deletes local data; `--yes` is required without a TTY; `--dry-run` previews).
+- `improve-context` and `install-runtime` are internal integration commands (hook plumbing and managed runtime install). Never run `improve-context` directly; `plannotator install-runtime agent-terminal` exists for reinstalling the optional annotate-terminal runtime and is normally run by the installer.
+- Additional host-internal subcommands (the `opencode-*` and `copilot-plan` family) are invoked by their plugins, not by you.
+
+## Environment variables that change behavior
+
+| Variable | Use |
+| --- | --- |
+| `PLANNOTATOR_REMOTE=1` | Force remote mode (fixed port 19432, wide bind) for SSH/devcontainer sessions; `0` forces local. Unset means SSH auto-detection. |
+| `PLANNOTATOR_PORT` | Fix the port instead of a random one. |
+| `PLANNOTATOR_ORIGIN` | Override agent-origin detection (`claude-code`, `codex`, `opencode`, `pi`, `oh-my-pi`, `amp`, `droid`, `copilot-cli`, `gemini-cli`, `kiro-cli`). Set it when launching Plannotator from a wrapper the detection cannot see through. |
+| `PLANNOTATOR_AI=disabled` | Disable Ask AI and agent-launched review surfaces in the UI. |
+| `PLANNOTATOR_SHARE=disabled` | Disable URL sharing, including guide share links. |
+| `PLANNOTATOR_DATA_DIR` | Move the data directory (default `~/.plannotator`): plans, history, drafts, config. |
+| `PLANNOTATOR_BROWSER` | Open sessions in a specific browser. |
+
+## Posting annotations into a live session
+
+A running plan-review session exposes a small HTTP API on its base URL for external annotations: `POST /api/external-annotations` adds inline annotations the reviewer sees immediately, with PATCH/DELETE for updates and an SSE stream at `/api/external-annotations/stream`. The UI's "copy agent instructions" action puts the full API contract for the current session, with the correct base URL, on the clipboard for handing to an agent or script. If the user pastes such instructions, follow them; do not invent endpoints beyond that contract.
+
+## Do not
+
+- Do not parse or scrape the browser UI's HTML; the CLI's stdout (and the documented HTTP API above) is the whole contract.
+- Do not use `--hook` outside a real hook context; use `--json` when you need structured output.
+- Do not run bare `plannotator` interactively; it is the hook entry point.
+- Do not guess flags. Run `plannotator <command> --help` when unsure; unknown dashed tokens make annotate fail on purpose.
+- Do not point `plannotator annotate` at source-code files or `.env` files; code goes through `plannotator review`, and `.env` is refused.
+- Do not start a strict gate (`--require-approval`) unless a human is actually there to review; the session blocks until they act.