wiki-viewer 2.16.0 → 2.16.1

package/.next/standalone/.scratch/tweak-running-app/craft-checklist.md

@@ -0,0 +1,52 @@
+# Design-fidelity / craft checklist (acceptance-level)
+
+Purpose: the old Tweak UX was loved for its *craft* — the elements, interactions,
+and polish, not just that it worked. This checklist carries that craft into the
+re-home (Comment + Suggest better UX + Copy-as-prompt). Treat each line as an
+acceptance item a reviewer verifies by hand, not just "the feature works."
+
+Applies to: the Suggest inline-redline surface, its review popover, the
+Copy-as-prompt surface, and any composer/popover added. Retire only the
+engine-bound widgets (see bottom); keep everything else.
+
+## Keyboard & input
+- [ ] Primary commit on **Cmd/Ctrl+Enter** in every text input (composer, note, reply).
+- [ ] **esc** cancels; **outside-click while the input is empty** = cancel (never a silent commit).
+- [ ] Inputs **autofocus** on open; focus returns sensibly on close.
+- [ ] Full keyboard path through review: open popover, cycle overlap (◂/▸), Accept/Reject without the mouse.
+
+## Anchoring & layout
+- [ ] Popovers anchor to their target and are **viewport-clamped** (min ~8px margin, never off-screen).
+- [ ] Scroll containment: long content scrolls inside the popover/panel (max-height viewport-safe), page doesn't jump.
+- [ ] Tap targets meet **44px** touch slop on coarse pointers (badges use a 16px glyph with 44px hit area).
+
+## Motion (use existing tokens)
+- [ ] Transitions use `--motion-fast 100ms` / `--motion-base 150ms`; nothing janky or instant-pop.
+- [ ] Suggesting-mode flush **crossfades** typed text into posted redline in place (no flash-revert).
+- [ ] Respect `prefers-reduced-motion`.
+
+## Visual language (existing tokens only — no new palette)
+- [ ] Redline uses `--success` (insert, underline) / `--destructive` (delete, strike); block changes get left-bar + `*-soft` wash.
+- [ ] Agent-authored ranges: 45° hatched texture + `✦` glyph, visibly distinct from human.
+- [ ] **Mono snippet chips** for block/selector references; `pre` snippet blocks for quoted source; tag chips where a kind is shown.
+- [ ] Tight editorial type scale (~10.5–13px on chrome, serif for prose/diff), warm-paper surfaces, soft `--shadow-*` elevation.
+
+## Feedback & states
+- [ ] Copy actions show a **"Copied" flip for ~1500ms**, then revert.
+- [ ] Clipboard-blocked (non-secure context) falls back to a **"Show text"** manual-copy box; one code path, always numbered `1.`.
+- [ ] Hover-reveal for secondary row controls (remove/copy) on fine pointers; always visible on touch.
+- [ ] Honest empty state = **zero chrome** (no stray bars/placeholders).
+- [ ] Overlap switcher shows **N of M** and live-swaps the prose redline as you cycle.
+- [ ] Drift / stale-anchor never silently drops: explicit `⚠ target changed` with Re-anchor / Remove.
+- [ ] Author + kind attribution visible on every comment/suggestion (`by`, human vs agent).
+
+## Copy-as-prompt surface specifics
+- [ ] Reads only persisted comments/suggestions; creates/writes nothing.
+- [ ] Per-item ⎘ copy **and** Copy-all; default scope = open/unresolved items.
+- [ ] Emits the established string: ``Edit the file `X` (a Markdown document). Apply these changes:\n\n1. `snippet`: text`` .
+
+## Retire (engine-bound widgets — do NOT resurrect)
+- Bottom-center queue bar (existed only to batch the live engine's single round-trip).
+- Variant apply/revert-into-iframe live preview + variant pills as a *generation* device.
+- The "Apply with the agent?" confirm modal and the live poll/waiting panels.
+Their *feel* (cycling, in-place feedback, keyboard-first, tactile chips) transfers to the new surfaces; the widgets themselves do not.

package/.next/standalone/.scratch/tweak-running-app/issues/01-isolated-origin.md

@@ -0,0 +1,108 @@
+## Parent
+
+OPS-1 — Spec: Tweak on a running app (proxied node-app runtime).
+
+## What to build
+
+Serve proxied running node-apps from a dedicated **isolated origin** so a
+sandboxed, opaque-origin Tweak preview can talk to the wiki-viewer parent only
+through the postMessage boundary, and page JS inside the proxied app can never
+reach `parent.document` to forge an Accept.
+
+Today the proxied app iframe is served from the wiki-viewer origin and keeps
+`allow-same-origin` (required for the app to function), so hostile page script
+could reach the parent and click Accept, bypassing the postMessage boundary.
+The static-HTML Tweak surface avoids this by rendering into an opaque origin
+(`srcDoc` + `sandbox="allow-scripts"`). A running app cannot use that trick
+because it must stay same-origin to work. The only fix is a separate origin.
+
+This ticket is the security foundation for the whole feature. It introduces the
+isolated origin, the grant-based authorization for it, and the wiki-origin
+hardening that becomes load-bearing once the app moves to a sibling origin. It
+does **not** add any Tweak UI yet.
+
+**Critical design fact (do not skip): a different origin is still the same
+_site_.** Browser origin includes the port, but *site* does not, so serving the
+app from `host:PORT2` (or a same-registrable-domain subdomain) is a different
+origin yet the **same site** as the wiki UI. Consequences that this ticket MUST
+handle, because they are the real boundary now:
+
+- `SameSite` cookies do not stop the app's JS from issuing same-site
+  `fetch(..., {credentials:'include'})` against wiki mutating routes. CORS blocks
+  reading the response, not the state change. So **every** mutating wiki route
+  must enforce an Origin check (`checkOrigin`), and the app-proxy route (which
+  does not today) is included.
+- The app page can nest an iframe of the wiki UI itself (session cookie is
+  delivered, same-site) and overlay/click the real Accept. So all wiki HTML must
+  send `frame-ancestors 'self'` (CSP) / `X-Frame-Options`.
+
+The app is served from a sibling **same-site** origin only. A truly cross-site
+`WIKI_APP_ORIGIN` is rejected at boot in v1 (so a `SameSite=Strict` grant cookie
+is still delivered inside the iframe).
+
+The origin and injection wiring must be **surface-agnostic**: keyed on "a
+proxied live surface," not hard-wired to node-app-only assumptions, so a future
+proxied surface (for example a dynamic HTML file served through the proxy)
+reuses this path with no new mechanism. The running node app is the first and
+driving consumer, not the only conceivable one.
+
+## Acceptance criteria
+
+Origin + serving:
+- [ ] Proxied node-apps are served from a dedicated **same-site** origin distinct
+      from the wiki-viewer app origin (default: same host, dedicated port;
+      overridable via `WIKI_APP_ORIGIN`), and the running app still functions end
+      to end (assets, forms, popups, navigation as before).
+- [ ] A cross-site `WIKI_APP_ORIGIN` is rejected at boot with a clear error (v1
+      supports same-site sibling origins only).
+- [ ] The isolated-origin listener serves ONLY the app proxy and the grant
+      exchange; every other path on that origin 404s (no wiki UI, no `/api/wiki/*`,
+      no auth routes reachable there). https mode reuses the existing cert.
+- [ ] When no isolated origin is configured (e.g. `next dev` single-port), Tweak
+      on proxied apps is hard-disabled; the code never falls back to injecting the
+      picker on the same origin as the wiki UI.
+
+Authorization (grant-only on the isolated origin):
+- [ ] The isolated-origin proxy authorizes via a short-lived HMAC grant only; it
+      rejects wiki session-cookie and Bearer-API-key auth (ambient credentials
+      must not reach it). Cookies continue to be stripped before forwarding
+      upstream.
+- [ ] The grant is scoped to `{userId, workspaceId, appRelPath, exp, jti}` and the
+      server enforces the requested `?ws` matches the grant workspace and the
+      requested path is under `appRelPath` (a grant for app A cannot drive app B).
+- [ ] The grant HMAC key is derived from the server auth secret with a distinct
+      label (not reused from another subsystem). The exchange token is one-time
+      (server-side jti seen-set) with a short TTL (~60s); it swaps for a
+      path-scoped `HttpOnly` cookie on the isolated origin and is never left in a
+      logged URL.
+- [ ] Existing workspace access + app-runner permission checks still gate before
+      the child process is reached (no regression to path containment or
+      workspace isolation).
+
+Wiki-origin hardening (load-bearing once the app is a same-site sibling):
+- [ ] Every mutating wiki route enforces `checkOrigin`; the app-proxy route gains
+      an Origin check. Verified by an audit test that fails if a mutating
+      `/api/wiki/*` or `/api/system/*` route omits it.
+- [ ] All wiki HTML responses send `frame-ancestors 'self'` (CSP) and
+      `X-Frame-Options`, so the proxied app cannot frame-and-overlay the wiki UI.
+- [ ] Both the wiki and isolated origins send `Origin-Agent-Cluster: ?1` (closes
+      the `document.domain` same-site bridge).
+
+Surface-agnostic + docs:
+- [ ] The isolated-origin serving and picker-injection point are surface-agnostic
+      (not coupled to node-app-only keying), so another proxied live surface could
+      be served through the same path without changing the origin layer.
+- [ ] Tests: grant mint/verify + scope/replay rejection (unit, mirroring the
+      shared-docs access-grant tests); isolated listener refuses wiki API/UI;
+      proxy rejects missing/expired/mis-scoped grant and rejects session/Bearer;
+      the mutating-route Origin-check audit. In-process tests assert these
+      server-side contracts; the browser DOM cross-origin guarantee holds by
+      construction and is documented as a manual verification step (it cannot be
+      asserted in-process).
+- [ ] `docs/ux-contracts.md` and the isometric map (`isometric-codebase-map.json`
+      + `.html`) updated in this same change to describe the isolated proxy origin,
+      the grant flow, and the hardening.
+
+## Blocked by
+
+- None — can start immediately.

package/.next/standalone/.scratch/tweak-running-app/issues/01-runtime-containment.md

@@ -0,0 +1,18 @@
+## Parent
+OPS-8 — Spec: Unified live tweak for web surfaces (Impeccable-live model)
+
+## What to build
+The live engine's runtime directory is treated as internal runtime state, never as
+user content: it cannot be resolved through path containment, cannot be reached
+through any browser or agent file route, and is never committed. This is the safety
+floor the rest of the feature builds on.
+
+## Acceptance criteria
+- [ ] The engine runtime directory segment is denied by the canonical path-containment primitive, alongside the existing denied segments.
+- [ ] File-browser and agent file routes cannot read, list, or write anything inside the engine runtime directory (verified by tests).
+- [ ] The engine runtime directory is gitignored so it is never committed.
+- [ ] Proof tests assert the directory is denied by path resolution and unreachable via file routes. Prior art: app-proxy-auth.test.ts, containment tests.
+- [ ] docs/ux-contracts.md and the isometric codebase map are updated in this same change if this introduces any user-facing or subsystem change.
+
+## Blocked by
+None — can start immediately.

package/.next/standalone/.scratch/tweak-running-app/issues/02-injection-transform.md

@@ -0,0 +1,18 @@
+## Parent
+OPS-8 — Spec: Unified live tweak for web surfaces (Impeccable-live model)
+
+## What to build
+A single pure string transform that injects the live engine prelude globals plus
+the overlay script tag into a page's HTML at the correct anchor. It is the shared
+mechanism both the static-HTML viewer render and the app-proxy serve-time rewrite
+will reuse, so tweak is enabled without editing any source file.
+
+## Acceptance criteria
+- [ ] A pure function injects the prelude globals and the overlay script tag at the correct HTML anchor.
+- [ ] The transform is idempotent (injecting twice yields the same result as once) and does not corrupt surrounding HTML.
+- [ ] The injected globals are parameterized (engine endpoints/token) so callers can point the overlay at either a direct helper or proxied paths later.
+- [ ] Unit-tested as a pure function. Prior art: app-proxy HTML-rewrite tests, web-tweak-picker.test.ts.
+- [ ] docs/ux-contracts.md and the isometric codebase map are updated in this same change if this introduces any user-facing or subsystem change.
+
+## Blocked by
+None — can start immediately.

package/.next/standalone/.scratch/tweak-running-app/issues/02-tracer-bullet.md

@@ -0,0 +1,48 @@
+## Parent
+
+OPS-1 — Spec: Tweak on a running app (proxied node-app runtime).
+
+## What to build
+
+The first complete, demoable Tweak round-trip on a running app: happy path,
+one element, one file.
+
+The user opens their running app in the proxied view, enters Tweak mode, points
+at one real element on the live page, types one instruction, and dispatches. The
+attached agent receives the request through the existing poll/reply channel and
+returns one reviewable proposal. The user reviews and Accepts. On Accept,
+wiki-viewer sends an approval to the agent (carrying the proposal identity and
+the base hash captured at proposal time); the agent writes the single source
+file, triggers the app rebuild/reload, and returns a success receipt.
+wiki-viewer records the receipt and the user sees the running app reflect the
+change.
+
+Scope is the tracer bullet only: exactly one queued element, one written file,
+success path. Failure/cancel/discard, multi-file, drift refusal, and full batch
++ parity affordances are separate tickets.
+
+The running node app is the concrete driver for this round-trip, but the Tweak
+surface wiring should sit on the surface-agnostic proxied-live-surface
+foundation from ticket 1, not bake in node-app-only assumptions beyond what this
+slice needs.
+
+## Acceptance criteria
+
+- [ ] The proxied running-app view exposes a Tweak entry point (picker injected
+      into the proxied app via the isolated origin from ticket 1).
+- [ ] Selecting one element highlights it as the Tweak target and lets the user
+      type an instruction.
+- [ ] Dispatch sends the request over the existing human→agent request channel;
+      the agent replies with one reviewable proposal over the existing poll/reply
+      channel (no new transport).
+- [ ] Accept transitions the proposal to approval-sent and hands the agent an
+      approval carrying the proposal identity and the per-file base hash.
+- [ ] The agent write of a single file, followed by app reload, is reflected in
+      the running app; wiki-viewer records a success receipt and shows success.
+- [ ] Route-level proof test in `src/tests/proof/` exercises the full
+      dispatch → propose → accept → approval → receipt-success path in process.
+- [ ] `docs/ux-contracts.md` and the isometric map updated in this same change.
+
+## Blocked by
+
+- Ticket 1 (isolated proxy origin).

package/.next/standalone/.scratch/tweak-running-app/issues/03-accept-carbonize-mutator.md

@@ -0,0 +1,19 @@
+## Parent
+OPS-8 — Spec: Unified live tweak for web surfaces (Impeccable-live model)
+
+## What to build
+A pure transform that turns an accepted variant into clean permanent source:
+locate the engine markers, extract the chosen variant, bake in the tuned knob
+values, and emit the final source with all live-mode scaffolding removed. It
+enforces the speculative-until-Accept invariant by refusing when the base content
+has drifted since the preview began.
+
+## Acceptance criteria
+- [ ] A pure function locates markers, extracts the chosen variant, bakes knob values, and produces clean final source with no live-mode leftovers.
+- [ ] Accept is refused when the base content hash no longer matches (drift), and commits verbatim when it matches.
+- [ ] Non-accepted variants and their scaffolding are fully removed from the output.
+- [ ] Unit-tested as a pure function including the drift-refusal and verbatim-commit paths. Prior art: web-tweak-collab.test.ts.
+- [ ] docs/ux-contracts.md and the isometric codebase map are updated in this same change if this introduces any user-facing or subsystem change.
+
+## Blocked by
+None — can start immediately.

package/.next/standalone/.scratch/tweak-running-app/issues/03-run-robustness.md

@@ -0,0 +1,37 @@
+## Parent
+
+OPS-1 — Spec: Tweak on a running app (proxied node-app runtime).
+
+## What to build
+
+Make the running-app Tweak run survive the unhappy paths, reusing the same
+recovery discipline the markdown/HTML surfaces already have (core parity).
+
+Covers the failure and control transitions layered on the tracer bullet:
+
+- **Receipt-failed**: when the agent's write receipt reports failure, the user
+  sees a clear reason, the queue is preserved, and the same proposal can be
+  retried without re-describing it.
+- **Cancel run**: while a run waits on the agent, the user can cancel it, which
+  frees the single outstanding slot and writes nothing.
+- **Discard proposal**: the user can discard a returned proposal; the app source
+  is left byte-identical.
+- **Single-outstanding enforcement**: dispatching while a run is already
+  outstanding is cleanly rejected and the queued work is not lost.
+
+## Acceptance criteria
+
+- [ ] A failure receipt surfaces a clear reason, preserves the queue, and allows
+      retry of the same proposal (state returns to a retryable point, not lost).
+- [ ] Cancel while waiting on the agent frees the outstanding slot and performs
+      no write.
+- [ ] Discard leaves the app source byte-identical (verified by hash/no-op).
+- [ ] A second dispatch while one run is outstanding is rejected with a clear
+      message and the queue is preserved.
+- [ ] Route-level proof tests cover receipt-failure retry, cancel, discard, and
+      the outstanding-run rejection.
+- [ ] `docs/ux-contracts.md` and the isometric map updated in this same change.
+
+## Blocked by
+
+- Ticket 2 (tracer bullet round-trip).

package/.next/standalone/.scratch/tweak-running-app/issues/04-multifile-safety.md

@@ -0,0 +1,37 @@
+## Parent
+
+OPS-1 — Spec: Tweak on a running app (proxied node-app runtime).
+
+## What to build
+
+Let a single accepted running-app tweak span multiple source files, and enforce
+the write-safety guarantees every other wiki-viewer write already honors.
+
+- **Multi-file write**: lift the v1 "candidate must edit exactly one file" cap
+  for this flow. Because the agent owns the write, an accepted tweak may
+  legitimately touch several files; the approval carries per-file base hashes.
+- **Drift / stale refusal**: if any underlying source file changed since the
+  proposal was made (base-hash mismatch at approval time), the write is refused
+  (invalidated) rather than silently clobbering a concurrent edit.
+- **Containment + isolation**: every written path is validated through the
+  canonical path-containment primitive and stays inside the target workspace.
+- **File-vs-collab safety**: a `.md` file a human currently has open (`active`
+  collab state) is never overwritten by a proxied-app tweak write.
+
+## Acceptance criteria
+
+- [ ] An accepted tweak can write more than one file in a single approval, with
+      per-file base hashes carried on the approval.
+- [ ] A base-hash mismatch on any file at approval time refuses the whole write
+      (invalidated, no partial write) and reports it to the user.
+- [ ] Every written path is resolved through `resolveWorkspacePath` and cannot
+      escape the workspace (traversal / symlink / absolute path rejected).
+- [ ] A write targeting a `.md` file in `active` collab state is rejected in
+      honor of file-vs-collab authority.
+- [ ] Route-level proof tests cover multi-file success, drift refusal, a
+      containment escape attempt, and the collab-active rejection.
+- [ ] `docs/ux-contracts.md` and the isometric map updated in this same change.
+
+## Blocked by
+
+- Ticket 2 (tracer bullet round-trip).

package/.next/standalone/.scratch/tweak-running-app/issues/04-static-tracer-bullet.md

@@ -0,0 +1,27 @@
+## Parent
+OPS-8 — Spec: Unified live tweak for web surfaces (Impeccable-live model)
+
+## What to build
+The complete unified live-tweak spine, proven end to end on the simplest surface:
+a static HTML file, localhost. The user opens a static `.html` in wiki-viewer,
+points at an element, picks an action or types an instruction, hits Go, gets 2 to 5
+variants with tunable knobs, cycles and tunes them with instant client-side
+feedback, and Accepts the chosen variant into the file (or Discards to restore the
+original). This is the tracer bullet: it wires together the engine helper
+lifecycle, the overlay injection (02), the product-side poll loop / live bridge,
+the existing attached-agent channel for variant generation, and the accept mutator
+(03) through wiki-viewer's own writer. It is a deliberate serialization point; the
+wider surfaces build on it.
+
+## Acceptance criteria
+- [ ] wiki-viewer spawns, supervises (health, stop), and tears down the engine helper for a static-file tweak session, keyed per surface like the node-app runner keys apps.
+- [ ] The overlay is injected into the static-file render via the transform from ticket 02; the picker highlights elements and offers named actions plus freeform.
+- [ ] A product-side poll loop (the live bridge) translates engine generate/steer/accept/discard events into the existing live-store request kinds and back, honoring one-outstanding-per-session and idempotent replay.
+- [ ] A generate request is fulfilled by the user's existing attached agent; 2 to 5 variants with 0 to 4 knobs each appear via instant client-side swap (no reload).
+- [ ] Accept writes the chosen variant (with baked knob values) into the file through wiki-viewer's writer + path containment + write lock, only on matching base hash; Discard restores the original exactly; nothing writes before Accept.
+- [ ] An interrupted session (reload/disconnect) recovers to a safe state via the engine journal rather than leaving half-applied variants.
+- [ ] Proof tests drive the bridge at the route-handler level asserting the reconciled state machine, write-on-accept-only, and drift refusal. Prior art: live-collab.test.ts, web-tweak-collab.test.ts.
+- [ ] docs/ux-contracts.md (§1.4 area) and the isometric codebase map are updated in this same change to describe the unified static-HTML flow.
+
+## Blocked by
+01, 02, 03.

package/.next/standalone/.scratch/tweak-running-app/issues/05-batch-parity.md

@@ -0,0 +1,43 @@
+## Parent
+
+OPS-1 — Spec: Tweak on a running app (proxied node-app runtime).
+
+## What to build
+
+Bring the running-app Tweak surface to full **core parity** with the existing
+markdown and HTML surfaces: batch queueing and the shared affordances.
+
+- **Batch queue**: queue several element tweaks before dispatching and send them
+  as one batch; the agent returns one reviewable proposal per queued item.
+- **Select-again-to-update**: re-selecting an already-queued element updates its
+  instruction in place rather than inflating the queued count.
+- **Remove one**: drop a single queued tweak without losing the rest; Cancel-all
+  clears the whole queue without dispatching.
+- **Presence indicator**: show whether an agent is listening.
+- **Connect-an-agent**: with queued tweaks but no attached agent, the dispatch
+  button becomes "Connect an agent" and opens the agent panel without losing the
+  queue.
+- **Surface-specific dispatch label**: the dispatch button carries a label that
+  reads naturally on the running-app surface (parity with markdown "Rewrite" /
+  HTML "Apply").
+- **Per-item review**: the user reviews and Accepts/Discards each item's proposal
+  independently.
+
+## Acceptance criteria
+
+- [ ] Multiple element tweaks can be queued and dispatched as one batch; the
+      agent returns one proposal per item, each independently reviewable.
+- [ ] Re-selecting a queued element updates its instruction in place (queued
+      count unchanged); a single queued tweak can be removed; Cancel-all clears
+      the queue without dispatching.
+- [ ] Presence indicator reflects agent-listening state; with no agent the
+      dispatch button becomes "Connect an agent" and opens the panel, queue
+      intact.
+- [ ] The dispatch button shows the surface-specific label.
+- [ ] Route-level / component proof tests cover batch dispatch, in-place update,
+      remove-one, and the no-agent Connect affordance.
+- [ ] `docs/ux-contracts.md` and the isometric map updated in this same change.
+
+## Blocked by
+
+- Ticket 2 (tracer bullet round-trip).

package/.next/standalone/.scratch/tweak-running-app/issues/05-dynamic-node-app.md

@@ -0,0 +1,22 @@
+## Parent
+OPS-8 — Spec: Unified live tweak for web surfaces (Impeccable-live model)
+
+## What to build
+Extend the unified live tweak to running node apps viewed through the proxy. The
+overlay is injected at proxy serve time so the tweak surface is available on the
+app's own page. After Go, the page performs one full reload through the proxy to
+render the freshly written variants; the overlay re-attaches automatically. After
+that single reload, cycling and knob-tuning stay instant and client-side. Accept
+writes to the true template/component source, never a generated build output.
+
+## Acceptance criteria
+- [ ] The overlay is injected into proxied app HTML at serve time (reusing ticket 02), only where the user is authorized for the workspace and app-runner permissions allow.
+- [ ] After a generate on a compiled app, a single full-reload-through-proxy renders the variants and the overlay re-attaches via its durable per-origin session.
+- [ ] Cycling variants and tuning knobs after the reload are instant and client-side (variants already present in the page).
+- [ ] Accept writes to true source; generated/build-output files are guarded and routed to the real template/component via the fallback path.
+- [ ] Node-app launching remains gated by the existing app-runner permission model (no change to who may start apps).
+- [ ] Proof tests cover injection authorization and the accept-to-true-source path. Prior art: app-proxy-auth.test.ts, web-tweak-collab.test.ts.
+- [ ] docs/ux-contracts.md and the isometric codebase map are updated in this same change to describe the dynamic/node-app flow, including the one-reload behavior.
+
+## Blocked by
+04.

package/.next/standalone/.scratch/tweak-running-app/issues/06-remote-transport-bridge.md

@@ -0,0 +1,20 @@
+## Parent
+OPS-8 — Spec: Unified live tweak for web surfaces (Impeccable-live model)
+
+## What to build
+Make the tweak overlay work when wiki-viewer is served remotely, not just on
+localhost. The overlay runs on wiki-viewer's origin but the browser may be on a
+different machine than the engine helper, so the engine endpoints the overlay
+needs are exposed through wiki-viewer's own origin, and the injected globals point
+the overlay at those proxied paths instead of a hardcoded local helper port.
+
+## Acceptance criteria
+- [ ] The overlay bundle, event downlink (SSE), event uplink, source read, design-system read, and annotation upload are all reachable through wiki-viewer's own origin.
+- [ ] The injected globals (ticket 02) point the overlay at the proxied paths so it never depends on the browser reaching the helper's local port directly.
+- [ ] The proxied endpoints enforce wiki-viewer session/agent authorization and the existing CSRF Origin checks; unauthorized access is rejected.
+- [ ] Both static-HTML and node-app tweak sessions function with wiki-viewer served on a non-localhost origin.
+- [ ] Proof tests assert auth/CSRF enforcement on the proxied engine endpoints. Prior art: app-proxy-auth.test.ts.
+- [ ] docs/ux-contracts.md and the isometric codebase map are updated in this same change.
+
+## Blocked by
+04.

package/.next/standalone/.scratch/tweak-running-app/issues/07-retire-bespoke-web-tweak.md

@@ -0,0 +1,17 @@
+## Parent
+OPS-8 — Spec: Unified live tweak for web surfaces (Impeccable-live model)
+
+## What to build
+Remove the previous bespoke static-HTML tweak flow (opaque-origin sandbox, DOM-ops
+picker, "Iterate" variants) and its supporting code and tests, so there is a single
+unified tweak behavior rather than two. The unified flow from ticket 04 fully covers
+the static-HTML case before this deletion lands.
+
+## Acceptance criteria
+- [ ] The bespoke web-tweak request/resolve/picker/preview/accept paths that the unified flow replaces are removed, along with their now-dead tests.
+- [ ] No user-facing static-HTML tweak capability regresses relative to the unified flow.
+- [ ] The full test suite passes and the test floor is updated only via the sanctioned path.
+- [ ] docs/ux-contracts.md is updated to remove the retired §1.4 bespoke behavior and reflect only the unified flow; the isometric codebase map is updated to drop the retired subsystem.
+
+## Blocked by
+04.

package/.next/standalone/.scratch/tweak-running-app/keep-ticket.md

@@ -0,0 +1,74 @@
+## Purpose
+
+The live "tweak" collaboration engine (web + markdown live-instruct) is being
+**removed** (see the tweak-engine removal commits). The tweak *interaction* was
+genuinely pleasant and should be rebuilt later on top of the existing
+comments/suggestions (sidecar "proof") engine, so there is exactly one
+collaboration engine underneath. This ticket captures everything needed to
+resurrect the UX. **No design work is scoped here yet.**
+
+## Recovery pointer
+
+- git tag **`pre-tweak-removal`** = commit `056fd01` — the last commit where the
+  tweak UX exists in full. Recover any file via
+  `git show pre-tweak-removal:<path>`.
+
+## Reusable chrome to resurrect (surface-agnostic)
+
+- `src/components/editor/tweak/tweak-overlay.tsx` — thin shell (targeting + queue bar + run panel)
+- `src/components/editor/tweak/tweak-queue-bar.tsx` — fixed bottom-center queue bar, per-item remove, Cancel-clears-all, dispatch label, extras slot
+- `src/components/editor/tweak/tweak-queue.ts` — queue model (dedup by targetKey)
+- `src/components/editor/tweak/use-tweak-session.ts` — session/phase state, add/update-in-place, presence gate
+- `src/components/editor/tweak/tweak-types.ts` — the `ContentKindAdapter` pattern (contentKind, dispatchLabel, items, onDispatch, renderTargeting, renderRunPanel, renderQueueBarExtras)
+- **Copy-as-prompt** (already built): `buildPrompt()` / `handleCopyPrompt` in
+  `adapters/markdown-adapter.tsx:218` and `adapters/html-adapter.tsx:388`
+  ("Edit the file X … Apply these changes: 1. <snippet>: <instruction> …"),
+  secure-context clipboard gate + textarea fallback.
+
+## UX contract (verbatim extraction from docs/ux-contracts.md pre-removal)
+
+### Tweak queue (shared across surfaces) — §1.2
+
+The user-facing feature is **Tweak**. In the editor action menu, **Comment**
+starts a discussion/annotation, **Suggest** proposes a human edit for review, and
+**Tweak** asks the AI to rewrite the selected target. A Tweak is first added to a
+queue. Selecting the same target again updates its queued instruction and snippet
+in place, so the count does not increase. Users can remove one queued item or
+choose **Cancel** to clear all queued selections without dispatching. Clicking
+outside while an instruction input is empty equals **Cancel**. The dispatch button
+label is surface-specific. Queue bars also offer **Copy as prompt** and **Show**
+fallback controls. When no agent is attached, dispatch becomes **Connect an
+agent**.
+
+### Markdown targets — §1.3 (interaction only; the live-dispatch mechanics are being removed)
+
+Target is a rendered **block** (paragraph, heading, list item), with an optional
+in-block text selection carried only as context. Markdown/text gather queued
+targets before dispatch (batch, no immediate single-target dispatch). Previews
+are ephemeral; **Accept** is the only write (write-on-accept), gated on the
+block's base hash with drift refusal. Cancel discards without writing.
+
+### Web targets — §1.4 (interaction only; the live engine is being removed)
+
+Point at an element, say what you want, see a few variants to compare and tune
+(knobs), Accept one into source. Previews speculative; Accept is the only write,
+with containment + base-drift protection.
+
+## Design direction (deferred — do NOT implement without a fresh spec)
+
+Fold the above UX onto the sidecar comments/suggestions engine: the dispatch
+button persists each queued item as an instruction-comment
+(`comment.add {kind:"instruction"}`) via `POST /api/agent/files`, which the user's
+agent picks up through its normal snapshot/activity flow and answers with
+suggestions (reviewed in the existing `suggestion-card`). Copy-as-prompt stays as
+the no-agent escape hatch.
+
+**Open default (undecided):** does the tweak action default to creating an
+instruction-comment (durable, agent picks up on its own schedule) or copy-as-prompt
+only? PM leaned copy-as-prompt for simplicity; implementer leaned instruction-comment
+default with copy-as-prompt as the escape hatch. Decide when this is specced.
+
+## Out of scope
+
+Any code here. This is a capture-only ticket. Removal of the live tweak engine
+lands separately; this ticket is picked up later for the re-home design.