vantage-md 0.7.1 → 0.8.1

package/dist/index.js

@@ -2,14 +2,14 @@ import { unified } from "unified";
 import remarkParse from "remark-parse";
 import remarkRehype from "remark-rehype";
 import rehypeStringify from "rehype-stringify";
-import remarkGfm from "remark-gfm";
-import remarkMath from "remark-math";
 import rehypeRaw from "rehype-raw";
 import rehypeSanitize, { defaultSchema } from "rehype-sanitize";
 import rehypeHighlight from "rehype-highlight";
 import rehypeKatex from "rehype-katex";
 import rehypeSlug from "rehype-slug";
 import { visit } from "unist-util-visit";
+import remarkGfm from "remark-gfm";
+import remarkMath from "remark-math";
 import YAML from "yaml";
 import { parse } from "smol-toml";
 //#region src/rehypeVantageAnchors.ts
@@ -124,6 +124,12 @@ const VANTAGE_ALERTS = [
 	"warning",
 	"caution"
 ];
+/**
+* The class on the title element this plugin injects, which
+* `styles/directives.css` styles. Exported because the sanitizer runs after
+* this plugin and admits a `div`'s class only when it is this one.
+*/
+const ALERT_TITLE_CLASS = "vantage-alert-title";
 /** The visible label per kind. Title case, as GitHub renders it. */
 const ALERT_TITLES = {
 	note: "Note",
@@ -147,7 +153,7 @@ const ALERT_TITLES = {
 * anchored test on the first text node is enough, and the plugin does not have
 * to reassemble the marker across siblings.
 */
-const MARKER = /^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\][ \t]*(?:\r?\n|$)/;
+const ALERT_MARKER = /^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\][ \t]*(?:\r?\n|$)/;
 /** The first child, if it is an element. */
 function firstElement(node) {
 	const child = node.children.find((c) => c.type === "element" || c.type === "text" && c.value.trim() !== "");
@@ -174,7 +180,7 @@ function rehypeVantageAlerts() {
 			if (paragraph === void 0 || paragraph.tagName !== "p") return;
 			const lead = paragraph.children[0];
 			if (lead === void 0 || lead.type !== "text") return;
-			const match = MARKER.exec(lead.value);
+			const match = ALERT_MARKER.exec(lead.value);
 			if (match === null) return;
 			const kind = match[1].toLowerCase();
 			lead.value = lead.value.slice(match[0].length);
@@ -186,7 +192,7 @@ function rehypeVantageAlerts() {
 			node.children.unshift({
 				type: "element",
 				tagName: "div",
-				properties: { className: ["vantage-alert-title"] },
+				properties: { className: [ALERT_TITLE_CLASS] },
 				children: [{
 					type: "text",
 					value: ALERT_TITLES[kind]
@@ -233,16 +239,78 @@ const VANTAGE_SENTINEL = "vantage:";
 *
 * Position picks the target; the name picks the extent. `section` before a
 * heading reaches the heading's whole section, `block` reaches one block, and
-* `oq` marks one answerable question. The name cannot disagree with position —
-* it only says how far the stamp reaches — so §4.2's refusal of a `scope=` key
-* stands.
+* `question` declares one question in any state, as `oq`, the name it
+* replaces, still does (`VANTAGE_QUESTION_NAMES`). The name cannot disagree
+* with position — it only says how far the stamp reaches — so §4.2's refusal
+* of a `scope=` key stands.
+*
+* `fallback` is the one name that stamps nothing: it withholds the block after
+* it, which is written for the renderers that cannot show something Vantage
+* shows — an inline `<svg>`, today. Every renderer that does not know the name
+* drops the comment and shows the block, a 0.7.x Vantage included, which is
+* the whole mechanism: the name is new, so no older reader gives it a meaning
+* (`docs/reference/inline-markup.md`, "Fallback blocks").
 */
 const DIRECTIVE_NAMES = [
 	"section",
 	"block",
-	"oq"
+	"oq",
+	"question",
+	"fallback"
 ];
 /**
+* The two names that declare a question: `question`, the one to write, and
+* `oq`, which it replaces and which every Vantage keeps reading.
+*
+* - **`question`** declares a question in any state: open (💬, 💬 🤷 or no
+*   marker at all), 🔒 blocked or ✅ answered. The state comes from the marker
+*   and never from the name, so a question that changes state changes its
+*   marker and nothing else. A viewer from 0.8 on offers Take this leaning on
+*   an open one, and never on a 🔒 or ✅ one.
+* - **`oq`** is deprecated, never removed. It keeps the meaning it shipped
+*   with in 0.7, an open question to answer in one click, because documents
+*   outlive releases and a release never gives existing notation a new
+*   meaning (`docs/design/checker-version-skew.md`, P0). Every viewer before
+*   0.8 offers the button on every `oq` it meets, whatever its marker says,
+*   so `vantage-check` reports one on a 🔒 or ✅ question as an error and any
+*   other as a warning that names the `question` to write.
+*
+* The two take the same keys, `id` and `leaning`, with one grammar. A viewer
+* that predates `question` drops it whole, as it drops every name it does not
+* know, so on a question written with it that viewer offers no button and no
+* anchor: it does less, and misreads nothing. A run holding both names is one
+* question, read as such a viewer reads it: where both set a key, the `oq`'s
+* value wins.
+*/
+const VANTAGE_QUESTION_NAMES = ["oq", "question"];
+/** Whether `name` declares a question, `question` or the deprecated `oq`. */
+function isQuestionDirective(name) {
+	return name === "oq" || name === "question";
+}
+/**
+* The attribute every question carries in the rendered page, whichever name
+* declared it, with the value `"true"`. It is how a reader of this package's
+* markup finds every question: `[data-vantage-question]`
+* (`VANTAGE_QUESTION_SELECTOR`).
+*/
+const VANTAGE_QUESTION_ATTRIBUTE = "data-vantage-question";
+/** `[data-vantage-question]`: every question in a rendered page. */
+const VANTAGE_QUESTION_SELECTOR = `[${VANTAGE_QUESTION_ATTRIBUTE}]`;
+/**
+* The attribute a question declared with `oq` carries besides
+* `VANTAGE_QUESTION_ATTRIBUTE`, with the value `"true"`. It means what it has
+* meant since 0.7, "declared with `oq`", and nothing more: whether a question
+* offers Take this leaning is read from its state (`questionOffersTake`),
+* never from this attribute.
+*/
+const VANTAGE_OQ_ATTRIBUTE = "data-vantage-oq";
+/**
+* The attribute that carries a question's `leaning=`, normalized
+* (`normalizeLeaning`), on the element `VANTAGE_QUESTION_ATTRIBUTE` is on,
+* whichever name declared it. Absent when the directive states none.
+*/
+const VANTAGE_LEANING_ATTRIBUTE = "data-vantage-leaning";
+/**
 * The `tone` vocabulary: GitHub's alert words plus `muted`.
 *
 * Semantic, never chromatic (P2, Ledger OQ-3). A document says what a section
@@ -334,13 +402,32 @@ const VANTAGE_STYLE_TARGETS = [
 	"div"
 ];
 /**
-* The tags an `oq` directive may stamp — strictly the tags the review system
-* can resolve an anchor on (`ANCHOR_TAGS` in the app's `MarkdownViewer`, and the
-* block map in `useReviewHighlights`). `ul`, `ol`, `tr`, `hr` and `div` are in
-* neither, so a button on one of them would build an anchor no review pass can
-* find — the "mis-wired button" D6 forbids.
+* The tags a `fallback` directive may **withhold**: `VANTAGE_STYLE_TARGETS`
+* minus the six headings, written as a subtraction so the narrowing stays
+* visible.
+*
+* A heading is refused because it is the document's structure rather than a
+* stand-in for anything: the contents column lists it, other documents link to
+* its slug, and the planning index reads sections under it. A fallback heading
+* would be an anchor that exists on GitHub and nowhere in Vantage. What a
+* fallback holds — a sentence naming the release a drawing needs, a link to
+* the drawing as a file, an ASCII sketch in a fence — is a paragraph, a list,
+* a quote, a code block, a table or a `<div>`, and those are all here.
 *
-* The gap between this list and `VANTAGE_STYLE_TARGETS` is why an `oq`
+* Three callers read it, and they must agree: `rehypeVantageDirectives`, which
+* withholds the block; the planning index's scan, which must not read a
+* question or a link from a block the page never shows; and the checker's
+* `vantage/orphan`, which reports a fallback that withholds nothing.
+*/
+const VANTAGE_FALLBACK_TARGETS = VANTAGE_STYLE_TARGETS.filter((tag) => !/^h[1-6]$/.test(tag));
+/**
+* The tags a question directive, `oq` or `question`, may stamp — strictly the
+* tags the review system can resolve an anchor on (`ANCHOR_TAGS` in the app's
+* `MarkdownViewer`, and the block map in `useReviewHighlights`). `ul`, `ol`,
+* `tr`, `hr` and `div` are in neither, so a button on one of them would build
+* an anchor no review pass can find — the "mis-wired button" D6 forbids.
+*
+* The gap between this list and `VANTAGE_STYLE_TARGETS` is why a question
 * directive at column 0 above a list silently does nothing: the target is the
 * `<ul>`, not the `<li>`. The checker says so.
 */
@@ -358,9 +445,11 @@ const VANTAGE_ANCHOR_TARGETS = [
 	"table"
 ];
 /**
-* The tags a `<!-- vantage: oq … -->` directive actually yields a *button* on —
-* `VANTAGE_ANCHOR_TARGETS` minus `pre` and `table`, written as an explicit
-* subtraction so the narrowing stays visible.
+* The tags a question directive declares a question on, and so the only ones
+* an open question's *button* can sit on — `VANTAGE_ANCHOR_TARGETS` minus `pre`
+* and `table`, written as an explicit subtraction so the narrowing stays
+* visible. One list for both names and every state, so a question that changes
+* state is declared in exactly the same place.
 *
 * Anchorable and button-hosting are different questions, and this is the second
 * one. A comment *can* be anchored on a `<pre>` or a `<table>` — both are in
@@ -368,17 +457,18 @@ const VANTAGE_ANCHOR_TARGETS = [
 * button renders as part of the code, and a `<button>` child of `<table>` is not
 * valid HTML at all, so the parser hoists it out.
 *
-* Both consumers read it from here: `OQ_HOST_TAGS` in the app's
-* `useOpenQuestionButtons`, and the `oq` branch of the checker's
-* `vantage/orphan`. They were two hand-written lists that disagreed — the
-* checker called an `oq` above a fence fine while the app rendered no button
-* and said nothing, which is the D5 break this module exists to prevent.
+* Every consumer reads it from here: `OQ_HOST_TAGS` in the app's
+* `useOpenQuestionButtons`, the planning index's scan, and the question branch
+* of the checker's `vantage/orphan`. They were two hand-written lists that
+* disagreed — the checker called an `oq` above a fence fine while the app
+* rendered no button and said nothing, which is the D5 break this module
+* exists to prevent.
 */
 const VANTAGE_OQ_HOST_TARGETS = VANTAGE_ANCHOR_TARGETS.filter((tag) => tag !== "pre" && tag !== "table");
 /**
-* The shape of an `oq` directive's `id`: `OQ-` then an optional short uppercase
-* prefix then digits. `OQ-9`, `OQ-TP6` and `OQ-A03` are ids; `OQ-foo`, `OQ-tp6`
-* and a bare `OQ6` are not.
+* The shape of a question directive's `id`, on `oq` and `question` alike:
+* `OQ-` then an optional short uppercase prefix then digits. `OQ-9`, `OQ-TP6`
+* and `OQ-A03` are ids; `OQ-foo`, `OQ-tp6` and a bare `OQ6` are not.
 *
 * The prefix is what keeps ids distinct once one document references another's
 * questions — `trust-paths.md`'s `OQ-4` and a design sketch's `OQ-4` are
@@ -386,10 +476,15 @@ const VANTAGE_OQ_HOST_TARGETS = VANTAGE_ANCHOR_TARGETS.filter((tag) => tag !== "
 * reference means. It is optional because most documents never leave their own
 * file, and requiring it everywhere would fire on every single-doc sketch.
 *
-* Three consumers read it from here and none of them may re-spell it: the
-* plugin that stamps the anchor, the sanitizer that allowlists the value, and
-* the checker's `vantage/oq-id-format`. A fourth copy is how the checker starts
-* calling a working anchor malformed.
+* Read from here, never re-spelled, by the sanitizer that allowlists the value,
+* by the checker's `collectOqIds` (which feeds `vantage/oq-id-format` and the
+* anchors the checker accepts) and by the planning index. The directive plugin
+* that stamps the anchor deliberately does not test it: it stamps any non-empty
+* id and leaves refusing a malformed one to the sanitizer. A re-spelled copy is
+* how the checker starts calling a working anchor malformed — and the patterns
+* that look for an id in text (`OQ_REFERENCE` and `OQ_EXACT` in the checker's
+* `rules/references.ts`, `OQ_TOKEN` in `planning/scan.ts` and in
+* `FrontmatterDisplay.tsx`) restate this shape, so they change with it.
 */
 const VANTAGE_OQ_ID = /^OQ-(?:[A-Z][A-Z0-9]{0,5})?[0-9]+$/;
 /**
@@ -405,11 +500,12 @@ const VANTAGE_OQ_ID = /^OQ-(?:[A-Z][A-Z0-9]{0,5})?[0-9]+$/;
 * that a screen reader can say. They were private constants in the checker until
 * the second consumer arrived.
 *
-* `open` is the only state that wants a one-click answer. `settled` and
-* `blocked` deliberately carry no directive at all — a control offering to
-* answer a question that is already decided, or that cannot be answered yet, is
-* a lie — so the checker keys on the distinction rather than on the word
-* "Leaning:" alone. Either non-open marker wins when both appear on one item.
+* `open` is the only state that wants a one-click answer, so it is the only one
+* a viewer offers Take this leaning on (`questionOffersTake`). A `settled` or
+* `blocked` question carries no control — a control offering to answer a
+* question that is already decided, or that cannot be answered yet, is a lie.
+* The checker keys on the distinction rather than on the word "Leaning:"
+* alone. Either non-open marker wins when both appear on one item.
 */
 const VANTAGE_OQ_STATUS = {
 	/** 💬 — an active decision awaiting a ruling. */
@@ -444,6 +540,20 @@ function vantageOqStatus(text) {
 	if (text.includes(VANTAGE_OQ_STATUS.open)) return "open";
 	return null;
 }
+/**
+* Whether a question in this state offers Take this leaning in review mode: an
+* open one, marked 💬 or 💬 🤷, or one carrying no marker, which counts as
+* open. A 🔒 question cannot be answered yet and a ✅ one has been ruled, so
+* neither has a leaning left to take, whatever its directive's name.
+*
+* One home for the rule, because every surface that answers it must agree:
+* the page's button and the planning card, the counts of questions waiting on
+* a human, and `vantage-check`, which reports an `oq` on a question this says
+* no to, since every viewer before 0.8 offers the button there anyway.
+*/
+function questionOffersTake(status) {
+	return status === null || status === "open";
+}
 const STYLE_KEYS = {
 	tone: VANTAGE_TONES,
 	emphasis: VANTAGE_EMPHASIS,
@@ -454,10 +564,21 @@ const STYLE_KEYS = {
 * Name → key → the closed value set for that key.
 *
 * `section` and `block` share their keys: they differ in *extent*, not in what
-* they can say. `oq`'s two keys are the design's only values with no closed set
-* — `id` is a token an author chose and `leaning` is a sentence (§8.3) — so
-* neither can be value-allowlisted, which is recorded here as `null` rather
-* than left to a caller to guess.
+* they can say. The two question names share theirs too, and they are the
+* design's only values with no closed set — `id` is a token an author chose
+* and `leaning` is a sentence (§8.3) — so neither can be value-allowlisted,
+* which is recorded here as `null` rather than left to a caller to guess.
+*
+* `question` takes exactly `oq`'s keys and nothing more. Starting narrow is
+* the forward-compatible choice: a key added later is one older viewers drop
+* pair by pair, while a key accepted now could never be given a meaning (P0).
+* A `leaning` on a 🔒 or ✅ question is allowed and simply not offered
+* (`questionOffersTake`), so changing a question's state changes only its
+* marker.
+*
+* `fallback` takes no keys: whether a block is withheld is the whole of what
+* it says, and a key added later is dropped pair by pair by this release, as
+* D2 drops any other.
 */
 const DIRECTIVE_VOCABULARY = {
 	section: STYLE_KEYS,
@@ -465,9 +586,59 @@ const DIRECTIVE_VOCABULARY = {
 	oq: {
 		id: null,
 		leaning: null
-	}
+	},
+	question: {
+		id: null,
+		leaning: null
+	},
+	fallback: {}
 };
 /**
+* Merge the question directives of one run — the comments up to the block they
+* land on — into the one question they declare, or `undefined` when the run
+* holds none. Directives of any other name are skipped.
+*
+* A run holding an `oq` is read exactly as a viewer that predates `question`
+* reads it: that viewer drops every `question` and reads the `oq` alone, so
+* the `oq` wins wherever it appears in the run, and only its keys apply — a
+* key only a `question` in the same run sets applies nowhere, in no release.
+* That is the one reading every viewer agrees on (`VANTAGE_QUESTION_NAMES`),
+* so the same bytes file the same Take in 0.7 and in 0.8. Within one name, the
+* last value of a key wins, as `section` and `block` resolve theirs. A pair
+* its name does not accept, or a value outside a closed set, is dropped (D2).
+*
+* One function for every reader of a run: the plugin that stamps the question
+* and the planning index that reads it, which the checker reads a question
+* through, so none can disagree about which leaning or which id a run carries
+* (D5).
+*/
+function mergeQuestionRun(run) {
+	let name;
+	for (const directive of run) {
+		if (!isQuestionDirective(directive.name)) continue;
+		if (name !== "oq") name = directive.name;
+	}
+	if (name === void 0) return void 0;
+	const accepted = DIRECTIVE_VOCABULARY[name] ?? {};
+	const keys = /* @__PURE__ */ new Map();
+	const sources = /* @__PURE__ */ new Map();
+	run.forEach((directive, index) => {
+		if (directive.name !== name) return;
+		for (const pair of directive.pairs) {
+			const values = accepted[pair.key];
+			if (values === void 0) continue;
+			if (values !== null && !values.includes(pair.value)) continue;
+			keys.set(pair.key, pair.value);
+			sources.set(pair.key, index);
+		}
+	});
+	return {
+		name,
+		keys,
+		sources
+	};
+}
+/**
 * `ws` is `[ \t\r\n]` — the design's grammar leaves it undefined, and `\n` has
 * to be in the set because a directive may legally wrap: a multi-line comment
 * is one node whose value contains the newlines.
@@ -583,10 +754,24 @@ function parseVantageDirective(comment) {
 		pairs
 	};
 }
+/**
+* A question directive's `leaning=` value as the page carries it: whitespace
+* runs collapsed to one space, trimmed, and capped at `MAX_LEANING`.
+*
+* A wrapped directive puts newlines and indentation into the value. Two readers
+* need the result and must agree on it: `rehypeVantageDirectives`, which stamps
+* it as `data-vantage-leaning` for the one-click answer, and the planning index,
+* which reports the leaning a question carries. An empty result means the
+* question states no leaning.
+*/
+function normalizeLeaning(raw) {
+	return raw.replace(/\s+/g, " ").trim().slice(0, 500);
+}
 //#endregion
 //#region src/rehypeVantageDirectives.ts
 /**
-* What a `section`/`block` and an `oq` directive may **target**.
+* What a `section`/`block` and a question directive (`oq`, `question`) may
+* **target**.
 *
 * Both lists live in `vantageDirectives.ts`, with the reasoning for each tag,
 * because the CLI checker resolves the same question over mdast and must reach
@@ -596,6 +781,8 @@ function parseVantageDirective(comment) {
 */
 const STYLE_TARGET_TAGS = new Set(VANTAGE_STYLE_TARGETS);
 const ANCHOR_TARGET_TAGS = new Set(VANTAGE_ANCHOR_TARGETS);
+/** What a `fallback` may withhold: every style target but a heading. */
+const FALLBACK_TARGET_TAGS = new Set(VANTAGE_FALLBACK_TARGETS);
 const HEADING_DEPTHS = /* @__PURE__ */ new Map([
 	["h1", 1],
 	["h2", 2],
@@ -636,6 +823,19 @@ const RANGE_PROPERTIES = /* @__PURE__ */ new Map([["tone", "dataVantageTone"], [
 */
 const POINT_PROPERTIES = /* @__PURE__ */ new Map([["badge", "dataVantageBadge"]]);
 const RUN_PROPERTY = "dataVantageRun";
+/**
+* What a question stamps, whichever name declared it: `data-vantage-question`
+* on every question, and `data-vantage-oq` besides on one an `oq` declared
+* (`VANTAGE_QUESTION_ATTRIBUTE`, `VANTAGE_OQ_ATTRIBUTE`).
+*
+* Two attributes, and neither one ever means more than it says. Every release
+* since 0.7 stamps `data-vantage-oq` on an `oq` and on nothing else, so a
+* reader of this package's markup that has ever read it keeps reading exactly
+* what it read; `data-vantage-question` is the one to read for "a question",
+* and the question's state, from its marker, is what decides whether anything
+* offers to answer it (`questionOffersTake`).
+*/
+const QUESTION_PROPERTY = "dataVantageQuestion";
 const OQ_PROPERTY = "dataVantageOq";
 const LEANING_PROPERTY = "dataVantageLeaning";
 /**
@@ -670,8 +870,6 @@ const OQ_ID_PROPERTY = "dataVantageOqId";
 const COLLAPSED_PROPERTY = "dataVantageCollapsed";
 const COLLAPSE_GROUP_PROPERTY = "dataVantageCollapseGroup";
 const COLLAPSE_TOGGLE_PROPERTY = "dataVantageCollapseToggle";
-/** A review-comment body, not prose. Bounds the attribute; 500 is generous. */
-const MAX_LEANING = 500;
 /**
 * Nodes that may sit between a directive and its target.
 *
@@ -805,13 +1003,14 @@ function stampStyle(children, targetIndex, name, pairs, state) {
 		}
 	}
 }
-function stampOq(target, pairs) {
-	setProperty(target, OQ_PROPERTY, "true");
+function stampQuestion(target, name, pairs) {
+	setProperty(target, QUESTION_PROPERTY, "true");
+	if (name === "oq") setProperty(target, OQ_PROPERTY, "true");
 	const id = pairs.get("id");
 	if (id !== void 0 && id !== "") setProperty(target, OQ_ID_PROPERTY, id);
 	const leaning = pairs.get("leaning");
 	if (leaning === void 0) return;
-	const text = leaning.replace(/\s+/g, " ").trim().slice(0, MAX_LEANING);
+	const text = normalizeLeaning(leaning);
 	if (text !== "") setProperty(target, LEANING_PROPERTY, text);
 }
 /**
@@ -826,18 +1025,14 @@ function stampOq(target, pairs) {
 function stampRun(children, targetIndex, run, state) {
 	const target = children[targetIndex];
 	const style = /* @__PURE__ */ new Map();
-	const oq = /* @__PURE__ */ new Map();
 	let styleName;
-	let hasOq = false;
 	for (const directive of run) if (directive.name === "section" || directive.name === "block") {
 		styleName = directive.name;
 		for (const pair of directive.pairs) style.set(pair.key, pair.value);
-	} else if (directive.name === "oq") {
-		hasOq = true;
-		for (const pair of directive.pairs) oq.set(pair.key, pair.value);
 	}
 	if (styleName !== void 0) stampStyle(children, targetIndex, styleName, style, state);
-	if (hasOq && ANCHOR_TARGET_TAGS.has(target.tagName)) stampOq(target, oq);
+	const question = mergeQuestionRun(run);
+	if (question !== void 0 && ANCHOR_TARGET_TAGS.has(target.tagName)) stampQuestion(target, question.name, question.keys);
 }
 /** A directive comment, or `undefined` for anything else — malformed included. */
 function directiveOf(node) {
@@ -850,7 +1045,7 @@ function directiveOf(node) {
 *
 * The whole tree, not just the root: `rehype-raw` leaves comment nodes inside
 * `blockquote`, inside `li`, inside `td` and inline inside `p`, and the real
-* Open Questions layout puts the `oq` directive inside a list item — so a
+* Open Questions layout puts the question directive inside a list item — so a
 * root-only walk finds none of them.
 *
 * Pass order is also what resolves a nested section: an inner heading's
@@ -889,8 +1084,66 @@ function processChildren(parent, state) {
 		i = j;
 	}
 }
+/**
+* Remove every block a `fallback` run lands on, with the run itself.
+*
+* A fallback block is written for the renderers that cannot show something
+* Vantage shows — "This drawing needs Vantage 0.8 or later", beside an inline
+* `<svg>`. Every renderer that does not know the name drops the comment and
+* shows the block; this one never renders it, in any mode, in print, or
+* through any of the renderers that share this plugin (D5).
+*
+* The run is found exactly as `processChildren` finds one — the same skip
+* rules, the same first-element target, the same whole-tree walk — and it
+* withholds when any directive in it is a `fallback` and the target is on
+* `VANTAGE_FALLBACK_TARGETS`. Anything else is left for the stamping pass,
+* where a `fallback` is inert.
+*
+* A pass of its own, and first, because a `section` reaches *forward* over its
+* siblings: stamped in one pass, a toned section would count a fallback block
+* after it among its members, give it the run's last `end` marker, and leave
+* the last block anyone sees marked `middle`. Withheld first, the block was
+* never there for any later decision — the section's extent, its run markers,
+* a collapse group's members, a review anchor or an outline entry.
+*/
+function withholdFallbacks(parent) {
+	const children = parent.children;
+	let i = 0;
+	while (i < children.length) {
+		const node = children[i];
+		if (node.type === "element") {
+			withholdFallbacks(node);
+			i++;
+			continue;
+		}
+		const first = directiveOf(node);
+		if (first === void 0) {
+			i++;
+			continue;
+		}
+		let withholds = first.name === "fallback";
+		let j = i + 1;
+		let targetIndex = -1;
+		for (; j < children.length; j++) {
+			const next = children[j];
+			if (next.type === "element") {
+				targetIndex = j;
+				break;
+			}
+			if (!isSkippable(next)) break;
+			if (directiveOf(next)?.name === "fallback") withholds = true;
+		}
+		const target = targetIndex >= 0 ? children[targetIndex] : void 0;
+		if (withholds && target?.type === "element" && FALLBACK_TARGET_TAGS.has(target.tagName)) {
+			children.splice(i, targetIndex - i + 1);
+			continue;
+		}
+		i = j;
+	}
+}
 const rehypeVantageDirectives = () => {
 	return (tree) => {
+		withholdFallbacks(tree);
 		processChildren(tree, { nextGroup: 1 });
 	};
 };
@@ -983,12 +1236,144 @@ const rehypeRestoreMathStamps = () => {
 };
 //#endregion
 //#region src/sanitize.ts
+/** Whether an attribute definition is for `className`. */
+const isClassName = (definition) => (typeof definition === "string" ? definition : definition[0]) === "className";
 /**
-* Sanitization schema for the rendering pipeline.
-* Allows GFM, KaTeX MathML, syntax highlighting classes, and
-* data-source-line attributes while blocking XSS vectors.
+* The value list the default schema gives `className` on `tag`, or an empty
+* list if it gives none.
 */
-const DECLARATION = `(?:(?:${[
+function defaultClasses(tag) {
+	const entry = defaultSchema.attributes?.[tag]?.find(isClassName);
+	return Array.isArray(entry) ? entry.slice(1) : [];
+}
+/**
+* The only classes an element keeps: the ones the pipeline itself emits on it
+* before `rehypeSanitize` runs. Every other element keeps none.
+*
+* **A class is a style by another name.** The app ships Tailwind's utility CSS
+* for its own markup, so `<div class="fixed inset-0 z-50 bg-white">` in a
+* document laid a white sheet over the whole Vantage window, header and
+* sidebar included. That is the overlay `SAFE_STYLE` bans `position` to
+* prevent, spelled as a class instead of a declaration, and `className` used
+* to be admitted with any value on every element. A document could also
+* borrow a class the app's own code looks for: `.overflow-y-auto` is how an
+* anchor link finds the element to scroll when no `data-content-scroll` is in
+* reach, and `.heading-anchor` is what the outline strips from a heading's
+* text. The comment-body sanitizer (`frontend/src/lib/commentMarkdown.ts`)
+* already refused `class` for the same reason.
+*
+* What each entry is for, and who emits it:
+*
+* - `code`: `language-*`, from a fence's info string (`mdast-util-to-hast`).
+*   `rehype-highlight` reads it, `rehype-katex` keys on `language-math`, and
+*   the viewers render `language-mermaid` as a diagram.
+* - `ul`, `ol` and `li`: `contains-task-list` and `task-list-item`, from GFM
+*   task lists. `styles/task-list.css` draws the checkbox from them.
+* - `section`, `h2` and `a`: GFM footnotes (`mdast-util-to-hast`), on the
+*   section, its label and each back-reference.
+* - `div`: `ALERT_TITLE_CLASS`, on the title `rehypeVantageAlerts` injects.
+*
+* `remark-math` also emits `math-display` and `math-inline` on its `code`.
+* They were never kept, because the default schema's `code` entry takes only
+* `language-*`, and nothing needs them: `rehype-katex` keys on `language-math`
+* and tells display from inline by whether the `code` sits in a `pre`.
+*
+* **A class added after the sanitizer needs no entry**, and that is most of
+* the classes the page styles: `rehype-highlight`'s `hljs-*`, KaTeX's output,
+* Mermaid's diagrams, and everything the app's components and hooks add. A
+* document that writes one of those on an element keeps nothing.
+*
+* **Mermaid source is the route this list cannot close.** Mermaid renders
+* after the sanitizer and copies the names a diagram's source gives a node
+* (`:::name`, `class A name`, `classDef`) onto that node, so a diagram can
+* carry any of the app's utilities on its own nodes. The diagram bounds it:
+* `position` does nothing on an SVG group, and the diagram's `svg` clips what
+* is inside it. `frontend/e2e/mermaid.spec.ts` measures that bound. The
+* stylesheet a diagram's source could write did reach past the diagram, and
+* `MERMAID_SECURE_KEYS` in `mermaidLoader.ts` refuses the settings that write
+* it.
+*
+* A document may still write these names on these elements. By the time the
+* sanitizer runs, a hand-written `<li class="task-list-item">` and the one GFM
+* emitted are the same node, and none of the names can lay an element over
+* anything outside the document's scroll container. `styles/task-list.css`
+* floats the checkbox of a `task-list-item` instead of positioning it
+* absolutely, so it stays in the document's flow whatever the item's own
+* `style` does, and the checkbox takes no `style` itself (see
+* `UNSTYLED_TAGS`). The footnote label's class, where a stylesheet defines it,
+* clips its element to a single pixel.
+*
+* **The footnote label's class is read from the default schema, never
+* spelled here, and the tests spell it in halves.** It is a Tailwind utility,
+* and Tailwind generates a utility for every class name it finds in the files
+* it scans, comments included — this directory and all of `frontend/`. The app
+* renders the label as a visible heading only because nothing it scans spells
+* that name. Spelled whole in a test, it generated the rule, and the label
+* would have been hidden from sight as it is on GitHub: a change of rendering,
+* not a sanitizer fix.
+*
+* The list is measured, not remembered. The test "takes no class from
+* anything the pipeline emits" in `frontend/src/lib/sanitize.test.ts` records
+* every class on the tree on both sides of `rehypeSanitize`, over a document
+* that uses every feature that emits one, so a plugin that starts emitting a
+* new class fails there instead of losing it in every renderer.
+*/
+const PIPELINE_CLASSES = {
+	code: [/^language-./],
+	ul: ["contains-task-list"],
+	ol: ["contains-task-list"],
+	li: ["task-list-item"],
+	section: ["footnotes"],
+	h2: defaultClasses("h2"),
+	a: ["data-footnote-backref"],
+	div: [ALERT_TITLE_CLASS]
+};
+/**
+* `tag`'s attributes: the default schema's, less any `className`, then its
+* `PIPELINE_CLASSES` entry, then `extra`.
+*
+* **Always a value list, never a bare `"className"`.** `hast-util-sanitize`
+* reads a bare name, or a tuple holding no values, as "any value", and an
+* element's own entry is consulted before `*`'s — the first match wins, and
+* `*` is not consulted when that element's own entry filters a class list down
+* to nothing. An element with no entry has none added.
+*/
+function withClasses(tag, ...extra) {
+	const classes = PIPELINE_CLASSES[tag] ?? [];
+	const own = (defaultSchema.attributes?.[tag] ?? []).filter((definition) => !isClassName(definition));
+	if (classes.length > 0) own.push(["className", ...classes]);
+	return [...own, ...extra];
+}
+/**
+* CSS properties an inline `style` may set.
+*
+* **The only `style` this list ever filters is one a document wrote by hand.**
+* Nothing the pipeline generates reaches it: `rehypeKatex` and `rehypeHighlight`
+* both run *after* `rehypeSanitize` (`pipeline.ts`), so their output is trusted
+* rather than filtered, and `remark-gfm` emits table alignment as an `align`
+* attribute rather than as CSS. So this is a filter on untrusted author HTML and
+* nothing else — which is exactly the hole that made it necessary: `<div
+* style="position:fixed;inset:0">` covered the viewport and
+* `style="background:url(https://…)"` called home on render, both verbatim,
+* because `rehype-sanitize` does not parse CSS. Scripts were never the risk
+* here; layout and network were.
+*
+* The list is therefore deliberately typographic: the styling a prose document
+* has any business asking for. It is *not* sized to KaTeX, and a KaTeX release
+* that starts using a new property is a non-event here — `\pmb` already emits
+* `text-shadow`, which is not on this list and renders anyway.
+*
+* **The design doc used to argue the opposite — that `style` had to be allowed
+* and `position` enumerated because KaTeX needs them — and it was wrong.** The
+* measurement behind it was real (KaTeX does emit `position:relative` on every
+* integral) but the inference was not, because the sanitizer has finished before
+* the first KaTeX span exists. Rebuilding the shipped rehype order with a filter
+* that rejects *every* value leaves all ten of the integral's style attributes
+* untouched. The "Security" section of `docs/reference/inline-markup.md`
+* records the correction; the test that would catch a reordering is in
+* `frontend/src/lib/sanitize.test.ts`.
+*/
+const SAFE_STYLE_PROPERTIES = [
 	"height",
 	"min-height",
 	"max-height",
@@ -1043,12 +1428,89 @@ const DECLARATION = `(?:(?:${[
 	"white-space",
 	"vertical-align",
 	"list-style-type",
-	"display",
 	"float",
 	"clear",
 	"opacity",
 	"overflow"
-].join("|")})\\s*:[^;:()"'\\\\]*)`;
+];
+/**
+* A `style` value we will keep, as a whole.
+*
+* One rule beyond the property list does the work: **no parentheses anywhere**,
+* which closes `url(…)` and `expression(…)` in one stroke — the network and
+* legacy-script vectors. Its cost is borne entirely by authors, who lose
+* `calc()`, `rgb()` and `var()` along with them; that is the trade, and it is
+* worth it for a filter this small.
+*
+* **`position` is not on the property list at all**, so every value of it is
+* refused — `static` and `relative` along with `fixed` and `sticky`. It used to
+* be enumerated, on the belief that KaTeX needed `relative`; KaTeX renders after
+* the sanitizer and never meets this regex, so the enumeration was buying
+* nothing but the residual it conceded. Banning the property closes that
+* residual, and it is bigger than "overlaps its neighbors" made it sound:
+* measured in Chrome against the viewer's real ancestor chain, an author's
+* `position:absolute;top:0;left:0;width:100%;height:100%` is sized to the whole
+* content pane (the nearest positioned ancestor is outside the scroll
+* container), is not clipped by the scroller, and survives scrolling to the end
+* of the document. It was `position:fixed` in all but the keyword.
+*
+* Matching is all-or-nothing: one unrecognized declaration drops the whole
+* attribute, and the element renders unstyled rather than partly styled. That
+* is the safe direction to fail, and it degrades to plain text rather than to a
+* broken page.
+*
+* **The grammar must stay unambiguous, and `;` is what keeps it so.** The value
+* class is "anything but the delimiters", which includes whitespace — a value
+* legitimately contains it (`margin: 0 auto`). So if whitespace could *also*
+* end a declaration, both constructs would compete for the same characters and
+* the match would fork at every declaration; on a value that ultimately fails,
+* the engine explores every fork. An earlier form of this regex separated
+* declarations with `\s*;?\s*`, and 200 document-controlled characters took the
+* renderer — and the CLI checker, and therefore CI — 94 seconds. Requiring `;`
+* pins each declaration's extent to the delimiter positions, so there is exactly
+* one way to parse any input and rejection is linear. `VALUE` absorbs the
+* padding on both sides for the same reason: a separate `\\s*` next to it would
+* put the ambiguity straight back. Pinned by the flat-time test in
+* `frontend/src/lib/sanitize.test.ts` — do not loosen the separator.
+*
+* Residual, stated plainly and now genuinely small: negative `margin` still lets
+* an element overlap its neighbors *inside the flow*. That one scrolls with the
+* content and is clipped by the scroll container, and closing it means giving up
+* margins, which prose actually uses. Containment in the stylesheet, not another
+* rule here, is what would close it. `overflow: visible` on an inline `<svg>` is
+* the same residual by another route — see `SVG_ROOT_ATTRIBUTES`.
+*
+* **The app's table of contents is inside that scroll container too**, beside
+* the document column, so a block carried over it took its clicks whenever the
+* block painted in the positioned layer: one with `opacity`, a toned block, a
+* heading, or a link to anywhere. The contents sit at `z-10` for that
+* (`frontend/src/components/TableOfContents.tsx`), and a document cannot climb
+* back over them only because `z-index` is not on the property list.
+*/
+const VALUE = `[^;:()"'\\\\]*`;
+const DISPLAY_DECLARATION = `display\\s*:\\s*(?:${[
+	"none",
+	"block",
+	"inline-block",
+	"inline-flex",
+	"inline-grid",
+	"inline-table",
+	"inline",
+	"flow-root",
+	"flex",
+	"grid",
+	"table-row-group",
+	"table-row",
+	"table-header-group",
+	"table-footer-group",
+	"table-cell",
+	"table-column-group",
+	"table-column",
+	"table-caption",
+	"table",
+	"list-item"
+].join("|")})\\s*(?:!\\s*important\\s*)?`;
+const DECLARATION = `(?:(?:${SAFE_STYLE_PROPERTIES.join("|")})\\s*:${VALUE}|${DISPLAY_DECLARATION})`;
 const SAFE_STYLE = new RegExp(`^\\s*(?:${DECLARATION};\\s*)*${DECLARATION}?$`, "i");
 /**
 * A collapse group id: one or more digits, anchored.
@@ -1060,6 +1522,281 @@ const SAFE_STYLE = new RegExp(`^\\s*(?:${DECLARATION};\\s*)*${DECLARATION}?$`, "
 */
 const COLLAPSE_GROUP_ID = /^[0-9]+$/;
 /**
+* Inline SVG, admitted as static drawing and nothing else.
+*
+* The allowlist is shapes, text and grouping. Everything in SVG that can run
+* code, fetch, or reach outside the element is refused: `script`,
+* `foreignObject`, `use` and `image` (both take an `href`), `xlink:href` on
+* `a`, the `animate`/`set` family (which can rewrite an `href` after the
+* sanitizer has looked), `style` elements, and every attribute that takes a
+* `url(…)` reference — `filter`, `mask`, `clip-path`, `marker-*`, `cursor`.
+*
+* Gradients, patterns and `<defs>` are out for a second reason: they are only
+* reachable through `url(#id)`, and the sanitizer prefixes every `id` with
+* `user-content-`, so the reference would dangle even if it were allowed.
+*
+* **Refusing an element is not the same as removing it.** `hast-util-sanitize`
+* *unwraps* an element it does not allow — drops the tag and keeps its
+* children — unless the tag is on `strip`. See `SVG_STRIPPED` for why that
+* matters here, and for the pass that removes those containers instead.
+*
+* `switch` is admitted, as a plain container, because draw.io wraps every label
+* in one: `<switch><foreignObject>…</foreignObject><text>…</text></switch>`. A
+* `switch` renders only its first child whose conditions hold, and with the
+* `foreignObject` removed and the conditional attributes (`requiredFeatures`,
+* `systemLanguage`) refused, that is the `<text>` fallback. Unwrapped instead,
+* it would render *every* branch — including the "Text is not SVG - cannot
+* display" notice draw.io appends for viewers without `foreignObject`.
+*
+* Every child requires an `svg` ancestor, so no shape or text element is
+* admitted into HTML flow on its own.
+*
+* `title` and `desc` are not children at all. They are admitted nowhere, inside
+* a drawing they are removed with their contents (see `SVG_STRIPPED`), and
+* `aria-label` on the root is the drawing's accessible name. Both are HTML
+* integration points — the parser reads what is inside them as HTML — and an
+* `svg` ancestor turned out not to be enough to keep a `<title>` in SVG
+* context. `<math><svg><title>` keeps MathML context, and React hoists any
+* `title` outside SVG context into the page's `<head>`, so the document set the
+* tab title. In `renderMarkdown`'s string output, `<svg><desc><title>`,
+* `<svg><title><title>` and a `title` inside a `foreignObject` all re-parse into
+* an HTML `title`, which is what `document.title` reads on a page that has none
+* of its own.
+*/
+const SVG_CHILD_TAGS = [
+	"g",
+	"path",
+	"rect",
+	"circle",
+	"ellipse",
+	"line",
+	"polyline",
+	"polygon",
+	"text",
+	"tspan",
+	"switch"
+];
+/**
+* Refused SVG elements removed *with their contents* when they sit inside an
+* `<svg>`, rather than unwrapped.
+*
+* Each of these holds children that are never meant to be painted where they
+* stand: a clip region, a mask, a gradient's stops, a marker's arrowhead, a
+* symbol's body, a filter's primitives, an exporter's RDF, the text of a
+* `title` or `desc` (see `SVG_CHILD_TAGS`), or — for `foreignObject` — HTML.
+* Unwrapped, those children land in the drawing as ordinary shapes. A default
+* Figma export ends in `<defs><clipPath><rect fill="white"/>`, and unwrapping
+* it painted that white rect over the whole drawing; a `<marker>` arrowhead
+* became a stray triangle at the origin. The HTML inside a `foreignObject`
+* survived as descendants of `svg`, which React then created as invisible
+* SVG-namespace `div`s and `p`s — the anchor an Open Question button looks for
+* — and which a browser re-parsing `renderMarkdown`'s string output breaks out
+* of the `svg` at, spilling the rest of the drawing into the page.
+*
+* **Only inside an `<svg>`, which is why this is a pass and not the schema's
+* `strip`.** `strip` removes a tag wherever it stands, and most of these names
+* are lowercase in prose too. There a bare `<pattern>` on a line of its own is
+* an HTML element nothing closes, so every Markdown block after it was parsed
+* into it, and stripping it removed the rest of the document — in every
+* renderer, with `vantage-check` silent. Inside a drawing the same container is
+* bounded by the `svg`, because a Markdown paragraph or heading breaks out of
+* SVG. Outside one the sanitizer unwraps these like any tag it does not know:
+* `title` and `desc` are not admitted anywhere, so no `title` element survives
+* to be hoisted, and what they held is text or ordinary sanitized HTML.
+*
+* Names compare case-insensitively. The camel-cased ones are how the HTML
+* parser spells these elements in SVG, but under `<math><svg>` the parser stays
+* in MathML and leaves them lowercase.
+*/
+const SVG_STRIPPED = [
+	"foreignObject",
+	"defs",
+	"clipPath",
+	"mask",
+	"pattern",
+	"marker",
+	"symbol",
+	"linearGradient",
+	"radialGradient",
+	"filter",
+	"metadata",
+	"title",
+	"desc"
+];
+const SVG_STRIPPED_NAMES = new Set(SVG_STRIPPED.map((name) => name.toLowerCase()));
+/**
+* The camel-cased `SVG_STRIPPED` names, which the schema strips on its own.
+*
+* Only an SVG-namespace element carries one of these spellings, so stripping
+* them everywhere costs prose nothing. It keeps the worst of the list — the
+* HTML inside a `foreignObject` — out of a drawing for a consumer who hands
+* `sanitizeSchema` to `rehype-sanitize` without the rest of `buildPipeline`.
+*/
+const SVG_STRIPPED_EVERYWHERE = SVG_STRIPPED.filter((name) => name !== name.toLowerCase());
+function stripSvgContainers(parent, inSvg) {
+	if (inSvg) parent.children = parent.children.filter((child) => child.type !== "element" || !SVG_STRIPPED_NAMES.has(child.tagName.toLowerCase()));
+	for (const child of parent.children) if (child.type === "element") stripSvgContainers(child, inSvg || child.tagName.toLowerCase() === "svg");
+}
+/**
+* Remove every `SVG_STRIPPED` element below an `svg`, with its contents.
+*
+* Runs immediately before `rehypeSanitize` (`pipeline.ts`), and only when the
+* pipeline sanitizes: with the sanitizer off these elements are left to work
+* as SVG defines them.
+*/
+function rehypeStripSvgContainers() {
+	return (tree) => {
+		stripSvgContainers(tree, false);
+	};
+}
+/**
+* A paint value: a keyword, a named color, or a hex color. No parentheses, for
+* the same reason `SAFE_STYLE` refuses them — `fill="url(https://…)"` is a
+* render-time fetch, and `rgb()` is the price of closing it.
+*/
+const SVG_PAINT = /^(?:#[0-9a-f]{3,8}|[a-z]+)$/i;
+/**
+* Attributes any SVG element may carry, drawing and typography alike.
+*
+* **Each entry is a hast property name, which is not always the camel case of
+* the attribute.** `property-information` decides the spelling, and it has
+* `strokeLineCap` for `stroke-linecap` — a naive `strokeLinecap` matches
+* nothing, and the attribute is dropped in every renderer without a word. The
+* table-driven test in `frontend/src/lib/sanitize.test.ts` renders every entry
+* in its written spelling, so a misspelled one fails there.
+*
+* `stroke-dasharray` (and with it `stroke-dashoffset`, which does nothing
+* alone) is refused, because it lets a few bytes buy an unbounded paint. The
+* number of dashes is the path's length over the dash period, both in user
+* units the document chooses. Measured in headless Chromium, fifty 90-byte
+* paths with a 0.0011 dash took 21 s to paint and a hundred took 37 s. A value
+* grammar cannot bound it: refusing sub-unit dashes is undone by scaling the
+* user units, and the same fifty paths with `stroke-dasharray="1.1"` under a
+* `viewBox` a thousand times larger still took 15 s.
+*/
+const SVG_ATTRIBUTES = [
+	["fill", SVG_PAINT],
+	["stroke", SVG_PAINT],
+	"fillOpacity",
+	"fillRule",
+	"strokeOpacity",
+	"strokeWidth",
+	"strokeLineCap",
+	"strokeLineJoin",
+	"opacity",
+	"transform",
+	"fontFamily",
+	"fontSize",
+	"fontWeight",
+	"fontStyle",
+	"letterSpacing",
+	"textAnchor",
+	"dominantBaseline",
+	"x",
+	"y",
+	"x1",
+	"y1",
+	"x2",
+	"y2",
+	"cx",
+	"cy",
+	"r",
+	"rx",
+	"ry",
+	"dx",
+	"dy",
+	"d",
+	"points"
+];
+/**
+* The root `<svg>`'s attributes: `SVG_ATTRIBUTES` less `transform`, plus the
+* viewport, a `role` from a closed list, and the accessible name.
+*
+* `transform` on the root is not an SVG transform at all. The root is an
+* in-flow CSS box, and the attribute becomes a CSS transform of that box, so
+* `<svg width="10" height="10" transform="translate(-300 -300) scale(80)">`
+* laid out as a 10px box and painted as an 800px one over the paragraphs
+* around it. On a child it moves shapes inside the viewport, which clips them.
+*
+* Residual: that clip is the root's `overflow`, which `SAFE_STYLE` lets a
+* document set. `style="overflow:visible"` on the root lets a child with a
+* large `transform` or large coordinates paint over its neighbors — measured in
+* Chromium, the same overlap. It is the negative-`margin` residual described at
+* `SAFE_STYLE` by another route: it stays in the flow, scrolls with the content,
+* and the scroll container clips it.
+*/
+const SVG_ROOT_ATTRIBUTES = [
+	...SVG_ATTRIBUTES.filter((attribute) => attribute !== "transform"),
+	"xmlns",
+	"viewBox",
+	"preserveAspectRatio",
+	[
+		"role",
+		"img",
+		"presentation",
+		"none"
+	],
+	"ariaLabel"
+];
+/** Every element the sanitizer admits. */
+const TAG_NAMES = [
+	...defaultSchema.tagNames || [],
+	"math",
+	"semantics",
+	"mrow",
+	"mi",
+	"mo",
+	"mn",
+	"msup",
+	"msub",
+	"mfrac",
+	"mover",
+	"munder",
+	"msqrt",
+	"mroot",
+	"mtable",
+	"mtr",
+	"mtd",
+	"mtext",
+	"mspace",
+	"annotation",
+	"figure",
+	"figcaption",
+	"summary",
+	"details",
+	"svg",
+	...SVG_CHILD_TAGS
+];
+/**
+* The admitted elements that take no `style`: only `input`, which GFM emits as
+* a task list's checkbox, and never with a style.
+*
+* `styles/task-list.css` draws that checkbox and positions it, so on it `top`
+* and `left` are not the no-ops they are on an element nothing positions, and
+* with `width`, `height` and `background-color` beside them a document laid a
+* box of its own over the page. Measured in Chromium at 1280x800 while the
+* checkbox was positioned absolutely,
+* `top:-3000px;left:-3000px;width:9000px;height:9000px;background-color:white`
+* on it covered the whole content pane. It needed no class written:
+* GFM puts `task-list-item` on the item, and a checkbox typed into the item's
+* text is a child of that item too.
+*
+* **This is why `style` is on each element's own entry, never on `*`.**
+* `hast-util-sanitize` consults `*` whenever an element's own entry yields
+* nothing, so no entry on `input` could refuse a value that `*` admits. An
+* element takes `style` only by being in `TAG_NAMES` and not in this set.
+*/
+const UNSTYLED_TAGS = /* @__PURE__ */ new Set(["input"]);
+/**
+* `attributes`, with `["style", SAFE_STYLE]` added to the entry of every
+* element in `TAG_NAMES` but the `UNSTYLED_TAGS`.
+*/
+function withStyle(attributes) {
+	const styled = { ...attributes };
+	for (const tag of new Set(TAG_NAMES)) if (!UNSTYLED_TAGS.has(tag)) styled[tag] = [...styled[tag] ?? [], ["style", SAFE_STYLE]];
+	return styled;
+}
+/**
 * Never set `allowComments` here.
 *
 * `hast-util-sanitize` drops comment nodes because that boolean defaults to
@@ -1073,38 +1810,16 @@ const COLLAPSE_GROUP_ID = /^[0-9]+$/;
 */
 const sanitizeSchema = {
 	...defaultSchema,
-	tagNames: [
-		...defaultSchema.tagNames || [],
-		"math",
-		"semantics",
-		"mrow",
-		"mi",
-		"mo",
-		"mn",
-		"msup",
-		"msub",
-		"mfrac",
-		"mover",
-		"munder",
-		"msqrt",
-		"mroot",
-		"mtable",
-		"mtr",
-		"mtd",
-		"mtext",
-		"mspace",
-		"annotation",
-		"figure",
-		"figcaption",
-		"summary",
-		"details"
-	],
-	attributes: {
+	strip: [...defaultSchema.strip || [], ...SVG_STRIPPED_EVERYWHERE],
+	tagNames: TAG_NAMES,
+	ancestors: {
+		...defaultSchema.ancestors,
+		...Object.fromEntries(SVG_CHILD_TAGS.map((tag) => [tag, ["svg"]]))
+	},
+	attributes: withStyle({
 		...defaultSchema.attributes,
 		"*": [
 			...defaultSchema.attributes?.["*"] || [],
-			"className",
-			["style", SAFE_STYLE],
 			"dataSourceLine",
 			["dataVantageTone", ...VANTAGE_TONES],
 			["dataVantageEmphasis", ...VANTAGE_EMPHASIS],
@@ -1114,35 +1829,22 @@ const sanitizeSchema = {
 			["dataVantageCollapseToggle", COLLAPSE_GROUP_ID],
 			["dataVantageRun", ...VANTAGE_RUNS],
 			["dataVantageOq", "true"],
+			["dataVantageQuestion", "true"],
 			["dataVantageOqId", VANTAGE_OQ_ID],
 			["dataVantageAlert", ...VANTAGE_ALERTS],
 			"dataVantageLeaning"
 		],
-		code: [...defaultSchema.attributes?.code || [], "className"],
-		span: [
-			...defaultSchema.attributes?.span || [],
-			"className",
-			["style", SAFE_STYLE]
-		],
-		div: [
-			...defaultSchema.attributes?.div || [],
-			"className",
-			["style", SAFE_STYLE]
-		],
-		a: [
-			...defaultSchema.attributes?.a || [],
-			"id",
-			"className"
-		],
+		...Object.fromEntries(Object.keys(PIPELINE_CLASSES).map((tag) => [tag, withClasses(tag)])),
+		a: withClasses("a", "id"),
 		math: ["xmlns"],
 		annotation: ["encoding"],
 		img: [...defaultSchema.attributes?.img || [], "loading"],
-		td: [...defaultSchema.attributes?.td || [], ["style", SAFE_STYLE]],
-		th: [...defaultSchema.attributes?.th || [], ["style", SAFE_STYLE]]
-	}
+		svg: SVG_ROOT_ATTRIBUTES,
+		...Object.fromEntries(SVG_CHILD_TAGS.map((tag) => [tag, SVG_ATTRIBUTES]))
+	})
 };
 //#endregion
-//#region src/pipeline.ts
+//#region src/remarkPlugins.ts
 /**
 * The mdast half of the chain. Exported on its own because there is a real
 * mdast-only consumer: the CLI checker parses documents without ever running
@@ -1156,6 +1858,8 @@ function buildRemarkPlugins(options = {}) {
 	if (math) plugins.push([remarkMath, { singleDollarTextMath: false }]);
 	return plugins;
 }
+//#endregion
+//#region src/pipeline.ts
 /** The hast half. Deliberately not exported: see `buildPipeline`. */
 function buildRehypePlugins(options = {}) {
 	const { math = true, highlight = true, sourceLines = true, sanitize = true, bodyLineOffset = 0 } = options;
@@ -1163,7 +1867,7 @@ function buildRehypePlugins(options = {}) {
 	if (sourceLines) plugins.push([rehypeSourceLines, { offset: bodyLineOffset }]);
 	plugins.push(rehypeVantageAlerts);
 	plugins.push(rehypeVantageDirectives);
-	if (sanitize) plugins.push([rehypeSanitize, sanitizeSchema]);
+	if (sanitize) plugins.push(rehypeStripSvgContainers, [rehypeSanitize, sanitizeSchema]);
 	plugins.push(rehypeVantageAnchors);
 	plugins.push(rehypeSlug);
 	if (highlight) plugins.push(rehypeHighlight);
@@ -1727,6 +2431,43 @@ let mermaidLoading = null;
 * configured for, `null` until loaded.
 */
 let configuredTheme = null;
+/**
+* The configuration keys a diagram's own source may not set, from an `init`
+* directive or from frontmatter: Mermaid's default list, then the three
+* that write a diagram's stylesheet.
+*
+* **A diagram's stylesheet reaches past the diagram.** Mermaid puts every
+* selector of it under the diagram's id, but leaves the names of its
+* `@keyframes` global, so a diagram that defined `flash-update` redefined the
+* animation the viewer plays on a block that just changed. Given
+* `position: fixed` at the size of the window, the next flash laid that block,
+* and the link it held, over the header and the sidebar. The same stylesheet
+* fetched images from any host, which is why `SAFE_STYLE` refuses parentheses.
+*
+* - `themeCSS` is a stylesheet, and Mermaid checks only that its braces pair.
+* - `fontFamily` is copied into `themeVariables` *after* Mermaid's check on
+*   theme variables has run, and lands in the stylesheet as a declaration's
+*   value, where a nested block becomes a rule of its own.
+* - `altFontFamily` lands in a rule the browser parses first, which drops
+*   what does not belong. It is refused anyway: nothing needs it, and that
+*   parse is all that stands in the way.
+*
+* Mermaid applies the list at every depth, so `themeVariables.fontFamily` in
+* a diagram is refused too. The list is spelled whole rather than relying on
+* Mermaid merging it with its default. `frontend/e2e/mermaid.spec.ts` measures
+* all four routes; see "Mermaid" in `docs/reference/inline-markup.md`.
+*/
+const MERMAID_SECURE_KEYS = [
+	"secure",
+	"securityLevel",
+	"startOnLoad",
+	"maxTextSize",
+	"suppressErrorRendering",
+	"maxEdges",
+	"themeCSS",
+	"fontFamily",
+	"altFontFamily"
+];
 function configure(m, palette) {
 	const theme = mermaidThemeOf(palette);
 	m.initialize({
@@ -1734,7 +2475,8 @@ function configure(m, palette) {
 		theme,
 		themeVariables: mermaidThemeVariables(theme),
 		securityLevel: "strict",
-		suppressErrorRendering: true
+		suppressErrorRendering: true,
+		secure: MERMAID_SECURE_KEYS
 	});
 	configuredTheme = palette;
 }
@@ -1769,15 +2511,6 @@ async function getMermaid() {
 //#endregion
 //#region src/renderMermaidBlocks.ts
 /**
-* Client-side utility to find and render mermaid code blocks in a container.
-*
-* After calling `renderMarkdown()`, mermaid blocks come through as
-* `<pre><code class="language-mermaid">...</code></pre>`. This function
-* finds those blocks and replaces them with rendered SVG diagrams.
-*
-* Framework-agnostic — works in any browser environment.
-*/
-/**
 * Find all `<pre><code class="language-mermaid">` blocks in a container
 * and replace them with rendered SVG diagrams.
 *
@@ -1858,6 +2591,7 @@ function replaceWithSvg(preEl, svg, className) {
 	wrapper.innerHTML = svg;
 	preEl.replaceWith(wrapper);
 }
+unified().use(remarkParse).use(buildRemarkPlugins());
 //#endregion
 //#region src/resolveLinks.ts
 /**
@@ -1908,12 +2642,15 @@ function resolveLinks(html, options = {}) {
 * The canonical Vantage Markdown style guide.
 *
 * This string is the single source of truth for the conventions Vantage's
-* renderer expects. Two consumers read it:
+* renderer expects. It reaches readers three ways:
 *
 * - the in-app "Style Guide for Agents" modal, which shows it with a copy
-*   button, and
+*   button,
 * - the `vantage-check style-guide` command, which prints it so an agent can
-*   fetch it without a human in the loop.
+*   fetch it without a human in the loop, and
+* - this package's own export, for anyone who renders with `vantage-md`.
+*
+* How the CLI serves it, and why there is one copy: docs/reference/agent-cli.md
 *
 * Every rule stated here should be one a checker can enforce or a renderer
 * actually cares about — if a line is neither, it does not belong.
@@ -1969,6 +2706,41 @@ vantage:
 - **Prefer \`status-chip: true\`**, which shows the document's own \`status:\` and therefore cannot disagree with it. A literal \`status-chip: accepted\` is accepted too, but it is a second value that goes stale on its own — \`vantage-check\` reports the disagreement.
 - The chip's vocabulary is \`status\`'s, exactly: \`draft | in-review | accepted | deprecated\`, lowercase. \`Draft\` renders no chip at all, silently.
 
+### Planning documents: \`stage\`, \`next\`, \`depends-on\`
+- **Vantage reads a repository's plans as a set.** A document whose frontmatter has \`status\` or \`stage\`, or that carries a \`question\` directive (or an \`oq\`, the name it replaces), is a *planning document*, and Vantage shows its state (status, stage, open questions) in a badge beside every link to it. So write each fact once, in the document it belongs to, and link to it everywhere else: a copied status or count is the one that goes stale.
+- Three top-level keys beside \`status\` hold the rest of a document's planning state. They are facts about the file, so they sit at the top level, never under \`vantage:\`:
+\`\`\`yaml
+---
+title: "Payload bootstrap"
+status: in-review
+stage: DESIGN
+next: "Rule OQ-B2 \u2014 the install step waits on it"
+depends-on:
+  - pypi-distribution.md
+  - ../plans/rollout.md#OQ-R1
+---
+\`\`\`
+- **\`stage\` is one word from the repository's own vocabulary**, the words \`[planning.stages]\` declares (below), spelled exactly as declared: matching is case-sensitive, so \`Decided\` is not \`DECIDED\`. \`vantage-check\` reports a word outside them as \`planning/stage-vocabulary\`.
+- **Frontmatter is the stage's one home.** Do not repeat the word in a prose \`**Status:**\` line: that is a second copy, and no tool can read or check it. Keep the prose line, where a document has one, for the date and the why.
+- **\`next\` is the next step, on one line of plain text.** A bare \`OQ-\` id in it links to this document's question of that id, so name the question rather than paraphrasing it.
+- **\`depends-on\` lists what the document waits on**: relative paths, resolved like links, each optionally ending in \`#OQ-\u2026\` to name one question. A single path may stand on its own. A target that does not exist, lies outside the repository, or does not contain the id is an error (\`planning/depends-on-missing\`).
+- **Never a \`priority\` key.** A priority only means something relative to the others, so it lives in an ordered list, a roadmap, and not in each document.
+- **A roadmap is ordered links.** Every \`roadmap.md\` Vantage reads is a roadmap, in any directory, unless \`[planning]\` lists the roadmaps instead; one in a hidden directory, matched by \`.vantageignore\`, or ruled out by \`include\` or \`exclude\` is not read, and so is not a roadmap. Each entry is a link to a document or a question, then a one-clause reason for its place; the badge beside the link carries the rest, so never copy a status, a stage or a count into it. Prose beneath an entry holds only what has no other home, such as what would unblock it. A bare link to a document *routes* every question in it into the roadmap's order, and a link to one question's \`#OQ-\u2026\` anchor routes that question; a link to any other heading routes nothing. A question is routed when any roadmap routes it, and with \`planning/unrouted\` turned on, \`vantage-check\` reports an open question no roadmap routes.
+- **\`[planning]\` in \`.vantage.toml\`** says which files are read, which of them are roadmaps, and what each stage word means. Every key is optional:
+\`\`\`toml
+[planning]
+# roadmap = ["roadmap.md", "docs/plans/roadmap.md"]  # absent: every roadmap.md
+exclude = ["docs/gallery/**"]   # gitignore syntax; every .md is included by default
+
+[planning.stages]               # each word maps to open | ready | built | done
+DESIGN = "open"
+DECIDED = "ready"
+BUILT = "built"
+SUPERSEDED = "done"
+\`\`\`
+- **Each stage word maps to one of four roles**, which is what the word means to Vantage: \`open\` is still being decided, \`ready\` is decided and not built, \`built\` is built, and \`done\` is no longer a live proposal, so its questions leave every list of what needs a ruling. \`vantage-check index\` prints those lists.
+- **Never change \`target\`.** A \`target = "X.Y"\` line at the top of \`.vantage.toml\` names the oldest Vantage release the repository's readers use, and only a human edits it. A \`vantage-check\` older than the target refuses to run and names the release it needs: run that release, and leave the target as it is.
+
 ### Mermaid diagrams
 - Use \`\`\`mermaid code blocks for flowcharts, sequence diagrams, and architecture diagrams. Vantage provides interactive zoom, pan, dark/light theme adaptation, and SVG export.
 - **Quote labels with special characters**: Always quote node labels containing parentheses, brackets, or colons to prevent syntax errors:
@@ -1978,6 +2750,26 @@ flowchart TD
     srv --> git["Git CLI (git diff)"]
 \`\`\`
 
+### Inline SVG (needs Vantage 0.8 or later)
+- **Inline \`<svg>\` is a capability, not notation: it needs Vantage 0.8 or later.** GitHub, every other renderer and Vantage before 0.8 drop the drawing and leave the words of its \`<text>\` elements behind as loose text, so keep \`<text>\` to short labels a reader can bear to see as loose words.
+- **Name the drawing with \`aria-label\` on the \`<svg>\`, never with \`<title>\` or \`<desc>\`.** Vantage 0.8 removes both, so they name nothing there, and every other reader prints them: Vantage before 0.8 as loose words, GitHub with the tags.
+- **Pair every inline drawing with a fallback block**: a \`<!-- vantage: fallback -->\` directive above the block that stands in for the drawing. Vantage 0.8 and later never show that block; every other reader drops the comment and shows it. Say what the drawing shows and that it needs Vantage 0.8 or later, and link a copy of it committed as a file where there is one (\`[the drawing](diagram.svg)\`). The block is a paragraph, a list, a quote, a code block, a table or a \`<div>\`; Vantage shows a raw \`<img>\`, \`<figure>\` or \`<details>\` there, so wrap one in a \`<div>\`.
+- **Wrap the drawing in a \`<div>\` on a line of its own, with no blank line anywhere inside it**, and give it a \`width\`, a \`height\` and a \`viewBox\`. Paint with \`fill\`/\`stroke\` set to \`currentColor\` or a hex color, so it reads in light and dark mode.
+\`\`\`markdown
+<div>
+<svg xmlns="http://www.w3.org/2000/svg" width="120" height="40" viewBox="0 0 120 40" role="img" aria-label="Two boxes joined by an arrow">
+  <rect x="1" y="1" width="40" height="38" fill="none" stroke="currentColor"/>
+  <path d="M45 20 H75 M68 14 L75 20 L68 26" fill="none" stroke="currentColor"/>
+  <rect x="79" y="1" width="40" height="38" fill="none" stroke="currentColor"/>
+</svg>
+</div>
+
+<!-- vantage: fallback -->
+
+Two boxes joined by an arrow. This drawing needs Vantage 0.8 or later.
+\`\`\`
+- **For a document read mostly on GitHub**, commit the drawing as a file and embed it with \`![alt](diagram.svg)\` instead, which every renderer shows.
+
 ### Code blocks and diffs
 - Always tag fenced code blocks with language identifiers (\`ts\`, \`go\`, \`python\`, \`bash\`, \`json\`, \`yaml\`, \`diff\`, \`sql\`, etc.) for syntax highlighting.
 - For proposed code modifications, use \`\`\`diff blocks with \`+\` and \`-\` prefixes:
@@ -2015,25 +2807,60 @@ Vantage reads a few styling hints from ordinary HTML comments. Every other rende
 The steps below predate the rewrite.
 \`\`\`
 
-- **Three names**: \`section\` (the heading and everything under it), \`block\` (the one block after it), \`oq\` (one answerable Open Question).
+- **Four names to write**: \`section\` (the heading and everything under it), \`block\` (the one block after it), \`question\` (one Open Question, in any state; see Open questions below), \`fallback\` (the one block after it, which Vantage 0.8 and later never show; see Inline SVG above). \`fallback\` takes no keys, and withholds only a paragraph, a list, a quote, a code block, a table, a rule or a \`<div>\`, never a heading. A fifth, \`oq\`, is the name \`question\` replaces (below).
 - **The keys and values are a closed set**: \`tone\` = \`note | tip | important | warning | caution | muted\`; \`emphasis\` = \`strong | normal | quiet\`; \`badge\` = \`draft | stale | blocked | done | wip\`; \`collapsed\` = \`true | false\`. Name a *tone*, never a color — the theme decides what a warning looks like, in light mode, in dark mode, and in print.
 - **Use them sparingly.** One or two per document, on the sections that genuinely differ. A document where everything is toned says nothing, and a rainbow one is harder to read than a plain one.
 - **Anything outside those sets is silently ignored** — nothing breaks, and nothing styles either. Run \`vantage-check\` on the document: the \`vantage/*\` rules are the only thing that will ever tell you a directive did nothing.
 - **Always close the comment with \`-->\`.** Never \`--!>\`, and never leave it open: Markdown reads every line below an unclosed \`<!--\` as part of the comment, and the whole rest of the document vanishes from the page. For the same reason \`-->\` cannot appear *inside* a value — it ends the comment early and spills the remainder into the page as literal text.
 - **In a list, indent the directive inside the item**, with blank lines around it (below). At the start of a line between two items it ends the list and starts a second one, which changes the numbering and the spacing in every renderer — the one thing a directive must never do.
-- **An open question's id is \`OQ-\` then an optional short uppercase prefix then digits** — \`OQ-9\`, \`OQ-TP6\`, \`OQ-A03\`. The prefix is what keeps ids distinct once one document references another's questions, so use one in both whenever they cross-reference. \`vantage-check\` reports anything outside that shape as \`vantage/oq-id-format\`, and the same id twice in one document as \`vantage/oq-id-duplicate\` — both are silent otherwise, because the id becomes the block's anchor and a refused or duplicated one simply goes nowhere.
+- **A question's id is \`OQ-\` then an optional short uppercase prefix then digits** — \`OQ-9\`, \`OQ-TP6\`, \`OQ-A03\`. The prefix is what keeps ids distinct once one document references another's questions, so use one in both whenever they cross-reference. \`vantage-check\` reports anything outside that shape as \`vantage/oq-id-format\`, and the same id twice in one document as \`vantage/oq-id-duplicate\` — both are silent otherwise, because the id becomes the block's anchor and a refused or duplicated one simply goes nowhere.
 - **A reference is a link, or it is a lie.** An \`OQ-\` id, a \`\u00a7N\` section number and a filename all read like pointers, and written as bare prose none of them can be followed or checked — which is exactly why a stale one is never caught. Link the question to its anchor (\`[OQ-4](#OQ-4)\`, or the Decision Ledger once it is compacted), the section to its heading, the filename to the file. \`vantage-check\` reports all three (\`ref/*\`) as errors, and checks that the link points at the thing the reference names rather than merely at something. Writing a specimen rather than a reference? Put it in a fenced block, which the rules never read.
-- **Every open question (\u{1F4AC}) with a stated leaning gets an \`oq\` directive.** The convention's prose — the emoji, the \`OQ-N\` id, the \`_Leaning:_\` line, the fill-in \`**Answer:**\` — produces no button on its own. Writing the convention and stopping there is the most common way this feature goes missing: the questions look complete, review mode is on, and there is nothing to click. **\`vantage-check\` reports it as an error** (\`vantage/oq-missing\`), because a question awaiting a ruling that the reviewer cannot file is not a style preference. Mark it \u{1F512} if it is blocked on something upstream and cannot be answered yet, or \u2705 once it is decided; either state needs no directive.
-- **A \`leaning\` restates the leaning; it is never "yes".** The one-click button in review mode files that text as a review comment, and the comment is all the agent reading it has — nobody remembers which button was clicked. \`leaning="Yes"\` beside a two-branch question is a support ticket.
+
+### Open questions
+A question a document leaves for a human to rule on is an *Open Question*, written in a numbered list under a heading of its own.
+
+- **Write each question in its parts, never as one run-together paragraph.** Vantage lays a question out by these parts: the contents column and the planning page's card show its title as the question, and the card shows the leaning as the leaning and the Answer as the answer, so a part run into another one is read as neither. Each part is a block of its own, with a blank line before it:
+  1. **The title line**: the status marker, the id and the question itself in bold, saying what is being decided: \`\u{1F4AC} **OQ-9: Where does a job go when it re-enters the queue?**\`.
+  2. **The context**, in short paragraphs: only what a ruling needs. Background, history and cross-references belong in the document's own sections, linked from the question.
+  3. **The options as a list**, one item each, when there are options to choose between.
+  4. **\`_Leaning:_\` as a paragraph of its own**: which option, and why, in a sentence or two.
+  5. **\`**Answer:**\` as a paragraph of its own**, with the ruling below it once there is one.
 
 \`\`\`markdown
-1. **OQ-9: Queue position on re-entry.**
+## Open Questions
+
+1. \u{1F4AC} **OQ-9: Where does a job go when it re-enters the queue?**
 
-   <!-- vantage: oq id=OQ-9 leaning="Back of the queue — the fix might interact with what merged while it was out." -->
+   A job that fails its checks leaves the queue and comes back once it is fixed. What merged while it was out may change what it does.
 
-   _Leaning:_ Back of the queue.
+   - **A — The back of the queue.** It waits its turn again.
+   - **B — Its old place.** It skips ahead of what joined since.
+
+   <!-- vantage: question id=OQ-9 leaning="A — the back of the queue: the fix might interact with what merged while it was out." -->
+
+   _Leaning:_ A. The fix might interact with what merged while it was out.
+
+   **Answer:**
+
+   > _(empty — fill in when decided)_
+
+2. \u{1F512} **OQ-10: How large is the retry budget?**
+
+   <!-- vantage: question id=OQ-10 -->
+
+   Waits on the load test, so there is no leaning to state yet.
 \`\`\`
 
+- **The marker is the question's state**: \u{1F4AC} open (\u{1F4AC} \u{1F937} when it is a matter of preference), \u{1F512} blocked on something upstream that has to happen first, \u2705 answered. Review mode offers a one-click **Take this leaning** on an open question, and on nothing else.
+- **Every question gets a \`question\` directive**, \`<!-- vantage: question id=OQ-9 leaning="…" -->\`, in every state, indented into its list item on a line of its own directly above the \`_Leaning:_\` paragraph, or above another of its paragraphs when it states no leaning. The directive is what makes it a question to Vantage: it gives the question its \`#OQ-9\` anchor, and Vantage's planning index (its model of a repository's plans) reads a question from nothing else, so without one nothing counts it, badges it or lists it as waiting. It goes when the question is compacted into the Decision Ledger, and not before.
+- **Changing a question's state changes its marker and nothing else.** Mark it \u{1F512} when it cannot be answered yet, and \u2705 once it is decided; the directive stays as it is, its \`leaning\` included, which nothing offers to take once the question is not open.
+- **Every open question with a stated leaning restates it as the directive's \`leaning\`.** The convention's prose — the emoji, the \`OQ-N\` id, the \`_Leaning:_\` line, the fill-in \`**Answer:**\` — produces no button on its own, and writing it and stopping there is the most common way the button goes missing: the questions look complete, review mode is on, and there is nothing to click. \`vantage-check\` reports an open question with a \`_Leaning:_\` and no directive as an error (\`vantage/oq-missing\`). An open question with no leaning yet takes the directive without \`leaning\`, so the planning index still counts it; until it states one, its button files the literal text "Take the stated leaning."
+- **A \`leaning\` restates the leaning; it is never "yes".** The one-click button in review mode files that text as a review comment, and the comment is all the agent reading it has — nobody remembers which button was clicked. \`leaning="Yes"\` beside a two-branch question is a support ticket.
+- **Keep the text below the title short.** The planning page shows each question as a card that leads with the title and shows only the first few lines of the rest, so a question buried in a paragraph of background is one the reviewer has to dig for. \`vantage-check\` warns when a question's text, not counting its \`_Leaning:_\` paragraph and its \`**Answer:**\`, runs past 120 words (\`planning/question-length\`), and when a leaning shares a paragraph with other text (\`vantage/question-layout\`); a repository can raise the limit with \`max-words\`, or turn either rule off, under \`[check.rules]\`.
+- **Enumerate with a list, never inline.** A question's options, or any three steps or parts, go in a Markdown list, one item per line, rather than run together in one sentence as \`(a) \u2026 (b) \u2026 (c)\`, where a reader has to find where each one starts. \`vantage-check\` warns on a paragraph that runs three or more together (\`prose/inline-list\`).
+- **Write a question as a list item.** Outside a list, a question runs from the block its directive lands on through the blocks after it, up to the next heading (for a question written as a heading, the next one of its level or higher), the next rule or the next question, so whatever prose follows it before then is read as part of it. There the directive goes above the question's title, since every viewer reads the question's marker from the block it lands on: a directive below the bold title lands on the block after it, which carries no marker, so every viewer reads the question as open. \`vantage-check\` reports that as \`vantage/question-name\`.
+- **\`oq\` is the name \`question\` replaces.** Vantage keeps reading \`<!-- vantage: oq id=OQ-9 leaning="…" -->\` as it always has, and \`vantage-check\` warns on it (\`vantage/oq-deprecated\`) with the \`question\` to write instead, keys unchanged. Vantage before 0.8 drops \`question\` whole, so a reader still on 0.7 gets no one-click answer and no anchor on a question written with it, and misreads nothing. So keep an \`oq\` on an open question unless you know every reader of the repository is on 0.8 or later. A repository whose readers are still on 0.7 says so with a \`target\` before 0.8, such as \`target = "0.7"\`: there an open question takes \`oq\`, new ones included, and \`vantage-check\` asks for \`oq\` rather than \`question\` on one. **Never put \`oq\` on a \u{1F512} or \u2705 question**: every Vantage before 0.8 offers the one-click button on every \`oq\`, whatever its marker says, and on a question with no leaning it files the literal text "Take the stated leaning." \`vantage-check\` reports that as an error (\`vantage/question-name\`).
+
 ### Tables, task lists, and math
 - **Tables**: Use standard markdown tables for structured comparisons and schemas.
 - **Task lists**: Use \`- [ ]\` and \`- [x]\` for actionable checklists and status tracking.
@@ -2041,6 +2868,6 @@ The steps below predate the rewrite.
   - Single dollars are **not** math delimiters: \`$HOME\` and \`$100\` stay literal, so prose and shell snippets are safe to write as-is.
 `;
 //#endregion
-export { ALERT_TITLES, COLOR_THEME_ATTRIBUTE, COLOR_THEME_SOURCE_ATTRIBUTE, DIRECTIVE_NAMES, DIRECTIVE_VOCABULARY, DOC_STATUSES, DOC_STATUS_TONES, SAFE_STYLE, STYLE_GUIDE, VANTAGE_ALERTS, VANTAGE_BADGES, VANTAGE_COLLAPSED, VANTAGE_EMPHASIS, VANTAGE_FRONTMATTER_KEYS, VANTAGE_OQ_HOST_TARGETS, VANTAGE_OQ_STATUS, VANTAGE_OQ_STATUS_LABEL, VANTAGE_RUNS, VANTAGE_SENTINEL, VANTAGE_TONES, buildPipeline, buildRemarkPlugins, clearLineAnchorHighlights, currentColorTheme, hasVantageSentinel, isDocStatus, parseFrontmatter, parseLineAnchor, parseVantageDirective, readVantageFrontmatter, rehypeSourceLines, rehypeVantageAlerts, rehypeVantageAnchors, rehypeVantageDirectives, renderMarkdown, renderMermaidBlocks, resolveLinks, sanitizeSchema, scrollToLineAnchor, vantageOqStatus };
+export { ALERT_TITLES, COLOR_THEME_ATTRIBUTE, COLOR_THEME_SOURCE_ATTRIBUTE, DIRECTIVE_NAMES, DIRECTIVE_VOCABULARY, DOC_STATUSES, DOC_STATUS_TONES, SAFE_STYLE, STYLE_GUIDE, VANTAGE_ALERTS, VANTAGE_BADGES, VANTAGE_COLLAPSED, VANTAGE_EMPHASIS, VANTAGE_FRONTMATTER_KEYS, VANTAGE_LEANING_ATTRIBUTE, VANTAGE_OQ_ATTRIBUTE, VANTAGE_OQ_HOST_TARGETS, VANTAGE_OQ_STATUS, VANTAGE_OQ_STATUS_LABEL, VANTAGE_QUESTION_ATTRIBUTE, VANTAGE_QUESTION_NAMES, VANTAGE_QUESTION_SELECTOR, VANTAGE_RUNS, VANTAGE_SENTINEL, VANTAGE_TONES, buildPipeline, buildRemarkPlugins, clearLineAnchorHighlights, currentColorTheme, hasVantageSentinel, isDocStatus, isQuestionDirective, parseFrontmatter, parseLineAnchor, parseVantageDirective, questionOffersTake, readVantageFrontmatter, rehypeSourceLines, rehypeVantageAlerts, rehypeVantageAnchors, rehypeVantageDirectives, renderMarkdown, renderMermaidBlocks, resolveLinks, sanitizeSchema, scrollToLineAnchor, vantageOqStatus };
 
 //# sourceMappingURL=index.js.map