wiki-viewer 2.12.0 → 2.14.0

package/.next/standalone/specs/changes/live-collab/proposal.md

@@ -0,0 +1,133 @@
+# Proposal: Live agent collaboration
+
+**Status:** Draft (implementing)
+**Change name:** live-collab
+
+## Problem
+
+Agent collaboration in wiki-viewer is pull-based and stateless. An agent calls the HTTP
+API when *it* decides to, applies an edit, and disconnects. There is no notion of a human
+sitting in the editor right now with an agent attached and waiting. A person cannot point
+at a specific block, say "shorten this," and get a response in the same breath.
+
+The impeccable skill's live mode nails that UX for websites: a human selects a rendered
+element, an already-attached agent receives the request over a held-open channel, responds
+in seconds, and the human iterates (steer) or resolves (accept/discard) in one continuous
+session. We want that interaction for wiki-viewer documents, starting with Markdown, without
+importing impeccable's HTML/DOM/HMR machinery (which does not apply to a text editor whose
+real render surface is TipTap over the true file).
+
+## Desired outcome
+
+A human editing a Markdown file can select a top-level block, ask an attached agent to act
+on it with a freeform instruction, and see the agent's proposal appear as a normal
+`activity record` in TipTap within seconds, then track it. The agent stays attached
+across the turn so the human can steer and iterate. This is the day-to-day primary mode of
+agent collaboration.
+
+## What we are actually emulating
+
+Not "selection-scoped edits." The load-bearing combination is:
+
+- **Selection** — the human points at a precise block; the agent's edit scope is bounded to it.
+- **Presence** — the agent holds a long-poll open and is *already blocked waiting*, so human
+  input wakes it immediately (semantically live, even though the transport is agent-initiated
+  long-poll, not literal server push).
+- **Live dispatch** — a human action in the editor pushes an event to that waiting agent now.
+- **Iteration** — generate -> steer -> accept/discard is one continuous session, not unrelated
+  HTTP calls.
+
+The presence + live-dispatch + session-continuity control plane is genuinely new surface. It
+sits *above* the existing mutation engine.
+
+## Architecture decision: one commit engine, two preflight policies
+
+We do **not** build a second write engine, and we do **not** rewrite the proof protocol.
+
+- Both live and async edits flow through the **same canonical commit path** (block-ops ->
+  `.md` + `.proof/` provenance -> lock -> audit -> idempotency). This is the invariant a
+  reviewer enforces: live and async both call the same commit function.
+- They differ only in a **preflight anchor policy**:
+  - `exact` (live): exact `blockRef` + exact `baseRevision` + deterministic idempotency.
+    Fail closed on any staleness. No fuzzy quote-matching, no moved-content search, no
+    cross-revision block-ref recovery, no auto-rebase. "This request applies to exactly what
+    the human selected at revision R; if that is no longer true, reject it."
+  - `recover` (async/MCP): today's full defensive machinery (durable block-ref recovery,
+    reconciliation) for stateless agents that may return hours later.
+
+It becomes a forbidden "second writer" only if someone applies live edits outside the
+canonical commit path. That is the line review enforces.
+
+### Live is primary; async is niche
+
+Unattended/remote agent edits (MCP, scheduled jobs) are a real but niche use case. Live is
+much more useful day-to-day. Therefore:
+
+- The `exact` (live) path is the default and where day-to-day effort and polish go.
+- The `recover` (async) path is kept but not centered or grown. When the two policies would
+  diverge on a design detail, the live path wins; async follows.
+- Proof's convolution (block-ref indirection, sidecar recovery) is **retained and quarantined
+  behind `anchorPolicy: "recover"`**, justified by the niche async user, never by the live UX.
+- We do **not** delete async machinery now. Revisit shrinking `recover` only if the niche user
+  disappears, and only after the live UX is proven and we can measure what actually fires.
+
+## Scope
+
+- New agent-facing live session/presence transport: attach (long-poll), event delivery, ACK,
+  session + request lifecycle. Per-workspace namespaced, auth via existing bearer + `X-Agent-Id`
+  + `X-Workspace`.
+- Editor affordance: select a top-level block -> "Ask agent" -> freeform instruction ->
+  dispatch a `generate` event; steer / accept / discard controls for the live turn.
+- Live request correlation: tier-2 provenance records carry `{liveSessionId, liveRequestId}`.
+- `exact` preflight policy wired into the existing commit path via `Idempotency-Key =
+  live:<requestId>`.
+- Minimal durable state in the existing SQLite db: live sessions + requests + delivery/ACK
+  cursor. No new on-disk journal directory.
+
+## Non-goals
+
+- No impeccable helper server, no injected `live.js`, no HTML/CSS source localization, no HMR
+  overlay, no variants, no scribble annotations.
+- No arbitrary text/code selection (Markdown top-level blocks only for v1).
+- No served-app / website collaboration.
+- **No second write engine / no `applyLiveEdit()` outside the canonical commit path.**
+- No rewrite of the proof protocol; no deletion of async recovery machinery.
+- No multiple concurrent proposals per block; one outstanding request per session/block.
+- No Yjs/CRDT/WebSockets; no multi-human concurrent editing.
+- No fuzzy recovery, rebasing, or heroic stale-request recovery on the live path.
+
+## Risks
+
+1. **Stale human intent** (top correctness risk). Human selects block at R1, sends
+   instruction, edits manually to R2, agent then processes. The agent must use the request's
+   original `baseRevision`; on conflict the request is marked `stale`/`conflicted` and a new
+   human request is required. Fail closed.
+2. **Replayed requests -> duplicate edits.** Solved by deterministic
+   `Idempotency-Key = live:<requestId>`; the agent must not invent a fresh key after recovery.
+3. **Structural edits destroying block identity** (move/split/merge/delete while pending).
+   Fail closed via revision + exact block-ref check; no fuzzy recovery in v1.
+4. **Presence ambiguity** (working vs crashed vs network-gone vs forgot-to-reopen-poll).
+   Handled with a small lease/timeout: timeout means disconnected; reconnect resumes from last
+   ACK. Do not over-model presence.
+5. **Accidentally creating another editor protocol.** Red flag if the live layer starts adding
+   live snapshots / live accept-writer / live diff format. Those already belong to tier-2.
+
+## Acceptance criteria
+
+1. An agent can attach to a workspace live session over a held-open long-poll and receive a
+   `generate` event pushed by a human editor action within ~1s of the action.
+2. Selecting a top-level Markdown block in TipTap and submitting an instruction produces a
+   tier-2 activity/audit provenance edit committed through the existing commit path, correlated with the live
+   request id in provenance.
+3. The human can steer (send a follow-up instruction in the same session) and the agent
+   receives it on its next held poll.
+4. Accept and revert of the resulting activity/audit provenance work through the existing editor UI and are
+   reported back to the live session as `resolved{accepted|reverted}`.
+5. A manual edit that changes the target block's revision before the agent commits causes the
+   live request to fail closed as `stale`, not a silent re-interpretation.
+6. Replaying the same live request (agent crash before ACK, then reconnect) does not produce a
+   duplicate edit, verified via the deterministic idempotency key.
+7. Live edits and existing async tier-2 edits both go through one commit function; there is no
+   separate live filesystem-mutation path.
+8. `pnpm test`, `pnpm typecheck`, `pnpm lint` pass; new behavior covered by tests in
+   `src/tests/proof/`.

package/.next/standalone/specs/changes/live-collab/requirements.md

@@ -0,0 +1,91 @@
+# Requirements: Live agent collaboration
+
+Each requirement is observable behavior with GIVEN/WHEN/THEN scenarios.
+
+## R1 — Agent attaches and holds presence
+
+GIVEN a registered agent with a valid bearer token, `X-Agent-Id`, and `X-Workspace`
+WHEN it `POST /api/agent/live/attach`
+THEN a live session is created (or the existing open one reused) and `{ sessionId }` returned
+AND while the agent holds `GET /api/agent/live/poll` open, the session's `agent_last_seen`
+    is refreshed so the session reports `attached: true`.
+
+## R2 — Human dispatch reaches the waiting agent quickly
+
+GIVEN an attached agent holding a live poll
+AND a human editing a Markdown file with a top-level block selected
+WHEN the human submits an instruction via `POST /api/wiki/live/request`
+    `{ path, blockRef, baseRevision, kind: "generate", instruction }`
+THEN the held agent poll returns `{ type: "generate", request: { requestId, path, blockRef,
+    baseRevision, instruction } }` within ~1s of the submission (not on a fixed slow interval).
+
+## R3 — Agent edit lands as a activity/audit provenance through the existing engine, correlated
+
+GIVEN a delivered `generate` request with id `<rid>`
+WHEN the agent `POST /api/agent/files/<path>` with `Idempotency-Key: live:<rid>`,
+    `baseRevision` equal to the request's, and an op carrying `inResponseTo: "live:<rid>"`
+THEN the edit is committed by the existing `applyOps` path, written as clean markdown whose
+    `ActivityAttrs.inResponseTo === "live:<rid>"`
+AND no new/separate write path is used.
+
+## R4 — Steer within the same session
+
+GIVEN an open live session with a resolved-or-working prior turn
+WHEN the human submits another `POST /api/wiki/live/request { kind: "steer", instruction }`
+THEN the agent receives it on its next held poll as `{ type: "steer", ... }`.
+
+## R5 — Accept / revert reported to the session
+
+GIVEN a activity/audit provenance produced by a live request
+WHEN the human accepts or reverts it through the existing editor proof UI and the client
+    posts `POST /api/wiki/live/request { kind: "accept" | "discard" }`
+THEN the corresponding `live_request` is marked `resolved` with
+    `outcome = accepted | reverted`.
+
+## R6 — Stale intent fails closed
+
+GIVEN a `generate` request captured at `baseRevision = R`
+AND the human manually edits the file so its revision becomes `R+1` before the agent commits
+WHEN the agent commits with `baseRevision = R`
+THEN `applyOps` returns `409 STALE_REVISION`, the agent replies `error`, and the
+    `live_request` is marked `stale`
+AND the document is NOT silently re-edited against `R+1`.
+
+## R7 — Replay safety
+
+GIVEN a `generate` request `<rid>` whose tier-2 edit already committed
+AND the agent crashed before replying, then reconnects and re-POSTs the same edit
+WHEN it reuses `Idempotency-Key: live:<rid>` with the identical payload
+THEN the cached tier-2 response is returned and NO duplicate edit is produced.
+
+## R8 — One outstanding request per session
+
+GIVEN a session with a non-terminal (`pending`/`delivered`/`working`) request
+WHEN a human submits another `generate` for that session
+THEN the dispatch is rejected with a clear conflict status until the prior turn resolves.
+
+## R9 — Presence timeout
+
+GIVEN a session whose agent stopped polling longer than the lease TTL
+WHEN the editor queries `GET /api/wiki/live/status`
+THEN it reports `attached: false`.
+
+## R10 — Auth and workspace isolation
+
+GIVEN two workspaces
+WHEN an agent attached to workspace A polls
+THEN it never receives live requests enqueued for workspace B
+AND all agent live routes reject requests failing `checkAuth` / `enforceScope`.
+
+## R11 — Editor affordance
+
+GIVEN the Markdown editor with a top-level block selected
+WHEN the user opens the bubble menu
+THEN an "Ask agent" action is present that opens an instruction popover and dispatches R2.
+
+## Verification
+
+- `pnpm test` (proof suite) with new tests in `src/tests/proof/` covering R1-R10 at the
+  store + route level.
+- `pnpm typecheck`, `pnpm lint`, `pnpm build` pass.
+- R11 verified by component wiring (bubble-menu action present, dispatch call shape correct).

package/.next/standalone/specs/changes/live-collab/tasks.md

@@ -0,0 +1,39 @@
+# Tasks: Live agent collaboration
+
+## Backend
+- [x] Live store (`src/lib/proof/live/store.ts`): SQLite `live.db`, session + request
+      tables, presence TTL, one-outstanding-per-session enqueue, deterministic ids.
+- [x] Agent transport: `POST /api/agent/live/attach`, `GET /api/agent/live/poll`
+      (long-poll, presence via held request), `POST /api/agent/live/reply`.
+- [x] Human dispatch: `POST /api/wiki/live/request` (generate/steer/accept/discard,
+      CSRF-checked), `GET /api/wiki/live/status`.
+- [x] Correlation: poll event surfaces `idempotencyKey = live:<id>` and
+      `inResponseTo = live:<id>` for the agent to carry into the Tier-2 edit. No new
+      write path; commit stays `applyOps`.
+
+## Frontend
+- [x] `EditorBubbleMenu`: add "Ask agent" action (`onAskAgent`).
+- [x] `AskAgentPopover`: instruction input, agent-attached indicator, dispatch to
+      `/api/wiki/live/request`, stale/conflict/detached feedback.
+- [x] `editor.tsx`: `openAskAgentForSelection` using existing `resolveSelectionBlock`,
+      render popover, wire prop.
+
+## Tests
+- [x] `src/tests/proof/live-collab.test.ts` covering R1, R2/R3, R5, R6, R7, R8, R9, R10.
+
+## Docs
+- [x] `agents/wiki-viewer-skill/SKILL.md`: "Live collaboration" section (loop + rules).
+- [x] proposal.md / requirements.md / design.md.
+
+## Verification
+- [x] `pnpm typecheck` clean.
+- [x] `pnpm lint` clean.
+- [x] `pnpm test` — 656 pass, floor 648 (8 new live-collab tests included).
+
+## Deferred / out of scope (recorded, not built)
+- R4 steer + R11 editor-affordance covered by wiring, not a dedicated automated test
+  (steer reuses the same enqueue/poll path proven by R2/R8).
+- Client-side agent runtime that actually attaches and edits (this change ships the
+  server channel + human UI; the agent side is the skill contract in SKILL.md).
+- Async `recover` policy untouched; live path relies on `applyOps`' built-in exact
+  revision/ref checks. No deletion of proof machinery.

package/.next/standalone/specs/changes/live-collab-web/findings-termdeck.md

@@ -0,0 +1,120 @@
+> SUPERSEDED for the v1 shape. TermDeck is retained here as *ideation reference
+> only*. The actual build target is impeccable-grade (variant preview bound to an
+> immutable candidate source patch, write-on-accept). See `proposal.md`. Do not
+> implement the shallow "prose to agent, reload" model described at the bottom of
+> this file.
+
+# Gap 2 research: TermDeck's "Tweak mode" and what it means for wiki-viewer
+
+Source studied: `huytieu/termdeck-localterm` (a fork of `localterm`, whose wiki
+is itself *inspired by wiki-viewer*). Commit `25e6850`. The relevant feature is
+**Tweak mode**: "point at the pixel, the agent gets the selector."
+
+## What TermDeck actually built
+
+Much simpler than impeccable. No HMR, no variants, no DOM→source localization,
+no write-on-accept. The whole thing is ~200 lines of injected JS + a proxy + a
+prose message to a terminal agent. Three pieces:
+
+### 1. An injected element-picker script (`packages/server/src/artifact-picker.ts`)
+A self-contained IIFE (`ARTIFACT_PICKER_JS`) appended into any rendered HTML.
+- Hover highlights the element under the cursor (`elementFromPoint`), click marks it.
+- Builds a **robust CSS selector** by walking up ≤6 ancestors: prefers `#id`
+  (and stops), else `tag.class1.class2` (first two non-picker classes), adds
+  `:nth-of-type(n)` only when siblings share the tag. (`cssPath()`)
+- Captures a **snippet** (`outerHTML`, truncated to ~400 chars → open tag + text)
+  and the element's `textContent` (≤200 chars).
+- Talks to the parent **only via `window.postMessage`** — protocol
+  `{source:'termdeck-picker', cmd:'enable'|'disable'|'remove'|'clear'}` down,
+  `{event:'ready'|'selected', id, selector, tag, snippet, text, rect}` up.
+- Because it's postMessage-only, it works from a **sandboxed null-origin iframe**
+  (no `allow-same-origin` needed). Overlay chrome is fixed-position, pointer-events
+  none, huge z-index, and self-marked so it never picks itself.
+
+### 2. Two HTML surfaces get the picker (`apps/terminal/src/components/wiki-detail.tsx`)
+- **Local `.html` file** → rendered via `srcDoc`, with `<script src="/api/artifact/picker.js">`
+  appended before `</body>`.
+- **Remote deploy URL** → fetched server-side through `/api/artifact/proxy`, which
+  strips CSP `<meta>`, injects a `<base href>` so relative assets resolve to the
+  real origin, and **inlines** the picker (`injectArtifactChrome`). Manual redirect
+  following detects cross-host SSO gates and shows a readable notice instead of a
+  blank login page.
+- The parent React component bridges: translates the in-frame element rect to page
+  coords (using the iframe's own offset) and anchors a "what should change?" note
+  popover. One pending pick at a time; a batch tray stacks several.
+
+### 3. Dispatch is just prose to a terminal (`sendTweaks`)
+No structured edit protocol at all. It formats:
+```
+In the artifact `path`, apply these N edits to the matching elements:
+
+Tweak 1 — `selector` (<tag>):
+  Current: <snippet>
+  Change: <your note>
+```
+…and sends it as one chat message into the linked terminal session (`chatAboutSelection`).
+The agent (Claude in a shell) reads it, finds the source, edits the file itself, the
+dev server/HMR reloads the iframe. Accept/revert is just "look at the page again."
+
+## How this maps onto wiki-viewer
+
+We are closer than TermDeck was, in the parts that matter:
+
+- **Injection seam already exists.** `src/app/api/app-proxy/[...path]/route.ts`
+  already `rewriteHtml()`s proxied app HTML and injects a `<script>` + a service
+  worker. Adding a picker `<script>` is the same move TermDeck makes.
+- **Sandbox already correct.** `website-viewer.tsx` sandboxes without
+  `allow-same-origin`; a postMessage-only picker fits that exactly (per AGENTS.md
+  security model: never combine `allow-scripts` + `allow-same-origin`).
+- **We already have live presence + a real dispatch channel.** TermDeck fires a
+  prose message into a terminal. We have the live-collab control plane
+  (`/api/wiki/live/request` → attached agent → reply). A web "tweak" is just a
+  new live request `kind` carrying `{selector, tag, snippet, note}` instead of
+  `{blockRef, instruction}`.
+
+What we do NOT get for free, and what makes web genuinely different from markdown:
+
+- **No source identity.** For markdown, a block-ref maps a rendered node to a
+  canonical source region and the edit commits through tier-2. For an arbitrary
+  HTML app, a CSS selector does **not** identify a source location — the agent
+  must *find* where that element is generated (JSX, template, framework) and edit
+  that. That search is the agent's job (exactly as in TermDeck), not the protocol's.
+- **No activity/audit provenance / accept-revert.** The edit lands in real source files via tier-1
+  raw FS (or the agent's own shell), not as a reviewable block-op. Review is
+  "reload the preview." This is a *different persistence model* and must not be
+  bolted onto the tier-2 engine.
+
+## Recommended shape for wiki-viewer Gap 2 (v1)
+
+Steal TermDeck's model almost verbatim, ride our existing rails:
+
+1. **Picker script** served/injected into (a) local `.html` previews via `srcDoc`
+   and (b) proxied node-apps via the existing `rewriteHtml` seam. postMessage-only.
+   Reuse TermDeck's `cssPath`/`snippet` logic (MIT — reimplement, credit in comment).
+2. **Element-select UX** in `website-viewer.tsx` / `node-app-viewer.tsx`: a "Tweak"
+   toggle, hover highlight, click → note popover, optional batch tray.
+3. **Dispatch via live channel**, new request kind `tweak` (or `web.tweak`):
+   `{ path, selector, tag, snippet, note }`. The attached agent receives it on poll.
+4. **Agent edits real source** through tier-1 raw FS (`/api/agent/fs/*`), not tier-2.
+   No activity/audit provenance. The preview reloads (node-app HMR, or re-fetch for static HTML).
+5. Explicit non-goals for v1: no HMR variant preview, no write-on-accept staging,
+   no DOM→source auto-localization, no CSS-only inline patching. The agent finds
+   and edits source, same as a human would from a bug report.
+
+## The load-bearing decision (needs Anh)
+
+Web tweak is a **second persistence model** (edit real source, reload preview),
+distinct from markdown live (block-op activity/audit provenance, activity tracking). That is fine and
+matches reality — but it means "live collaboration" becomes an umbrella over two
+concretely different flows. Options:
+
+- **A. Two explicit modes under one presence channel** (recommended): same attach/
+  poll/reply + session, request `kind` distinguishes `generate|steer` (markdown,
+  tier-2) from `tweak` (web, tier-1). One agent runtime handles both. Honest about
+  the two persistence models; minimal new surface.
+- **B. Keep web tweak entirely separate** (TermDeck-style, prose to a terminal),
+  not wired to the proof/live stack at all. Simplest, but throws away the presence
+  channel we just built and duplicates dispatch.
+
+Recommend A. Ship the picker + element UX first (pure frontend + injection, no
+protocol risk), then wire the `tweak` request kind onto the existing live channel.

package/.next/standalone/specs/changes/live-collab-web/proposal.md

@@ -0,0 +1,184 @@
+# Proposal: impeccable-grade live collaboration for web surfaces
+
+## Problem
+
+Live collaboration (markdown) shipped: point at a rendered block, an attached
+agent edits it in-session, the change lands as a reviewable activity/audit provenance. That
+covers `.md`. It does **not** cover the web surfaces wiki-viewer renders in an
+iframe: local `.html` previews (`website-viewer`) and running node-apps behind
+`app-proxy` (`node-app-viewer`).
+
+For web, the analogous experience is impeccable's: point at a rendered DOM
+element, describe the change, **see it applied live on the real page before
+anything is written**, then accept (commit to source) or discard (revert, source
+never touched). We want that experience baked in, at impeccable's depth, not a
+shallow "send a note to a terminal" imitation.
+
+## Desired outcome
+
+In a web preview, the user toggles **Tweak** mode, clicks an element, and types
+what should change. The attached agent returns a **preview patch** that is
+applied inside the iframe via postMessage, so the user sees the variant on the
+live page immediately. The user then:
+
+- **Accept** → agent writes the real source (tier-1 raw FS); preview reload
+  reflects the committed change.
+- **Discard** → the DOM patch is reverted in-frame; no source was touched.
+
+Same attach / poll / reply presence channel already built for markdown. One
+attached agent runtime handles both markdown (`generate`/`steer`) and web
+(`web.tweak`) requests.
+
+## Why this is achievable with minimum new machinery
+
+Impeccable's expensive invention was the variant hot-swap pipeline. We get the
+equivalent almost free because our web surfaces are **already iframes** and we
+already have a **postMessage element picker** (`src/lib/web-tweak/picker.ts`):
+
+- **Variant preview = a DOM/CSS patch applied inside the iframe**, not an HMR
+  rebuild. The picker gains `apply`/`revert` commands; the parent posts the
+  agent's patch in, the element visibly changes, the original is retained for
+  revert. The DOM patch is the *rendering* of the variant; the bound candidate
+  source patch is the *thing accept commits*. Both are produced by the single
+  `web.tweak` reply so accept never re-synthesizes.
+- **Presence + dispatch already exist** (the live channel we shipped).
+- **Injection seam already exists**: `app-proxy` `rewriteHtml()` injects scripts
+  into proxied app HTML; static `.html` can carry the picker via `srcDoc` or the
+  assets route. The picker is postMessage-only, so it runs in the existing
+  no-`allow-same-origin` sandbox with no security regression.
+- **Source write already exists**: tier-1 raw FS (`/api/agent/fs/*`).
+
+## The deliberate divergence: write-on-accept
+
+Web live is **write-on-accept**: source is untouched until the user accepts a
+previewed variant. This is the *opposite* of markdown live (write-first, then
+review the activity/audit provenance). That divergence is intentional and is *why* the claim
+holds. Each surface uses the persistence model that is impeccable-grade for it:
+
+| | Markdown live | Web live (this) |
+|---|---|---|
+| Preview | activity/audit provenance in TipTap over real file | DOM patch in iframe, source clean |
+| Persistence | write-first, activity tracking span | write-on-accept to real source |
+| Write path | tier-2 block-ops | tier-1 raw FS |
+| Identity | block-ref → source region | CSS selector (agent localizes source) |
+
+Both ride one presence channel and one agent runtime. Two persistence models,
+one product promise.
+
+## The preview transaction (the core object)
+
+Identity for a web tweak is NOT just a CSS selector. Every tweak is a versioned
+**preview transaction**, keyed by a server-issued `previewId`:
+
+```
+previewId
+  ->  selected DOM fingerprint  (selector, tag, snippet, text)
+  ->  domPreviewOps             (ephemeral, applied in-frame; data-only)
+  ->  candidateSourcePatch      (immutable; the exact edit accept will write)
+  ->  baseFiles[]               ({ path, sha256 }) the candidate was derived against
+  ->  status                    requested | preview-ready | accepted | discarded | invalidated
+```
+
+`web.tweak` reply MUST carry both `domPreviewOps` and `candidateSourcePatch`
+plus `baseFiles`. Accept commits `candidateSourcePatch` verbatim **iff** every
+`baseFiles[].sha256` still matches on disk; otherwise the transaction is
+`invalidated` (user re-tweaks). Accept never re-localizes or re-synthesizes.
+This is what makes it a *reviewed variant* rather than a *visual proposal*.
+
+## Scope
+
+1. Extend the picker protocol with `apply`/`revert` (ephemeral DOM patch inside
+   the iframe) plus original-state retention. Patch language is **data-only**:
+   text, attributes (denylist: event handlers, `javascript:` URLs, script/iframe
+   insertion, form/nav targets), and inline style. No arbitrary JS/eval.
+2. New live request kind `web.tweak` carrying `{ path, previewId, selector, tag,
+   snippet, note }`; agent reply carries `{ domPreviewOps, candidateSourcePatch,
+   baseFiles }`. The candidate source patch is derived at reply time, not accept.
+3. Accept/discard control plane on the live channel: `web.accept` / `web.discard`
+   reference a `previewId`. `web.accept` verifies `baseFiles` hashes then commits
+   `candidateSourcePatch` via tier-1; mismatch -> `invalidated`, no write.
+4. Mount Tweak UX in `website-viewer.tsx` and `node-app-viewer.tsx`: toggle,
+   hover highlight (from picker), note popover, preview state, accept/discard bar.
+   Accept/Discard originate ONLY from trusted parent UI, never from an iframe
+   message.
+5. Inject the picker: proxied apps via `rewriteHtml`; static `.html` via the
+   assets/srcDoc path.
+6. Agent runtime: extend `runLiveLoop` to handle `web.tweak` (produce DOM preview
+   ops AND candidate source patch + base hashes in one reply) and `web.accept`
+   (verify hashes, tier-1 write). Passthrough reference handler for smoke tests.
+
+## Message-trust rules (iframe -> parent)
+
+Every iframe->parent message is hostile input:
+
+- Verify `event.source === iframe.contentWindow` (opaque origin makes
+  `event.origin` checks insufficient on their own).
+- Strict schema validation; reject unknown fields/types.
+- Iframe messages may only carry *selection* facts (selector/snippet/rect). They
+  MUST NOT be able to trigger a filesystem write or an accept. Accept/discard are
+  driven by parent control state keyed on `previewId`.
+- No nonce is assumed secret from page JS sharing the frame.
+
+## v1 surface note (post-review)
+
+Web tweak in v1 is offered **only on the opaque-origin static-HTML preview**
+(the `srcDoc` path in `website-viewer`). It is intentionally **not** offered for
+running node-apps: the proxied app is served from the wiki-viewer origin with an
+`allow-same-origin` iframe (required for the app to run), so hostile page JS
+could reach `parent.document` and click Accept, bypassing the postMessage
+boundary. Node-app tweak requires a dedicated isolated proxy origin and is
+deferred. The picker is still injected into proxied HTML (harmless, inert without
+parent postMessage) so the capability is ready once an isolated origin exists.
+
+## Non-goals (v1)
+
+- No HMR/build-pipeline variant rebuild (DOM patch preview is the mechanism).
+- No automatic DOM→source localization by the *protocol*; the agent finds the
+  source (as a human would), the selector+snippet+note is its lead.
+- No multi-variant A/B stacks; one pending preview per element.
+- No CSS-only inline persistence; accept always writes real source.
+- No collaboration on third-party remote sites we don't own the source for.
+- No change to the markdown tier-2 engine (must not bolt web preview onto it).
+
+## Risks
+
+- **Preview/source fidelity gap** (the main risk): a DOM mutation may map to a
+  materially different source change (CSS token vs prop vs conditional vs shared
+  class), a framework re-render may overwrite the DOM patch, or one rendered
+  instance may map to a component affecting many instances. Mitigation: the
+  candidate source patch is produced *with* the preview and bound to `previewId`;
+  accept commits that candidate, and the post-accept reload is *verification*
+  (does the reviewed candidate render as expected), not the first time source is
+  interpreted. If the agent cannot produce a confident candidate patch at
+  `web.tweak` time, it returns preview-only with `candidateSourcePatch: null` and
+  the UI shows "visual only, not acceptable" rather than offering a false accept.
+- **Base drift between preview and accept**: user, watcher, HMR, or another agent
+  changes the source files after preview. Mitigation: accept verifies
+  `baseFiles[].sha256`; any mismatch invalidates the transaction (no write, user
+  re-tweaks). Never opportunistically rebase.
+- **Two persistence models** invite confusion. Mitigation: explicit request-kind
+  namespacing (`web.*`), separate write path, this spec's boundary table, and a
+  line-review rule: `web.*` never touches tier-2, markdown never touches tier-1.
+- **Sandbox**: keep postMessage-only; never add `allow-same-origin` to a
+  script-enabled preview.
+
+## Acceptance criteria
+
+- Toggling Tweak in a web preview highlights elements on hover and captures a
+  selector+snippet on click.
+- A note dispatched for a selected element reaches the attached agent as a
+  `web.tweak` request on the existing poll channel, carrying a `previewId`.
+- The `web.tweak` reply produces a preview transaction with `domPreviewOps`,
+  `candidateSourcePatch` (or explicit null), and `baseFiles` hashes.
+- The DOM preview ops are applied inside the iframe and visibly change the live
+  page with no source file changing (verified: file sha256/mtime unchanged).
+- Discard reverts the element to its original state in-frame; source unchanged.
+- Accept with matching `baseFiles` hashes writes `candidateSourcePatch` via
+  tier-1 and reloads the preview; accept with a stale hash invalidates and writes
+  nothing.
+- A `candidateSourcePatch: null` transaction offers no accept (visual only).
+- An iframe->parent message cannot trigger a write or accept; accept/discard come
+  only from parent control state. (protocol-abuse test)
+- `event.source` identity is verified on picker messages. (protocol-abuse test)
+- No `allow-same-origin` is combined with `allow-scripts` on any tweak preview.
+- Markdown live behavior and tier-2 engine are unchanged (existing tests green).

package/.next/standalone/specs/changes/live-unified/design.md

@@ -0,0 +1,49 @@
+# Unified Live — design & contracts
+
+Grounded in recon (2026-08-15). File refs are current.
+
+## Server: markdown proposal store (write-on-accept)
+Mirror the web-tweak preview-store transaction, but for markdown. New store `src/lib/proof/live/md-proposal-store.ts` (or extend preview-store with `surface` tag — prefer a separate table to avoid destabilizing shipped web-tweak).
+
+Table `md_proposal`:
+- `previewId` (pk), `workspace_id`, `path`, `block_ref`, `base_revision`, `base_block_hash`,
+- `request_id`, `state` (requested|ready|resolving|accepted|discarded|invalidated),
+- `variants` JSON `[{variantId, label, markdown}]`, `selected_variant_id`,
+- `created_at`, `resolved_at`.
+Atomic `claimForResolve(previewId)`; drift check compares current block markdown hash to `base_block_hash` under file lock at accept.
+
+### Human routes (UI-only, trusted)
+- `POST /api/wiki/live/md-request` → `{path, blockRef, baseRevision, baseBlockHash, instruction, selectionText?, selectionStart?, selectionEnd?}` → creates proposal (state=requested), enqueues live request (kind `generate`, carries `previewId`), returns `{previewId, requestId}`.
+- `GET /api/wiki/live/md-status?previewId=` → `{state, variants, selectedVariantId, ...}`.
+- `POST /api/wiki/live/md-resolve` → `{previewId, action: accept|discard, variantId?}`. Accept: claim → re-read block, verify hash == base_block_hash (else `invalidated`) → commit chosen variant verbatim via tier-2 `block.replace` at `base_revision` → state=accepted. Discard: claim → state=discarded. **No agent auth accepted here.**
+
+### Agent submit (MCP backend)
+Reuse existing `/api/agent/live/*`. Extend the agent web-preview submit concept for markdown, OR add `POST /api/agent/live/md-preview` → `{previewId, requestId, variants:[{variantId,label,markdown}]}` (2–5 variants enforced) → validates ownership/scope, stores variants, state=ready, marks request resolved(working→ready). Data-only (markdown strings); no file write.
+
+## MCP tools (packages/wiki-viewer-mcp)
+Delete: `live` subcommand, `runLiveLoop`, `passthroughHandler`, `llmHandler`, `claudePrompt`, `passthroughWebHandler`, `passthroughVariantsHandler`, and loop/reference tests in `live-client.test.ts`. Keep `LiveClient.attach/poll/reply/snapshot/applyTier2Ops` as tool backends.
+
+New tools in `server.ts` + `tool-schemas.ts` + `tool-handlers.ts`:
+- `live_attach` → `{sessionId, workspaceId}`.
+- `live_poll {sessionId, afterSeq}` → held ~25s; returns next request `{requestId, kind, surface, previewId?, path, blockRef, baseRevision, instruction, selectionText?, ...}` or `{type:"timeout"}`. Model calls it in a loop while attending.
+- `live_snapshot {path}` → tier-2 blocks + revision (for finding target block markdown).
+- `live_reply {requestId, status}` → working|done|error.
+- `live_submit_markdown {previewId, requestId, variants:[{variantId?,label,markdown}]}` → posts to md-preview; enforces 2–5 variants; server derives variantId if absent.
+- `live_submit_web {previewId, requestId, variants|domPreviewOps, candidateSourcePatch, baseFiles}` → posts to existing web-preview.
+
+Agent flow (documented in skill): call `live_attach` once → loop `live_poll` → on `generate` markdown request: `live_snapshot`, produce 2–5 rewrites of the target block, `live_submit_markdown`, `live_reply done` → loop. Agent NEVER accepts.
+
+## Client: shared Live overlay + ephemeral markdown preview
+- Presence component (new, shared) `src/components/editor/live-presence.tsx`: polls `/api/wiki/live/status`; solid/amber + Connect; grace window.
+- Markdown ephemeral preview: integration point `editor.tsx:435-464` (block annotation effect provides `[data-block-ref]` slots + `blockRefPositions`). On proposal `ready`, render selected variant via `markdownToHtml(candidate, {pagePath, sanitize: isViewing})` into an overlay pinned to the target block slot; hide original block visually; cycle = swap candidate; **Accept** → POST md-resolve accept (server commits) then reload snapshot; **Discard** → drop client state only. Never call `editor.commands.setContent` for preview; never write activity/audit provenance for pending preview.
+- Target selection reuses `resolveSelectionBlock` (block primary, text-range as context fields).
+- Verb/label alignment in `web-tweak-overlay.tsx`: Target/Variant/Proposal/Accept/Discard/Go.
+
+## Delete from live path (client)
+`run-review-bar.tsx`, `instruction-queue-bar.tsx`, `instruction-popover.tsx`, activity/audit provenance hover popover + delegation IF no pending-review remains, `onInstruct` in `bubble-menu.tsx` and its editor wiring, `draftInstructions`/`sentInstructions` state. Keep: `ActivityProvenance` extension, sanitize-schema activity/audit provenance support, `wrapAsActivityProvenance`/`unwrapActivityProvenances`/`revertActivityProvenance` (accepted provenance), server accepted-provenance ops.
+
+## Keep as-is
+Tier-2 `/api/agent/files` commit path (stale/idempotency), web-tweak resolve/status/picker routes, content-clock revision, block-ref frontmatter offset fix, filesystem MCP tools.
+
+## Test floor
+Current floor 693–694. Replace deleted live/loop tests with: md-proposal store lifecycle (requested→ready→accept commits verbatim / discard leaves file identical / invalidated on drift), MCP tool-handler tests, presence honesty. Keep suite green.