wiki-viewer 2.16.0 → 2.16.1

package/.next/standalone/.scratch/tweak-running-app/suggest-inline-interaction-spec.md

@@ -0,0 +1,320 @@
+# Inline Suggesting — interaction spec (T1 + T2)
+
+Reference-only design artifact. Upgrades Suggest from side-mounted overlay
+cards (`suggestion-card.tsx`) to a GDocs-style inline redline surface. Coheres
+with `two-actions-interaction-spec.md`: Suggest's entry point stays human-only;
+the agent's rewrite arrives as a suggestion and is reviewed on THIS surface.
+That spec's "suggestion-card (existing, unchanged)" becomes "this surface".
+Scope: T1 (perception) + T2 (granularity) only. Comment untouched.
+
+---
+
+## 0. Model recap (drives every rendering decision)
+
+- Kinds `replace | insertAfter | insertBefore | delete`; status
+  `pending | accepted | rejected` (`types.ts:72-90`).
+- T2 adds `from`/`to` offsets within a block. Absent (T1-era data) → range =
+  whole block. **All rendering keys off range, not kind-era** — this is what
+  makes the T1→T2 boundary coherent (§7).
+- Suggestions carry `by`, optional `basisDetail`, and — per the tweak re-home
+  — `fromInstructionId` linking to an instruction comment.
+- Settling writes .md (accept) or discards (reject); accept supersedes other
+  pending suggestions on the same ref; 409 → one retry (unchanged).
+
+Rendering mechanism (technical shape, for the frontend agent): a ProseMirror
+**plugin decoration set**, NOT document marks, NOT the old absolute overlay.
+Decorations never enter the doc (can't leak into serialized .md), ride
+position mapping through concurrent edits, and give suggesting-mode capture a
+channel for local not-yet-persisted redline. Widget decorations carry block
+shells; inline decorations carry text ranges.
+---
+
+## 1. Inline rendering grammar
+
+Change type owns color; author owns texture. Survives dark mode, stays
+colorblind-legible (shape + position, not hue), never collides with the muted
+olive/gold palette.
+
+| Suggestion | In-prose appearance | Tokens |
+|---|---|---|
+| **Inserted range** | Green text, 2px solid green underline, `--success-soft` 8%-alpha wash | `--success`, `--success-soft` |
+| **Deleted range** | Red text, 1.5px strikethrough, 60% opacity | `--destructive` |
+| **Replacement** | Strikethrough deleted run *immediately followed* by green-underlined inserted run, SAME paragraph flow — GDocs "oldnew" pattern; never two stacked paragraphs | both |
+| **Block insert (insertAfter/Before)** | Full-width "ghost block": the proposed markdown rendered at document typography, `--success-soft` background, 2px `--success` left bar, 10px corner radius, no strikethrough | `--success`, `--success-soft` |
+| **Block delete** | Existing block keeps document typography but content strands get strikethrough; block gets `--destructive-soft` 8% wash + 2px `--destructive` left bar | `--destructive`, `--destructive-soft` |
+| **Hover (desktop)** | The full range (all runs of one suggestion) brightens +12% and a 1px outline in the change color appears | — |
+
+```
+word-level replace:   The report was ̶w̶r̶i̶t̶t̶e̶n carefully revised by Alice
+                                     └ red strike    └── green underline ─┘
+block delete:        ▍~~This entire paragraph is struck at 60% opacity.~~
+                     ▍ (red bar + soft red wash on the block)
+block insert:        ▍┌ proposed new paragraph, fully rendered ────────┐
+                     ▍│  at document typography, soft green card      │
+                     ▍└───────────────────────────────────────────────┘
+```
+
+**Whole-block vs word-level reads differently on purpose:** range <100% of a
+block → inline runs (seamless prose); range = 100% → block treatment (left bar
++ wash). Threshold: ≥90% of trimmed block text → block treatment (avoids a
+one-char-untouched eyesore).
+
+**Author attribution — human vs agent:**
+
+- **Human:** label lives in the popover header and the caret chip at the range
+  edge. Redline color never encodes author (hue-per-author collapses past 2).
+- **Agent (`by` starts with `ai:` or carries `fromInstructionId`):** underline
+  / strike renders **hatched** (repeating-linear-gradient, 45°, 4px period)
+  and a `✦` glyph sits at the range's leading edge. Hatching reads
+  machine-drawn in both themes without changing hue — agent and human editing
+  the same sentence stay comparable at a glance.
+
+```
+human:     ──────────────  solid green underline
+agent:  ✦  ░░▒▒░░▒▒░░▒▒░░  hatched green underline + diamond
+```
+
+**Attribution chip:** every range gets a 16px caret `▾` badge at its end
+(superscript, change-color); N>1 overlapping → `▾2` (§3). This chip is the
+touch click target. Redline applies equally inside code blocks/lists —
+decorations never re-set font.
+
+---
+
+## 2. Review affordance — the inline popover
+
+**Accept/Reject live in a popover anchored at the change, opened by click or
+tap. No margin gutter, no permanent side rail.** Rationale: the redline is
+already in place; a persistent control column duplicates the comment-pip
+geometry and dies on narrow/touch layouts.
+
+### 2.1 Open/close
+
+- Desktop: click any redline run (or hover 400ms → preview-popover).
+- Touch: tap the `▾` caret badge (44×44 hit slop).
+- One popover at a time. Esc / outside-click closes; accept/reject closes and
+  moves focus to the next pending suggestion.
+- Popover is a portal off the decoration's DOM rect, flipping on collision,
+  max-width 340px, `var(--radius)`, `--shadow-golden-pop`, `var(--popover)` —
+  same visual register as the comment composer.
+
+### 2.2 Anatomy
+
+```
+┌─ suggestion popover ────────────────────────────────────────┐
+│ ░✦░ agent suggests replacing · Alice · 2m ago        (header)│
+│ In response to: "Tighten this paragraph…" ↗      (if linked) │
+│ ┌─────────────────────────────────────────────────────────┐ │
+│ │ The report was ̶w̶r̶i̶t̶t̶e̶n carefully revised by the…  (diff) │ │
+│ └─────────────────────────────────────────────────────────┘ │
+│ Reason: clearer prose                          (if present) │
+│ [ ✓ Accept ]  [ ✕ Reject ]              44px touch targets  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+- **Header** = `{✦ agent|author label} suggests {kind verb}`; agent rows get
+  the hatched swatch.
+- **"In response to:"** renders ONLY when `fromInstructionId` is set; 48-char
+  truncate; `↗` scrolls to the instruction thread. Same linkage line as the
+  two-actions spec — moved, not redesigned.
+- **Diff pane = word-level diff of the suggestion's range**, even for T1
+  whole-block data (the block IS the range). Same §1 grammar, miniaturized,
+  rendered at document typography. >12 changed segments collapses behind a
+  "show full text" toggle.
+- Accept primary (`--primary` fill), Reject outline; `busy` disables both at
+  opacity-50 (existing pattern). 409-after-retry swaps the buttons for
+  `⚠ Document changed since this suggestion` + [Refresh review] — unchanged
+  semantics from the current card.
+
+### 2.3 Keyboard & a11y
+
+Tab reaches each redline range as one stop (role `button`, aria-label
+`"Suggestion by {by}: {kind}, press Enter to review"`); Enter opens the
+popover; ⌥Enter accepts directly. Popover traps focus; aria-live announces
+"Suggestion accepted".
+
+### 2.4 Review navigation
+
+With ≥1 pending suggestion, the status bar gains `✎ 3 suggestions`: click →
+dropdown (author, kind, diff preview) + prev/next arrows that scroll-into-view
+and open each popover. This inherits the "where are my suggestions?" job of
+today's always-visible side cards without pinning N cards beside blocks.
+
+---
+
+## 3. Overlapping suggestions
+
+Two+ pending suggestions whose ranges intersect (T2) or share a ref (T1):
+
+**In prose:** only ONE suggestion renders its full redline per overlapping
+cluster — the most recent. Others collapse into a **stack stripe**: the caret
+badge reads `▾N` with N−1 two-px tick marks stacked below it in each
+suggestion's change color. The document reads exactly once; no
+strike-on-green pile-ups. Hatched/solid texture survives in the stripe, so
+"the agent's and mine overlap here" is legible from the badge alone.
+
+```
+The report was ̶w̶r̶i̶t̶t̶e̶n revised▾2
+             │ red tick (Alice's)
+             ┆ green tick (agent's, hatched → agent is stacked)
+```
+
+**In the popover (the switcher):** header gains `◂ 1 of 3 ▸`. Arrows/arrow
+keys cycle the active suggestion; the diff pane re-renders; **Accept/Reject
+always act on the active item**. The prose redline swaps live as you cycle, so
+each option previews in context before settling.
+
+**Settling semantics (unchanged engine, extended):** accepting a suggestion
+supersedes overlapping pending ones on the same ref (today: same ref; T2:
+intersecting ranges). The popover of a superseded suggestion shows
+`Settled by another suggestion` and offers `[Dismiss]`. Rejecting one never
+touches the others.
+
+**Creation-time collision:** starting a Suggest on a range with a pending
+suggestion shows a non-blocking composer note: "Alice already suggested a
+change here — yours will stack." Never blocked, always informed.
+
+---
+
+## 4. Suggesting mode — live redline, no silent revert
+
+Keep the Editing/Suggesting radio and the banner. Kill capture-then-silent-revert.
+
+**T1 (block-granular capture, live presentation):**
+
+1. Typing behaves like editing; no mid-typing doc rewrite.
+2. Block-exit flush (existing `onSelectionUpdate` trigger) posts the op as
+   today — but the revert becomes a **crossfade swap**: typed text fades
+   (200ms, `--motion-slow`) from normal text into the §1 redline of the
+   just-posted suggestion, in place. Content never vanishes; it visibly
+   converts into "pending" state. Nothing is silent.
+3. Entering the mode re-snapshots and shows: `Suggesting — your edits appear
+   as suggestions, not saved text.` plus a `2 pending from you` badge.
+
+**T2 (true live):** the capture hook diffs the active block vs its snapshot per
+transaction (debounced 300ms) and renders the delta as §1 redline AS YOU TYPE.
+Ops still post only on block-exit; live redline is local decoration state, so
+undo shrinks it and block-exit posts the final range.
+
+**Mode exit:** flush everything, then one toast: `3 suggestions created —
+review in the ✎ chip`. Exit never discards; a failed post leaves the text as
+plain editing-mode text plus `Couldn't create suggestion — kept as plain edit`
+(error state, §8). Redline visibility is the proof of posting, killing the old
+silent-data-loss failure mode.
+
+---
+
+## 5. Agent suggestions — the tweak re-home lands here
+
+An agent's rewrite arrives as ordinary `suggestion.add` carrying
+`fromInstructionId` and `by: "ai:<id>"`. On this surface:
+
+1. **Prose:** hatched redline + `✦` leading glyph (§1) — unmistakable at
+   distance, same color grammar as human.
+2. **Popover:** ✦ header + hatched swatch + `agent`, with the
+   `In response to: "<instruction>" ↗` line under the header (italic,
+   `--muted-foreground`, 48-char truncate); `basisDetail` stays a separate
+   line below the diff.
+3. **Instruction stub (two-spec §4):** its `✦ answered — review the
+   suggestion below` line now scrolls to the redline and opens the popover.
+   The stacked "card above card" picture dissolves — no side card exists; the
+   stub remains, the suggestion is inline.
+4. **Settling linkage (two-spec §5, unchanged):** Accept or Reject resolves
+   the instruction. 409 drift still shows the popover refresh state.
+5. **Arrives while user is suggesting:** renders identically (target-anchored,
+   not edit-derived); obeys §3 overlap rules if ranges intersect.
+
+Nothing else differs from human — no extra buttons, no auto-accept, no
+agent-only popover variant. One review loop, two textures.
+
+---
+
+## 6. View-mode Suggest (the missing button)
+
+Parity with `ViewModeCommentButton` (named by ux-contracts §6.1, today only
+implemented for Comment):
+
+- **Placement:** identical selection-following floating button, rendered
+  BESIDE the Comment button when a selection exists in read-only view:
+  `[ 💬 Comment | ✎ Suggest ]`. Same geometry, same `touch-target` sizing,
+  same token set as the comment twin.
+- **Capability:** read-only humans CAN propose. Opens the existing
+  SuggestEditPopover pre-filled with the selection's block markdown. Posting
+  `suggestion.add` writes only the sidecar — never the .md — so view mode
+  stays read-only-for-human with zero integrity risk (the contract's intent).
+- **View-mode popovers:** clicking an existing redline gives the §2.2 popover
+  with the action row replaced by `Suggested by {by} · awaiting a reviewer`
+  (the card's existing `readOnly` prop models this).
+
+---
+
+## 7. Tier boundary — T1 shipped alone
+
+T1 without T2 means every suggestion's range = one whole block:
+
+- `replace` → old block in block-strike treatment immediately followed by the
+  proposed block as a green ghost insert, in place. Reads "this paragraph
+  becomes this paragraph" — verbose for a one-word fix (the known coarse cost)
+  but spatially coherent and scroll-stable.
+- `insertAfter/Before` → ghost block; `delete` → red block treatment. Both
+  already final form.
+- The popover already shows the WORD-LEVEL diff of the whole-block pair, so the
+  reviewer finds the one changed word instantly even at T1. Deliberate
+  pressure valve: diff granularity ships at T1 in the popover; range
+  granularity ships at T2 in the prose.
+
+T2 then only narrows WHAT the redline spans. No grammar change at the cutover;
+no re-learning; settled T1-era suggestions are archived/inert anyway.
+
+---
+
+## 8. States| State | Prose | Popover / chrome |
+|---|---|---|
+| **Composing** (bubble/popover draft) | none yet; block gets 2px `--primary` dashed outline while composer open | SuggestEditPopover as today, kind chips unchanged |
+| **Suggesting-mode typing (T2)** | live local redline, slightly desaturated (60% alpha) until posted (signals "not yet a suggestion") | banner + `pending from you` count |
+| **Pending (human)** | solid redline + `▾` badge | §2.2 popover; in `✎ N suggestions` chip |
+| **Pending (agent)** | hatched redline + ✦ | §2.2 popover + `In response to` line |
+| **Accepted** | redline crossfades to plain text as the .md write lands; 150ms `--motion-base` | toast `Suggestion accepted`; instruction linked → resolves |
+| **Rejected** | redline fades out (inserts vanish, strikes restore to plain) | toast `Suggestion rejected`; suggestion archived |
+| **Drift / stale anchor** (`stale` flag, ref/textHash miss) | block shows redline at last known position with `--warning` outline + ⚠ in caret badge | popover replaces actions: `⚠ Target text changed` + [Re-anchor] [Reject] [Dismiss]; Re-anchor reopens composer on best-effort match |
+| **Overlapping** | one full redline + `▾N` stack stripe | `◂ 1 of N ▸` switcher; settle-active-only |
+| **409 collision on accept** | redline dims to 60% | `Document changed since this suggestion` + [Refresh review] |
+| **Post failure (suggesting flush)** | typed text stays as NORMAL text (never silently kept as pretend-suggestion) | error toast `Couldn't create suggestion — kept as plain edit` + [Retry] |
+| **Empty** | none | `✎` chip absent; zero other chrome |
+
+---
+
+## Summary
+
+1. Inline redline lives in a ProseMirror decoration set (never doc marks),
+   grammar: green underline insert / red strike delete / strike→green replace,
+   block treatments for 100%-of-block ranges.
+2. Accept/Reject move into one inline popover per change with a word-level
+   diff pane and the instruction linkage line; a status-bar `✎ N` chip +
+   arrows carries navigation that the always-visible side cards used to own.
+3. Overlaps render as one redline + a stacked `▾N` stripe, with a
+   `1 of N` switcher in the popover; settling supersedes the rest.
+4. Suggesting mode keeps its radio but stops silently reverting: T1 crossfades
+   typed text into posted redline on block-exit; T2 renders live local redline
+   as you type.
+5. Agent suggestions are the same grammar with hatched texture + ✦ + the
+   `In response to` line — one review loop, two textures, tweak re-home intact.
+6. T1-alone is coherent: whole-block redline in place + word-level diff in the
+   popover; T2 only narrows prose granularity, changes no grammar.
+7. **Riskiest assumption:** ProseMirror decorations stay stable and cheap
+   across whole-document re-renders driven by our fs-event sidecar reloads —
+   if decoration positions flicker or drop during concurrent .md writes (the
+   same events that trigger today's "coarse whole-sidecar reload"), inline
+   redline will visibly jump, which reads far worse than a card ever did.
+   Needs a spike on decoration mapping through `setContent` refreshes before
+   T1 build.
+
+## Open questions
+
+1. T2 overlap: does same-ref supersede become range-intersection supersede in
+   the applier (engine change) or stay client-side gating? Spec assumes
+   range-intersection; engine owner confirms.
+2. `fromInstructionId` dedicated field vs reusing `inResponseTo` on the block
+   op — recommend dedicated; owned by two-actions spec open q2.
+3. Word-diff tokenization must treat markdown punctuation (link/emphasis
+   syntax) as separators or redline gets noisy; fix rules with frontend agent.

package/.next/standalone/.scratch/tweak-running-app/tweak-interaction-spec.md

@@ -0,0 +1,161 @@
+# Tweak — re-homed interaction spec (OPS-22)
+
+Reference-only design artifact. Rebuilds the Tweak interaction on the proof sidecar engine.
+No live engine, no polling, no variants, no speculative preview.
+
+Composed vocabulary used throughout:
+- **Comment** = discuss (human conversation about a target).
+- **Suggest** = propose (a human authors an edit for review).
+- **Tweak** = delegate (ask an agent to change a target; result arrives as a suggestion or reply).
+
+---
+
+## A. Entry point — third bubble-menu action
+
+**Decision: Tweak is a third, sibling action next to Comment and Suggest. Not a kind toggle inside Comment.**
+
+```
+[ B  I  U  S  <> | sup sub | link | 💬 Comment  ✎ Suggest  ✨ Tweak ]
+                                          (discuss) (propose) (delegate)
+```
+
+- Icon: `Wand2` (or `Sparkles`), same 28px button geometry as Comment/Suggest in `bubble-menu.tsx`. Title: "Tweak — ask an agent to change this".
+- Justification against existing semantics:
+  - Comment and Suggest are both **human-authored**. The unit of work the user commits to is "write words" (an opinion or a concrete edit).
+  - Tweak is **agent-bound**: the user commits to "describe intent", and the artifact's lifecycle (queued → sent → answered) is owned by the machine side. The two affordances diverge immediately after the first click.
+  - Folding Tweak into Comment with a kind toggle makes the dominant "discuss" path pay a mode choice it doesn't need, and hides the only agent entry point behind the least-agent-looking button in the UI.
+  - It also matches the surface truth: on text/code the entry point already exists as a separate pip, so parity is "one pip per intent", not "one pip with a toggle".
+- Read-only mode: Comment stays as-is. Tweak shows too (writing an instruction-comment is not a doc edit).
+
+### Text/code source viewer
+The existing Comment pip gains a sibling: **Tweak** pip on the same selection→lineAnchor detection. Same targeting panel. No new selection machinery.
+
+### HTML preview iframe
+**No Tweak affordance inside the iframe.** No element picker, no anchoring into the sandbox. See E.
+
+---
+
+## B. Default dispatch — instruction-comment (option a)
+
+**Decision: dispatch = persist `comment.add {kind:"instruction", instructionState:"queued"}` at the moment the user confirms the tweak. Copy-as-prompt is an ever-present secondary, not the default.**
+
+Rationale:
+1. **Durable and per-target by construction.** The artifact survives refresh, navigation, agent restarts. Copy-prompt dies the moment the user copies something else or the tab closes.
+2. **Agent idleness is not a failure mode.** The instruction waits in the sidecar; the agent picks it up on its own schedule via its normal snapshot/activity flow. "Queued" is a true statement, not a fake progress bar. PM's worry ("agent may be idle") is a *labeling* problem, not a dispatch problem — solve with copy, not with ephemerality.
+3. **One engine.** Option (b) reintroduces a second channel (clipboard) as the primary path and leaves the `instruction` kind — which already exists in the store — permanently UI-less. That leaves dead schema, which is worse than dormant lifecycle.
+4. The cost of (a) is honest-state UX (must visibly show "waiting", never imply work in progress). That cost is paid once, in the instruction card, and is itemized in F.
+
+Trade-off being accepted: if the user's agent never integrates with the sidecar, instructions dead-end at queued. Mitigation: every pending instruction card has **Copy as prompt** one click away, and nothing in the UI claims the agent is running.
+
+No client dispatcher in v1. "Dispatch" = write the op. The dormant queued→sent→answered lifecycle is driven by the agent's own reads/writes, exactly as designed in `types.ts`.
+
+---
+
+## C. Queue — dead. Each tweak persists immediately.
+
+**Decision: no queue bar, no batch step, no Cancel-all.** Cmd+Enter in the targeting panel writes the instruction-comment immediately. "Batch" = "the agent has N pending instructions", visible as N pips in the doc.
+
+- The old queue existed because the live engine needed a single dispatch moment for its variants round-trip. That reason is gone.
+- With instruction-comments, the sidecar *is* the queue. A second in-memory queue duplicates durable state, reintroduces lost-on-refresh risk, and forces Cancel semantics ("delete queued" vs "delete persisted") that don't exist anywhere else in the app.
+- **Dedup-in-place survives**: re-targeting a block/line that already has a pending instruction opens the panel prefilled with that instruction's text; Cmd+Enter updates it (`comment.update`), count does not grow.
+- Resulting chrome:
+
+```
+┌─ targeting panel (anchored to block, as before) ──────────────────┐
+│ ✨ Tweak this block                          [Copy as prompt]     │
+│ ┌──────────────────────────────────────────────────────────────┐ │
+│ │ What should change?                                          │ │
+│ └──────────────────────────────────────────────────────────────┘ │
+│                                      ⏎ Ask agent    esc Cancel   │
+└───────────────────────────────────────────────────────────────────┘
+
+  no bottom bar anywhere.
+
+┌─ pending instruction pip (block gutter, md) ───────────────────────┐
+│ ✨ you · queued — waiting for your agent            [Copy prompt]  │
+│ "Tighten this paragraph, keep the citation."                       │
+│                                                          [Remove]  │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+- Doc-level affordance (cheap, optional v1): toolbar chip "✨ N pending" when N>0; click = jump to first. This replaces the queue bar's only real value (visibility of outstanding work).
+
+---
+
+## D. Review loop
+
+### Markdown — full loop, existing machinery
+1. Agent reads the queued instruction, writes `suggestion.add` (replace/insert/delete) + flips the instruction to `answered` (link via `fromCommentId`/basis pointing at the instruction id).
+2. User sees the existing `suggestion-card.tsx` inline: two-pane replace diff, kindVerb header, Accept/Reject.
+3. Accept pushes the block op with `baseRevision`; 409 → retry once with `getLatestRevision()` (already implemented) → doc writes. The instruction is resolved when its linked suggestion settles.
+4. If the agent replies without a suggestion (a question/clarification), it lands as a **comment reply threaded on the instruction pip**. User can answer in-thread or dismiss the instruction.
+
+### Text/code — degraded, honest loop (comments only)
+- Instruction persists at the lineAnchor, pip appears in gutter, same queued/answered states.
+- The agent **cannot suggest**. Its answer arrives as a **comment reply containing the proposed lines in a fenced code block**, plus prose.
+- The user edits the file by hand. There is no Accept button.
+- The instruction card on these surfaces adds one line of expectation-setting copy:
+  > "Comments only on this file type — the agent replies here; you apply the change."
+- This is stated at *dispatch* time (footnote under the panel's Ask button), not discovered at answer time.
+
+### HTML
+No tweak in the preview. User path: switch to source view → line-anchored instruction → hand-apply. See E.
+
+---
+
+## E. Surface scope — ship markdown first
+
+**Ship: markdown-only tweak.** Then text/code (cheap incremental). HTML gets nothing beyond the source-view path.
+
+| Surface | Ships | Tweak gets | Honest limit |
+|---|---|---|---|
+| Markdown .md | v1 | instruction + suggestion + Accept-writes-doc | none |
+| Text/code | v1.1 (same engine, presumable immediately after) | instruction + comment-reply answer | no suggestions, no Accept; user hand-edits |
+| HTML | never in iframe | nothing | preview has no anchor model; all collaboration happens in source view |
+
+Explicit scope statement for the roadmap: **in-place accept exists only where suggestions exist, and suggestions exist only in markdown.** Any tweak on any other surface ends in "read the reply, edit by hand". The UI must say this at the moment of dispatch, not bury it.
+
+Html-iframe element-picking from the pre-removal build is permanently dropped with its engine. Do not resurrect.
+
+---
+
+## F. States
+
+1. **Targeting**
+   - md: select text/block → bubble menu ✨ → panel anchored. Text/code: selection → Tweak pip → same panel. Footer always: [Copy as prompt] secondary + ⏎ Ask agent primary + esc Cancel. Outside-click with empty input = cancel (unchanged from pre-removal build).
+   - Non-md panel footnote: "Agent answers as a comment on this line."
+2. **No-agent**
+   - Tweak still writes the instruction (durability doesn't depend on a live agent). Panel secondary button label: "Copy as prompt".
+   - Where agent status is surfaced (toolbar chip / AI panel entry): "Connect an agent" CTA opens the AI panel. Pending instruction is preserved (it's in the sidecar, so nothing to preserve — that's the point of B).
+   - Copy-as-prompt emits the exact pre-removal format: `Edit the file \`X\` (a Markdown document). Apply these changes:\n\n1. \`<snippet>\`: <instruction>`; single tweak → same string minus numbering OR keep numbering for format stability (recommend: keep `1.` always, one code path). Clipboard gate + "Show" textarea fallback unchanged.
+3. **Dispatched/pending** (`queued`/`sent`)
+   - Pip + expanded card: instruction text, state line "waiting for your agent", [Copy prompt], [Remove]. No spinner claiming activity. Copy states "Your agent will pick this up when it next reads this file."
+4. **Answered**
+   - md: suggestion-card inline (existing Accept/Reject). Instruction collapses to a settled state linked from the card's reason line ("In response to: <instruction text>").
+   - text/code: reply in instruction thread with fenced proposal; card gains [Mark done] (human-settled, no doc write).
+5. **Error/drift**
+   - Accept collision: handled (409 + single retry in suggestion-card). Fingerprint mismatch after retry: card shows "Document changed since this suggestion — refresh review"; user re-reviews.
+   - Target moved/deleted (stale ref/textHash): instruction pip turns to "⚠ target changed" with [Re-anchor] (re-open targeting on best-effort current match), [Copy prompt], [Remove]. Never silently drop.
+6. **Empty**
+   - No pending instructions + no open panel = zero chrome. No empty queue bar, no placeholder states.
+
+State→copy-prompt presence summary: visible in **every** state except Targeting-with-agent-idle (where it's the secondary anyway). It is the universal escape hatch, not a mode.
+
+---
+
+## Open questions
+
+1. Does the agent actually flip `instructionState` queued→sent→answered, or does it simply answer and we infer? (Server/route contract — needs an ops decision, not a UX one.)
+2. Suggestion↔instruction linkage: add `fromInstructionId` to suggestion, or reuse existing basis fields? Prefer explicit id; basis strings are for humans.
+3. Telemetry: none in v1, but "how many tweaks dead-end at queued for >24h" is the metric that validates decision B. Worth a follow-up.
+
+---
+
+## Summary (recommended design)
+
+1. Third bubble-menu action ✨ Tweak (delegate) beside Comment (discuss) and Suggest (propose); matching pip in text/code viewer; nothing in the HTML iframe.
+2. Dispatch persists a durable `instruction`-kind comment immediately — copy-as-prompt is the constant secondary/escape hatch, never the default.
+3. Queue bar is deleted; the sidecar is the queue; dedup-in-place survives.
+4. Markdown review = existing suggestion-card Accept/Reject; text/code review = agent reply in thread + human hand-edit, with the limitation stated at dispatch time.
+5. Ship markdown-only first; text/code follows on the same engine; HTML collaborates only via source view.
+6. **Riskiest assumption:** the user's chat agent actually consumes the sidecar and answers with a suggestion op — the dormant instruction lifecycle becoming real is the entire bet of option B; if it never integrates, every tweak ends at "queued + copy prompt", and the UI must already be honest about that on day one.