@suzumiyaaoba/mdxr 0.1.0

package/skill/references/components/investigation.md

@@ -0,0 +1,198 @@
+# Code investigation components
+
+Index: [../components.md](../components.md). MDX attributes are always strings; `children` is Markdown.
+
+### `<Findings title>` / `<Finding confidence="confirmed|inferred|unverified" title="…">` / `:::findings` / `:::finding`
+
+Investigation findings with an epistemic-status pill: `confirmed` (read from the code), `inferred` (deduced from evidence), `unverified` (claimed, not checked). `Findings` numbers each `Finding` and renders a count summary on top; children carry the evidence (`<FileRef>`, `<CodeFile>`).
+
+```mdx
+<Findings title="Investigation results">
+  <Finding confidence="confirmed" title="Rendering is synchronous">
+    `mdxToHtml` awaits `evaluate()` then calls `renderToStaticMarkup`.
+  </Finding>
+  <Finding confidence="unverified" title="Watch-mode reloads">
+    Probably, but no test covers it.
+  </Finding>
+</Findings>
+```
+
+### `<Files title>` / `<File path kind lines>` / `:::files`
+
+Related-file inventory — "the files this investigation touches". The row icon is picked automatically from the file name/extension (`vscode-icons` set: `package.json` → npm, `Dockerfile` → Docker, `*.test.ts` → test TS, …). `kind` is a free-form chip; known values get an icon and color: `entry` `core` `types` `config` `test` `docs` `generated`. Children render as a muted note. For change-sets (what a plan modifies) use `Changes` instead. `path` links to the file in the reader's editor when it exists on disk (`href` overrides; see "File links" in [../components.md](../components.md)).
+
+```mdx
+<Files title="Files involved">
+  <File path="src/mdx.ts" kind="entry" lines="70-106">
+    Pipeline entry.
+  </File>
+  <File path="src/define.ts" kind="types" />
+  <File path="tests/render.test.ts" kind="test" />
+</Files>
+```
+
+### `<Deps title>` / `<Dep from to kind>` / `:::deps`
+
+Dependency-edge list — compact alternative to a mermaid graph for module relationships. `kind` (default `imports`): `imports` `calls` `extends` `implements` `reads` `writes`. `from`/`to` accept paths, module names, or symbols; children render as a muted note.
+
+```mdx
+<Deps title="Module dependencies">
+  <Dep from="src/cli.ts" to="src/render.ts" kind="calls" />
+  <Dep from="src/mdx.ts" to="remark-directive" kind="imports" />
+  <Dep from="src/render.ts" to="dist/out.html" kind="writes" />
+</Deps>
+```
+
+### `<Changes>` / `<Change kind="add|modify|delete|rename" path="…" to="…">`
+
+Change-set list — the "files this plan touches" section. `kind` drives the icon and color (`to` is the new path on `rename`); the file path also gets an extension-based icon automatically. Children render as a muted note. The path links to the file in the reader's editor when it exists (`to` wins on `rename`; `href` overrides).
+
+```mdx
+<Changes>
+  <Change kind="add" path="src/remark/headings.ts">
+    slug + toc expansion
+  </Change>
+  <Change kind="modify" path="src/mdx.ts" />
+  <Change kind="rename" path="src/old.ts" to="src/new.ts" />
+  <Change kind="delete" path="src/dead.ts" />
+</Changes>
+```
+
+### `<Flow title="…">` / `<FlowStep name path lines>` / `:::flow{title="…"}`
+
+Numbered call/execution chain — "how a request travels through the code". Each `FlowStep` renders a numbered node on a connecting rail; `name` is the function/phase label (mono), `path`/`lines` pin the location (linked to the file in the reader's editor when it exists; `href` overrides), children describe what happens there. Use `Steps` for task checklists and `Timeline` for dates — `Flow` is for hops through code.
+
+```mdx
+<Flow title="Request path">
+  <FlowStep name="cli()" path="src/cli.ts" lines="12-30">
+    Parses argv, loads config.
+  </FlowStep>
+  <FlowStep name="mdxToHtml()" path="src/mdx.ts">
+    Compiles MDX and evaluates it.
+  </FlowStep>
+</Flow>
+```
+
+### `<Tree root="…">`
+
+File tree rendered from a nested Markdown list. Items ending in `/` or with children get a folder icon; `name — note` or `name # note` adds a muted note. Icons are picked automatically from the file extension or directory name (VS Code-style `vscode-icons` set, e.g. `.ts` → TypeScript logo, `src/` → src folder).
+
+Starlight-style extras: directories are collapsible (click to fold; works without JS), `open="false"` starts every folder collapsed, a `...` or `…` entry renders a placeholder for omitted files, and a `**bold**` name highlights the entry.
+
+```mdx
+<Tree root="mdxr/">
+
+- src/
+  - render.ts — pipeline entry
+  - ui/
+    - **plan.tsx**
+    - steps.tsx
+    - …
+- package.json
+- ...
+
+</Tree>
+```
+
+### `<FileRef path="src/mdx.ts" lines="40-52" />`
+
+Inline file reference chip with a copy button. The icon is picked automatically from the file extension (`vscode-icons` set). Links to the file in the reader's editor (`vscode://file/…` by default) when it exists on disk; `href` overrides the URL, `editor: none` disables linking.
+
+### `<SymbolRef name="mdxToHtml" kind="fn" path="src/mdx.ts" lines="70-106" />`
+
+Inline symbol reference chip for code explanations. `kind` picks the icon: `fn` `type` `class` `interface` `const` `enum` `prop` `component` (omit for no icon). `path`/`lines` show the definition site muted — the chip links to that file in the reader's editor when it exists (`href` overrides); the copy button copies `path` (or `name` when absent).
+
+```mdx
+<SymbolRef name="mdxToHtml" kind="fn" path="src/mdx.ts" /> returns
+<SymbolRef name="MdxResult" kind="interface" />.
+```
+
+### `<CodeFile path="src/x.ts" lines="40-52" lang="ts" />`
+
+Embeds a real file from disk as a fenced block — code explanations quote the actual source instead of drifting copies. `path` resolves relative to the document; `lines` slices a 1-based range (`"40"`, `"40-52"`, `"40-"`); `lang` overrides the extension-derived language. The filename header links back to the file in the reader's editor. Missing files and bad ranges are render errors.
+
+### `<Props of="…">` / `<Prop name type required default>`
+
+API/props table for documenting a component or function signature. `of` renders a caption bar; `required` (bare attr) adds a `*`; children are the description cell.
+
+```mdx
+<Props of="Step">
+  <Prop name="status" type="todo | doing | done | blocked" required>
+    Marker state.
+  </Prop>
+  <Prop name="effort" type="xs | s | m | l | xl" default="m" />
+</Props>
+```
+
+### `<Terminal cmd exit title>` / `:::terminal` / ` ```console `
+
+Terminal transcript — the standard evidence block for "what was run and what it printed". `cmd` renders as a `$ `-prompted first line; `exit` adds a title-bar badge (`0` green, anything else red). Children carry the output: put it in a fenced block for verbatim text — plain-text children are parsed as Markdown, which can mangle `_`, `*` etc. Body lines starting with `$ ` render as prompt lines, so multi-command sessions work too. The copy button copies the whole transcript.
+
+````mdx
+<Terminal cmd="pnpm test" exit="1" title="test run">
+
+```
+FAIL  tests/render.test.ts
+  ✗ renders markdown prose
+```
+
+</Terminal>
+````
+
+A ` ```console ` (or ` ```terminal ` / ` ```shellsession `) fence renders the same transcript with no component — `exit="N"` and `title="…"` in the fence meta work as well:
+
+````
+```console exit="1" title="grep evidence"
+$ rg 'evaluate' src/ --count
+src/mdx.ts: 3
+```
+````
+
+### `<Hypotheses title>` / `<Hypothesis status="supported|refuted|untested" title="…">` / `:::hypotheses` / `:::hypothesis`
+
+Hypothesis ledger — the "what we suspected, and whether it held up" section of a debugging-style investigation. `supported` = evidence backs it, `refuted` = ruled out (record dead ends — they save the reader from re-checking), `untested` = not yet checked. `Hypotheses` numbers each entry and summarizes per-status counts; children carry the reasoning and evidence (`<Terminal>`, `<FileRef>`).
+
+```mdx
+<Hypotheses title="Hypotheses tested">
+  <Hypothesis status="refuted" title="CSS loads at runtime">
+    Ruled out: the stylesheet is inlined into the HTML — see the
+    <Terminal cmd="grep stylesheet dist/out.html">…</Terminal>
+  </Hypothesis>
+  <Hypothesis status="supported" title="Directives expand before eval" />
+</Hypotheses>
+```
+
+### `<Trace title error>` / `<TraceFrame name path lines kind="app|lib">` / `:::trace`
+
+Stack/call trace for error and crash investigations. `error` renders the exception line on top (red); `TraceFrame`s are auto-numbered `#0…` top-down (most recent first, like `gdb bt`). `kind="lib"` dims framework/runtime frames and adds a `lib` tag. `path` links to the file in the reader's editor when it exists (`href` overrides). Children are per-frame notes.
+
+```mdx
+<Trace error="TypeError: Cannot read properties of undefined (reading 'kind')">
+  <TraceFrame name="toMdxComponent" path="src/remark/directives.ts" lines="64">
+    leaf directives have no attributes record
+  </TraceFrame>
+  <TraceFrame
+    name="visit"
+    path="node_modules/unist-util-visit/index.js"
+    kind="lib"
+  />
+  <TraceFrame
+    name="remarkMdxrDirectives"
+    path="src/remark/directives.ts"
+    lines="91"
+  />
+</Trace>
+```
+
+### `<Searches title>` / `<Search pattern path tool hits>` / `:::searches` / `:::search`
+
+Query log — provenance for an investigation: which patterns were searched where and how much came back. `pattern` is required; `path` is the scope (`in src/`), `tool` a small mono chip (`rg`, `grep`, …), `hits` a count badge — `0` renders "no hits" so dead ends read as deliberate exclusions. `Searches` adds a totals line; children are notes.
+
+```mdx
+<Searches title="How the code was searched">
+  <Search pattern="evaluate" path="src/" tool="rg" hits="3" />
+  <Search pattern="hydrateRoot" path="src/" tool="rg" hits="0">
+    Dead end — there is no client entry point.
+  </Search>
+</Searches>
+```

package/skill/references/components/layout.md

@@ -0,0 +1,68 @@
+# Layout components
+
+Index: [../components.md](../components.md). MDX attributes are always strings; `children` is Markdown.
+
+### `<Columns cols="2|3|4">` / `<Column>`
+
+Responsive grid layout for side-by-side content (options, before/after).
+
+### `<Grid cols min gap flow items>` / `<Cell span rowSpan>`
+
+Flexible 12-track grid for anything `<Columns>` can't express: asymmetric splits, dashboards, auto-wrapping card grids. Children that aren't `<Cell>` auto-place one track each.
+
+- `cols`: `1`–`12` tracks (default `12`); applies from `sm` up — below that everything stacks.
+- `min`: CSS length (`"12rem"`, `"200px"`) switches to `auto-fit` tracks at **every** viewport — use for card grids that wrap naturally. Overrides `cols`.
+- `gap`: `none|xs|sm|md|lg|xl` (default `md`). `flow`: `row|col|row-dense|col-dense` — `*-dense` backfills gaps in dashboards. `items`: `stretch|start|center|end`.
+- `<Cell>` `span`: `1`–`12` or `full` column span; `rowSpan`: `1`–`4`. Both apply from `sm` up. `className` on either adds arbitrary utilities.
+
+```mdx
+<Grid>
+  <Cell span="8">Main narrative…</Cell>
+  <Cell span="4">Sidebar: meta, links…</Cell>
+</Grid>
+
+<Grid cols="4" flow="row-dense">
+  <Cell span="2">
+    <Stat label="Coverage" value="92%" />
+  </Cell>
+  <Cell span="2" rowSpan="2">
+    Tall notes panel
+  </Cell>
+</Grid>
+
+<Grid min="14rem" gap="sm">
+  <Option title="A" status="recommended">
+    …
+  </Option>
+  <Option title="B" status="considered">
+    …
+  </Option>
+  <Option title="C" status="rejected">
+    …
+  </Option>
+</Grid>
+```
+
+### `<Row gap items>` / `<Stack gap items>`
+
+Flex containers for grouping components. Adjacent JSX elements render with no whitespace between them — margin-less primitives (the shadcn/ui set: `Button`, `Badge`, `Input`, `Switch`, …) end up glued together unless wrapped in `<Row>` or `<Stack>`.
+
+- `<Row>`: `flex flex-wrap items-center` — button/badge rows and other inline groups. `gap` default `sm`.
+- `<Stack>`: `flex flex-col` — vertical rhythm for stacked controls. `gap` default `md`.
+- `gap`: `none|xs|sm|md|lg|xl`. `items`: `stretch|start|center|end|baseline`. `className` adds arbitrary utilities.
+
+```mdx
+<Row>
+  <Button>Default</Button>
+  <Button variant="outline">Outline</Button>
+</Row>
+
+<Stack gap="sm">
+  <Progress value="60" />
+  <Skeleton className="h-4 w-40" />
+</Stack>
+```
+
+### `<Before>` / `<After>`
+
+Semantic before/after panels (red / green header). Wrap in `<Columns>` for side-by-side; `title` overrides the label ("Current" / "Proposed").

package/skill/references/components/output.md

@@ -0,0 +1,158 @@
+# Output artifacts — diffs, graphs, test reports, endpoints, JSON, timing
+
+Index: [../components.md](../components.md). MDX attributes are always strings; `children` is Markdown.
+
+### ` ```diff ` / ` ```patch ` fences → structured diff cards
+
+An ordinary unified-diff fence becomes one card per file: file-type icon, path (editor link when the file exists), a `new file` / `deleted` / `renamed` chip, `+N −M` counts with a proportional stat bar, a copy button, and hunks with dual old/new line numbers. Git meta lines (`index`, `similarity index`, `rename from/to`, modes) collapse into a muted strip. Diffs without `diff --git`/`---`/`+++` headers — bare `+`/`-` streams — still render. `title="path"` in the fence meta supplies the filename when the patch itself lacks headers.
+
+````mdx
+```diff title="src/render.ts"
+@@ -40,7 +40,8 @@
+-  const out = compile(src);
++  const doc = compile(src);
++  const out = minify(doc);
+   return out;
+```
+````
+
+For word-level inline edits inside prose use `<Ins>`/`<Del>`; for block alternatives use `<Before>`/`<After>`.
+
+### `<Comments>` / `<Comment lines side file>` / `:::comments` — line-anchored comment threads
+
+GitHub review-comment UX for a fenced block: the **first fenced child** (any ` ```ts ` code block or ` ```diff `/` ```patch ` patch) is the subject, and each `<Comment>` child becomes a thread card rendered **inline under the line it references** — the body is MDX, so ` ```diff ` suggestion fences and inline code just work. Code fences get a line-number gutter automatically.
+
+`<Comment>` props in this context:
+
+- `lines` — `"40"`, `"40-52"` (inclusive range) or `"40-"` (to EOF). The thread lands under the **last** matching line. `lines` past the end of the block falls back to the file-level strip.
+- `side` — `new` (default) or `old`: which side's line numbers anchor the thread inside a diff (`old` comments get a red `old` chip — for deleted/context lines).
+- `file` — selects the file card in multi-file diffs (old or new path, or the fence `title`); absent/unmatched targets the first card.
+- `author` — avatar initials + name in the thread header.
+- `severity`, `title` — severity pill and a bold headline, same as `<Review>` comments.
+- `href` — overrides the `:lines` chip's editor link.
+
+Without `lines` the comment renders at the end of the block — GitHub's file-level comment. Without a fenced child at all, `<Comments>` degrades to the standalone card list.
+
+The block is interactive in rendered documents: hovering (or keyboard-focusing) a code/diff row reveals a **+** button that opens a comment form under that line, and every thread ends with a **Reply** button. Reader comments post locally into the page — nothing is sent to a server — and the block's **Copy markdown** button serializes the fence plus every thread (authored and reader-added alike, with their `lines`/`side`/`file`/`author` anchors) back into `<Comments>` markup. Pasting that output over the source block persists the review.
+
+````mdx
+<Comments>
+
+```diff title="src/render.ts"
+@@ -40,3 +40,4 @@
+   const src = await read(path);
+-  const out = compile(src);
++  const doc = compile(src);
++  const out = minify(doc);
+```
+
+<Comment lines="41" side="old" author="@alice" severity="high">
+  Why was this inlined — is `compile()` still pure?
+</Comment>
+
+<Comment lines="41-42" author="@devin">
+The replacement keeps semantics.
+
+```diff
++  const out = minify(compile(src));
+```
+
+</Comment>
+
+</Comments>
+````
+
+Use `<Review>` for a summarized verdict report (severity tally + verdict pill); use `<Comments>` when the threads belong _on_ the code.
+
+### `<Graph title direction>` / `<Node>` / `<Edge>` / `:::graph`
+
+A static node/edge diagram — the "React Flow" shape without client JS: dagre computes the layout at render time and the output is absolute-positioned node cards over an SVG edge layer (printable, deterministic). Children are `<Node>` and `<Edge>` elements; anything else renders under the diagram.
+
+`direction` is `down` (default) / `right` / `up` / `left` — dagre `TB`/`LR`/`BT`/`RL`.
+
+`<Node>` props: `id` (required), `label` (display text, defaults to `id`), `note` (muted second line), `icon` (Iconify name), `path` + optional `lines`/`href` (file icon + editor link — something mermaid can't do), `status` (todo|doing|done|blocked → status icon), `external="true"` (dashed "outside the repo" styling).
+
+`<Edge>` props: `from` / `to` (required, node ids), `kind` (`imports` `calls` `extends` `implements` `reads` `writes` — same palette as `<Dep>`; edges without `kind` render neutral), `label` (chip at the path midpoint). Edges referencing unknown node ids are dropped.
+
+```mdx
+<Graph title="mdx → html pipeline" direction="right">
+  <Node id="doc" label="plan.mdx" path="examples/plan.mdx" />
+  <Node id="eval" label="evaluate" note="@mdx-js/mdx" />
+  <Node id="out" label="out.html" path="examples/out.html" />
+  <Edge from="doc" to="eval" kind="reads" />
+  <Edge from="eval" to="out" kind="writes" label="static markup" />
+</Graph>
+```
+
+When the nodes/edges don't need 2-D layout prefer `<Deps>` (a list); for sequence/state/ER diagrams prefer ` ```mermaid `.
+
+### `<Tests title tool>` / `<Test name status duration file>` / `:::tests`
+
+Structured test-run report. `Tests` renders a caption bar that counts `<Test>` children per status and sums parseable durations (`120ms`, `1.2s`, `2m`); `tool` adds a runner chip (`vitest`, `jest`, …). `Test` needs `name`; `status` is `pass` (default) / `fail` / `skip` / `todo`, `duration` shows right-aligned, `file`/`lines`/`href` link to the test file. Children render as an indented detail block — the failure output for `status="fail"`.
+
+```mdx
+<Tests title="render.test.ts" tool="vitest">
+  <Test name="renders markdown prose" status="pass" duration="12ms" />
+  <Test
+    name="rejects invalid props"
+    status="fail"
+    duration="800ms"
+    file="tests/render.test.ts"
+    lines="96"
+  >
+    AssertionError: expected body to contain "Invalid props"
+  </Test>
+</Tests>
+```
+
+### `<Endpoints title base>` / `<Endpoint method path auth deprecated>` / `:::endpoints`
+
+API route inventory. `Endpoint` renders a colored method chip (`GET` `POST` `PUT` `PATCH` `DELETE` `HEAD` `OPTIONS`; case-insensitive), the path in mono (with `base` prefixed in muted text), an optional `auth` chip, a `Deprecated` pill when `deprecated` is set, and children as the description.
+
+```mdx
+<Endpoints title="User service" base="/api/v1">
+  <Endpoint method="GET" path="/users">
+    List users, paginated.
+  </Endpoint>
+  <Endpoint method="POST" path="/users" auth="admin">
+    Create a user.
+  </Endpoint>
+  <Endpoint method="GET" path="/legacy/users" deprecated="true" />
+</Endpoints>
+```
+
+### `<Json title value open>` — collapsible JSON tree
+
+Renders a JSON payload as a nested tree of native `<details>` folds — no client JS; closed nodes show a `N keys`/`N items` badge. Supply the payload either as the `value` string attribute or as a fenced ` ```json ` block child (write the JSON inside the fence — bare `{…}` children are MDX expressions and rejected). `open="false"` starts every level folded. `title` adds a caption bar with a copy button. Values are typed: strings quoted/emerald, numbers sky, booleans violet, `null` dimmed; long strings truncate. Invalid JSON fails the render with `<Json> invalid JSON: …`.
+
+````mdx
+<Json title="tool result">
+
+```json
+{ "name": "mdxr", "stats": { "files": 12 }, "tags": ["agent", "render"] }
+```
+
+</Json>
+````
+
+### `<Waterfall title total unit>` / `<Span name start duration note>` / `:::waterfall`
+
+Timing waterfall — OTel-trace-style horizontal bars. Each `<Span>` needs `name` and `duration`; `start` is the offset from zero (both accept numbers or strings like `"120ms"` — the unit suffix is display-only). `total` overrides the scale end (defaults to the latest span end); `unit` labels the axis (default `ms`). Bars are colored by position automatically.
+
+```mdx
+<Waterfall title="GET /api/users" unit="ms">
+  <Span name="route match" start="0" duration="3ms" />
+  <Span name="db query" start="21" duration="120ms" note="users + roles" />
+  <Span name="serialize" start="141" duration="9ms" />
+</Waterfall>
+```
+
+### `<Ins>` / `<Del>` — inline edits
+
+Semantic `<ins>`/`<del>` inline elements for word-level changes inside a sentence or code span: `<Ins>` renders green with underline, `<Del>` red with strikethrough; `title` sets the hover tooltip. Pair them for a before→after edit.
+
+```mdx
+The compiler <Del>concatenates strings</Del> <Ins>streams tokens</Ins> and
+
+<Del>always</Del> <Ins>optionally</Ins> minifies the output.
+```

package/skill/references/components/planning.md

@@ -0,0 +1,155 @@
+# Planning & status components
+
+Index: [../components.md](../components.md). MDX attributes are always strings; `children` is Markdown.
+
+### `<Phase title="…" status="todo|doing|done|blocked" owner due>`
+
+A section heading with a status badge, plus optional owner chip and deadline. Also produced by `:::phase{title="…"}`.
+
+### `<Steps progress>` / `<Step status owner effort priority due>`
+
+Ordered, status-aware step list. `progress` on `<Steps>` renders an automatic progress bar counting `<Step>` children. `Step` accepts `owner="…"`, `effort="xs|s|m|l|xl"`, `priority="p0|p1|p2|p3"` and `due="YYYY-MM-DD"` — each renders a chip under the step text.
+
+```mdx
+<Steps progress>
+  <Step status="done">Read the existing parser</Step>
+  <Step status="doing" owner="@alice" priority="p1" due="2026-09-18">
+    Add directive transform
+  </Step>
+  <Step status="todo" effort="m">
+    Update snapshots
+  </Step>
+</Steps>
+```
+
+### `<Timeline title="…">` / `<Event date status title>`
+
+Chronological milestone list with a left rail. `Event` requires `date` (any string), optional `status` (todo|doing|done|blocked) and `title`. Also produced by `:::timeline{title="…"}`.
+
+```mdx
+<Timeline title="Milestones">
+  <Event date="2026-09-10" status="done" title="Skeleton merged" />
+  <Event date="2026-09-30" status="todo" title="v1.0 freeze" />
+</Timeline>
+```
+
+### `<Gantt title start end today>` / `<Task name start end status progress owner note>` / `<Milestone name date status owner note>` / `:::gantt`
+
+Date-based schedule chart. `<Task>` needs `name` + `start` (ISO `YYYY-MM-DD`); `end` defaults to `start` (a one-day bar). `status` (todo|doing|done|blocked) colors the bar, `progress="0–100"` shows a partial fill, `owner`/`note` add a muted sub-line. `<Milestone>` needs `name` + `date` and renders a diamond. The range spans the earliest start to the latest end; `start`/`end` on `<Gantt>` override it. A "today" marker is drawn when the render date falls inside the range — disable with `today="false"` or pin it with `today="YYYY-MM-DD"`. Axis ticks are days on short ranges, Mondays mid-range, month starts after.
+
+```mdx
+<Gantt title="v1.0 release">
+  <Task name="API design" start="2026-09-01" end="2026-09-05" status="done" />
+  <Task
+    name="Implementation"
+    start="2026-09-08"
+    end="2026-09-18"
+    status="doing"
+    progress="40"
+    owner="alice"
+  />
+  <Task name="Docs" start="2026-09-21" end="2026-09-25" />
+  <Milestone name="v1.0 freeze" date="2026-09-30" />
+</Gantt>
+```
+
+### `<Decision title="…" status="…" date="…">`
+
+Decision record (ADR-lite). `status` is `proposed|accepted|rejected|deprecated| superseded`. Children hold context and rationale. For a one-line record prefer `:::decision` (the Callout kind).
+
+```mdx
+<Decision
+  title="Use renderToStaticMarkup (sync)"
+  status="accepted"
+  date="2026-09-12"
+>
+  Documents have no data fetching — a synchronous renderer keeps the CLI simple.
+</Decision>
+```
+
+### `<Option title="…" status="recommended|considered|rejected">`
+
+Alternative-comparison card. Pair with `<Columns>` for side-by-side layout.
+
+```mdx
+<Columns>
+  <Option title="Template literals" status="rejected">
+    Escaping bugs keep recurring.
+  </Option>
+  <Option title="Component pipeline" status="recommended">
+    Deterministic + validated.
+  </Option>
+</Columns>
+```
+
+### `<Risk level="low|medium|high" title="…" mitigation="…">`
+
+Risk block with a severity pill; `mitigation` renders a dedicated line.
+
+```mdx
+<Risk level="high" title="Ecosystem drift" mitigation="Pin @mdx-js/mdx">
+  `evaluate()` semantics changed across majors before.
+</Risk>
+```
+
+### `<Approvals>` / `<Approval name role status date>`
+
+Sign-off list. `status` is `pending|approved|rejected|changes-requested`; children render as a comment next to the approver.
+
+```mdx
+<Approvals>
+  <Approval name="alice" role="tech lead" status="approved" date="2026-09-14" />
+  <Approval name="bob" role="security" status="pending" />
+</Approvals>
+```
+
+### `<Stats>` / `<Stat value label delta>`
+
+Metric card grid. `delta` colors by sign (`"+12"` green, `"-34%"` red).
+
+### `<Priority level="p0|p1|p2|p3">` / `<Effort size="xs|s|m|l|xl">` / `<Due date="YYYY-MM-DD">` / `<Owner name="…" role="…">`
+
+Inline chips: priority pill, T-shirt effort estimate (children = e.g. `3d`), deadline chip colored by urgency at render time (overdue → red, ≤3d → amber), and an initials-avatar person chip.
+
+### `<Reqs>` / `<Req id="REQ-1" status="…">`
+
+Requirement / acceptance-criteria rows: `id` renders a mono chip, optional `status` (todo|doing|done|blocked) a badge; children are the requirement text.
+
+### `<Board title>` / `<Lane title status>` / `<BoardCard title>` / `:::board`
+
+Kanban board — `Lane`s lay out side by side (horizontal scroll on narrow viewports); the header shows a status dot plus a card-count badge. `BoardCard` requires `title`; optional `status` icon plus the same inline chips as `Step` (`priority`, `effort`, `owner`, `due`); children are a muted description. Interactive: readers can drag cards between lanes (or use the ‹ › buttons on each card), and "Copy markdown" copies the current arrangement as `<Board>` markup to paste back into the source.
+
+```mdx
+<Board title="Sprint 12">
+  <Lane title="Todo" status="todo">
+    <BoardCard title="Write migration guide" priority="p1" owner="alice" />
+  </Lane>
+  <Lane title="In progress" status="doing">
+    <BoardCard title="Graph component" status="doing" due="2026-09-20">
+      dagre layout + svg edges
+    </BoardCard>
+  </Lane>
+  <Lane title="Done" status="done">
+    <BoardCard title="Ship v0.1" status="done" />
+  </Lane>
+</Board>
+```
+
+### `<Matrix title cols="…">` / `:::matrix{cols="…"}`
+
+Comparison matrix. `cols` is a comma-separated header row; each top-level list item is one matrix row — the item text before the first `|` is the row label, the `|`-separated rest are cells. Cell values `yes`/`ok`/`✓`/`○`, `no`/`✗`/`×`/`ng`, `partial`/`~`/`△`/`warn`, and `-`/`—`/`?` render as icons; anything else renders as text.
+
+```mdx
+<Matrix title="Renderer comparison" cols="mdxr, raw mdx, astro">
+  - standalone html | yes | no | partial - editor links | yes | no | no -
+  hydration | no | yes | yes
+</Matrix>
+```
+
+### `<Summary done="3" total="8" label="Progress" />`
+
+Progress bar.
+
+### `<StatusBadge status="…" />`
+
+Standalone status pill.