diff --git a/codev/plans/863-vscode-markdown-preview-marker.md b/codev/plans/863-vscode-markdown-preview-marker.md
new file mode 100644
index 000000000..6a1d39e30
--- /dev/null
+++ b/codev/plans/863-vscode-markdown-preview-marker.md
@@ -0,0 +1,107 @@
+# PIR Plan: Marker-aware artifact canvas — inline-below comment cards + right-edge minimap
+
+Issue: #863 — *vscode: markdown preview marker-aware features — inline REVIEW rendering + right-edge marker minimap*
+
+## Understanding
+
+The issue asks the Codev markdown preview to make the REVIEW-marker feedback layer **visible** in two complementary ways: (1) render each marker as an in-context call-out anchored to the block it annotates, and (2) give a spatial overview of where markers sit via a right-edge minimap.
+
+The issue body has two eras. The original "Implementation sketch" (a VSCode `markdown-it` plugin + `previewScripts`) is **stale** — its own "Update (post-#859 / PR #1045)" section says so. After #859/#945, the rendering surface is the React package **`packages/artifact-canvas/`**, mounted by VSCode as a read-only `CustomTextEditor` (`packages/vscode/src/markdown-preview/preview-provider.ts` + `webview/main.ts`). I verified this against the tree; the markdown-it/previewScripts files the sketch names do not exist.
+
+Two consequences of the `CustomTextEditor` reality that reshape the issue's acceptance criteria:
+
+1. **There is no separate "source editor" to jump into.** The canvas *is* the editor surface. The inline cards already sit beside the content they annotate, so the original "click call-out → open source file at the marker's line" loses its target. I reframe inline cards as **read-only display** (the AC's stated v1 intent is "read + click-to-jump only"); the click-to-jump affordance is preserved on the **minimap dots**, which smooth-scroll the canvas to the marker — an internal scroll, not a host round-trip.
+2. **The concrete bug to fix is the overlap.** Today `ArtifactCanvas.tsx` renders the active block's markers in an *absolutely-positioned hover overlay* anchored at the block's `offsetTop` (`ArtifactCanvas.tsx:193-216`, `.codev-canvas-marker-list` in `default-theme.css:79-88`). The list paints over the first lines of the block. The issue's recommended fix (and "Additional acceptance criteria for the layout fix") is **inline-below**: cards rendered in document flow below the annotated block, pushing subsequent content down, tied to the gutter by a thin vertical rule, with no slot when a block has zero comments.
+
+### Current code map (verified)
+
+- `packages/artifact-canvas/src/components/ArtifactCanvas.tsx` — owns content + markers state, the post-render decoration effect (`:118-149`), the hover overlay (`:193-216`).
+- `packages/artifact-canvas/src/renderer/renderer.ts` — strips full-line HTML comments, stamps `data-line` + `tabindex` on blocks. **No change needed.**
+- `packages/artifact-canvas/src/styles/default-theme.css` — 8 `--codev-canvas-*` tokens, overlay + marker-list styles.
+- `packages/artifact-canvas/src/overlays/CommentAffordance.tsx` — the `+` button. **No change needed.**
+- `packages/vscode/src/markdown-preview/preview-template.ts:39-50` — maps the 8 tokens to `--vscode-*`. Reusing existing tokens means **no host change** for theming.
+- `packages/vscode/src/markdown-preview/webview/main.ts` — mounts `<ArtifactCanvas>`. No new props needed (minimap + cards are internal to the package).
+- #861 floating TOC: **does not exist yet** (no grep hits) — "compose with TOC" is forward-looking; the minimap just must not hard-claim space a future TOC would want.
+
+## Proposed Change
+
+All work lands in the **`@cluesmith/codev-artifact-canvas` package** so every host (VSCode preview today; dashboard / mobile later) inherits it. No new public props, no new tokens, no host wiring changes.
+
+### 1. Inline-below comment cards (the layout fix + "inline REVIEW rendering")
+
+Replace the hover overlay's marker-list with an **always-visible card stack injected inline-below each annotated block**, in document flow.
+
+- Keep the existing post-render effect pattern (imperative DOM, consistent with `ArtifactCanvas.tsx:118-149`). For each `[data-line]` block that has markers, build a `<div class="codev-canvas-marker-cards">` containing one `<div class="codev-canvas-marker-card">` per marker (author label + body), and insert it as the block's next sibling. Clean up previously-injected stacks at the top of the effect (so re-renders from watch/refreshKey don't duplicate). Injecting real DOM siblings means the stack participates in flow and **pushes subsequent content down** (no overlap), satisfying the layout AC.
+- A thin vertical rule = a left border / accent on `.codev-canvas-marker-cards`, aligned into the existing left gutter (`padding-left: 1.9rem` on `.codev-artifact-canvas-body`), visually tying the stack to the `+` gutter.
+- Zero-comment blocks get **no injected node** → no slot, no consumed vertical space (AC).
+- Multiple markers on one line render in `markers` order, which is the codec's `parseReviewMarkers` order (creation order) (AC).
+- The hover overlay keeps **only** the `+` `CommentAffordance` (add-comment intent unchanged). Remove the `.codev-canvas-marker-list` branch and `activeMarkers` plumbing from the overlay.
+- Keep the existing `.codev-canvas-has-marker` left accent bar on the block as a cheap in-context "this block has feedback" cue (complementary, non-overlapping).
+- Cards are display-only (no click handler) — see Understanding for why click-to-jump moved to the minimap.
+
+### 2. Right-edge marker minimap
+
+A new `MarkerMinimap` component, rendered by `ArtifactCanvas` as a child of `.codev-artifact-canvas` (which is already `position: relative`).
+
+- One dot per marker. Dot vertical position is proportional to the annotated block's offset within the rendered body (`block.offsetTop / body.scrollHeight`), mapped onto the minimap column height. Recompute via a layout effect on `[html, markers]` and on a debounced `resize` (window) — the issue's "updates on resize and rebuild".
+- `position: fixed` column at the viewport right edge (matches the issue's drawing and the webview's full-window scroll model). Narrow strip so a future #861 TOC can sit beside it without fighting (documented, not enforced).
+- **Hover dot** → native `title` = `@author: <first ~80 chars of body>` (AC tooltip).
+- **Click dot** → `block.scrollIntoView({ behavior: 'smooth', block: 'center' })` (AC smooth-scroll). Dots are real `<button>`s (keyboard-reachable, accessible label), mirroring `CommentAffordance`.
+- **Hidden entirely when zero markers** (AC) — render nothing.
+
+### 3. Bundled polish: anchor the `+` to the first line's center (issue comment)
+
+The architect's issue comment asks to anchor the `+` affordance to the first line's vertical center instead of the block's top edge (`.codev-canvas-overlay { align-items: flex-start }` + `setOverlayTop(el.offsetTop)`). Small, directly related, and explicitly "fits alongside this issue's polish". I'll fold it in: offset the overlay `top` by roughly half the first line's height (computed from the block's line-height / first client rect) with `transform: translateY(-50%)` on the button, kept in the package. **Flagged for the human at the gate** — easy to drop from this bundle if you'd rather it be its own change.
+
+## Files to Change
+
+- `packages/artifact-canvas/src/components/ArtifactCanvas.tsx`
+  - Decoration effect (`:118-149`): inject/cleanup inline-below card stacks per annotated block.
+  - Overlay (`:193-216`): drop the `marker-list` branch; keep only the `+` affordance. Adjust the `+` anchor (bundled polish).
+  - Render `<MarkerMinimap markers={markers} bodyRef={bodyRef} />`.
+- `packages/artifact-canvas/src/overlays/MarkerMinimap.tsx` — **new.** Dots, positioning effect, resize handler, click→scroll, hover title, hidden-when-empty.
+- `packages/artifact-canvas/src/styles/default-theme.css`
+  - New `.codev-canvas-marker-cards` / `.codev-canvas-marker-card` (inline-below, vertical rule, theme tokens).
+  - New `.codev-canvas-minimap` / `.codev-canvas-minimap-dot` (fixed right column, dots).
+  - Remove/replace the now-unused `.codev-canvas-marker-list`; adjust `.codev-canvas-overlay` for the `+`-center anchor.
+- `packages/artifact-canvas/src/components/__tests__/artifact-canvas.test.tsx`
+  - Update the "surfaces … via the overlay" test (`:177-190`) to assert the **inline card** instead.
+  - Add: inline card injected below the annotated block; no slot for zero-comment blocks; multi-marker stack order; add-comment flow still works (regression).
+- `packages/artifact-canvas/src/overlays/__tests__/marker-minimap.test.tsx` — **new.** Dot count = marker count; hidden when zero; click → `scrollIntoView` spy; title contains author + truncated body.
+- `packages/artifact-canvas/src/index.ts` — export `MarkerMinimap` only if it needs to be public (likely internal-only; default: no export change).
+
+**No `packages/vscode/` changes expected.** If a CSP / fixed-positioning quirk in the real webview forces a tweak, it would be confined to `preview-template.ts` and called out at dev-approval.
+
+## Risks & Alternatives Considered
+
+- **Risk: imperative DOM injection desyncs from React's innerHTML body.** Mitigation: rebuild from scratch each effect run (cleanup-then-inject), keyed off `[html, markers]` exactly like the existing decoration effect — same proven pattern, same lifecycle.
+- **Risk: `scrollHeight`/`offsetTop` are 0 in jsdom**, so minimap *position* math is untestable in unit tests. Mitigation: unit-test structure/behavior (counts, hidden-when-empty, click→`scrollIntoView` spy, tooltip text); verify pixel positioning manually in the running webview at the `dev-approval` gate (the gate exists precisely for visual/running review).
+- **Risk: removing the overlay marker-list breaks an existing test.** Expected and intended — that test asserts the *old* overlapping behavior. I update it to assert the new inline card; the regression-relevant behavior (add-comment intent) keeps its own passing tests.
+- **Risk: `position: fixed` minimap fights a future #861 TOC.** #861 isn't built yet; I keep the strip narrow and documented as composable. No enforcement possible against code that doesn't exist.
+- **Alternative — render cards by interleaving React children** instead of DOM injection: rejected; the body is a single `dangerouslySetInnerHTML` blob, so interleaving means a full renderer rewrite (parse to React tree) — far larger blast radius than the issue warrants.
+- **Alternative — keep the overlay but add top-padding to the block** (the issue's "top padding push" row): rejected for the same reasons the issue rejects it (consumes space inelegantly, no clean multi-card story).
+- **Alternative — put the minimap in the VSCode webview (`previewScripts`)** per the stale sketch: rejected; it would not be inherited by the dashboard/mobile hosts and would duplicate marker state the package already holds.
+
+## Test Plan
+
+**Unit (vitest + @testing-library/react, run from `packages/artifact-canvas/`):**
+- `pnpm test` — existing suite stays green (add-comment intent, round-trip, error paths, request-versioning, refreshKey).
+- New/updated:
+  - Inline card renders below a block that has a marker; shows author + body.
+  - A block with zero markers injects no card node.
+  - Two markers on one line render two cards in creation order.
+  - Add-comment flow unchanged: hover → `+` → click → `onAddComment(line)`; package never calls `markerAdapter.add`.
+  - Minimap: dot count == marker count; nothing rendered when zero markers; clicking a dot calls `scrollIntoView` (spied); dot `title` contains author + truncated body.
+- `pnpm check-types` clean; `pnpm build` (tsup) clean.
+
+**Manual at the `dev-approval` gate (the killer move — run the worktree):**
+- Open a `codev/plans|specs|reviews/*.md` with REVIEW markers in the Codev Markdown Preview (`afx dev pir-863`, then "Reopen With… Codev Markdown Preview" or `codev.openMarkdownPreview`).
+- Verify: cards render inline-*below* each annotated block (no overlap); content below is pushed down; zero-comment blocks consume no space; the thin vertical rule ties cards to the gutter; multi-comment blocks stack in order.
+- Verify minimap: one dot per marker, roughly proportional vertical placement; hover shows author + truncated body; click smooth-scrolls to the card; minimap absent on a marker-free doc.
+- Verify `+` add-comment still works end-to-end (hover → `+` → InputBox → marker appears as a new card on refresh) and the `+` now sits centered on the first line.
+- Verify theme: switch a dark/light VSCode theme; colors track `--vscode-*` (cards + dots).
+- Path eligibility unchanged: a non-`codev/(plans|specs|reviews)` markdown file is unaffected (preview is opt-in for those paths).
+
+## Out of Scope (carried from the issue)
+
+Reply/thread display, resolve-state coloring, filter UI, editing from the call-out, per-marker minimap colors, outline-panel enrichment. v1 keeps single-comment-per-card display, uniform dot color, read + minimap-click-to-scroll only.
diff --git a/codev/projects/863-vscode-markdown-preview-marker/status.yaml b/codev/projects/863-vscode-markdown-preview-marker/status.yaml
new file mode 100644
index 000000000..907f6386e
--- /dev/null
+++ b/codev/projects/863-vscode-markdown-preview-marker/status.yaml
@@ -0,0 +1,30 @@
+id: '863'
+title: vscode-markdown-preview-marker
+protocol: pir
+phase: review
+plan_phases: []
+current_plan_phase: null
+gates:
+  plan-approval:
+    status: approved
+    requested_at: '2026-06-16T07:47:50.246Z'
+    approved_at: '2026-06-16T08:05:51.252Z'
+  dev-approval:
+    status: approved
+    requested_at: '2026-06-16T08:14:42.799Z'
+    approved_at: '2026-06-16T12:04:46.502Z'
+  pr:
+    status: approved
+    requested_at: '2026-06-16T12:15:30.869Z'
+    approved_at: '2026-06-16T12:21:46.756Z'
+iteration: 1
+build_complete: true
+history: []
+started_at: '2026-06-16T07:43:36.724Z'
+updated_at: '2026-06-16T12:21:46.756Z'
+pr_history:
+  - phase: review
+    pr_number: 1056
+    branch: builder/pir-863
+    created_at: '2026-06-16T12:08:43.047Z'
+pr_ready_for_human: false
diff --git a/codev/resources/lessons-learned.md b/codev/resources/lessons-learned.md
index 2197c9e7a..f5cde1c11 100644
--- a/codev/resources/lessons-learned.md
+++ b/codev/resources/lessons-learned.md
@@ -431,6 +431,8 @@ Generalizable wisdom extracted from review documents, ordered by impact. Updated
 - [From 1047] A backpressure "relief valve" that re-fetches the overflowing payload is an infinite loop. The VSCode terminal's old rule was "receive buffer > 1 MB → disconnect and reconnect for a fresh replay" — but the oversized thing *was* the replay, so each reconnect re-delivered it: ~14,000 connect→overflow→reconnect cycles in under an hour (visible 1:1:1 in the client log), pegging one core and starving every terminal. For ephemeral live output, *drop* under overload (the app repaints); reserve reconnect for genuine transport loss, and never make the overload remedy re-pull the same bytes.
 - [From 787] When adding a field to a multi-forge concept contract (`pr-list`, `issue-list`, …), per-CLI data availability diverges — do not assume parity across `gh`/`glab`/`tea`. Verify each empirically (live output or, failing that, the CLI's own `--help` and official docs): `gh pr list --json` exposes `isDraft` + `reviewRequests` (reviewer objects → flatten `.login`, dropping teams); `glab mr list --output json` exposes `draft` + `reviewers[].username` (same command, just add jq); but `tea pulls list` exposes *neither* (its JSON is limited to the selectable `--fields`, which omit draft/reviewers — the data exists only via raw `tea api`). Populate where the existing command can; default safely (`[]`/`false`) where it can't, and document the verified reason in the script. Defaulting a field the CLI *does* expose silently drops working data; rewriting a script onto a different command (e.g. `tea api`) to reach an unavailable field is a separate, larger change. Make the new required fields safe end-to-end by defaulting at the server mapping (`?? []` / `?? false`) so a non-conforming forge degrades rather than emitting `undefined`.
 
+- [From 863] React's `dangerouslySetInnerHTML` re-commits the element's innerHTML on *every* re-render, silently wiping any DOM children you injected imperatively into that same element. The artifact-canvas renders parsed markdown into the body via `dangerouslySetInnerHTML`, then injected inline comment cards as DOM children of the parsed blocks; the cards flashed on first paint and vanished on the next render (a refreshKey bump), while the React-owned minimap survived untouched — that asymmetry located the bug in the React-owned subtree, not the injection logic (a faithful jsdom repro of the injection round-trip kept the card every time, proving the defect was browser-render-only). Fix: stop letting React own that subtree — set `ref.innerHTML = html` imperatively inside a `[html]`-keyed `useEffect`, then inject the non-React DOM after, so React never re-commits those children (the standard escape hatch for mixing hand-built DOM into a React tree). Rule of thumb: never imperatively mutate the children of a node React controls via `dangerouslySetInnerHTML` — render everything through React, or own the whole subtree imperatively, never both.
+
 ---
 
 *Last updated: 2026-04-17 (Maintenance run 0007 — v3.0.0 pre-release)*
diff --git a/codev/reviews/863-vscode-markdown-preview-marker.md b/codev/reviews/863-vscode-markdown-preview-marker.md
new file mode 100644
index 000000000..b46ead7de
--- /dev/null
+++ b/codev/reviews/863-vscode-markdown-preview-marker.md
@@ -0,0 +1,60 @@
+# PIR Review: Markdown preview marker-aware features — inline REVIEW cards + right-edge minimap
+
+Fixes #863
+
+## Summary
+
+The Codev Markdown Preview previously rendered REVIEW markers as a minimal v1 overlay that sat *on top of* the annotated block, hiding its first lines. This change moves marker display into the `@cluesmith/codev-artifact-canvas` package as always-visible **inline-below comment cards** (rendered in document flow beneath each annotated block, so they push following content down instead of overlapping it) plus a new **right-edge marker minimap** (one dot per REVIEW marker, hover tooltip, click to smooth-scroll). Both surfaces derive from the same `parseReviewMarkers` source of truth and are pure rendering — no new interaction beyond click-to-jump, no on-disk format change. Implementing in artifact-canvas means every host that embeds the canvas inherits the behavior, not just VSCode.
+
+## Files Changed
+
+- `packages/artifact-canvas/src/components/ArtifactCanvas.tsx` (+~75 / -~35) — inline-below card stacks injected in flow; dropped the overlapping hover overlay marker-list; `+` affordance anchored to the first line's vertical center; body now set via imperative `innerHTML` in a `[html]`-keyed effect (see Lessons)
+- `packages/artifact-canvas/src/overlays/MarkerMinimap.tsx` (+87 / -0, new) — right-edge fixed dot column; hover title; click → smooth-scroll; hidden when zero markers
+- `packages/artifact-canvas/src/styles/default-theme.css` (+~55 / -~15) — card-stack + minimap styles using existing `--codev-canvas-*` tokens; left-rule + `padding-left` so the marker bar clears the annotated text
+- `packages/artifact-canvas/src/components/__tests__/artifact-canvas.test.tsx` (+~50) — updated overlay-marker assertions to inline cards
+- `packages/artifact-canvas/src/components/__tests__/marker-card-persistence.test.tsx` (+139 / -0, new) — regression repro for the flash-then-vanish card bug
+- `packages/artifact-canvas/src/overlays/__tests__/marker-minimap.test.tsx` (+69 / -0, new) — dot count / hidden-when-empty / click→scrollIntoView / tooltip
+- `codev/plans/863-vscode-markdown-preview-marker.md`, `codev/state/pir-863_thread.md`, `codev/projects/863-*/status.yaml` — protocol artifacts
+
+## Commits
+
+- `f13c6607` [PIR #863] Inline-below comment cards + right-edge marker minimap
+- `c7869a99` [PIR #863] Tests for inline cards and marker minimap
+- `256f5788` [PIR #863] Fix comment cards vanishing: own markdown body innerHTML imperatively
+- `cba892fd` [PIR #863] Thread: dev-approval card-disappear finding + fix
+- `be6a2958` [PIR #863] Add padding so marker bar doesn't crowd annotated text
+
+## Test Results
+
+- `pnpm --filter @cluesmith/codev-artifact-canvas build` (tsup): ✓ pass
+- `pnpm --filter @cluesmith/codev-artifact-canvas test` (vitest): ✓ pass (50 tests, ~30 new across the two new test files + updated assertions)
+- VSCode webview bundle (`node esbuild.js --production`): ✓ rebuilt
+- Manual verification (human, at the `dev-approval` gate): inline cards render below each annotated block with no overlap; multi-comment blocks stack in creation order; zero-comment blocks consume no space; minimap dots persist with working hover tooltip + click-scroll; `+` add-comment flow intact. The reviewer caught two issues during this gate, both fixed and re-reviewed: (1) added cards flashed then vanished; (2) the marker accent bar crowded the annotated text.
+
+## Architecture Updates
+
+No arch changes — this PR adds rendering surfaces *inside* the existing `artifact-canvas` package (a new internal overlay component + CSS). It introduces no new module boundary, invariant, port, or cross-cutting fact, and does not alter the marker on-disk format or the host adapter contract. Nothing qualifies for `arch-critical.md` (hot) or `arch.md` (cold).
+
+## Lessons Learned Updates
+
+Added one entry to the **cold** `codev/resources/lessons-learned.md` (Debugging and Root Cause Analysis section), `[From 863]`: React's `dangerouslySetInnerHTML` re-commits the element's innerHTML on every re-render, silently wiping imperatively-injected DOM children — which was the exact root cause of the flash-then-vanish bug the reviewer found at the gate. The fix is the standard escape hatch: set `innerHTML` imperatively in a `[html]`-keyed effect so React no longer owns that subtree. Routed to cold (not hot `lessons-critical.md`) because it is a spec-narrow React/webview recipe, not a behavior-changing cross-cutting rule, and the hot tier is at its cap.
+
+## Things to Look At During PR Review
+
+- **[Codex REQUEST_CHANGES — fixed] Multi-`data-line` block anchoring.** The PR-stage 3-way consult (Codex, HIGH confidence) found that the card-injection loop ran for *every* `[data-line]` match, but the renderer stamps the same `data-line` on multiple nested blocks for one source line (e.g. both a `ul` and its `li`; `renderer/__tests__/data-line.test.ts`). A marker on a list/blockquote/table line therefore injected a **duplicate** card stack and, worse, **invalid `ul > ul` DOM** (the stack is itself a `<ul>`, so `el.after(...)` on the inner `<li>` nested it under the parent list). Fixed in `ArtifactCanvas.tsx` by anchoring the stack + `has-marker` decoration to the *first* match per line (querySelectorAll yields tree order, so first = outermost block). Pinned by a regression test ("anchors a single card stack to the OUTERMOST block…") that fails without the fix (`expected 2 to be 1`). The minimap was assessed and is **not** affected: it maps over `markers` (one dot per marker, not per `[data-line]` node) and its `querySelector` returns the outermost block in tree order — consistent with the card anchor. Reviewer: please sanity-check a real list/blockquote/table marker in the running worktree.
+- **`ArtifactCanvas.tsx` body rendering** — the switch from `dangerouslySetInnerHTML` to an imperative `innerHTML` assignment in a `[html]`-keyed `useEffect`. This is the load-bearing fix for the card-persistence bug; confirm the effect dependency array is exactly `[html]` and that nested-block markers still resolve (the imperative path must preserve the same parsed DOM the JSX path produced).
+- **Card injection vs. React reconciliation** — cards are injected into the now-React-unowned body subtree. Verify no path re-introduces React ownership of that subtree (which would re-trigger the wipe).
+- **Minimap positioning under jsdom** — minimap position tests assert *structure* (dot count, hidden-when-empty, click→`scrollIntoView` spy, tooltip text), not pixel coordinates, because jsdom has no layout engine. Real proportional placement was verified manually at the dev-approval gate, not in unit tests.
+- **Theme tokens** — all colors flow through the eight `--codev-canvas-*` tokens; no hardcoded colors. Worth a glance that the new card/minimap rules don't introduce a raw hex outside `default-theme.css`'s token block.
+
+## How to Test Locally
+
+- **View diff**: VSCode sidebar → right-click builder `pir-863` → **Review Diff**
+- **Run dev server**: VSCode sidebar → **Run Dev Server**, or `afx dev pir-863`
+- **What to verify**:
+  - Open a `codev/(plans|specs|reviews)/*.md` containing REVIEW markers in the Codev Markdown Preview
+  - Inline cards render *below* each annotated block (no overlap); content below is pushed down; zero-comment blocks consume no extra space; the thin left rule ties cards to the gutter; multi-comment blocks stack in creation order
+  - Minimap: one dot per marker, roughly proportional placement; hover shows author + truncated body; click smooth-scrolls to the card; minimap absent on a marker-free doc
+  - `+` add-comment still works end-to-end (hover → `+` → input → marker appears as a new card on refresh); `+` sits centered on the first line
+  - Switch a dark/light theme; card + dot colors track `--vscode-*`
+  - A non-`codev/(plans|specs|reviews)` markdown file is unaffected (preview opt-in for those paths)
diff --git a/codev/state/pir-863_thread.md b/codev/state/pir-863_thread.md
new file mode 100644
index 000000000..d8fa3c544
--- /dev/null
+++ b/codev/state/pir-863_thread.md
@@ -0,0 +1,86 @@
+# PIR #863 — vscode markdown preview marker-aware features
+
+## Plan phase (in progress)
+
+Investigated the post-#859 world. Key findings:
+
+- The rendering surface is **`packages/artifact-canvas/`** (React package), NOT a VSCode
+  markdown-it plugin. The issue's original "Implementation sketch" (markdown-it plugin +
+  previewScripts) is stale; the update section confirms this.
+- The canvas is mounted as a **`CustomTextEditor`** (`packages/vscode/src/markdown-preview/
+  preview-provider.ts` + `webview/main.ts`). It REPLACES the source editor — there is no
+  separate "source editor" to click-to-jump into. So inline-card click-to-jump is reframed.
+- Current marker rendering: `ArtifactCanvas.tsx` shows markers two ways — (a) a left inset
+  accent bar (`.codev-canvas-has-marker`) on the block, and (b) an absolutely-positioned
+  hover overlay marker-list anchored at the block's `offsetTop`. The overlay marker-list is
+  the thing that **overlaps content** (the issue's "new concrete symptom").
+- #861 floating TOC does NOT exist yet (no grep hits) — "compose with TOC" is forward-looking;
+  I just need to not preclude it.
+- Theme tokens: 8 `--codev-canvas-*` vars in `default-theme.css`, mapped to `--vscode-*` in
+  `preview-template.ts`. Reuse existing tokens; no host changes needed for theming.
+- Tests: vitest + @testing-library/react (jsdom). jsdom has no layout, so minimap position
+  tests must assert structure (dot count, hidden-when-empty, click→scrollIntoView spy), not px.
+
+Decision: implement entirely in the artifact-canvas package (so all hosts inherit it):
+1. Move marker display from the hover overlay to always-visible **inline-below card stacks**.
+2. Add a **right-edge minimap** component (dots, hover tooltip, click→smooth-scroll).
+3. (Bundled, from issue comment) anchor the `+` affordance to the first line's vertical center.
+
+Writing plan to codev/plans/863-vscode-markdown-preview-marker.md.
+
+## Implement phase (in progress)
+
+plan-approval gate approved. Implementing in the artifact-canvas package:
+1. ArtifactCanvas.tsx — inject inline-below card stacks (DOM siblings, in flow);
+   drop the overlapping hover overlay marker-list; keep the "+" affordance; anchor "+"
+   to the first line's vertical center (bundled polish from the issue comment).
+2. MarkerMinimap.tsx (new) — right-edge fixed dot column; hover title; click→smooth-scroll;
+   hidden when zero markers.
+3. default-theme.css — card stack + minimap styles (existing --codev-canvas-* tokens only).
+4. Tests — update the old overlay-marker-list test to assert inline cards; add minimap tests.
+
+## dev-approval finding: comment cards flashed then vanished
+
+Reviewer reported: added comments appear momentarily then disappear; minimap dots persist.
+
+Diagnosis (captured, not guessed):
+- Built a faithful jsdom repro of the webview refreshKey round-trip (real parseReviewMarkers
+  semantics) — basic add, mid-paragraph split (#1036), and double-update. ALL kept the card.
+  So the injection logic is correct in isolation; the defect is browser-only.
+- Decisive asymmetry: the React-rendered minimap survived; the DOM-injected card (a child of the
+  dangerouslySetInnerHTML body that React owns) vanished. Root cause: React re-commits the body's
+  innerHTML on a re-render, wiping imperatively-injected children.
+
+Fix: stop using dangerouslySetInnerHTML for the body. Set body.innerHTML imperatively in a
+[html]-keyed effect so React no longer owns those children and can't re-commit/​wipe them (the
+standard React escape hatch for non-React DOM). Cards + has-marker decoration are now stable.
+Preserves nested-block markers and avoids HTML-splitting/layout risk. 50/50 tests pass; package +
+vscode webview bundle rebuilt.
+
+## Review phase
+
+dev-approval approved (reviewer caught + I fixed two things at the gate: card flash-then-vanish,
+and the marker accent bar crowding the text → added padding-left:10px).
+
+Wrote codev/reviews/863-vscode-markdown-preview-marker.md (Summary + Architecture Updates [none —
+internal-to-package] + Lessons Learned [added [From 863] React dangerouslySetInnerHTML re-commit
+wipes injected children → cold lessons-learned.md, Debugging section]). Opened PR #1056 (Fixes #863),
+recorded with porch. Ran `porch done 863` → single-pass 3-way consult in flight. Waiting at pr gate.
+
+Side discussion w/ architect: edit/delete/reply/resolve are out of scope here (storage-format
+blocked). Filed umbrella issue #1055 (Comment system v2) at architect's request.
+
+## PR-stage 3-way consult (single advisory pass)
+
+- gemini=APPROVE (off-track run — explored wrong dir, no weight)
+- claude=APPROVE (HIGH, no key issues; 2 non-blocking notes: emoji portability, key=index → no change)
+- codex=REQUEST_CHANGES (HIGH) — REAL: card stack injected per-[data-line] match, but renderer
+  stamps same data-line on nested blocks (ul+li) → duplicate stack + invalid ul>ul DOM for
+  list/blockquote/table markers. Minimap NOT affected (maps over markers, querySelector=outermost).
+
+FIXED: anchor stack+has-marker to first (outermost) match per line via decoratedLines Set.
+Regression test "anchors a single card stack to the OUTERMOST block…" — confirmed fails without
+fix (expected 2 to be 1), passes with. 51/51 green. Rebuttal at codev/projects/863-*/...rebuttals.md.
+
+Pushed to PR #1056. Notified architect (led with REQUEST_CHANGES + disposition; escalated that
+PIR won't re-review). pr gate PENDING — waiting for human approval, then merge.
diff --git a/packages/artifact-canvas/src/components/ArtifactCanvas.tsx b/packages/artifact-canvas/src/components/ArtifactCanvas.tsx
index 9bd274930..270b61532 100644
--- a/packages/artifact-canvas/src/components/ArtifactCanvas.tsx
+++ b/packages/artifact-canvas/src/components/ArtifactCanvas.tsx
@@ -2,6 +2,7 @@ import * as React from 'react';
 import type { ArtifactCanvasProps, ReviewMarker } from '../types.js';
 import { renderMarkdown } from '../renderer/renderer.js';
 import { CommentAffordance } from '../overlays/CommentAffordance.js';
+import { MarkerMinimap } from '../overlays/MarkerMinimap.js';
 
 /**
  * ArtifactCanvas — the composed review surface (Phase 3).
@@ -17,6 +18,40 @@ import { CommentAffordance } from '../overlays/CommentAffordance.js';
  * optional `onError` prop; the component never throws out of an event handler, and a failed
  * `list()` leaves the prior markers in place (spec D2).
  */
+/**
+ * Build an inline-below comment-card stack for one annotated block (#863). Returns a `<ul>` to be
+ * inserted as the block's next sibling. Markers render in `markers` order — i.e. the order
+ * `parseReviewMarkers` produces (creation order). Author and body are set via `textContent`, so
+ * document-supplied text can never inject markup into the canvas.
+ */
+function buildMarkerCards(line: number, markers: ReviewMarker[]): HTMLUListElement {
+  const stack = document.createElement('ul');
+  stack.className = 'codev-canvas-marker-cards';
+  // Human-facing line numbers are 1-based; the data model stays 0-based (spec D5).
+  stack.setAttribute('aria-label', `Comments on line ${line + 1}`);
+  for (const m of markers) {
+    const card = document.createElement('li');
+    card.className = 'codev-canvas-marker-card';
+
+    const icon = document.createElement('span');
+    icon.className = 'codev-canvas-marker-card-icon';
+    icon.setAttribute('aria-hidden', 'true');
+    icon.textContent = '💬';
+
+    const author = document.createElement('span');
+    author.className = 'codev-canvas-marker-card-author';
+    author.textContent = m.author;
+
+    const body = document.createElement('span');
+    body.className = 'codev-canvas-marker-card-body';
+    body.textContent = m.text;
+
+    card.append(icon, author, body);
+    stack.append(card);
+  }
+  return stack;
+}
+
 export function ArtifactCanvas(props: ArtifactCanvasProps): React.ReactElement {
   const { uri, fileAdapter, markerAdapter, onAddComment, onError, refreshKey } = props;
 
@@ -112,12 +147,34 @@ export function ArtifactCanvas(props: ArtifactCanvasProps): React.ReactElement {
 
   const html = React.useMemo(() => renderMarkdown(content), [content]);
 
-  // Decorate the rendered (innerHTML) DOM after each render: make blocks keyboard-focusable and
-  // mark lines that carry a ReviewMarker (v1 minimal marker rendering — deferred #4; #863 adds
-  // polished inline markers + the canvas minimap).
+  // Own the markdown body imperatively rather than via React's `dangerouslySetInnerHTML`. React
+  // must NOT manage these children: when it did, a re-render would re-commit `innerHTML` and wipe
+  // the comment cards we inject below (the "cards flash then vanish" bug — the React-rendered
+  // minimap survived precisely because React owned it, while the injected cards did not). With the
+  // body left out of React's child reconciliation, the cards + decoration we add are stable. This
+  // is the standard React escape hatch for integrating non-React DOM: render an empty container and
+  // fill it in an effect. Runs only when `html` changes, so a markers-only update (below) does not
+  // rebuild the body and lose scroll/focus. Synthetic events still fire — the handlers live on this
+  // div and native events from the (non-fiber) children bubble to it exactly as before.
+  React.useEffect(() => {
+    const root = bodyRef.current;
+    if (root) root.innerHTML = html;
+  }, [html]);
+
+  // Decorate the body after it (re)renders: mark lines that carry a ReviewMarker and inject an
+  // inline-below comment-card stack for each annotated block (#863). The stack is a real DOM sibling
+  // inserted *after* the block, so it sits in normal flow and pushes subsequent content down — it
+  // never overlaps the block (the layout fix that replaced the absolutely-positioned hover overlay
+  // marker-list). Card author/body use textContent, never innerHTML, so document-supplied marker
+  // text can't inject markup. Declared AFTER the innerHTML effect so on an `html` change the body is
+  // rebuilt first, then decorated.
   React.useEffect(() => {
     const root = bodyRef.current;
     if (!root) return;
+    // Remove previously-injected stacks first so a markers-only update (the body is NOT rebuilt
+    // then) doesn't accumulate duplicates. Idempotent on an html change too (body just rebuilt).
+    root.querySelectorAll('.codev-canvas-marker-cards').forEach((n) => n.remove());
+
     const byLine = new Map<number, ReviewMarker[]>();
     for (const m of markers) {
       const arr = byLine.get(m.line) ?? [];
@@ -127,15 +184,25 @@ export function ArtifactCanvas(props: ArtifactCanvasProps): React.ReactElement {
     // (tabindex is stamped at render time by the renderer, not here — keeps focusability free of
     // this effect's timing.) This effect only applies marker decoration, which depends on the
     // asynchronously-loaded markers.
+    // The renderer stamps the same `data-line` on multiple nested blocks for one source line
+    // (e.g. both a `ul` and its `li`; see renderer/__tests__/data-line.test.ts). Anchor the card
+    // stack + decoration to the FIRST match per line only — querySelectorAll yields tree order, so
+    // the first match is the outermost block for that line. Without this guard a list/blockquote
+    // marker injects a duplicate stack and, worse, invalid DOM: the stack is itself a `<ul>`, so
+    // `el.after(...)` on the inner `<li>` nests `ul > ul`. (Codex review iter-1.)
+    const decoratedLines = new Set<number>();
     root.querySelectorAll<HTMLElement>('[data-line]').forEach((el) => {
       const line = Number(el.getAttribute('data-line'));
       const ms = byLine.get(line);
-      if (ms && ms.length > 0) {
+      el.removeAttribute('title'); // the inline cards show author+text now — no tooltip needed
+      if (ms && ms.length > 0 && !decoratedLines.has(line)) {
+        decoratedLines.add(line);
         el.classList.add('codev-canvas-has-marker');
-        el.setAttribute('title', ms.map((m) => `${m.author}: ${m.text}`).join('\n'));
+        el.after(buildMarkerCards(line, ms)); // inline-below, in flow (#863)
       } else {
+        // Inner siblings that share the line (and genuinely unmarked blocks) get no card and no
+        // decoration; any stale class from a prior markers-only re-render is cleared here too.
         el.classList.remove('codev-canvas-has-marker');
-        el.removeAttribute('title');
       }
     });
     // Reconcile the overlay anchor against the *reloaded* DOM (iter-5 Codex): if a watch/refreshKey
@@ -156,21 +223,26 @@ export function ArtifactCanvas(props: ArtifactCanvasProps): React.ReactElement {
   };
 
   // Activate the hovered/focused block AND anchor the overlay to it: record the block's vertical
-  // offset so the `+` affordance renders next to that block instead of at the bottom of the canvas.
-  // (`offsetTop` is relative to `.codev-artifact-canvas`, which is the positioned ancestor.)
+  // offset so the `+` affordance renders beside that block. We anchor to the *first line's vertical
+  // center* (offsetTop + half the line height) rather than the block's top edge, and the overlay
+  // CSS applies `translateY(-50%)` so the `+` lands centered on the first line, not floating above
+  // it (#863 bundled polish from the issue comment). (`offsetTop` is relative to
+  // `.codev-artifact-canvas`, the positioned ancestor.)
   const activateFromTarget = (target: EventTarget | null): void => {
     const el = (target as HTMLElement | null)?.closest?.('[data-line]') as HTMLElement | null;
     if (!el) return;
     const n = Number(el.getAttribute('data-line'));
     if (Number.isNaN(n)) return;
     setActiveLine(n);
-    setOverlayTop(el.offsetTop);
+    const cs = getComputedStyle(el);
+    let lineHeight = parseFloat(cs.lineHeight);
+    if (!Number.isFinite(lineHeight)) {
+      const fontSize = parseFloat(cs.fontSize);
+      lineHeight = Number.isFinite(fontSize) ? fontSize * 1.2 : 0;
+    }
+    setOverlayTop(el.offsetTop + lineHeight / 2);
   };
 
-  // Markers on the currently-active (hovered/focused) line — surfaced author + text via the
-  // overlay (deferred #4: minimal v1 marker rendering; #863 adds polished inline markers).
-  const activeMarkers = activeLine === null ? [] : markers.filter((m) => m.line === activeLine);
-
   return React.createElement(
     'div',
     { className: 'codev-artifact-canvas', onMouseLeave: () => setActiveLine(null) },
@@ -188,31 +260,19 @@ export function ArtifactCanvas(props: ArtifactCanvasProps): React.ReactElement {
           }
         }
       },
-      dangerouslySetInnerHTML: { __html: html },
+      // No `dangerouslySetInnerHTML`: the body's content is set imperatively in the effect above so
+      // React never re-commits it (which would wipe the injected cards). Rendered with no children.
     }),
+    // The overlay now carries ONLY the "+" add-comment affordance. Existing markers render as
+    // always-visible inline cards below their block (injected above), not in this hover overlay —
+    // that's the layout fix that stopped the cards overlapping the block content (#863).
     activeLine !== null
       ? React.createElement(
           'div',
           { className: 'codev-canvas-overlay', style: { top: overlayTop } },
           React.createElement(CommentAffordance, { line: activeLine, onActivate: onAddComment }),
-          activeMarkers.length > 0
-            ? React.createElement(
-                'ul',
-                {
-                  className: 'codev-canvas-marker-list',
-                  'aria-label': `Comments on line ${activeLine + 1}`,
-                },
-                activeMarkers.map((m, i) =>
-                  React.createElement(
-                    'li',
-                    { key: String(i), className: 'codev-canvas-marker' },
-                    React.createElement('span', { className: 'codev-canvas-marker-author' }, m.author),
-                    `: ${m.text}`,
-                  ),
-                ),
-              )
-            : null,
         )
       : null,
+    React.createElement(MarkerMinimap, { markers, bodyRef }),
   );
 }
diff --git a/packages/artifact-canvas/src/components/__tests__/artifact-canvas.test.tsx b/packages/artifact-canvas/src/components/__tests__/artifact-canvas.test.tsx
index 2bcf82a9f..0daf00464 100644
--- a/packages/artifact-canvas/src/components/__tests__/artifact-canvas.test.tsx
+++ b/packages/artifact-canvas/src/components/__tests__/artifact-canvas.test.tsx
@@ -174,7 +174,7 @@ describe('ArtifactCanvas (Phase 3)', () => {
     expect(() => disposable.dispose()).not.toThrow(); // dispose() #2 — safe no-op
   });
 
-  it('surfaces an existing marker author + text via the overlay when its line is active (deferred #4)', async () => {
+  it('renders an existing marker as an always-visible inline card below its block (#863)', async () => {
     const host = makeHost('A paragraph.\n<!-- REVIEW(@bob): please fix -->'); // marker annotates line 0
     render(<ArtifactCanvas uri="x" {...host} onAddComment={vi.fn()} />);
     const p = await waitFor(() => {
@@ -182,11 +182,78 @@ describe('ArtifactCanvas (Phase 3)', () => {
       if (!el) throw new Error('no paragraph yet');
       return el as HTMLElement;
     });
-    await waitFor(() => expect(document.querySelector('.codev-canvas-has-marker')).not.toBeNull());
-    fireEvent.mouseOver(p);
-    const list = await screen.findByLabelText(/comments on line/i);
-    expect(list.textContent).toContain('bob');
-    expect(list.textContent).toContain('please fix');
+    // No hover needed — the card is in flow. It shows author + body.
+    const cards = await screen.findByLabelText(/comments on line/i);
+    expect(cards.textContent).toContain('bob');
+    expect(cards.textContent).toContain('please fix');
+    // Injected inline-BELOW the block (the layout fix): the stack is the block's next sibling,
+    // so it pushes following content down rather than overlaying the block.
+    expect(p.nextElementSibling).toBe(cards);
+    expect(cards.classList.contains('codev-canvas-marker-cards')).toBe(true);
+  });
+
+  it('injects NO card stack for a block with zero markers (no wasted vertical space, #863)', async () => {
+    const host = makeHost('# Title\n\nUncommented paragraph.'); // no markers anywhere
+    render(<ArtifactCanvas uri="x" {...host} onAddComment={vi.fn()} />);
+    await waitFor(() => expect(document.querySelector('p[data-line]')).not.toBeNull());
+    expect(document.querySelector('.codev-canvas-marker-cards')).toBeNull();
+  });
+
+  it('stacks multiple markers on one line as cards in creation (list) order (#863)', async () => {
+    // Two markers on the SAME line (line 0) — the shape parseReviewMarkers yields for a block with
+    // two stacked REVIEW comments. They must render as two cards in the order list() returns them.
+    const host = makeHost('A paragraph.');
+    host.markerAdapter.list = vi.fn(async () => [
+      { author: 'bob', line: 0, text: 'first', raw: 'r1' } as ReviewMarker,
+      { author: 'amy', line: 0, text: 'second', raw: 'r2' } as ReviewMarker,
+    ]);
+    render(<ArtifactCanvas uri="x" {...host} onAddComment={vi.fn()} />);
+    const cards = await screen.findByLabelText(/comments on line/i);
+    const items = cards.querySelectorAll('.codev-canvas-marker-card');
+    expect(items.length).toBe(2);
+    expect(items[0].textContent).toContain('first');
+    expect(items[1].textContent).toContain('second');
+  });
+
+  it('does not re-inject (duplicate) card stacks across a markers-only reload (#863)', async () => {
+    const host = makeHost('A paragraph.\n<!-- REVIEW(@bob): fix -->');
+    render(<ArtifactCanvas uri="x" {...host} onAddComment={vi.fn()} />);
+    await waitFor(() => expect(document.querySelector('.codev-canvas-marker-cards')).not.toBeNull());
+    // Re-list the same content via a watch tick — the prior stack must be cleaned up, not stacked.
+    await act(async () => { host.watchers.forEach((cb) => cb('A paragraph.\n<!-- REVIEW(@bob): fix -->')); });
+    await waitFor(() =>
+      expect(document.querySelectorAll('.codev-canvas-marker-cards').length).toBe(1),
+    );
+  });
+
+  it('anchors a single card stack to the OUTERMOST block when one line stamps multiple data-line nodes (list/blockquote, Codex iter-1)', async () => {
+    // The renderer stamps the SAME data-line on a `ul` and its `li` (renderer/data-line.test.ts).
+    // A marker on that line must inject exactly ONE stack, after the outermost `ul` — never a
+    // duplicate, and never the invalid `ul > ul` that `el.after()` on the inner `li` would create.
+    const host = makeHost('- item one\n<!-- REVIEW(@bob): fix the list -->'); // marker annotates line 0
+    render(<ArtifactCanvas uri="x" {...host} onAddComment={vi.fn()} />);
+    const ul = await waitFor(() => {
+      const el = document.querySelector('ul[data-line]');
+      if (!el) throw new Error('no list yet');
+      return el as HTMLElement;
+    });
+    const stacks = document.querySelectorAll('.codev-canvas-marker-cards');
+    expect(stacks.length).toBe(1); // exactly one — not one-per-data-line-node
+    const stack = stacks[0];
+    expect(ul.nextElementSibling).toBe(stack); // inline-below the outermost block, in flow
+    expect(stack.parentElement).not.toBe(ul); // NOT nested inside the list (no invalid ul > ul)
+    // Decoration is anchored to the outermost block only; the inner `li` carries no marker class.
+    expect(ul.classList.contains('codev-canvas-has-marker')).toBe(true);
+    expect(document.querySelector('li.codev-canvas-has-marker')).toBeNull();
+  });
+
+  it('renders marker body as text, never as markup (no innerHTML injection, #863)', async () => {
+    const host = makeHost('A paragraph.\n<!-- REVIEW(@bob): <img src=x onerror=alert(1)> -->');
+    render(<ArtifactCanvas uri="x" {...host} onAddComment={vi.fn()} />);
+    const cards = await screen.findByLabelText(/comments on line/i);
+    // The payload appears as literal text; no <img> element is created from the marker body.
+    expect(cards.textContent).toContain('<img');
+    expect(cards.querySelector('img')).toBeNull();
   });
 
   it('activates on Space (not just Enter) on a focused block', async () => {
diff --git a/packages/artifact-canvas/src/components/__tests__/marker-card-persistence.test.tsx b/packages/artifact-canvas/src/components/__tests__/marker-card-persistence.test.tsx
new file mode 100644
index 000000000..acb69205e
--- /dev/null
+++ b/packages/artifact-canvas/src/components/__tests__/marker-card-persistence.test.tsx
@@ -0,0 +1,139 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, screen, act, waitFor, cleanup } from '@testing-library/react';
+import * as React from 'react';
+import { ArtifactCanvas } from '../ArtifactCanvas.js';
+import type { ReviewMarker } from '../../types.js';
+
+afterEach(cleanup);
+
+/**
+ * Faithful replica of core's parseReviewMarkers: a marker annotates the nearest non-marker line
+ * ABOVE it (walking past stacked markers). This matches production semantics, unlike the simpler
+ * stub in artifact-canvas.test.tsx.
+ */
+const RE = /^(\s*)<!--\s*REVIEW\s*\(@([^)]+)\)\s*:\s*([\s\S]*?)\s*-->\s*$/;
+function parse(text: string): ReviewMarker[] {
+  const lines = text.split('\n');
+  const out: ReviewMarker[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = RE.exec(lines[i]);
+    if (!m) continue;
+    let anchor = i - 1;
+    while (anchor >= 0 && RE.test(lines[anchor])) anchor--;
+    if (anchor < 0) continue;
+    out.push({ author: m[2], line: anchor, text: m[3], raw: lines[i].trim() });
+  }
+  return out;
+}
+
+/**
+ * Harness mimicking webview/main.ts EXACTLY: no watcher; the host pushes updates by mutating
+ * content + bumping refreshKey. read() returns latest content, list() returns parse(content).
+ */
+function Webview({ initial }: { initial: string }) {
+  const [content, setContent] = React.useState(initial);
+  const [refreshKey, setRefreshKey] = React.useState(0);
+  const contentRef = React.useRef(content);
+  contentRef.current = content;
+
+  const fileAdapter = React.useMemo(
+    () => ({ read: async () => contentRef.current, watch: () => ({ dispose: () => {} }) }),
+    [],
+  );
+  const markerAdapter = React.useMemo(
+    () => ({ list: async () => parse(contentRef.current), add: async () => {} }),
+    [],
+  );
+  const themeAdapter = React.useMemo(
+    () => ({ resolve: () => '', onChange: () => ({ dispose: () => {} }) }),
+    [],
+  );
+
+  // Host-side addComment: insert marker on the line after `line`, then push an update (refreshKey).
+  (Webview as unknown as { add: (l: number, body: string, twice?: boolean) => void }).add = (
+    l,
+    body,
+    twice,
+  ) => {
+    const lines = contentRef.current.split('\n');
+    lines.splice(l + 1, 0, `<!-- REVIEW(@me): ${body} -->`);
+    setContent(lines.join('\n'));
+    setRefreshKey((k) => k + 1);
+    // Simulate document.save() firing a SECOND onDidChangeTextDocument with identical content.
+    if (twice) setRefreshKey((k) => k + 1);
+  };
+
+  return React.createElement(ArtifactCanvas, {
+    uri: 'codev:markdown-preview',
+    fileAdapter,
+    markerAdapter,
+    themeAdapter,
+    onAddComment: () => {},
+    refreshKey,
+  });
+}
+
+/**
+ * Regression for "comment card flashes then disappears" (#863 dev-approval finding). The card is
+ * injected into the markdown body; once React stopped owning that body's innerHTML (now set
+ * imperatively in an effect), a re-render can no longer re-commit innerHTML and wipe the card.
+ * NOTE: the original defect only surfaced in the real browser's React commit timing and does not
+ * reproduce under jsdom, so these assert the behavioral contract (the card survives the realistic
+ * update cycle) rather than the browser-only wipe; the running-app check at dev-approval covers that.
+ */
+describe('comment card persists after add (webview refreshKey path)', () => {
+  it('keeps the inline card after a comment is added', async () => {
+    render(<Webview initial={'## Understanding\n\nWaleed flagged a slow load.'} />);
+    await waitFor(() => expect(document.querySelector('p[data-line]')).not.toBeNull());
+
+    const para = document.querySelector('p[data-line]') as HTMLElement;
+    const line = Number(para.getAttribute('data-line'));
+
+    await act(async () => {
+      (Webview as unknown as { add: (l: number, body: string) => void }).add(line, 'please clarify');
+    });
+
+    // The card must be present AND STAY present (the reported bug: it flashes then vanishes).
+    const cards = await screen.findByLabelText(/comments on line/i);
+    expect(cards.textContent).toContain('please clarify');
+
+    // Let any trailing renders/effects settle, then assert it's still there.
+    await act(async () => { await Promise.resolve(); });
+    expect(screen.queryByLabelText(/comments on line/i)).not.toBeNull();
+  });
+
+  it('VARIANT: comment inserted MID multi-line paragraph (the #1036 split case)', async () => {
+    // A hard-wrapped paragraph: three source lines forming ONE block (data-line = first line).
+    render(
+      <Webview
+        initial={'Para line one here.\npara line two here.\npara line three here.'}
+      />,
+    );
+    await waitFor(() => expect(document.querySelector('p[data-line]')).not.toBeNull());
+    const para = document.querySelector('p[data-line]') as HTMLElement;
+    const line = Number(para.getAttribute('data-line')); // first line of the block
+
+    await act(async () => {
+      (Webview as unknown as { add: (l: number, b: string) => void }).add(line, 'mid-para comment');
+    });
+    await act(async () => { await Promise.resolve(); });
+    expect(screen.queryByLabelText(/comments on line/i)).not.toBeNull();
+  });
+
+  it('VARIANT: double update (save fires a second change event)', async () => {
+    render(<Webview initial={'## Understanding\n\nWaleed flagged a slow load.'} />);
+    await waitFor(() => expect(document.querySelector('p[data-line]')).not.toBeNull());
+    const para = document.querySelector('p[data-line]') as HTMLElement;
+    const line = Number(para.getAttribute('data-line'));
+
+    await act(async () => {
+      (Webview as unknown as { add: (l: number, b: string, t?: boolean) => void }).add(
+        line,
+        'please clarify',
+        true, // twice
+      );
+    });
+    await act(async () => { await Promise.resolve(); });
+    expect(screen.queryByLabelText(/comments on line/i)).not.toBeNull();
+  });
+});
diff --git a/packages/artifact-canvas/src/overlays/MarkerMinimap.tsx b/packages/artifact-canvas/src/overlays/MarkerMinimap.tsx
new file mode 100644
index 000000000..7df753ffb
--- /dev/null
+++ b/packages/artifact-canvas/src/overlays/MarkerMinimap.tsx
@@ -0,0 +1,87 @@
+import * as React from 'react';
+import type { ReviewMarker } from '../types.js';
+
+export interface MarkerMinimapProps {
+  /** The markers to plot — one dot per marker (#863). */
+  markers: ReviewMarker[];
+  /** The rendered-body element the dots are positioned against (the canvas scroll content). */
+  bodyRef: React.RefObject<HTMLDivElement | null>;
+}
+
+/** First ~80 chars of a marker body, for the hover tooltip (AC: "author + truncated body"). */
+function truncate(text: string, max = 80): string {
+  return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+
+interface Dot {
+  marker: ReviewMarker;
+  /** 0..1 fraction of the body height where the marker's block sits. */
+  frac: number;
+}
+
+/**
+ * Right-edge marker minimap (#863): a fixed vertical column with one dot per REVIEW marker,
+ * positioned proportional to the marker's block within the rendered body. Hovering a dot shows
+ * `author: truncated body`; clicking smooth-scrolls the canvas to that block. The column is
+ * hidden entirely when the document has zero markers, and recomputes dot positions on body
+ * resize (which also covers a content rebuild) — both AC requirements.
+ *
+ * Positioning reads layout (`offsetTop` / `scrollHeight`), so it is only meaningful in a real
+ * browser/webview; under jsdom the values are 0 and every dot collapses to the top — the unit
+ * tests therefore assert structure/behavior (dot count, hidden-when-empty, click→scroll, tooltip),
+ * and pixel placement is verified on the running worktree at the `dev-approval` gate.
+ */
+export function MarkerMinimap({ markers, bodyRef }: MarkerMinimapProps): React.ReactElement | null {
+  const [dots, setDots] = React.useState<Dot[]>([]);
+
+  React.useLayoutEffect(() => {
+    const body = bodyRef.current;
+    if (!body) {
+      setDots([]);
+      return;
+    }
+    const compute = (): void => {
+      const total = body.scrollHeight || 1;
+      setDots(
+        markers.map((marker) => {
+          const el = body.querySelector<HTMLElement>(`[data-line="${marker.line}"]`);
+          const top = el ? el.offsetTop : 0;
+          const frac = Math.min(1, Math.max(0, top / total));
+          return { marker, frac };
+        }),
+      );
+    };
+    compute();
+    // A ResizeObserver on the body fires on content rebuild AND window resize (both change the
+    // body's height), covering the "updates on resize and rebuild" AC with one observer. Guarded
+    // for non-browser hosts (e.g. jsdom under test) that don't provide ResizeObserver — the
+    // one-shot compute() above still positions the dots from current layout.
+    if (typeof ResizeObserver === 'undefined') return;
+    const ro = new ResizeObserver(compute);
+    ro.observe(body);
+    return () => ro.disconnect();
+  }, [markers, bodyRef]);
+
+  if (markers.length === 0) return null; // hidden when the doc has zero markers (AC)
+
+  return React.createElement(
+    'div',
+    { className: 'codev-canvas-minimap', 'aria-label': 'Review marker minimap' },
+    dots.map((dot, i) =>
+      React.createElement('button', {
+        key: String(i),
+        type: 'button',
+        className: 'codev-canvas-minimap-dot',
+        style: { top: `${dot.frac * 100}%` },
+        title: `${dot.marker.author}: ${truncate(dot.marker.text)}`,
+        'aria-label': `Jump to comment by ${dot.marker.author} on line ${dot.marker.line + 1}`,
+        onClick: () => {
+          const el = bodyRef.current?.querySelector<HTMLElement>(
+            `[data-line="${dot.marker.line}"]`,
+          );
+          el?.scrollIntoView({ behavior: 'smooth', block: 'center' });
+        },
+      }),
+    ),
+  );
+}
diff --git a/packages/artifact-canvas/src/overlays/__tests__/marker-minimap.test.tsx b/packages/artifact-canvas/src/overlays/__tests__/marker-minimap.test.tsx
new file mode 100644
index 000000000..af7b220e6
--- /dev/null
+++ b/packages/artifact-canvas/src/overlays/__tests__/marker-minimap.test.tsx
@@ -0,0 +1,69 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render, screen, fireEvent, cleanup } from '@testing-library/react';
+import * as React from 'react';
+import { MarkerMinimap } from '../MarkerMinimap.js';
+import type { ReviewMarker } from '../../types.js';
+
+afterEach(cleanup);
+
+/**
+ * Mount the minimap against a real body element carrying `[data-line]` blocks, so the component's
+ * `querySelector(...)` and click→scroll paths run against actual DOM. jsdom has no layout, so dot
+ * pixel-positions collapse to 0 — these tests assert structure/behavior (count, hidden-when-empty,
+ * click→scrollIntoView, tooltip), and placement is verified on the running worktree at dev-approval.
+ */
+function Harness({ markers, lines }: { markers: ReviewMarker[]; lines: number[] }) {
+  const ref = React.useRef<HTMLDivElement>(null);
+  return React.createElement(
+    'div',
+    null,
+    React.createElement(
+      'div',
+      { ref, className: 'codev-artifact-canvas-body' },
+      lines.map((l) =>
+        React.createElement('p', { key: l, 'data-line': String(l) }, `block ${l}`),
+      ),
+    ),
+    React.createElement(MarkerMinimap, { markers, bodyRef: ref }),
+  );
+}
+
+const marker = (line: number, author: string, text: string): ReviewMarker => ({
+  line,
+  author,
+  text,
+  raw: `<!-- REVIEW(@${author}): ${text} -->`,
+});
+
+describe('MarkerMinimap (#863)', () => {
+  it('renders nothing when there are zero markers (hidden on a marker-free doc)', () => {
+    const { container } = render(<Harness markers={[]} lines={[0, 1, 2]} />);
+    expect(container.querySelector('.codev-canvas-minimap')).toBeNull();
+  });
+
+  it('renders one dot per marker', () => {
+    const markers = [marker(0, 'bob', 'one'), marker(2, 'amy', 'two')];
+    render(<Harness markers={markers} lines={[0, 1, 2]} />);
+    expect(document.querySelectorAll('.codev-canvas-minimap-dot').length).toBe(2);
+  });
+
+  it('a dot tooltip shows author + truncated body (~80 chars)', () => {
+    const long = 'x'.repeat(200);
+    render(<Harness markers={[marker(0, 'bob', long)]} lines={[0]} />);
+    const dot = document.querySelector('.codev-canvas-minimap-dot') as HTMLElement;
+    expect(dot.title.startsWith('bob: ')).toBe(true);
+    expect(dot.title).toContain('…'); // truncated
+    expect(dot.title.length).toBeLessThan(long.length); // not the full 200 chars
+  });
+
+  it('clicking a dot smooth-scrolls the canvas to the marker block', () => {
+    // jsdom doesn't implement scrollIntoView, so install a mock (and restore after) rather than spy.
+    const original = Element.prototype.scrollIntoView;
+    const scrollSpy = vi.fn();
+    Element.prototype.scrollIntoView = scrollSpy;
+    render(<Harness markers={[marker(2, 'bob', 'fix')]} lines={[0, 1, 2]} />);
+    fireEvent.click(screen.getByRole('button', { name: /jump to comment by bob/i }));
+    expect(scrollSpy).toHaveBeenCalledWith({ behavior: 'smooth', block: 'center' });
+    Element.prototype.scrollIntoView = original;
+  });
+});
diff --git a/packages/artifact-canvas/src/styles/default-theme.css b/packages/artifact-canvas/src/styles/default-theme.css
index 1f75e6d5e..3e8a3c858 100644
--- a/packages/artifact-canvas/src/styles/default-theme.css
+++ b/packages/artifact-canvas/src/styles/default-theme.css
@@ -52,9 +52,12 @@
   outline: 2px solid var(--codev-canvas-accent);
 }
 
-/* v1 minimal indicator for a line carrying a review marker (#863 adds polished inline markers) */
+/* v1 minimal indicator for a line carrying a review marker (#863 adds polished inline markers).
+   The bar is an inset box-shadow on the left edge; padding-left keeps the text off the bar so
+   the gold rule doesn't crowd the prose it annotates. */
 .codev-canvas-has-marker {
   box-shadow: inset 3px 0 0 0 var(--codev-canvas-comment-marker);
+  padding-left: 10px;
 }
 
 .codev-artifact-canvas-body [data-line]:focus-visible {
@@ -65,24 +68,73 @@
 .codev-artifact-canvas-body pre,
 .codev-artifact-canvas-body code { background: var(--codev-canvas-code-background); }
 
-/* Overlay: the "+" affordance + the active line's existing comments (author + text).
-   Anchored to the active block: positioned absolutely in the canvas, with `top` set inline from
-   the block's offset (the `+` lands in the left gutter beside the hovered/focused block). */
+/* Overlay: the "+" add-comment affordance only. Anchored to the active block: positioned
+   absolutely in the canvas, with `top` set inline to the first line's vertical center; the
+   `translateY(-50%)` lands the `+` centered on that line (in the left gutter) rather than floating
+   above the block's top edge (#863). */
 .codev-canvas-overlay {
   display: flex;
   gap: 8px;
-  align-items: flex-start;
+  align-items: center;
   position: absolute;
   left: 0;
   z-index: 5;
+  transform: translateY(-50%);
 }
-.codev-canvas-marker-list {
+
+/* Inline-below comment cards (#863): rendered in flow beneath the annotated block, so they push
+   following content down instead of overlapping it. The left rule ties the stack visually to the
+   gutter where the "+" lives. No stack is injected for a block with zero markers, so a comment-free
+   block consumes no extra vertical space. */
+.codev-canvas-marker-cards {
   list-style: none;
-  margin: 0;
-  padding: 4px 8px;
+  margin: 4px 0 10px;
+  padding-left: 8px;
+  border-left: 2px solid var(--codev-canvas-comment-marker);
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+.codev-canvas-marker-card {
+  border: 1px solid var(--codev-canvas-border);
   border-left: 3px solid var(--codev-canvas-comment-marker);
+  border-radius: 4px;
+  padding: 4px 8px;
   background: var(--codev-canvas-code-background);
   color: var(--codev-canvas-foreground);
   font-size: 0.9em;
 }
-.codev-canvas-marker-author { font-weight: 600; color: var(--codev-canvas-muted); }
+.codev-canvas-marker-card-icon { margin-right: 4px; }
+.codev-canvas-marker-card-author { font-weight: 600; color: var(--codev-canvas-muted); margin-right: 4px; }
+
+/* Right-edge marker minimap (#863): a fixed, narrow column of dots — one per REVIEW marker,
+   positioned proportional to the marker's place in the document. The column itself is
+   click-transparent (pointer-events: none) so only the dots are interactive, and it is narrow
+   enough to sit alongside a future floating TOC (#861) without fighting for space. */
+.codev-canvas-minimap {
+  position: fixed;
+  top: 0;
+  right: 0;
+  height: 100vh;
+  width: 14px;
+  z-index: 4;
+  pointer-events: none;
+}
+.codev-canvas-minimap-dot {
+  position: absolute;
+  right: 3px;
+  width: 8px;
+  height: 8px;
+  padding: 0;
+  border: none;
+  border-radius: 50%;
+  background: var(--codev-canvas-comment-marker);
+  cursor: pointer;
+  pointer-events: auto;
+  transform: translateY(-50%);
+}
+.codev-canvas-minimap-dot:hover,
+.codev-canvas-minimap-dot:focus-visible {
+  outline: 2px solid var(--codev-canvas-accent);
+  outline-offset: 1px;
+}