diff --git a/AGENTS.md b/AGENTS.md
index 16c342f4a..bb230cc36 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -54,7 +54,8 @@ plannotator/
 │       └── extra/                 # EXTRA skills — NOT default-installed (except Kiro); add via `npx skills add backnotprop/plannotator/apps/skills/extra --global`
 │           ├── plannotator-compound/        # Research analysis agent (map-reduce over denied plans)
 │           ├── plannotator-setup-goal/      # Goal package scaffolder for /goal workflows
-│           └── plannotator-visual-explainer/ # Visual HTML generator (plans, diagrams, PR explainers) with Plannotator theming
+│           ├── plannotator-visual-explainer/ # Visual HTML generator (plans, diagrams, PR explainers) with Plannotator theming
+│           └── plannotator-markup/          # Agent answers as annotations on a document (external-annotations API driver)
 ├── packages/
 │   ├── server/                   # Shared server implementation
 │   │   ├── index.ts              # startPlannotatorServer(), handleServerReady()
@@ -633,6 +634,8 @@ interface Block {
 
 Text highlighting uses `web-highlighter` library. Code blocks use manual `<mark>` wrapping (web-highlighter can't select inside `<pre>`).
 
+**Anchoring an annotation to the document.** An external annotation quotes the markdown SOURCE (that is what `/api/plan` serves) and is pinned by searching the RENDERED DOM, so the two diverge wherever the renderer consumes syntax, drops a delimiter, or draws text of its own. That divergence has no inverse worth writing: `packages/ui/utils/renderedText.tsx` runs the real renderer (`parseMarkdownToBlocks` → `BlockRenderer` → `renderToStaticMarkup` into an inert `<template>`) over the quote and compares its text, so a markdown feature is covered the day it renders rather than after someone notices the missing highlight. Both sides are read through `visibleText`, never `textContent`, which skips `[aria-hidden="true"]` and `[data-decorative]` — see the rule in `packages/ui/CLAUDE.md` before adding renderer chrome. `useAnnotationHighlighter`'s ladder is then only: the literal quote, the rendered quote, and a last-resort match that drops markdown noise and whitespace from both sides for a quote that cuts a block in half (`Install** now`). `stripInlineMarkdown` is no longer part of it and now serves `slugifyHeading` alone, which stays a pure DOM-free function.
+
 **Raw-HTML annotate:** the sandboxed viewer never mutates the visited page's DOM. Committed annotations render as numbered placed comment markers plus overlay-projected highlight rectangles inside a shadow-rooted fixed overlay host: the durable anchor data (element selector, text snapshot, normalized selected point) is persisted, and the markers/highlights are disposable projections re-resolved from it on every reconcile. Shift-click multi-select joins additional elements to one comment (`htmlAdditionalTargets`).
 
 **HTML and live-app interaction model:** raw-HTML sessions and live app sessions (`mode: "annotate-app"`) share one contract. Both open with pinpoint **armed** (`htmlAnnotateArmed` defaults to `true`, `packages/editor/App.tsx:493`; live sessions open armed like every other HTML surface, `App.tsx:2871`). `Esc` walks a ladder instead of exiting outright: a pending draft closes first, then the pinpoint hover outline clears, and only then does `Esc` drop the surface to **Interact**, where the bridge goes passive so clicks, forms, text selection, and SPA navigation reach the page natively (`packages/ui/components/html-viewer/bridge-script.ts:3066-3080`; committed markers stay visible and a marker click still opens its comment, and in Interact an open drag-comment draft still closes before `Esc` is handed back to the page). Vim owns its own ladder and is skipped here. The header **pen** button re-arms (`packages/editor/components/AppHeader.tsx:386-404`, `aria-pressed`), as does `Mod+Shift+A` (`packages/ui/shortcuts/plan-review/htmlAnnotate.shortcuts.ts:13-21`), which the bridge mirrors inside the iframe on the capture phase and forwards to the parent (`bridge-script.ts:3085-3091`), so the chord works whichever document owns focus. Text drag-selection commenting is **always live**, on both surfaces and in both states, ungated from the armed flag and from the input method (`bridge-script.ts:384-386`, `:1420-1436`): while armed, a click pins an element and a drag selects text at the same time, and the one-shot `dragEndedClick` guard stops a completed drag's trailing click from re-pinning (`bridge-script.ts:1381-1390`).
diff --git a/apps/skills/extra/plannotator-markup/SKILL.md b/apps/skills/extra/plannotator-markup/SKILL.md
new file mode 100644
index 000000000..450924738
--- /dev/null
+++ b/apps/skills/extra/plannotator-markup/SKILL.md
@@ -0,0 +1,171 @@
+---
+name: plannotator-markup
+disable-model-invocation: true
+description: >
+  Answer with markup on the document instead of prose in chat. Opens the user's
+  markdown, text, config, or HTML file in a live Plannotator annotate session and
+  posts your response into it as inline comments and strikethrough edits pinned to
+  the exact phrases they concern. Use when the user asks you to annotate, mark up,
+  redline, or comment on a document they already have — anything where naming a
+  section number ("as noted in 3.1") would force them to cross-reference your
+  reply against the file by hand.
+---
+
+# Plannotator Markup
+
+Your response becomes annotations on the user's document, not chat prose.
+
+This skill is only the mechanics of driving Plannotator. What to say about the
+document is decided by the request you were given, not here.
+
+## When not to use this
+
+- One or two remarks — just say them in chat; a browser session is heavier than the feedback.
+- Source code — use `plannotator review` instead (`annotate` refuses code files).
+- The user wants you to *edit* the file — edit it. This surface proposes; it does not write.
+
+## Flow
+
+1. Launch the session in the background.
+2. Read the document back from the session.
+3. POST your annotations.
+4. Tell the user the session is open.
+5. Wait for the process to exit and act on what it returns.
+
+### 1. Launch in the background
+
+```bash
+plannotator annotate <path-or-url>
+```
+
+**Never run this in the foreground.** It blocks until the human decides, so a
+foreground call leaves you unable to post anything into the session you just
+started. In Claude Code, use Bash with `run_in_background: true`; elsewhere
+append `&`.
+
+**Browser session patience rule:** the session is driven by a human in a
+browser and can stay open for minutes. Keep waiting until they submit, dismiss,
+or tell you to stop. Do not kill, restart, or open a second copy because the UI
+looks idle — a session that ends without a decision reads as no feedback.
+
+### 2. Get the base URL
+
+```bash
+plannotator sessions 2>&1 | grep -oE 'http://[^[:space:]]+' | head -1
+```
+
+`plannotator sessions` writes to **stderr**, not stdout. Without `2>&1` you get
+nothing. Do not set `PLANNOTATOR_PORT` to work around this; the port is already
+discoverable.
+
+With several sessions running, take the row whose second column is `annotate`,
+then confirm you have the right one — `GET /api/plan` returns `filePath`:
+
+```bash
+curl -s "$BASE/api/plan" | jq -r .filePath
+```
+
+### 3. Read the document
+
+```bash
+curl -s "$BASE/api/plan" | jq -r .plan
+```
+
+Read it from the session, not from disk. Annotations are pinned by matching
+`originalText` as a **verbatim substring of this text** — there are no line
+numbers to reference. Copy phrases out of this output exactly; a single
+character of drift and the annotation silently degrades to a sidebar entry with
+no highlight.
+
+### 4. POST the annotations
+
+```bash
+curl -s -X POST "$BASE/api/external-annotations" \
+  -H 'Content-Type: application/json' \
+  -d '{"annotations": [
+    {"source": "claude-code", "author": "Claude", "type": "COMMENT",
+     "originalText": "<verbatim phrase from the document>",
+     "text": "<what you have to say about that phrase>"},
+    {"source": "claude-code", "author": "Claude", "type": "DELETION",
+     "originalText": "<verbatim phrase to strike through>",
+     "text": "<ignored — see below>"},
+    {"source": "claude-code", "author": "Claude", "type": "GLOBAL_COMMENT",
+     "text": "<remark about the document as a whole>"}
+  ]}'
+```
+
+Pick the longest unambiguous `originalText` you can. A short one may match
+somewhere you did not intend; the match is plain substring search, first hit
+wins.
+
+`201 {"ids": [...]}` on success, `400 {"error": "..."}` on validation failure.
+Each POST is live the instant it lands; there is no send step. Batch them in one
+call rather than firing one request per remark.
+
+| Field | Required | Notes |
+|---|---|---|
+| `source` | always | Stable identifier for you. Reuse the same value for every annotation in a session — it is how you clean up your own on a re-run. |
+| `text` | always | Non-empty, or `400`. Ignored for `DELETION` (see below). |
+| `type` | always | `COMMENT` (inline), `DELETION` (strikethrough), `GLOBAL_COMMENT` (sidebar only). |
+| `originalText` | `COMMENT`, `DELETION` | Verbatim substring of the document. A `COMMENT` without it is `400`; use `GLOBAL_COMMENT` for remarks that belong to no phrase. |
+| `author` | no | Label shown beside the annotation. |
+
+**`DELETION` carries no message.** The exported feedback says "I don't want
+this in the file" and drops your `text` entirely. It means *delete this*,
+nothing more. To propose a replacement, post a `COMMENT` with the rewrite in
+`text` — either instead of the `DELETION`, or alongside it on the same phrase
+when you want both the strikethrough and the reasoning.
+
+#### Referring to another section
+
+To point at a different section from inside a comment, write `#` immediately
+followed by that heading's text, copied verbatim:
+
+```
+#3.1 Single source of truth contradicts this.
+```
+
+The heading text becomes a link that scrolls the reader to it. Resolution is
+exact match against the document's own headings, so a title you paraphrase or
+misremember silently stays plain text — copy it from the `/api/plan` output like
+any other quote. A heading whose text is used twice never resolves.
+
+`#` with a space after it, a `#` welded to a word (`C#`), and anything that
+matches no heading (`#fff`, `#123`) all stay plain text.
+
+Prefer this over a bare number even when the document is numbered: the full
+heading text still reads correctly if the link ever fails to resolve, and `3.1`
+alone does not.
+
+### 5. Hand it over and wait
+
+Tell the user the session is open and where, in one line. Then wait for the
+background process to exit and read its stdout:
+
+- Empty — they closed the tab. No feedback; say so briefly and move on.
+- Text — their reply, including any of your annotations they kept. Act on it.
+
+Add `--json` at launch if you want `{"decision": "...", "feedback": "..."}`
+instead of prose. An `approved` decision can still carry notes in `feedback`:
+treat those as guidance, not a change request.
+
+## Re-running on the same session
+
+Delete your own annotations before reposting, or they accumulate:
+
+```bash
+curl -s -X DELETE "$BASE/api/external-annotations?source=claude-code"
+```
+
+Returns `{"ok": true, "removed": N}`. Scoped by `source`, so it never touches
+the human's own annotations or another tool's. `PATCH ?id=<id>` edits one in
+place if you only need to revise a single remark.
+
+## Do not
+
+- Do not run `plannotator annotate` in the foreground; you will not be able to post.
+- Do not write a bare section number ("as noted in 3.1") in `text`. It is inert, and it hands the reader the cross-referencing work this surface exists to remove. Use a `#` reference instead (step 4).
+- Do not put a suggested replacement in a `DELETION`'s `text`. It is discarded.
+- Do not post into a session over a network — remote and `--tailscale` sessions expose this API to peers, and it has no authentication.
+- Do not scrape the browser UI. `/api/plan`, `/api/external-annotations`, and the process stdout are the whole contract.
+- Do not clear annotations without a `source` filter; a bare `DELETE` wipes the human's too.
diff --git a/apps/skills/extra/plannotator-markup/SKILL.test.ts b/apps/skills/extra/plannotator-markup/SKILL.test.ts
new file mode 100644
index 000000000..565224c17
--- /dev/null
+++ b/apps/skills/extra/plannotator-markup/SKILL.test.ts
@@ -0,0 +1,70 @@
+/// <reference types="bun-types" />
+/// <reference types="node" />
+
+/**
+ * The skill documents an HTTP contract and two behaviors that live in code:
+ * the annotation types the server accepts, and the fact that DELETION's `text`
+ * is discarded by the export. Both are the kind of claim that goes stale
+ * silently — the skill keeps rendering fine while telling an agent something
+ * untrue. These pin the claims to their sources.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const skill = readFileSync(join(import.meta.dir, "SKILL.md"), "utf-8");
+const repoRoot = join(import.meta.dir, "../../../..");
+const read = (rel: string) => readFileSync(join(repoRoot, rel), "utf-8");
+
+describe("plannotator-markup contract freshness", () => {
+  test("documents the endpoint the servers actually mount", () => {
+    const handler = read("packages/server/external-annotations.ts");
+    const base = handler.match(/const BASE = "([^"]+)"/)?.[1];
+    expect(base).toBe("/api/external-annotations");
+    expect(skill).toContain(base!);
+  });
+
+  test("documents exactly the annotation types the plan transformer accepts", () => {
+    const core = read("packages/core/external-annotation.ts");
+    const listed = core.match(/VALID_PLAN_TYPES[^=]*=\s*\[([^\]]+)\]/)?.[1];
+    expect(listed).toBeDefined();
+    const types = [...listed!.matchAll(/["']([A-Z_]+)["']/g)].map((m) => m[1]!);
+    expect(types.length).toBeGreaterThan(0);
+
+    // Every accepted type is named in the skill's field table, and the skill
+    // invents none — an agent told about a fourth type would get a 400.
+    for (const type of types) expect(skill).toContain(type);
+    for (const type of skill.match(/\b[A-Z]+_?[A-Z]*COMMENT\b|\bDELETION\b/g) ?? []) {
+      expect(types).toContain(type);
+    }
+  });
+
+  test("still warns that DELETION discards its text", () => {
+    const parser = read("packages/ui/utils/parser.ts");
+    const deletionBranch = parser.slice(
+      parser.indexOf("case 'DELETION':"),
+      parser.indexOf("case 'COMMENT':"),
+    );
+    expect(deletionBranch.length).toBeGreaterThan(0);
+    // The export writes a fixed sentence and never `ann.text`. The moment it
+    // does, the skill's "DELETION carries no message" guidance is wrong.
+    expect(deletionBranch).not.toContain("ann.text");
+    expect(skill).toContain("`DELETION` carries no message");
+  });
+
+  test("still tells the agent that `plannotator sessions` writes to stderr", () => {
+    // Without the redirect an agent's pipe reads empty and the whole flow
+    // stalls at step 2, so this is the skill's most load-bearing detail.
+    expect(skill).toContain("2>&1");
+    expect(skill).toMatch(/writes to \*\*stderr\*\*/);
+  });
+
+  test("section references match the resolver's rules", () => {
+    const resolver = read("packages/ui/utils/sectionRefs.ts");
+    expect(resolver).toContain("export function parseSectionRefs");
+    expect(skill).toContain("### Referring to another section");
+    // The one rule an agent has to follow for a reference to resolve.
+    expect(skill).toContain("copied verbatim");
+  });
+});
diff --git a/packages/editor/App.tsx b/packages/editor/App.tsx
index 49fc6d041..db0423b69 100644
--- a/packages/editor/App.tsx
+++ b/packages/editor/App.tsx
@@ -5057,6 +5057,7 @@ const App: React.FC = () => {
       isOpen={isOpen}
       presentation={presentation}
       blocks={blocks}
+      onNavigateAnchor={(hash) => viewerRef.current?.scrollToAnchor(hash)}
       annotations={allAnnotations}
       selectedId={selectedAnnotationId ?? selectedCodeAnnotationId}
       onSelect={handleSelectAnnotation}
diff --git a/packages/ui/AGENTS.md b/packages/ui/AGENTS.md
index 62823cb12..2011489cd 100644
--- a/packages/ui/AGENTS.md
+++ b/packages/ui/AGENTS.md
@@ -8,3 +8,4 @@ This is the **published, reusable document UI** (`@plannotator/ui` + `@plannotat
 - To support a host's different backend, **add an optional seam** (a module-level `setX`/`resetX` default, or an optional prop) whose default reproduces today's behavior. Plannotator passes nothing and stays **byte-for-byte unchanged**.
 - `@plannotator/core` is browser-safe and zero-dep — **no `node:` imports** (CI enforces it). `@plannotator/shared`/`@plannotator/ai` stay private; `shared` re-exports `core` via shims.
 - **Never delete working Plannotator code until a human confirms parity in the browser.**
+- **Text the renderer draws but the document does not contain must be flagged**, or annotation anchoring silently breaks. Annotation restore matches a markdown quote against the page by rendering the quote with this same renderer (`utils/renderedText`) and walking both sides with `VISIBLE_TEXT`, which skips `[aria-hidden="true"]` and `[data-decorative]`. So a new bullet, numeral, badge, or counter needs one of those two attributes — `aria-hidden` when nothing should hear it, `data-decorative` when it must stay audible (a list glyph, since these list items are divs and carry no list semantics). Never widen the walker to `textContent`.
diff --git a/packages/ui/HANDOFF.md b/packages/ui/HANDOFF.md
index 65bfa6d2f..8af6c3f9c 100644
--- a/packages/ui/HANDOFF.md
+++ b/packages/ui/HANDOFF.md
@@ -672,6 +672,34 @@ Additive only, but required: `@plannotator/ui` 0.32.0 imports the new `@plannota
 
 ---
 
+## Section references in comment text (unreleased)
+
+One additive seam plus one new method on an existing handle. **No version assigned** — the maintainer picks it at release; nothing under `packages/core` changed, so this is a ui-only publish.
+
+### `AnnotationPanel` `onNavigateAnchor?: (hash: string) => void`
+
+An annotation that names another section in prose ("this contradicts 3.1") makes the reader hold the reply in their head while they go find 3.1. The panel now renders `#` followed by a heading's exact text as a link to that heading.
+
+1. **Opt-in and inert by default.** The text is parsed only when BOTH `onNavigateAnchor` and a non-empty heading index are present; otherwise `parseSectionRefs` returns the original string and the same single `<p>` renders. A host that passes nothing gets byte-identical output.
+2. **The document defines the vocabulary.** A reference resolves by exact match against this document's heading text — no numbering grammar to get wrong, and no configuration. A title used by two headings resolves to neither.
+3. **Non-references stay plain by construction**, because resolution requires a heading to exist: `#fff` and `#123` need a heading literally named `fff` / `123`. A `#` welded to a word (`C#`) and a `#` followed by whitespace (markdown heading intent) are both skipped before lookup, and backtick spans are never scanned.
+4. **Longest match wins**, so a document with both `3.1` and `3.1 Scope` resolves `#3.1 Scope` to the longer heading.
+5. **Clicks do not select the card.** The link stops propagation, so navigating to a referenced section never also scrolls to the annotation's own highlight.
+
+Only `AnnotationCard` renders these. `CodeAnnotationCard` is untouched: code-review annotations address files and lines, and a review surface has no heading blocks.
+
+### `ViewerHandle.scrollToAnchor: (hash: string) => boolean`
+
+`Viewer` already had this callback for in-document anchor links; it is now on the imperative handle so the panel can drive it. Returns `false` when the anchor is not in the current document.
+
+It is **required, not optional**, deliberately: the interface is implemented inside this package only (`Viewer`, `HtmlViewer`) and consumed everywhere else through a ref, so requiring it costs no host anything while forcing both implementations to stay in step — `HtmlViewer` was caught by `tsc` and implements it as `() => false`, since a raw HTML page has no markdown heading blocks to resolve against. A host that holds a `ViewerHandle` ref is unaffected; only a host writing its own `forwardRef<ViewerHandle, …>` component would need to add it, which is not a supported shape.
+
+### `utils/sectionRefs` (pure, exported)
+
+`buildSectionRefIndex(blocks)` → `Map<headingText, anchorId>` over `buildHeadingSlugMap`, minus ambiguous titles. `parseSectionRefs(text, index)` → `Array<string | { label, anchor }>`. Both are DOM-free and dependency-free; `packages/ui/utils/sectionRefs.test.ts` pins the particle-boundary, longest-match, duplicate-title, `C#`, `# `, backtick, and no-heading cases.
+
+---
+
 ## Publishing & versioning
 
 - The current pair is `@plannotator/ui` `0.34.0` on `@plannotator/core` `0.25.0`. **No lockstep again**: nothing under `packages/core` changed since the 0.32.0 pair, so core is not republished and ui 0.34.0 pins the already published core 0.25.0 (only the ui tarball is built and published). 0.34.0 carries the 0.33.0 adoption feedback: the Mermaid KaTeX redirect target `utils/mermaid-math-slot`, `HtmlViewer` `bridgeErrorDisplay`, the anchored bridge-script alias, and `resetMathRenderer` keeping the registered loader (with `setMathRendererLoader(null)` and `getMathRendererLoader`). 0.33.0 carried the bridge-script asset (`bridge-script.asset.js`, `bridge-script.lite`, both generated by `prepack`), the `utils/math-default-loader` split, and `HANDOFF.md` inside the tarball so the README's section references resolve for a consumer.
diff --git a/packages/ui/README.md b/packages/ui/README.md
index 39b4caf48..10ddee508 100644
--- a/packages/ui/README.md
+++ b/packages/ui/README.md
@@ -129,6 +129,18 @@ The srcdoc then carries one classic `<script src>` in the exact place the inline
 - **`@plannotator/ui/shortcuts`**: the declarative keyboard-shortcut engine (`defineShortcutScope`, `useShortcutScope`) and the per-surface scopes, including `useHtmlAnnotateShortcuts` for the Mod+Shift+A Annotate/Interact chord on HTML surfaces. Pure React plus `utils/platform`; no backend.
 - **`@plannotator/ui/utils/inputMethod`**: `getInputMethod(surface)` / `saveInputMethod(method, surface)` / `refreshInputMethodStamp(method)`, the per-surface pinpoint-or-drag preference with its TTL, persisted through the `storageBackend` seam.
 
+### Section references in comment text (`AnnotationPanel` `onNavigateAnchor`; unreleased)
+
+A comment that says "this contradicts 3.1" hands the reader the cross-referencing work the annotation surface exists to remove. Writing `#3.1 Single source of truth` instead renders that heading text as a link that scrolls the document to it.
+
+- **`AnnotationPanel` `onNavigateAnchor?: (hash: string) => void`**: opt in by passing it. Plannotator wires it to the viewer handle; a host passing nothing renders comment text exactly as before (one `<p>`, no parsing, no links). The panel already receives `blocks`, so the resolution index costs the host nothing extra.
+- **`ViewerHandle.scrollToAnchor(hash) => boolean`**: the scroll executor, previously internal to `Viewer`. Returns `false` when the anchor is not in the current document. `HtmlViewer` implements it as a no-op — raw HTML pages carry no markdown heading blocks for a reference to resolve to.
+- **`utils/sectionRefs`** (pure): `buildSectionRefIndex(blocks)` maps heading text to its anchor id, dropping any title used by two headings; `parseSectionRefs(text, index)` splits comment text into plain runs and resolved references.
+
+Resolution is **exact match against the document's own headings** — there is no grammar of section numbers, so nothing has to be taught about `3.1` versus `A.` versus `IV.`. A reference that matches nothing stays plain text, which is what keeps `#fff`, `#123`, `C#`, and a `#` followed by a space inert. Backtick spans are skipped. Longest match wins, so a heading whose title extends another's resolves to the longer one.
+
+Not applied to `CodeAnnotationCard`: code-review annotations address files and lines, not headings.
+
 ### WebMCP provider (`@plannotator/ui/webmcp`; 0.32.0)
 
 The engine that lets a browser-integrated agent (Chrome/Edge WebMCP, `document.modelContext`) call in-page tools on a document surface. Feature-detected once; a browser without the API sees no registration, no DOM, no network, no timers. Seam: `configurePlannotatorUI({ webmcp: { enabled, namePrefix } })`, default enabled with the `plannotator.` prefix; pass `enabled: false` to keep a host page tool-free, or your own prefix to namespace the tools beside your own. There is deliberately no confirmation seam: the catalog is read-and-comment only (no approve / submit / close tools), and the agent may only edit or remove comments stamped `source: "browser-agent"`.
diff --git a/packages/ui/components/AnnotationPanel.tsx b/packages/ui/components/AnnotationPanel.tsx
index f51275af2..3b6842320 100644
--- a/packages/ui/components/AnnotationPanel.tsx
+++ b/packages/ui/components/AnnotationPanel.tsx
@@ -1,5 +1,6 @@
 import React, { useState, useRef, useEffect } from 'react';
 import { AnnotationType, type Annotation, type Block, type CodeAnnotation, type EditorAnnotation } from '../types';
+import { buildSectionRefIndex, parseSectionRefs } from '../utils/sectionRefs';
 import { isCurrentUser } from '../utils/identity';
 import { ImageThumbnail } from './ImageThumbnail';
 import { EditorAnnotationCard } from './EditorAnnotationCard';
@@ -110,6 +111,8 @@ interface PanelProps {
   editorAnnotations?: EditorAnnotation[];
   onDeleteEditorAnnotation?: (id: string) => void;
   onClose?: () => void;
+  /** Navigate the document to a heading anchor, for `#Heading` references in comment text. */
+  onNavigateAnchor?: (hash: string) => void;
   /** Copy the full feedback payload. May resolve a success boolean; resolving
     *  `false` suppresses the "Copied" flash. A void resolution (existing hosts)
     *  is treated as success, preserving the original behavior. */
@@ -142,6 +145,7 @@ interface PanelProps {
 export const AnnotationPanel: React.FC<PanelProps> = ({
   isOpen,
   annotations,
+  blocks,
   onSelect,
   onDelete,
   onEdit,
@@ -164,7 +168,9 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
   readOnly = false,
   presentation = 'panel',
   unanchoredIds,
+  onNavigateAnchor,
 }) => {
+  const sectionRefs = React.useMemo(() => buildSectionRefIndex(blocks), [blocks]);
   const isMobile = useIsMobile();
   const embedded = presentation === 'embedded';
   const mobilePanel = isMobile && !embedded;
@@ -290,6 +296,8 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
                   >
                     <AnnotationCard
                       annotation={entry.annotation}
+                      sectionRefs={sectionRefs}
+                      onNavigateAnchor={onNavigateAnchor}
                       isSelected={selectedId === entry.annotation.id}
                       isMe={isCurrentUser(entry.annotation.author)}
                       onSelect={() => onSelect(entry.annotation.id)}
@@ -304,6 +312,8 @@ export const AnnotationPanel: React.FC<PanelProps> = ({
                 <AnnotationCard
                   key={entry.annotation.id}
                   annotation={entry.annotation}
+                  sectionRefs={sectionRefs}
+                  onNavigateAnchor={onNavigateAnchor}
                   isSelected={selectedId === entry.annotation.id}
                   isMe={isCurrentUser(entry.annotation.author)}
                   onSelect={() => onSelect(entry.annotation.id)}
@@ -531,6 +541,47 @@ const DirectEditsCard: React.FC<{
   );
 };
 
+/**
+ * Annotation body text, with `#Heading text` turned into a link to that heading.
+ * Falls back to the raw string whenever nothing resolves, so the common comment
+ * renders exactly as it did before this existed.
+ */
+const AnnotationText: React.FC<{
+  text: string;
+  className: string;
+  sectionRefs?: Map<string, string>;
+  onNavigateAnchor?: (hash: string) => void;
+}> = ({ text, className, sectionRefs, onNavigateAnchor }) => {
+  const parts = React.useMemo(
+    () => (sectionRefs && onNavigateAnchor ? parseSectionRefs(text, sectionRefs) : [text]),
+    [text, sectionRefs, onNavigateAnchor],
+  );
+
+  return (
+    <p className={className}>
+      {parts.map((part, i) =>
+        typeof part === 'string' ? (
+          part
+        ) : (
+          <button
+            key={i}
+            type="button"
+            title={`Go to "${part.label}"`}
+            className="text-primary font-medium hover:underline"
+            onClick={(e) => {
+              // The card's own onSelect would scroll to the annotation instead.
+              e.stopPropagation();
+              onNavigateAnchor!(`#${part.anchor}`);
+            }}
+          >
+            {part.label}
+          </button>
+        ),
+      )}
+    </p>
+  );
+};
+
 const AnnotationCard: React.FC<{
   annotation: Annotation;
   isSelected: boolean;
@@ -542,7 +593,9 @@ const AnnotationCard: React.FC<{
   footer?: React.ReactNode;
   /** The annotation has no live location in the document (host-reported). */
   unanchored?: boolean;
-}> = ({ annotation, isSelected, isMe, onSelect, onDelete, onEdit, readOnly = false, footer, unanchored = false }) => {
+  sectionRefs?: Map<string, string>;
+  onNavigateAnchor?: (hash: string) => void;
+}> = ({ annotation, isSelected, isMe, onSelect, onDelete, onEdit, readOnly = false, footer, unanchored = false, sectionRefs, onNavigateAnchor }) => {
   const [isEditing, setIsEditing] = useState(false);
   const [editText, setEditText] = useState(annotation.text || '');
   const textareaRef = useRef<HTMLTextAreaElement>(null);
@@ -688,9 +741,12 @@ const AnnotationCard: React.FC<{
         isEditing ? (
           editComposer
         ) : (
-          <p className="whitespace-pre-wrap text-[13px] leading-relaxed text-foreground/90">
-            {annotation.text}
-          </p>
+          <AnnotationText
+            text={annotation.text || ''}
+            className="whitespace-pre-wrap text-[13px] leading-relaxed text-foreground/90"
+            sectionRefs={sectionRefs}
+            onNavigateAnchor={onNavigateAnchor}
+          />
         )
       ) : (
         <>
@@ -705,9 +761,12 @@ const AnnotationCard: React.FC<{
               editComposer
             ) : (
               annotation.text && (
-                <p className="whitespace-pre-wrap text-[13px] leading-relaxed text-foreground/90">
-                  {annotation.text}
-                </p>
+                <AnnotationText
+                  text={annotation.text}
+                  className="whitespace-pre-wrap text-[13px] leading-relaxed text-foreground/90"
+                  sectionRefs={sectionRefs}
+                  onNavigateAnchor={onNavigateAnchor}
+                />
               )
             )
           )}
diff --git a/packages/ui/components/InlineMarkdown.tsx b/packages/ui/components/InlineMarkdown.tsx
index 7123b7b7f..2578313bb 100644
--- a/packages/ui/components/InlineMarkdown.tsx
+++ b/packages/ui/components/InlineMarkdown.tsx
@@ -266,7 +266,10 @@ const CodeFileLink: React.FC<{
         {display}
         <CodeFileIcon />
         {isAmbiguous && (
-          <sup className="text-[0.6rem] opacity-70 -ml-0.5">{(gate as { matches: string[] }).matches.length}</sup>
+          // aria-hidden: a count the `title` already states, and text the
+          // document does not contain — annotation restore searches this DOM
+          // for quotes of the markdown source and must not see it.
+          <sup aria-hidden="true" className="text-[0.6rem] opacity-70 -ml-0.5">{(gate as { matches: string[] }).matches.length}</sup>
         )}
       </code>
       {hoverPreview && hasLineRef && (
diff --git a/packages/ui/components/ListMarker.tsx b/packages/ui/components/ListMarker.tsx
index 8a1fea777..25f36b45e 100644
--- a/packages/ui/components/ListMarker.tsx
+++ b/packages/ui/components/ListMarker.tsx
@@ -15,6 +15,18 @@ import React from 'react';
  *
  * Interactivity is opt-in: the Viewer passes `interactive` + `onToggle`
  * for click-to-toggle checkboxes; the diff view leaves both undefined.
+ *
+ * The glyph spans carry `data-decorative`: a bullet and a numeral are drawn by
+ * the renderer and are not text the document contains, so annotation anchoring
+ * (`utils/renderedText`) must not see them. This matters most for ordered
+ * items, whose numeral comes from the item's POSITION — CommonMark renumbers
+ * `1. / 2. / 5.` as 1, 2, 3 — while a quote of that source line rendered on its
+ * own has no list to be positioned in.
+ *
+ * Deliberately not `aria-hidden`: these divs carry no list semantics, so the
+ * glyph is the only thing telling assistive tech this is a list item. The flag
+ * also sits on the glyphs rather than the wrapper, which is the checkbox itself
+ * when interactive.
  */
 interface ListMarkerProps {
   level: number;
@@ -51,7 +63,7 @@ export const ListMarker: React.FC<ListMarkerProps> = ({
       aria-checked={interactive ? checked : undefined}
     >
       {showNumeral && (
-        <span className="text-primary/60 tabular-nums text-right" style={{ minWidth: '1.5rem' }}>
+        <span data-decorative="true" className="text-primary/60 tabular-nums text-right" style={{ minWidth: '1.5rem' }}>
           {orderedIndex}.
         </span>
       )}
@@ -66,7 +78,7 @@ export const ListMarker: React.FC<ListMarkerProps> = ({
           </svg>
         )
       ) : !showNumeral ? (
-        <span className="text-primary/60">{bullet}</span>
+        <span data-decorative="true" className="text-primary/60">{bullet}</span>
       ) : null}
     </span>
   );
diff --git a/packages/ui/components/Viewer.tsx b/packages/ui/components/Viewer.tsx
index 6630e4961..839c4be07 100644
--- a/packages/ui/components/Viewer.tsx
+++ b/packages/ui/components/Viewer.tsx
@@ -148,6 +148,8 @@ export interface ViewerHandle {
   removeHighlight: (id: string) => void;
   clearAllHighlights: () => void;
   applySharedAnnotations: (annotations: Annotation[]) => void;
+  /** Scroll a heading anchor into view. Returns false when it is not in this document. */
+  scrollToAnchor: (hash: string) => boolean;
 }
 
 interface CodeBlockToolbarTarget {
@@ -684,6 +686,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
 
   // Imperative handle — delegates to hook, extends removeHighlight for code blocks
   useImperativeHandle(ref, () => ({
+    scrollToAnchor,
     removeHighlight: (id: string) => {
       // The re-highlight below notifies the swap listener, which would happily
       // paint this annotation's mark straight back in — the host has not
@@ -710,7 +713,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
     },
     clearAllHighlights,
     applySharedAnnotations: applyAnnotations,
-  }), [hookRemoveHighlight, clearAllHighlights, applyAnnotations, blocks]);
+  }), [hookRemoveHighlight, clearAllHighlights, applyAnnotations, blocks, scrollToAnchor]);
 
   // --- Viewer-specific: code block annotation ---
 
diff --git a/packages/ui/components/html-viewer/HtmlViewer.tsx b/packages/ui/components/html-viewer/HtmlViewer.tsx
index 5572cc4b5..2500bfa20 100644
--- a/packages/ui/components/html-viewer/HtmlViewer.tsx
+++ b/packages/ui/components/html-viewer/HtmlViewer.tsx
@@ -949,6 +949,9 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
     }, [iframeReadyVersion, hostTheme]);
 
     useImperativeHandle(ref, () => ({
+      // Raw HTML pages have no markdown heading blocks, so there is nothing for
+      // a `#Heading` reference in a comment to resolve to on this surface.
+      scrollToAnchor: () => false,
       removeHighlight: hook.removeHighlight,
       clearAllHighlights: hook.clearAllHighlights,
       // Shared/draft restores respect the live page filter too.
diff --git a/packages/ui/hooks/useAnnotationHighlighter.restoreLadder.test.tsx b/packages/ui/hooks/useAnnotationHighlighter.restoreLadder.test.tsx
new file mode 100644
index 000000000..2bfe7b980
--- /dev/null
+++ b/packages/ui/hooks/useAnnotationHighlighter.restoreLadder.test.tsx
@@ -0,0 +1,150 @@
+import { describe, expect, test } from 'bun:test';
+import React, { useRef, useImperativeHandle, forwardRef } from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react';
+import { AnnotationType, type Annotation } from '../types';
+
+const hasDom = typeof document !== 'undefined';
+
+// Same lazy-import dance as useAnnotationHighlighter.test.tsx: the hook pulls
+// in a UMD bundle that reads `window` at module-eval time.
+const mod = hasDom ? await import('./useAnnotationHighlighter') : null;
+const useAnnotationHighlighter =
+  mod?.useAnnotationHighlighter as typeof import('./useAnnotationHighlighter')['useAnnotationHighlighter'];
+const parser = hasDom ? await import('../utils/parser') : null;
+const blockRenderer = hasDom ? await import('../components/BlockRenderer') : null;
+
+/**
+ * The document, as markdown. The harness renders it with the app's own parser
+ * and BlockRenderer, so the DOM under test is the DOM the app produces — the
+ * point of the whole exercise is that restore agrees with the real renderer,
+ * and a hand-written approximation of it here would be the same mistake one
+ * level up.
+ */
+const DOCUMENT = [
+  '**Install** now',
+  '',
+  'Setup `bun`',
+  '',
+  '[Deployment](./s.md) guide',
+  '',
+  'Part 1 --- end',
+  '',
+  'Plain unmarked sentence',
+  '',
+  '| 영역 | 변경 |',
+  '| --- | --- |',
+  '| config 표면 분기 | `config.ts` — `ENABLED_SURFACES=mcp` 파싱, `JIRA_*` 요구를 Slack 활성 시로 한정 |',
+  '',
+  '- `tests/config.test.ts` — `ENABLED_SURFACES=mcp`가 Slack 토큰 없이 config 로드 성공',
+  '',
+  '1. first step',
+  '2. second step',
+  // CommonMark renumbers a run, so this renders as "3." — the numeral the
+  // reader sees is nowhere in the source, and the source's "5." is nowhere in
+  // the DOM. Only treating the numeral as chrome reconciles the two.
+  '5. WP1~WP7 구현 → 기존 서버에 배포하여 **동작 불변 확인**',
+].join('\n');
+
+const Harness = forwardRef<{ apply: (a: Annotation[]) => void }, {}>((_props, ref) => {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const hook = useAnnotationHighlighter({
+    containerRef,
+    annotations: [],
+    selectedAnnotationId: null,
+    mode: 'comment',
+  });
+  useImperativeHandle(ref, () => ({ apply: hook.applyAnnotations }), [hook.applyAnnotations]);
+
+  const BlockRenderer = blockRenderer!.BlockRenderer;
+  const { parseMarkdownToBlocks, groupBlocks, computeListIndices } = parser!;
+
+  // Exactly Viewer's own render path, list grouping included — an ordered item
+  // gets its numeral from the group, which is the context a quoted fragment
+  // does not have.
+  return (
+    <div ref={containerRef}>
+      {groupBlocks(parseMarkdownToBlocks(DOCUMENT)).map((group) =>
+        group.type === 'list-group'
+          ? (() => {
+              const indices = computeListIndices(group.blocks);
+              return group.blocks.map((block, i) => (
+                <BlockRenderer key={block.id} block={block} orderedIndex={indices[i]} />
+              ));
+            })()
+          : <BlockRenderer key={group.block.id} block={group.block} />,
+      )}
+      {/* An ambiguous code-file link. Its match-count <sup> is chrome the
+          renderer draws from a runtime file lookup this test cannot stage, so
+          this one block is written by hand. */}
+      <p data-block-id="hand-written">
+        See <code>config.ts<sup aria-hidden="true">7</sup></code> now
+      </p>
+    </div>
+  );
+});
+
+const annotation = (id: string, originalText: string): Annotation => ({
+  id,
+  blockId: 'external',
+  startOffset: 0,
+  endOffset: originalText.length,
+  type: AnnotationType.COMMENT,
+  text: 'from an external tool',
+  originalText,
+  createdA: 0,
+  source: 'external',
+} as unknown as Annotation);
+
+describe('external annotations quoting markdown source still highlight', () => {
+  // An agent copies phrases out of `/api/plan`, which serves the markdown
+  // SOURCE, while restore searches the RENDERED DOM. Every case below is a
+  // faithful source quote; each was once accepted, listed, and silently never
+  // highlighted, with a `console.warn` as the only trace.
+  test.skipIf(!hasDom)('markup-bearing source quotes resolve to the rendered text', async () => {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const root = createRoot(host);
+    const ref = React.createRef<{ apply: (a: Annotation[]) => void }>();
+
+    await act(async () => {
+      root.render(<Harness ref={ref} />);
+    });
+
+    const cases: [string, string][] = [
+      ['**Install** now', 'emphasis'],
+      ['Setup `bun`', 'code span'],
+      ['[Deployment](./s.md)', 'link'],
+      ['Part 1 --- end', 'smart punctuation'],
+      ['Plain unmarked sentence', 'no markup'],
+      ['Install now', 'quote of the rendered text, not the source'],
+      [
+        '| config 표면 분기 | `config.ts` — `ENABLED_SURFACES=mcp` 파싱, `JIRA_*` 요구를 Slack 활성 시로 한정 |',
+        'table row — pipes and cell padding exist only in the source',
+      ],
+      [
+        '- `tests/config.test.ts` — `ENABLED_SURFACES=mcp`가 Slack 토큰 없이 config 로드 성공',
+        'bulleted list item — source has `- `, DOM has a • glyph',
+      ],
+      [
+        '5. WP1~WP7 구현 → 기존 서버에 배포하여 **동작 불변 확인**',
+        'ordered list item — source numeral 5 renders as 3',
+      ],
+      ['See `config.ts` now', 'ui-only decoration text'],
+      ['Install** now', 'fragment cutting an emphasis span in half'],
+    ];
+
+    await act(async () => {
+      ref.current!.apply(cases.map(([text], i) => annotation(`ann-${i}`, text)));
+    });
+
+    const unhighlighted = cases.filter(
+      (_, i) => !host.querySelector(`[data-bind-id="ann-${i}"]`),
+    );
+
+    expect(unhighlighted.map(([, label]) => label)).toEqual([]);
+
+    root.unmount();
+    host.remove();
+  });
+});
diff --git a/packages/ui/hooks/useAnnotationHighlighter.ts b/packages/ui/hooks/useAnnotationHighlighter.ts
index c32df6fcb..06f314bd3 100644
--- a/packages/ui/hooks/useAnnotationHighlighter.ts
+++ b/packages/ui/hooks/useAnnotationHighlighter.ts
@@ -11,7 +11,7 @@ import type { Annotation, EditorMode, ImageAttachment } from '../types';
 import { AnnotationType } from '../types';
 import type { QuickLabel } from '../utils/quickLabels';
 import { getIdentity } from '../utils/identity';
-import { transformPlainText } from '../utils/inlineTransforms';
+import { renderMarkdownToText, visibleText, VISIBLE_TEXT } from '../utils/renderedText';
 
 // --- Exported state types ---
 
@@ -175,6 +175,11 @@ const selectionHasNonMathContent = (
   return false;
 };
 
+// Markdown syntax and the whitespace element boundaries add and remove, for the
+// last-resort rung below. Dropped from the DOM text as well as the quote, so a
+// half-rendered fragment can still be matched from either side.
+const MARKDOWN_NOISE = /[`*_~|[\]\s]/;
+
 const annotationId = (): string => {
   const cryptoRef = globalThis.crypto;
   if (cryptoRef && typeof cryptoRef.randomUUID === 'function') {
@@ -365,7 +370,7 @@ export function useAnnotationHighlighter({
         const walker = document.createTreeWalker(
           containerRef.current!,
           NodeFilter.SHOW_TEXT,
-          null
+          VISIBLE_TEXT
         );
 
         let charCount = 0;
@@ -402,13 +407,17 @@ export function useAnnotationHighlighter({
         return null;
       };
 
-      const normalizeWithMap = (text: string): { text: string; map: number[] } => {
+      const normalizeWithMap = (
+        text: string,
+        dropNoise = false,
+      ): { text: string; map: number[] } => {
         let normalized = '';
         const map: number[] = [];
         let inWhitespace = false;
 
         for (let i = 0; i < text.length; i++) {
           const ch = text[i];
+          if (dropNoise && MARKDOWN_NOISE.test(ch)) continue;
           if (/\s/.test(ch)) {
             if (!inWhitespace) {
               normalized += ' ';
@@ -436,7 +445,7 @@ export function useAnnotationHighlighter({
       const walker = document.createTreeWalker(
         containerRef.current,
         NodeFilter.SHOW_TEXT,
-        null
+        VISIBLE_TEXT
       );
 
       let node: Text | null;
@@ -451,7 +460,7 @@ export function useAnnotationHighlighter({
         }
       }
 
-      const fullText = containerRef.current.textContent || '';
+      const fullText = visibleText(containerRef.current);
       const searchIndex = fullText.indexOf(needle);
       if (searchIndex !== -1) {
         return rangeFromTextOffsets(searchIndex, searchIndex + needle.length);
@@ -466,19 +475,46 @@ export function useAnnotationHighlighter({
         return rangeFromTextOffsets(originalStart, originalEnd);
       }
 
+      // Last resort, and the only rung the renderer cannot replace: a quote
+      // that starts or ends INSIDE a block. `Install** now` is half of an
+      // emphasis span, so rendering it leaves the `**` literal — the render is
+      // faithful, the fragment just isn't what the document rendered. Dropping
+      // markdown noise from BOTH sides (whitespace included, since element
+      // boundaries add and remove it) still lands such a fragment on its text.
+      const canonical = normalizeWithMap(fullText, true);
+      const canonicalNeedle = normalizeWithMap(needle, true).text;
+      const canonicalIndex = canonical.text.indexOf(canonicalNeedle);
+      if (canonicalNeedle && canonicalIndex !== -1) {
+        const originalStart = canonical.map[canonicalIndex];
+        const originalEnd = canonical.map[canonicalIndex + canonicalNeedle.length - 1] + 1;
+        return rangeFromTextOffsets(originalStart, originalEnd);
+      }
+
       return null;
     };
 
-    // First try the literal text. If that misses, re-try with the same
-    // transform the renderer applies to plain text (emoji shortcodes +
-    // smart punctuation) so annotations made before those transforms
-    // shipped can still re-bind to their target after reload.
-    const direct = searchOnce(searchText);
-    if (direct) return direct;
-
-    const transformed = transformPlainText(searchText);
-    if (transformed !== searchText) {
-      return searchOnce(transformed);
+    // The needle is source text; the haystack is the rendered DOM.
+    //
+    // Rung 1 is the literal quote: text selected in the page is already
+    // rendered, and source carrying no markup renders to itself.
+    //
+    // Rung 2 asks the renderer. A quote taken from the markdown SOURCE — what
+    // `/api/plan` serves, and therefore what an agent posting external
+    // annotations copies from — is not what the page shows: `**Install** now`,
+    // `` `bun` ``, `[Setup](./s.md)`, `| a | b |` and `- item` all render to
+    // something else, and the last two also gain text (a bullet) that no
+    // rewrite of the needle could produce. Running the real renderer over the
+    // quote settles all of it at once, and settles the next markdown feature
+    // for free. This replaced four rungs of regex approximation.
+    const seen = new Set<string>();
+    for (const candidate of [
+      searchText,
+      renderMarkdownToText(searchText),
+    ]) {
+      if (!candidate || seen.has(candidate)) continue;
+      seen.add(candidate);
+      const range = searchOnce(candidate);
+      if (range) return range;
     }
 
     return null;
diff --git a/packages/ui/hooks/useLinkedDoc.test.tsx b/packages/ui/hooks/useLinkedDoc.test.tsx
index 4b274b167..1ffd34b43 100644
--- a/packages/ui/hooks/useLinkedDoc.test.tsx
+++ b/packages/ui/hooks/useLinkedDoc.test.tsx
@@ -19,6 +19,7 @@ import type { Annotation, ImageAttachment } from '../types';
 const hasDom = typeof document !== 'undefined';
 
 const noopViewerHandle: ViewerHandle = {
+  scrollToAnchor: () => false,
   removeHighlight: () => {},
   clearAllHighlights: () => {},
   applySharedAnnotations: () => {},
diff --git a/packages/ui/utils/inlineTransforms.test.ts b/packages/ui/utils/inlineTransforms.test.ts
index 99c273ddc..ab3dfc10b 100644
--- a/packages/ui/utils/inlineTransforms.test.ts
+++ b/packages/ui/utils/inlineTransforms.test.ts
@@ -1,5 +1,6 @@
 import { describe, test, expect } from 'bun:test';
-import { transformPlainText } from './inlineTransforms';
+import { stripInlineMarkdown, transformPlainText } from './inlineTransforms';
+import { slugifyHeading } from './slugify';
 
 describe('transformPlainText — emoji shortcodes', () => {
   test('replaces known shortcode with unicode emoji', () => {
@@ -46,3 +47,35 @@ describe('transformPlainText — smart punctuation', () => {
     expect(transformPlainText("he said 'hi'")).toBe('he said ‘hi’');
   });
 });
+
+describe('stripInlineMarkdown', () => {
+  // Each row is a source fragment an agent can faithfully copy out of
+  // /api/plan whose rendered form carries none of that syntax. These are the
+  // quotes that were accepted, listed, and silently never highlighted.
+  test.each([
+    ['**Install** now', 'Install now'],
+    ['Setup `bun`', 'Setup bun'],
+    ['[Setup](./setup.md)', 'Setup'],
+    ['see [[architecture]]', 'see architecture'],
+    ['_em_ and ~~struck~~', 'em and struck'],
+  ])('%p renders as %p', (source, rendered) => {
+    expect(stripInlineMarkdown(source)).toBe(rendered);
+  });
+
+  test('leaves text without inline markup untouched', () => {
+    expect(stripInlineMarkdown('plain sentence, 3.1 included')).toBe('plain sentence, 3.1 included');
+  });
+});
+
+describe('slugifyHeading after sharing the stripper', () => {
+  // Extracting the stripper must not move any anchor: a changed slug silently
+  // breaks every `#anchor` already written against these documents.
+  test.each([
+    ['**Install** `bun`', 'install-bun'],
+    ['[Setup](./s.md)', 'setup'],
+    ['[[architecture]] notes', 'architecture-notes'],
+    ['snake_case config', 'snakecase-config'],
+  ])('%p slugs to %p', (heading, slug) => {
+    expect(slugifyHeading(heading)).toBe(slug);
+  });
+});
diff --git a/packages/ui/utils/inlineTransforms.ts b/packages/ui/utils/inlineTransforms.ts
index 9c33b7036..c27b1ca60 100644
--- a/packages/ui/utils/inlineTransforms.ts
+++ b/packages/ui/utils/inlineTransforms.ts
@@ -36,6 +36,30 @@ function smartypants(s: string): string {
     .replace(/'/g, '’');
 }
 
+/**
+ * Approximate the renderer's inline output for a fragment of source markdown:
+ * drop the syntax that `InlineMarkdown` consumes without rendering.
+ *
+ * Only `slugifyHeading` calls this now. Annotation restore used to, and that is
+ * what made leaving the crudeness in place affordable; it now asks the renderer
+ * directly (`utils/renderedText`), because approximating an inverse that does
+ * not exist cost four rungs of a ladder and still could not see text the DOM
+ * ADDS — a bullet, an ordered numeral, a match-count badge.
+ *
+ * Slugs stay here on purpose. `slugifyHeading` is pure and runs where no DOM
+ * exists, which `renderedText` cannot do, and its output is anchor ids that
+ * live in URLs — so the one place the two would disagree (`snake_case` slugging
+ * to `snakecase` rather than `snake-case`) is a link-stability question, not a
+ * correctness one. Stripping every `*_`~` rather than only paired ones is safe
+ * for that caller: a heading is slugged whole, never matched against anything.
+ */
+export function stripInlineMarkdown(text: string): string {
+  return text
+    .replace(/\[\[([^\]]+)\]\]/g, '$1')
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+    .replace(/[*_`~]/g, '');
+}
+
 export function transformPlainText(text: string): string {
   return smartypants(replaceEmoji(text));
 }
diff --git a/packages/ui/utils/renderedText.test.tsx b/packages/ui/utils/renderedText.test.tsx
new file mode 100644
index 000000000..32f5d1b72
--- /dev/null
+++ b/packages/ui/utils/renderedText.test.tsx
@@ -0,0 +1,45 @@
+import { describe, expect, test } from 'bun:test';
+
+const hasDom = typeof document !== 'undefined';
+const mod = hasDom ? await import('./renderedText') : null;
+const renderMarkdownToText = mod?.renderMarkdownToText as
+  typeof import('./renderedText')['renderMarkdownToText'];
+
+describe('renderMarkdownToText', () => {
+  // Each row is a quote an agent can legitimately take from `/api/plan` (which
+  // serves markdown SOURCE) paired with what the page actually shows. The
+  // point of the function is that the second column is produced by the real
+  // renderer rather than guessed at, so these are the divergences that used to
+  // need a regex rung each.
+  const cases: [string, string, string][] = [
+    ['**Install** now', 'Install now', 'emphasis is consumed'],
+    ['Setup `bun`', 'Setup bun', 'code span delimiters are consumed'],
+    ['[Deployment](./s.md) guide', 'Deployment guide', 'link target is consumed'],
+    ['Part 1 --- end', 'Part 1 — end', 'smart punctuation is applied'],
+    ['ship it :rocket:', 'ship it 🚀', 'emoji shortcodes are expanded'],
+    ['plain sentence', 'plain sentence', 'text with no markup renders to itself'],
+    [
+      '| a | `JIRA_*` |',
+      'aJIRA_*',
+      'table pipes vanish, and a code span keeps the `_*` a stripper would eat',
+    ],
+    ['- item one', 'item one', 'the bullet is drawn, not document text'],
+    ['5. item five', 'item five', 'the ordered numeral is drawn, not document text'],
+  ];
+
+  for (const [source, rendered, label] of cases) {
+    test.skipIf(!hasDom)(label, () => {
+      expect(renderMarkdownToText(source)).toBe(rendered);
+    });
+  }
+
+  test.skipIf(!hasDom)('table cells are joined the way sibling <td>s are: with nothing', () => {
+    // Not cosmetic. The document DOM has no text between cells either, so a
+    // needle that inserted a space here would never match.
+    expect(renderMarkdownToText('| left | right |')).toBe('leftright');
+  });
+
+  test.skipIf(!hasDom)('empty source has no rendering', () => {
+    expect(renderMarkdownToText('')).toBeNull();
+  });
+});
diff --git a/packages/ui/utils/renderedText.tsx b/packages/ui/utils/renderedText.tsx
new file mode 100644
index 000000000..bec83bf8b
--- /dev/null
+++ b/packages/ui/utils/renderedText.tsx
@@ -0,0 +1,95 @@
+/**
+ * What the renderer makes of a piece of markdown, as text.
+ *
+ * Several features match SOURCE markdown against the RENDERED DOM: an external
+ * annotation quotes `/api/plan`, which serves the source, and is then pinned by
+ * searching the page. The two disagree wherever the renderer consumes syntax
+ * (`**bold**`, `` `code` ``, `[a](b)`), drops a delimiter that carries no glyph
+ * (a table row's `|`, a list item's `- `), or injects text of its own (a
+ * bullet, an ordered numeral, an ambiguous code-file link's match count).
+ *
+ * That divergence has no inverse worth writing. Approximating one with regexes
+ * cost this codebase four rungs of a restore ladder and still missed every case
+ * where the DOM side is what diverges, because rewriting the needle cannot
+ * remove text the haystack gained. So don't approximate: run the real renderer
+ * over the quote and compare its output. A markdown feature added tomorrow is
+ * covered the day it renders.
+ *
+ * Two rules make the comparison sound, and both sides must follow them:
+ *
+ *   1. Text the renderer injects for the UI's own sake is flagged (see
+ *      `DECORATION_SELECTOR`) and excluded here AND from the document walker.
+ *      This is what makes a bullet, an ordered numeral and a match-count badge
+ *      simply not exist for either side, which matters because a fragment
+ *      rendered alone cannot know its position in a list.
+ *   2. The document is walked with `visibleText`, never `textContent`.
+ *
+ * Returns null when the source renders to nothing or the render throws (a
+ * block needing a live DOM, KaTeX, a highlighter): callers fall back to their
+ * other rungs rather than losing the annotation.
+ */
+
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { parseMarkdownToBlocks } from './parser';
+import { BlockRenderer } from '../components/BlockRenderer';
+
+/**
+ * Skips chrome the renderer drew: text that is not in the document.
+ *
+ * Two flags, because they are two different claims. `aria-hidden` says "no one
+ * needs to hear this", which fits a badge that repeats its own `title`.
+ * `data-decorative` says "this is not document text" WITHOUT hiding it — a list
+ * bullet has to stay audible, since these list items are divs and the glyph is
+ * the only thing marking them as a list.
+ */
+const DECORATION_SELECTOR = '[aria-hidden="true"],[data-decorative]';
+
+export const VISIBLE_TEXT: NodeFilter = {
+  acceptNode: (node) =>
+    node.parentElement?.closest(DECORATION_SELECTOR)
+      ? NodeFilter.FILTER_REJECT
+      : NodeFilter.FILTER_ACCEPT,
+};
+
+export function visibleText(root: Node): string {
+  const doc = root.ownerDocument ?? (typeof document !== 'undefined' ? document : null);
+  if (!doc) return '';
+  const walker = doc.createTreeWalker(root, NodeFilter.SHOW_TEXT, VISIBLE_TEXT);
+  let text = '';
+  let node: Text | null;
+  while ((node = walker.nextNode() as Text | null)) text += node.textContent || '';
+  return text;
+}
+
+// Restore runs over every annotation on load, and a quote is stable for the
+// life of the page. Bounded rather than an LRU: the working set is one
+// document's annotations, and dropping all of it costs one re-render.
+const CACHE_LIMIT = 500;
+const cache = new Map<string, string | null>();
+
+function render(source: string): string | null {
+  if (typeof document === 'undefined') return null;
+  try {
+    const blocks = parseMarkdownToBlocks(source);
+    if (blocks.length === 0) return null;
+    // A <template> is inert: its content is parsed but never run or laid out.
+    const holder = document.createElement('template');
+    holder.innerHTML = blocks
+      .map((block) => renderToStaticMarkup(<BlockRenderer block={block} />))
+      .join('');
+    return visibleText(holder.content) || null;
+  } catch {
+    return null;
+  }
+}
+
+export function renderMarkdownToText(source: string): string | null {
+  if (!source) return null;
+  const cached = cache.get(source);
+  if (cached !== undefined) return cached;
+  const rendered = render(source);
+  if (cache.size >= CACHE_LIMIT) cache.clear();
+  cache.set(source, rendered);
+  return rendered;
+}
diff --git a/packages/ui/utils/sectionRefs.test.ts b/packages/ui/utils/sectionRefs.test.ts
new file mode 100644
index 000000000..71e30b864
--- /dev/null
+++ b/packages/ui/utils/sectionRefs.test.ts
@@ -0,0 +1,131 @@
+import { describe, expect, it } from 'bun:test';
+import { buildSectionRefIndex, parseSectionRefs } from './sectionRefs';
+
+const heading = (id: string, content: string) => ({ id, type: 'heading', content });
+const para = (id: string, content: string) => ({ id, type: 'paragraph', content });
+
+const DOC = [
+  heading('b1', 'Design notes'),
+  heading('b2', '3.1 Single source of truth'),
+  para('b3', 'body text'),
+  heading('b4', 'Overview'),
+];
+
+describe('buildSectionRefIndex', () => {
+  it('indexes headings by their exact text', () => {
+    const index = buildSectionRefIndex(DOC);
+    expect(index.get('3.1 Single source of truth')).toBe('3-1-single-source-of-truth');
+    expect(index.has('body text')).toBe(false);
+  });
+
+  it('drops a title shared by two headings rather than picking one', () => {
+    const index = buildSectionRefIndex([
+      heading('b1', 'Overview'),
+      heading('b2', 'Overview'),
+      heading('b3', 'Conclusion'),
+    ]);
+    expect(index.has('Overview')).toBe(false);
+    expect(index.has('Conclusion')).toBe(true);
+  });
+
+  it('keeps unicode headings addressable', () => {
+    const index = buildSectionRefIndex([heading('b1', 'Café metrics')]);
+    expect(index.get('Café metrics')).toBe('café-metrics');
+  });
+});
+
+describe('parseSectionRefs', () => {
+  const index = buildSectionRefIndex(DOC);
+
+  it('links a reference and leaves what follows it outside the link', () => {
+    // The match ends where the heading text ends, with no trailing word
+    // boundary required. That is what lets a script without spaces between a
+    // noun and its suffix reference a section at all; the cost is that
+    // `#Overviewing` would resolve `Overview` and leave `ing`, which only
+    // happens when someone typed `#` meaning a reference in the first place.
+    const parts = parseSectionRefs("#3.1 Single source of truth's premise breaks", index);
+    expect(parts).toEqual([
+      { label: '3.1 Single source of truth', anchor: '3-1-single-source-of-truth' },
+      "'s premise breaks",
+    ]);
+  });
+
+  it('links several references in one comment', () => {
+    const parts = parseSectionRefs('#Overview and #3.1 Single source of truth disagree', index);
+    expect(parts.filter((p) => typeof p !== 'string')).toHaveLength(2);
+  });
+
+  it('takes the longest matching title', () => {
+    const nested = buildSectionRefIndex([
+      heading('a', '3.1'),
+      heading('b', '3.1 Single source of truth'),
+    ]);
+    const parts = parseSectionRefs('#3.1 Single source of truth, see above', nested);
+    expect(parts[0]).toEqual({
+      label: '3.1 Single source of truth',
+      anchor: '3-1-single-source-of-truth',
+    });
+  });
+
+  it('leaves text that matches no heading alone', () => {
+    expect(parseSectionRefs('#fff on issue #123', index)).toEqual(['#fff on issue #123']);
+  });
+
+  it('ignores a hash welded to a word', () => {
+    const csharp = buildSectionRefIndex([heading('a', 'Overview')]);
+    expect(parseSectionRefs('C#Overview notes', csharp)).toEqual(['C#Overview notes']);
+  });
+
+  it('ignores a hash followed by a space, which is markdown heading intent', () => {
+    expect(parseSectionRefs('# Overview', index)).toEqual(['# Overview']);
+  });
+
+  it('does not resolve references inside code spans', () => {
+    expect(parseSectionRefs('`#Overview` is code', index)).toEqual(['`#Overview` is code']);
+  });
+
+  it('returns the original text when the document has no headings', () => {
+    expect(parseSectionRefs('#Overview', new Map())).toEqual(['#Overview']);
+  });
+});
+
+describe('headings whose rendered text differs from their markdown', () => {
+  // A reader copies the heading off the page, not out of the source. Each row
+  // is a heading whose two spellings diverge, and the comment as it would
+  // actually be typed. Before both spellings were indexed, every one of these
+  // rendered as plain text.
+  const resolved = (headingText: string, comment: string) => {
+    const index = buildSectionRefIndex([heading('b1', headingText)]);
+    return parseSectionRefs(comment, index).filter((p) => typeof p !== 'string');
+  };
+
+  it.each([
+    ['**Install** now', '#Install now', 'emphasis'],
+    ['Setup `bun`', '#Setup bun', 'code span'],
+    ['[Setup](./s.md) guide', '#Setup guide', 'link'],
+    ['Part 1 --- end', '#Part 1 — end', 'smart punctuation'],
+    [':rocket: Launch', '#🚀 Launch', 'emoji shortcode'],
+  ])('%p referenced as %p resolves (%s)', (headingText, comment) => {
+    expect(resolved(headingText as string, comment as string)).toHaveLength(1);
+  });
+
+  it('still resolves the raw markdown spelling', () => {
+    // The panel is not the only writer — an agent quoting `/api/plan` sees the
+    // source. Adding the rendered key must not cost the source key.
+    expect(resolved('**Install** now', '#**Install** now')).toHaveLength(1);
+  });
+
+  it('drops a title two different headings both claim after stripping', () => {
+    const index = buildSectionRefIndex([
+      heading('b1', 'Install'),
+      heading('b2', '**Install**'),
+    ]);
+    expect(index.has('Install')).toBe(false);
+  });
+
+  it('keeps a heading whose two spellings are identical', () => {
+    // Registering the same anchor twice is one heading, not a collision.
+    const index = buildSectionRefIndex([heading('b1', 'Overview')]);
+    expect(index.get('Overview')).toBe('overview');
+  });
+});
diff --git a/packages/ui/utils/sectionRefs.ts b/packages/ui/utils/sectionRefs.ts
new file mode 100644
index 000000000..7f7681435
--- /dev/null
+++ b/packages/ui/utils/sectionRefs.ts
@@ -0,0 +1,163 @@
+/**
+ * Section references inside annotation text.
+ *
+ * An annotation that says "this contradicts 3.1" forces the reader to go find
+ * 3.1 by hand — the exact cross-referencing cost the annotation surface exists
+ * to remove. Writing `#3.1 Single source of truth` instead makes the reference
+ * a link to that heading.
+ *
+ * The document defines the vocabulary: only text that exactly matches a heading
+ * in THIS document resolves. There is no grammar of section numbers to get
+ * wrong, and `#fff` / `#123` / `C#` stay plain text unless a heading is
+ * literally named `fff` / `123`.
+ */
+
+import { buildHeadingSlugMap } from './slugify';
+import { stripInlineMarkdown, transformPlainText } from './inlineTransforms';
+
+export interface SectionRefSegment {
+  /** The heading text, rendered as the link label. */
+  label: string;
+  /** Anchor id to navigate to, matching the heading's rendered element id. */
+  anchor: string;
+}
+
+export type SectionRefPart = string | SectionRefSegment;
+
+/**
+ * heading text → anchor id, for headings whose text is unambiguous.
+ *
+ * Each heading is registered under two spellings, because the writer of a
+ * comment and the storage of a heading do not see the same string. A block's
+ * `content` is raw markdown (`**Install** \`bun\``), while the panel and the
+ * document show what `InlineMarkdown` made of it (`Install bun`) — so a reader
+ * copying the heading off the page produced a reference that resolved against
+ * nothing. Registering the rendered approximation alongside the raw text is
+ * what makes the reference work whichever one they typed; it is also the only
+ * way a heading containing a code span can be referenced at all, since
+ * `splitOnCodeSpans` removes the backticked run from the comment before lookup.
+ *
+ * A title claimed by two DIFFERENT headings is dropped rather than resolved to
+ * the first: a reference that could mean either is not a reference. Anchors are
+ * already deduplicated per heading, so an anchor identifies its heading and a
+ * repeat under the same anchor is just one heading's two spellings.
+ */
+export function buildSectionRefIndex(
+  blocks: Array<{ id: string; type: string; content: string }>,
+): Map<string, string> {
+  const slugs = buildHeadingSlugMap(blocks);
+  const index = new Map<string, string>();
+  const ambiguous = new Set<string>();
+
+  const register = (title: string, anchor: string) => {
+    const key = title.trim();
+    if (!key) return;
+    const existing = index.get(key);
+    if (existing === undefined) {
+      index.set(key, anchor);
+      return;
+    }
+    if (existing !== anchor) ambiguous.add(key);
+  };
+
+  for (const block of blocks) {
+    if (block.type !== 'heading') continue;
+    const raw = block.content.trim();
+    const anchor = slugs.get(block.id);
+    if (!raw || !anchor) continue;
+    register(raw, anchor);
+    register(transformPlainText(stripInlineMarkdown(raw)), anchor);
+  }
+
+  for (const title of ambiguous) index.delete(title);
+  return index;
+}
+
+/** Backtick-delimited spans are quoted material, never markup. */
+function splitOnCodeSpans(text: string): Array<{ code: boolean; text: string }> {
+  const parts: Array<{ code: boolean; text: string }> = [];
+  const pattern = /`[^`]*`/g;
+  let last = 0;
+  let match: RegExpExecArray | null;
+
+  while ((match = pattern.exec(text)) !== null) {
+    if (match.index > last) parts.push({ code: false, text: text.slice(last, match.index) });
+    parts.push({ code: true, text: match[0] });
+    last = match.index + match[0].length;
+  }
+  if (last < text.length) parts.push({ code: false, text: text.slice(last) });
+  return parts;
+}
+
+function matchAt(segment: string, start: number, titles: string[]): string | null {
+  // `# heading` is someone writing a markdown heading, not a reference.
+  if (segment[start + 1] === undefined || /\s/.test(segment[start + 1]!)) return null;
+  // Longest first, so `#3.1 Scope` never resolves to a shorter `#3.1` sibling.
+  for (const title of titles) {
+    if (segment.startsWith(title, start + 1)) return title;
+  }
+  return null;
+}
+
+/**
+ * Split annotation text into plain runs and resolved section references.
+ *
+ * Returns a single-element array of the original text when nothing resolves,
+ * so callers can render the common case without special-casing.
+ */
+export function parseSectionRefs(
+  text: string,
+  index: Map<string, string>,
+): SectionRefPart[] {
+  if (!text || index.size === 0 || !text.includes('#')) return [text];
+
+  // Longest-first is what makes the scan greedy; ties are irrelevant since
+  // equal-length distinct titles cannot both match at one position.
+  const titles = [...index.keys()].sort((a, b) => b.length - a.length);
+  const parts: SectionRefPart[] = [];
+  let pending = '';
+
+  const flush = () => {
+    if (pending) {
+      parts.push(pending);
+      pending = '';
+    }
+  };
+
+  for (const segment of splitOnCodeSpans(text)) {
+    if (segment.code) {
+      pending += segment.text;
+      continue;
+    }
+
+    let i = 0;
+    while (i < segment.text.length) {
+      if (segment.text[i] !== '#') {
+        pending += segment.text[i];
+        i += 1;
+        continue;
+      }
+      // `C#`, `issue#4` — a `#` welded to a word is part of that word.
+      const previous = i > 0 ? segment.text[i - 1]! : (pending.slice(-1) || '');
+      if (/[\p{L}\p{N}_]/u.test(previous)) {
+        pending += segment.text[i];
+        i += 1;
+        continue;
+      }
+
+      const title = matchAt(segment.text, i, titles);
+      if (!title) {
+        pending += segment.text[i];
+        i += 1;
+        continue;
+      }
+
+      flush();
+      parts.push({ label: title, anchor: index.get(title)! });
+      i += 1 + title.length;
+    }
+  }
+
+  flush();
+  return parts.length > 0 ? parts : [text];
+}
diff --git a/packages/ui/utils/slugify.ts b/packages/ui/utils/slugify.ts
index 8f93e0269..cddf1893a 100644
--- a/packages/ui/utils/slugify.ts
+++ b/packages/ui/utils/slugify.ts
@@ -1,14 +1,12 @@
+import { stripInlineMarkdown } from './inlineTransforms';
+
 /**
  * Convert heading text into a URL-safe anchor id.
  * Strips common inline markdown so `**Install** \`bun\`` → `install-bun`.
  * Preserves unicode letters (e.g. "Café" → "café").
  */
 export function slugifyHeading(text: string): string {
-  return text
-    .toLowerCase()
-    .replace(/\[\[([^\]]+)\]\]/g, '$1')
-    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
-    .replace(/[*_`~]/g, '')
+  return stripInlineMarkdown(text.toLowerCase())
     .replace(/[^\p{L}\p{N}]+/gu, '-')
     .replace(/^-+|-+$/g, '');
 }
diff --git a/scripts/install.cmd b/scripts/install.cmd
index f053939a5..db587197e 100644
--- a/scripts/install.cmd
+++ b/scripts/install.cmd
@@ -1052,7 +1052,7 @@ if exist "!PREFS_FILE!" (
 REM Extras already on disk? Then the extras question is moot - they still
 REM count toward the picker list, and we never launch the npx flow over them.
 set "EXTRAS_PRESENT=0"
-for %%S in (plannotator-compound plannotator-setup-goal plannotator-visual-explainer) do (
+for %%S in (plannotator-compound plannotator-setup-goal plannotator-visual-explainer plannotator-markup) do (
     if exist "!CLAUDE_SKILLS_DIR!\%%S" set "EXTRAS_PRESENT=1"
     if exist "!AGENTS_SKILLS_DIR!\%%S" set "EXTRAS_PRESENT=1"
 )
@@ -1769,10 +1769,11 @@ set "SKILL_1=plannotator-review"
 set "SKILL_2=plannotator-annotate"
 set "SKILL_3=plannotator-last"
 if "!EXTRAS_CHOICE!"=="yes" (
-    set "SKILL_COUNT=6"
+    set "SKILL_COUNT=7"
     set "SKILL_4=plannotator-compound"
     set "SKILL_5=plannotator-setup-goal"
     set "SKILL_6=plannotator-visual-explainer"
+    set "SKILL_7=plannotator-markup"
 )
 REM Preselect previously chosen skills. NOTE: no pipes here - each side of a
 REM cmd pipe runs in a child without delayed expansion, so !vars! would pass
diff --git a/scripts/install.ps1 b/scripts/install.ps1
index 0f1083caf..8e44dae04 100644
--- a/scripts/install.ps1
+++ b/scripts/install.ps1
@@ -854,7 +854,7 @@ if (-not (Test-Path $extrasMigration)) {
 # redirected/CI runs never prompt. Flags win over everything.
 $prefsFile = Join-Path $configDir "install-prefs"
 $coreSkillNames = @("plannotator-review", "plannotator-annotate", "plannotator-last")
-$extraSkillNames = @("plannotator-compound", "plannotator-setup-goal", "plannotator-visual-explainer")
+$extraSkillNames = @("plannotator-compound", "plannotator-setup-goal", "plannotator-visual-explainer", "plannotator-markup")
 
 $savedExtras = ""
 $savedInvocable = ""
diff --git a/scripts/install.sh b/scripts/install.sh
index b4a43c656..347a9d318 100644
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -1377,7 +1377,7 @@ fi
 # CI runs without a terminal never prompt. CLI flags win over everything.
 PREFS_FILE="$_config_dir/install-prefs"
 CORE_SKILL_NAMES="plannotator-review plannotator-annotate plannotator-last"
-EXTRA_SKILL_NAMES="plannotator-compound plannotator-setup-goal plannotator-visual-explainer"
+EXTRA_SKILL_NAMES="plannotator-compound plannotator-setup-goal plannotator-visual-explainer plannotator-markup"
 
 saved_extras=""
 saved_invocable=""