wiki-viewer 2.16.0 → 2.16.1

package/.next/standalone/.scratch/tweak-running-app/ops22-context.md

@@ -0,0 +1,84 @@
+# OPS-22 re-home context (ground truth, main @ 23a5129)
+
+Goal: rebuild the (removed) "Tweak" interaction on top of the EXISTING
+comments/suggestions sidecar ("proof") engine, so there is one collaboration
+engine underneath. Tweak = "point at a target, say what you want, the agent
+rewrites it." No live engine, no polling, no variants-in-iframe.
+
+## What the proof engine already gives us (do not rebuild)
+
+Store: `.proof/<path>.json` sidecar per file, opaque JSON, event log, revisioned.
+Write API: `POST /api/agent/files/[...path]` `{baseRevision, by, ops[]}`, bearer
++ Idempotency-Key, `STALE_REVISION` 409 + fresh snapshot on drift.
+
+Comment kinds (src/lib/proof/types.ts):
+- `comment` (legacy): discussion/annotation. Anchor = md `ref` (block) OR
+  `lineAnchor{lineStart,lineEnd,textHash}` for text/code files.
+- `instruction` (`kind:"instruction"`): ALREADY EXISTS. Fields
+  `instructionState: draft|queued|sent|answered`, `runId?`, `fromCommentId?`.
+  Created today only via "Turn into an instruction" (comment-thread.tsx). It has
+  NO client dispatcher and the queued/sent/answered lifecycle is dormant
+  (driven only in tests). This is the durable home for a tweak.
+
+Suggestions (`suggestion.add`, kinds replace/insertAfter/insertBefore/delete,
+status pending|accepted|rejected): reviewed in `suggestion-card.tsx`; Accept
+pushes the equivalent block op into the same batch and writes the doc, gated on
+base fingerprint. THIS IS MARKDOWN-ONLY (route + applier both gate non-md to
+comment ops only).
+
+Surface capability asymmetry (hard constraint):
+- Markdown (.md): full — block-ref comments, instruction comments, suggestions,
+  accept-writes-doc. Reviewed inline via suggestion-card + comment-pip.
+- Text/code/HTML/any other file (source viewer): line-anchored COMMENTS ONLY.
+  No suggestions, no edits, no instruction dispatcher UI, no in-place accept.
+  (source-viewer.tsx already builds the selection→lineAnchor detection UI.)
+
+## Current entry points (post-removal)
+
+- Markdown editor bubble menu: **Comment** (discuss/annotate) + **Suggest**
+  (propose human edit for review). Tweak was removed.
+- Source viewer (text/code): select text → **Comment** pip only.
+- HTML files render as a sandboxed preview iframe (website-viewer.tsx); no
+  collaboration affordance on it at all right now.
+
+## Pre-removal Tweak UX we are preserving (recovered from tag pre-tweak-removal)
+
+Shared chrome:
+- Bottom-center fixed **queue bar**: "{n} tweak(s) ready" · Cancel (clears all) ·
+  [Copy as prompt | Show] extras · dispatch button (label surface-specific).
+- **Targeting panel** anchored to the target: header "Target", textarea
+  placeholder "What should change?", Cmd/Enter = add, Cancel, Add tweak.
+  Outside-click on empty input = cancel.
+- **Dedup in place**: re-picking the same target updates its instruction/snippet,
+  count does not grow.
+- **Copy as prompt** (works with no agent): emits
+  `Edit the file \`X\` (a Markdown document). Apply these changes:\n\n1. \`<snippet>\`: <instruction>` (html variant lists `Element \`selector\` (<tag>): ...`).
+  Clipboard gate + "Show" textarea fallback for non-secure contexts.
+- **Connect an agent**: when no agent attached, dispatch label becomes "Connect
+  an agent" and opens the AI panel; queue preserved.
+
+Markdown surface: click rendered block → targeting panel → queue → "Rewrite".
+HTML surface: element picker in iframe → note editor anchored to element → queue
+→ "Apply" (confirm modal) → variants. (The whole speculative-preview/variant/
+Accept-writes machinery is the part being deleted.)
+
+## HARD FRAMING (user correction, authoritative)
+
+There is NO standalone "Tweak" action and none will be created. There stay
+exactly TWO editor actions: **Comment** and **Suggest**. The pleasant tweak UX
+is PORTED INTO those two, not added beside them. Concretely, the intended split
+(confirm/refine): Comment absorbs "tell the agent what to change" via the
+existing `instruction` comment kind + the targeting affordance ("What should
+change?") + copy-as-prompt + connect-an-agent; the agent's rewrite answer lands
+as a **Suggestion** reviewed in the existing suggestion-card. Reject any design
+that adds a third button.
+
+## The open decision to resolve
+
+Default dispatch action for a tweak:
+- (a) instruction-comment default: dispatch persists each queued item as
+  `comment.add {kind:"instruction"}` on the target block/line; the user's agent
+  picks it up through its normal snapshot/activity flow and answers with a
+  suggestion (md) reviewed in suggestion-card. Copy-as-prompt = escape hatch.
+- (b) copy-as-prompt only: no durable artifact; user pastes into their agent.
+PM leaned (b) for simplicity; implementer leaned (a) durable with (b) as hatch.

package/.next/standalone/.scratch/tweak-running-app/pivot-note.md

@@ -0,0 +1,25 @@
+## Direction change: unify on the Impeccable live model (supersedes the node-app-scoped plan)
+
+After reviewing what the Impeccable `live` skill actually does (inject an overlay
+into the app's own running page; hot-swap agent-written source variants via the
+dev server's HMR; carbonize the chosen variant into permanent source on accept;
+2–5 variants + tunable per-variant knobs), we are replacing the embed-in-iframe
+node-app approach with a single unified mechanism.
+
+Decisions:
+- Scope = web/visual surfaces only: static HTML, dynamic HTML, and node apps.
+  Markdown prose stays on its current variants-in-place flow (no HMR / rendered
+  UI to hot-swap).
+- Engine = reuse the existing Impeccable live engine (helper server + injection
+  adapters + HMR hot-swap + carbonize) rather than reimplement it or drop the
+  in-product experience. Requires a feasibility spike: confirm the engine can be
+  driven by the wiki-viewer product, not only by a chat agent.
+
+Consequence:
+- This spec (OPS-1) and its tickets (OPS-2 isolated origin, OPS-3 tracer bullet,
+  OPS-4 robustness, OPS-5 multi-file safety, OPS-6 batch parity) are SUPERSEDED.
+  The isolated-origin / grant / same-site-hardening architecture is no longer
+  needed because the Impeccable model injects into the app's own page (no parent
+  to protect) instead of embedding it in the wiki editor's iframe.
+- Next steps: feasibility spike on driving the Impeccable engine from the product,
+  then a fresh unified spec (to-spec) and tickets (to-tickets).

package/.next/standalone/.scratch/tweak-running-app/qa-live-engine.ts

@@ -0,0 +1,104 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { LiveEngineClient } from "/home/sil/wiki-viewer/src/lib/live-engine/client";
+import { startEngine, stopEngine } from "/home/sil/wiki-viewer/src/lib/live-engine/supervisor";
+
+async function main() {
+
+const results: string[] = [];
+function check(name: string, cond: boolean, extra = ""): void {
+	results.push(`${cond ? "PASS" : "FAIL"}  ${name}${extra ? "  ::  " + extra : ""}`);
+}
+
+const appRoot = fs.mkdtempSync(path.join(os.tmpdir(), "qa-live-"));
+fs.writeFileSync(
+	path.join(appRoot, "index.html"),
+	'<!doctype html><html><head><title>qa</title></head><body><button id="b">Hi</button></body></html>',
+);
+
+let failed = false;
+try {
+	const info = await startEngine({ workspaceId: "qa", relPath: "index.html", appRoot });
+	check("engine boots via product supervisor + running", info.state === "running", `port=${info.port} tokenLen=${info.token.length}`);
+
+	const client = new LiveEngineClient(info);
+	const h = await client.health();
+	check("health -> ok", h.status === "ok");
+
+	const base = `http://127.0.0.1:${info.port}`;
+
+	const noTok = await fetch(`${base}/live.js`);
+	await noTok.text();
+	check("live.js without token -> 401", noTok.status === 401, `status=${noTok.status}`);
+
+	const js = await fetch(`${base}/live.js?token=${info.token}`);
+	const jsBody = await js.text();
+	check("live.js with token -> 200 real bundle", js.status === 200 && jsBody.length > 1000, `status=${js.status} len=${jsBody.length}`);
+	check("live.js self-embeds the token", jsBody.includes(info.token));
+	check("bundle references __IMPECCABLE_ globals we inject", /__IMPECCABLE_(PORT|TOKEN|VOCAB)__/.test(jsBody), (jsBody.match(/__IMPECCABLE_[A-Z_]+__/g) || []).slice(0, 6).join(","));
+
+	// Opaque-origin (sandboxed srcDoc iframe = Origin: null) CORS preflight
+	const opt = await fetch(`${base}/events?token=${info.token}`, { method: "OPTIONS", headers: { Origin: "null" } });
+	await opt.text();
+	check("OPTIONS opaque-origin preflight -> 204", opt.status === 204, `status=${opt.status}`);
+	check("CORS reflects opaque origin (null)", opt.headers.get("access-control-allow-origin") === "null", `acao=${opt.headers.get("access-control-allow-origin")}`);
+
+	// Opaque-origin with WRONG token gets no CORS grant
+	const optBad = await fetch(`${base}/events?token=nope`, { method: "OPTIONS", headers: { Origin: "null" } });
+	await optBad.text();
+	check("opaque origin + bad token -> no CORS grant", optBad.headers.get("access-control-allow-origin") == null, `acao=${optBad.headers.get("access-control-allow-origin")}`);
+
+	// Browser uplink: POST /events generate (session-creating), Origin: null
+	const genId = "a1b2c3d4";
+	const gen = await fetch(`${base}/events`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json", Origin: "null" },
+		body: JSON.stringify({
+			token: info.token,
+			type: "generate",
+			id: genId,
+			action: "bolder",
+			count: 3,
+			pageUrl: "/index.html",
+			element: { outerHTML: '<button id="b">Hi</button>', tagName: "BUTTON" },
+		}),
+	});
+	const genBody = await gen.text();
+	check("POST /events generate (opaque origin, token) accepted", gen.ok, `status=${gen.status} body=${genBody.slice(0, 140)}`);
+
+	// POST /events with bad token rejected
+	const genBad = await fetch(`${base}/events`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ token: "nope", type: "generate", id: "b2c3d4e5", action: "bolder", count: 3, pageUrl: "/index.html", element: { outerHTML: "<x/>" } }),
+	});
+	await genBad.text();
+	check("POST /events bad token -> 401", genBad.status === 401, `status=${genBad.status}`);
+
+	// Product-side poll receives the browser's generate
+	const poll = await client.poll({ timeoutMs: 10000, leaseMs: 30000 });
+	check("product /poll receives the generate event", poll?.type === "generate" && poll?.id === genId, `type=${String(poll?.type)} id=${String((poll as { id?: string })?.id)}`);
+
+	await stopEngine({ workspaceId: "qa", relPath: "index.html" });
+	let unreachable = false;
+	try {
+		await new LiveEngineClient(info).health();
+	} catch {
+		unreachable = true;
+	}
+	check("stopEngine tears down helper (health unreachable)", unreachable);
+} catch (err) {
+	failed = true;
+	results.push(`FAIL  harness threw  ::  ${(err as Error).message}`);
+} finally {
+	try {
+		await stopEngine({ workspaceId: "qa", relPath: "index.html" });
+	} catch {}
+	fs.rmSync(appRoot, { recursive: true, force: true });
+}
+
+console.log(results.join("\n"));
+if (failed || results.some((r) => r.startsWith("FAIL"))) process.exitCode = 1;
+}
+main();

package/.next/standalone/.scratch/tweak-running-app/spike.md

@@ -0,0 +1,256 @@
+# B1 feasibility spike: driving the Impeccable live engine from wiki-viewer
+
+**Date:** 2026-08-18
+**Question:** Can the wiki-viewer *product* (a server, not a chat agent) drive the
+Impeccable `live` engine end to end (helper server, `live.js` injection, HMR
+hot-swap, carbonize-on-accept), and how does the engine's poll loop reconcile with
+wiki-viewer's existing attached-agent channel?
+
+**Verdict: feasible, with a defined bridge.** The engine has no hard dependency on
+a chat-agent CLI. Its contract is plain HTTP plus file-based state, so a product
+server can drive it. Two integration points need real work and carry the risk:
+(1) the browser-to-helper transport when wiki-viewer is served remotely, and
+(2) reconciling two source-write/lock systems on the same files. One item needs a
+quick confirmation before spec: WebSocket-upgrade passthrough for HMR in the
+app-proxy. Everything else maps cleanly.
+
+This memo is concrete enough to write a spec from.
+
+---
+
+## What the engine actually is (verified)
+
+Not a monolith and not chat-agent-bound. Three cooperating pieces:
+
+1. **A long-lived helper HTTP server** (`live-server.mjs`), bound to `127.0.0.1`,
+   auto-port from `8400`, token-gated. It writes `.impeccable/live/server.json`
+   (`{pid, port, token}`). Endpoints that matter:
+   - `GET /live.js?token=` — the assembled browser overlay bundle.
+   - `GET /events?token=` — **SSE downlink**, server to browser (variant mounts,
+     `connected`, `exit`).
+   - `POST /events?token=` — browser to server uplink (`generate`, `steer`,
+     `accept`, `discard`, annotations).
+   - `GET /poll?token=&timeout=&leaseMs=` — **agent long-poll**, default 600 s.
+   - `POST /poll` — **agent reply** (`done`/`steer_done`/`error`/`complete`).
+   - `GET /source?token=&path=`, `GET /design-system.json`, `POST /annotation`,
+     `GET /health` (unauthenticated liveness), `GET /stop`.
+   - CORS allows loopback origin **or** a valid token.
+
+2. **A set of stateless per-call CLI mutators** that read/write project source and
+   `.impeccable/live/` state: `live-wrap.mjs` (write the variant wrapper into
+   source), `live-accept.mjs` (stitch the chosen variant into source / carbonize),
+   `live-complete.mjs` (final gate), `live-status.mjs` / `live-resume.mjs`
+   (recovery), `live-inject.mjs` (inject the `<script>` tag).
+
+3. **File-based canonical state** under `<appRoot>/.impeccable/live/`: an
+   append-only per-session JSONL journal (`sessions/<id>.jsonl`) is the source of
+   truth; plus `server.json`, `config.json`, `roots.json`, accept receipts, and
+   per-file locks. Sessions survive helper restart via journal replay.
+
+The pi-impeccable harness extension is just sugar over this: it spawns the poll,
+maps events to prompts, and wraps `--reply`. **The engine underneath is HTTP plus
+files.** That is the whole reason a product can drive it.
+
+---
+
+## Answering the five spike questions
+
+### (a) Can wiki-viewer run/embed the helper server? — YES
+
+`live-server.mjs --background` spawns a detached child, prints the connection JSON,
+and exits. wiki-viewer's server can spawn it exactly as `app-runner.ts` already
+spawns child processes (module-level singleton Map, keyed per workspace). Boot via
+`live.mjs --target <appRoot>` resolves and persists `roots.json`, so every helper
+call is cwd-independent afterward.
+
+- Auth is a single token from `server.json`. The product reads it server-side and
+  never exposes it in logs (matches wiki-viewer's existing token discipline).
+- `GET /health` gives a clean readiness probe, same pattern as `app-runner`'s port
+  probe.
+- Lifecycle keys naturally onto wiki-viewer's `{workspaceId, relPath}` app model:
+  one helper per served surface, torn down with the app.
+
+**No blocker.** This is the same shape of work wiki-viewer already does for node
+apps.
+
+### (b) Can wiki-viewer inject `live.js` for both served apps and static HTML? — YES, and the seam already exists
+
+- **Served (node) apps:** `src/app/api/app-proxy/[...path]/route.ts` already
+  rewrites upstream HTML at serve time (injects `<base href>`, `fetch`/`XHR`
+  shims, a `<script>` block before `</head>`). Injecting the Impeccable prelude
+  globals plus a `<script src=".../live.js">` at that exact point is a natural
+  extension. This is **better** than `live-inject.mjs`'s source-file editing: it is
+  serve-time only, touches no source, and needs no `--remove` cleanup.
+- **Static HTML files:** `website-viewer.tsx` renders the file (today via an
+  opaque-origin `srcDoc` sandbox). The same injection happens at render.
+
+**Caveat that shapes the spec:** the stock `live.js` expects to reach the helper
+directly at `http://localhost:8400` and reads prelude globals
+`__IMPECCABLE_PORT__` / `__IMPECCABLE_TOKEN__`. That is fine only when the browser
+is on the same machine as the helper. See (c)/transport below — for a remote
+wiki-viewer the product must point those globals at proxied paths on its own
+origin. Injection itself is not the hard part; the transport target is.
+
+### (c) Can HMR hot-swap through the proxy, with fetch-source fallback for static? — NO for HMR (confirmed), but not a blocker
+
+The engine's hot-swap model: `live-wrap`/variant writes edit **real source files**;
+the app's own dev server HMR recompiles and pushes the swap; the browser overlay
+re-mounts. For no-HMR surfaces (static HTML), the overlay fetches source directly
+via the `--file` reply and swaps client-side.
+
+- **Static HTML fetch-source fallback:** clean fit. wiki-viewer serves the file and
+  can serve `/source`-equivalent reads; no dev server needed.
+- **Dynamic apps / HMR: CONFIRMED does not pass through the proxy today.** Verified
+  by inspection (convergent, not by a browser run):
+  1. No `upgrade`/WebSocket handler exists anywhere in `bin/` or `src/` (grep clean).
+  2. The proxy **strips** the `upgrade` header as hop-by-hop (`route.ts:20`) and the
+     route is an HTTP GET/POST handler; a Next App Router route handler cannot
+     service a WebSocket upgrade at all.
+  3. The optional HTTPS front-proxy (`bin/cli/serve.js:402`) only pipes `req -> res`;
+     no `server.on('upgrade')`.
+  4. Apps mostly run without HMR regardless: `defaultScript` prefers
+     `start > preview(built) > dev` (`app-runner.ts:139-144`), so the HMR `dev` mode
+     is the last-resort default.
+
+  **Why this is not a blocker.** Impeccable's variant swap is fundamentally a
+  browser-side operation the overlay performs; the app framework's HMR is only the
+  "smooth" way to get the freshly written source rendered. Two live options for
+  dynamic apps without WS work:
+  - **Full-reload-through-proxy:** after a variant write, force a page reload. The
+    page reloads over plain HTTP (already handled by the proxy's SW/bootstrap
+    machinery), the new markup renders, the overlay re-attaches via its durable
+    per-origin session. Functionally correct; loses only the flicker-free feel.
+  - **fetch-source fallback:** works directly for raw/static-HTML-shaped surfaces
+    (no dev server needed). It does **not** help compiled-framework apps, whose
+    rendered DOM is not their source, which is exactly why those need HMR or reload.
+
+  If the smooth HMR experience is wanted for compiled apps, the real work is adding
+  a WebSocket-upgrade passthrough: attach `server.on('upgrade')` on wiki-viewer's
+  standalone server and forward the socket to the child dev-server port (bounded,
+  but genuinely new proxy code). That is a deliberate scope decision, not a
+  prerequisite for shipping.
+
+**Net:** static-HTML surface is unaffected and is the correct tracer bullet.
+Dynamic-app hot-swap works via full-reload today, or gets the smooth path later via
+WS-upgrade passthrough.
+
+### (d) Can carbonize-on-accept map onto wiki-viewer write safety? — YES, but this is the real integration work
+
+`live-accept.mjs` writes directly to source with its own safety layer: per-file
+locks (`.impeccable/live/locks/<sha>.lock`, pid-liveness sweep), accept receipts
+for idempotency (`accept-receipts/<id>.json`, conflicting op returns
+`accept_receipt_conflict`), a generated-file guard, and a carbonize stitch-in that
+a later step rewrites to permanent form. `live-complete.mjs` gates on a
+`source_dirty` scan for leftover markers.
+
+wiki-viewer has its **own** parallel safety spine: `resolveWorkspacePath()`
+containment, `proper-lockfile` write locks, collab-state `409 COLLAB_ACTIVE`
+enforcement, and the web-tweak accept path's base-hash drift guard ("Accept is the
+only thing that writes the file, iff hashes still match").
+
+Two write/lock systems over the same files is the core hazard. Resolution options
+(a spec decision, not a blocker):
+
+- **Preferred:** route Impeccable's source writes through wiki-viewer's own write
+  path so containment, collab-state, and locking stay authoritative. Concretely,
+  the product performs the accept mutation using wiki-viewer's writer, reusing
+  Impeccable's *logic* (marker find, variant extract, carbonize) but not its raw
+  `fs.writeFile` + its own lockfile. Impeccable's accept logic is mechanical and
+  self-contained enough to host.
+- **Alternative:** let `live-accept.mjs` write, but fence it: ensure the target is
+  never a collab-`active` markdown file, confirm `.impeccable/` is path-denied and
+  gitignored (it is designed to be), and accept two lock systems that only ever
+  contend under concurrent edits (rare, and each is pid/owner-scoped).
+
+Either way, `.impeccable/live/` is runtime data: must be added to `resolveWorkspacePath`'s
+denied segments and gitignore, same treatment as `.proof`/`.git`.
+
+### (e) Can the two poll loops reconcile? — YES, clean 1:1 mapping
+
+wiki-viewer's attached-agent channel (`src/lib/proof/live/store.ts`) is already a
+poll/reply state machine strikingly close to Impeccable's:
+
+| Impeccable engine | wiki-viewer live/store |
+|---|---|
+| `GET /poll` long-poll (600 s) | agent held long-poll (25 s / 400 ms tick) |
+| event `type`: generate/steer/accept/discard/exit | request `kind`: generate/steer/accept/discard/exit (+ web.* kinds) |
+| session journal `sessions/<id>.jsonl` | `live.db` sessions + requests, monotonic `seq` |
+| pending → leased → replied | pending → delivered → working → resolved |
+| one pending event per lease | one-outstanding-per-session (`409 OUTSTANDING_REQUEST`) |
+| idempotency via accept receipts | idempotency key `live:<requestId>` |
+| accept = only write, receipt-guarded | Accept = only write, base-hash-guarded |
+
+The natural topology (**"product hosts engine, existing agent generates"**):
+
+1. wiki-viewer spawns the helper and injects `live.js` (served surface or static).
+2. The browser overlay talks to the helper (directly on localhost, or via proxied
+   endpoints when remote — see transport risk).
+3. wiki-viewer's **server** runs the Impeccable `/poll` loop (not a chat agent).
+4. On a `generate` event, wiki-viewer translates it into a request on its **own**
+   attached-agent channel (`live/store`), so the user's existing chat agent (AI
+   panel / MCP) produces the variants it already knows how to produce.
+5. wiki-viewer applies the variant writes (via `live-wrap` logic) and replies
+   `done --file` to the Impeccable `/poll`; HMR/fetch-source mounts them.
+6. On `accept`, wiki-viewer runs the accept/carbonize mutation through its write
+   path and completes.
+
+This preserves wiki-viewer's "live is speculative until Accept" invariant and reuses
+the agent channel that already exists, rather than duplicating it.
+
+---
+
+## Risks, ranked
+
+1. **Browser-to-helper transport when wiki-viewer is remote (highest).** `live.js`
+   assumes it can reach `localhost:8400` from the browser and read
+   `__IMPECCABLE_PORT__/__IMPECCABLE_TOKEN__`. wiki-viewer serves the app page from
+   *its* origin, and the browser may be on a different machine than the helper. The
+   product must proxy the helper's `/live.js`, `/events` (SSE), `/poll`-uplink,
+   `/source`, `/design-system.json`, `/annotation` through wiki-viewer's own origin
+   and set the injected globals to those proxied paths. This is a defined, bounded
+   bridge, but it is real code and it is the make-or-break for non-localhost use.
+2. **HMR WebSocket passthrough in app-proxy (CONFIRMED absent).** See (c). Not a
+   shipping blocker: static HTML is unaffected; dynamic apps work via
+   full-reload-through-proxy. The smooth HMR path for compiled apps is optional
+   later work (add `server.on('upgrade')` forwarding to the child dev port).
+3. **Dual source-write/lock systems (defined, needs a decision).** See (d). Prefer
+   routing writes through wiki-viewer's writer.
+4. **Runtime-dir hygiene.** `.impeccable/live/` must be path-denied
+   (`resolveWorkspacePath`) and gitignored so it is never served, traversed, or
+   committed. Low effort, must not be forgotten.
+5. **Auth/CSRF surface.** The helper's token is loopback-scoped; once proxied
+   through wiki-viewer, the proxied endpoints inherit wiki-viewer's session/agent
+   auth and CSRF Origin checks. Straightforward but must be explicit in the spec.
+
+None of these is a "does not work." They are the shape of the bridge.
+
+---
+
+## Recommendation
+
+**Proceed to `to-spec` for the unified Impeccable-live tweak, topology "product
+hosts engine, existing agent generates."** Risk #2 is now settled: HMR does not
+pass through the proxy today, but it is not required to ship. Scope the spec so the
+first slice is the static-HTML surface (no HMR, no proxy transport), dynamic apps
+land next via full-reload-through-proxy, and smooth compiled-app HMR is an explicit
+later ticket (WS-upgrade passthrough) rather than a gate.
+
+Do **not** fall back to the canceled isolated-origin/iframe architecture. The
+pivot rationale holds: Impeccable injects into the app's own page, so there is no
+parent to protect, which is exactly what deletes the old security problem.
+
+### Suggested first vertical slice (tracer bullet)
+Static HTML surface only (no HMR, no proxy transport complexity): spawn helper,
+inject `live.js` into the static preview, run the product-side `/poll` loop, wire
+one `generate` through the existing agent channel, land one `accept` through
+wiki-viewer's writer. That proves the whole spine end to end on the simplest
+surface, then dynamic apps (proxy transport + HMR) layer on top.
+
+---
+
+## Evidence base
+- Impeccable engine: `/home/sil/.pi/agent/skills/impeccable/scripts/{live,live-server,live-poll,live-inject,live-wrap,live-accept,live-complete,live-status,live-resume}.mjs`; `reference/live.md`, `reference/live-setup.md`.
+- wiki-viewer proxy injection point: `src/app/api/app-proxy/[...path]/route.ts` (serve-time HTML rewrite, `<script>` before `</head>`).
+- Dev/HMR launchable: `src/lib/app-runner.ts` (`defaultScript` start>preview>dev, `detectCmd`, port probe).
+- Existing agent channel: `src/lib/proof/live/store.ts` (session/request state machine); companion write-up `docs/web-tweak-live-channel.md`.
+- Static-HTML tweak today: `src/components/editor/website-viewer.tsx`; `src/lib/web-tweak/*`.

package/.next/standalone/.scratch/tweak-running-app/suggest-current-assessment.md

@@ -0,0 +1,39 @@
+# Current Suggest feature — assessment (main @ 23a5129)
+
+Verdict: REAL propose→pending→accept-writes/reject-discards pipeline with a
+proper "Suggesting mode", but COARSE and side-mounted, which is why it reads like
+comments.
+
+## Current flow (file:line)
+- Entry: bubble menu "Suggest edit" (bubble-menu.tsx:236-247) -> openSuggestForSelection (editor.tsx:973-975).
+- Block resolution: resolveSelectionBlock picks the WHOLE top-level block; selection offsets computed but UNUSED by Suggest (editor.tsx:267-361, 320, 352-358).
+- Popover: SuggestEditPopover, kind chips Replace/Insert after/Insert before/Delete, whole-block markdown textarea + optional reason (suggest-edit-popover.tsx:47-111). Posts {type:"suggestion.add", ref, kind, markdown?, basisDetail?} with 409 retry once.
+- Suggesting mode (typing capture): status-bar radio Editing/Suggesting (editor.tsx:1047-1068); banner (852-857). flush() diffs EACH top-level block vs snapshot: changed->replace, gone->delete, appended->insertAfter (use-suggestion-capture.ts:70-124), then REVERTS editor to snapshot. No autosave in suggesting (editor-store.ts:324-328,353-356).
+- Render: pending suggestions absolutely positioned OUTSIDE ProseMirror DOM (suggestion-card.tsx:44-48; editor.tsx:901-933). Two static panes "current / proposed" (suggestion-card.tsx:116-137).
+- Accept: suggestion.accept -> archive + supersede other pending same-ref (ops-applier.ts:872-891) + apply block.replace/insertAfter/insertBefore/delete (893-900) -> writes .md (972). Guard: 409 retry once.
+- Reject: archive, file unchanged (902-909).
+
+## Capability vs Google Docs suggesting
+- Suggesting mode toggle: PRESENT.
+- Edits captured, never written: PRESENT.
+- Inline text-range diffs (word-level): ABSENT (whole-block string equality).
+- In-context redline in prose: ABSENT (overlay card beside block, not in editor DOM).
+- Review diff clarity: PARTIAL (two static panes, no word-level diff).
+- Per-change accept/reject in place: PARTIAL (buttons on overlay card).
+- Accept writes doc: PRESENT. Reject discards: PRESENT.
+- Overlapping suggestions same range: DEGENERATE (N cards pile on same pixel, no switcher/offset).
+- Multi-author: PARTIAL (by-label; coarse whole-sidecar reload on fs events, no targeted push).
+- View-mode Suggest button: ABSENT despite ux-contracts §6.1 promising it (contract drift; only Comment has a view-mode button).
+
+## Gaps to make it real (T1 = perception, T2 = granularity)
+T1:
+1. In-doc redline rendering: TipTap mark extension (inserted=green underline, deleted=strikethrough) mounted INSIDE ProseMirror, replacing the absolute overlay card (editor.tsx:901-933, suggestion-card.tsx:44-48).
+2. Word-level diff in review affordance (suggestion-card.tsx:116-137) even before/if kept as a card.
+3. In-place accept/reject at the caret + overlapping-suggestion switcher ("1/3").
+4. View-mode Suggest button (parity with ViewModeCommentButton; view-mode-comment-button.tsx:26, editor.tsx:987).
+T2:
+5. Text-range suggestion model: from/to offsets within block markdown instead of whole-block; touches capture (use-suggestion-capture.ts:70-124), proposal (suggest-edit-popover.tsx:85-95), model (types.ts:167-200), applier (ops-applier.ts:830-900).
+6. Accept-merge: real text-range merge on accept instead of whole-block block.replace clobber (ops-applier.ts:893-900), for edits made while the block changed concurrently.
+
+## Cut impact (why we are NOT cutting)
+suggestion.accept is the ONLY human path that applies an edit (ux-contracts §6.2 :562). It is the review surface the tweak re-home routes the agent's rewrite into. Cutting kills the tweak review loop, orphans agent suggestion.add ops, breaks suggesting mode into silent data-loss, and breaks ux-contracts §6.1-6.3 + activity feed + tests.