@suzumiyaaoba/mdxr 0.1.0

package/skill/references/components/reports.md

@@ -0,0 +1,252 @@
+# Reports — code review, CI checks, audits, metrics, config, ops & releases
+
+Index: [../components.md](../components.md). MDX attributes are always strings; `children` is Markdown.
+
+This file covers report-shaped deliverables a coding agent produces beyond plans and investigations: review results, verification status, security/dependency scans, quantitative metrics, config documentation, and ops/release summaries.
+
+### `<Review title verdict>` / `<Comment severity title file>` / `:::review`
+
+Code-review result. `Review` tallies `<Comment>` children by severity in a summary line and shows an optional `verdict` pill — `approve` (green, "Approved"), `changes` (amber, "Changes requested"), `comment` (sky, "Commented"). `Comment` renders a numbered card: `severity` is `critical|high|medium|low|info` (default `info`), `title` is a bold headline, `file`/`lines`/`href` link to the code location, children are the finding text (a ` ```diff ` fence inside makes a great suggestion block).
+
+```mdx
+<Review title="PR #42 review" verdict="changes">
+  <Comment
+    severity="high"
+    file="src/mdx.ts"
+    lines="42-58"
+    title="Unbounded recursion"
+  >
+    The visitor recurses without a depth cap — a hostile doc can overflow the
+    stack.
+  </Comment>
+  <Comment severity="low" title="Naming nit">
+    `out` → `result` reads better at the call site.
+  </Comment>
+</Review>
+```
+
+### `<Verdict status title label>` / `:::verdict`
+
+Standalone verdict banner — a colored edge panel with a status pill. `status` is `approve`/`pass` (green), `warn` (amber), `fail` (red), `info` (sky); `label` overrides the pill text; children are the rationale. Use at the top or bottom of any report to state the conclusion ("do not merge", "safe to deploy", "migration is reversible").
+
+```mdx
+<Verdict status="warn" title="Deploy with care">
+  Schema change ships without a backfill — run it off-peak.
+</Verdict>
+```
+
+### `<Severity level>`
+
+Inline severity pill: `critical|high|medium|low|info`. Reused by `<Comment>`, `<Vuln>` and `<Incident>`; use standalone inside prose or tables.
+
+### `<Checks title context>` / `<Check name status duration required>` / `:::checks`
+
+CI/verification status list — the "checks" tab of a PR. `Checks` counts `<Check>` children per status and sums parseable durations in the caption; `context` adds a chip (commit SHA, PR number). `Check` needs `name`; `status` is `pass` (default) / `fail` / `running` / `pending` / `skip`, `duration` shows right-aligned, `required` adds a Required chip, `href` links to the job log. Children render as an indented log excerpt — red-tinted when the check failed.
+
+```mdx
+<Checks title="CI — main" context="a1b2c3d">
+  <Check name="lint" status="pass" duration="32s" required />
+  <Check name="test" status="fail" duration="4m12s" required>
+    AssertionError in render.test.ts
+  </Check>
+  <Check name="deploy" status="pending" />
+</Checks>
+```
+
+For unit-test runs prefer `<Tests>` (pass/fail/skip/todo per assertion); `Checks` models pipeline stages (lint/build/deploy).
+
+### `<Audit title tool>` / `<Vuln severity id package affected fix>` / `:::audit`
+
+Vulnerability/audit report. `Audit` counts `<Vuln>` children per severity in the caption; `tool` adds a scanner chip (`npm audit`, `osv`, `trivy`). `Vuln` renders: severity pill, optional `title`, `id` (CVE/GHSA — `href` links it to the advisory), `package` + `affected` range in mono, `→ fix` version in green, and a `wontfix` badge. Children are the description.
+
+```mdx
+<Audit title="Dependency audit" tool="npm audit">
+  <Vuln
+    severity="critical"
+    id="GHSA-35jh-r3h4-6jhm"
+    package="minimatch"
+    affected="<3.1.2"
+    fix="3.1.2"
+    href="https://github.com/advisories/GHSA-35jh-r3h4-6jhm"
+    title="ReDoS in brace expansion"
+  />
+  <Vuln severity="low" package="left-pad" wontfix="true">
+    No fix planned upstream.
+  </Vuln>
+</Audit>
+```
+
+### `<Bumps title>` / `<Bump name from to kind breaking cves>` / `:::bumps`
+
+Dependency upgrade plan. `Bumps` counts major/minor/patch bumps in the caption. `Bump` needs `name`; `from`/`to` display as `old → new` and the kind (`major`=red, `minor`=amber, `patch`=neutral) is **auto-detected from the versions** — `kind` only overrides. `breaking` adds a warning chip, `cves="2"` shows the CVEs the upgrade fixes, `href` links to the changelog, `note`/children carry the plan detail.
+
+```mdx
+<Bumps title="Dependency upgrades">
+  <Bump name="react" from="18.3.1" to="19.3.0" breaking />
+  <Bump name="minimatch" from="3.0.9" to="3.1.2" cves="2" note="security" />
+</Bumps>
+```
+
+### `<Packages title>` / `<Package name version kind license>` / `:::packages`
+
+Package inventory — a flat list with a total count in the caption. `Package` needs `name`; `version`, `kind` (`dep`=sky, `dev`=neutral, `peer`=violet, `optional`=amber), `license`, `href` (registry/repo link), `note`/children for the "why it's here".
+
+```mdx
+<Packages title="Direct dependencies">
+  <Package name="react" version="19.3.0" kind="dep" license="MIT" />
+  <Package name="ultracite" version="7.11.1" kind="dev" />
+</Packages>
+```
+
+### `<Gauges title unit>` / `<Gauge value target tone label path>` / `:::gauges`
+
+Percent-bar list — coverage reports, score breakdowns, progress by area. `Gauge` needs `value` (0–100, or a fraction via `max`). Color is automatic: with `target`, green when met else red; without, graded 80/50 bands — `tone` (`emerald|amber|red|sky|violet|neutral`) pins it. Label via `label` or `path` (a real file becomes an editor link); `detail` adds a muted second line ("412/500 lines").
+
+```mdx
+<Gauges title="Coverage by area" unit="lines">
+  <Gauge path="src/mdx.ts" value="82" target="80" detail="412/500 lines" />
+  <Gauge path="src/cli.ts" value="45" detail="90/200 lines" />
+</Gauges>
+```
+
+### `<Score value max label detail>` — 0-100 ring gauge
+
+Circular score gauge — health scans, lint scores, quality grades. `value` is required (`max` changes the denominator); 80+ green, 50+ amber, below red. `label` names the metric, `detail` the sub-line. Inline-flex sized — group several in `<Row>` or `<Grid>`.
+
+```mdx
+<Row>
+  <Score value="87" label="react-doctor" detail="0 errors, 2 warnings" />
+  <Score value="9" max="10" label="a11y audit" />
+</Row>
+```
+
+### `<Spark values tone label>` — inline sparkline
+
+Tiny inline trend line for prose. `values` is a comma/space-separated number list, `tone` a color, `label` the accessible name. Renders nothing with <2 points.
+
+```mdx
+p95 latency improved <Spark values="120,110,96,88,71,65" tone="emerald" /> over 6 runs.
+```
+
+### `<Benchmarks title better unit>` / `<Bench name before after>` / `:::benchmarks`
+
+Before/after measurement table. `Bench` needs `name`; `before`/`after` show as `old → new` and the % delta is computed automatically (`unit` suffixes are display-only). `Benchmarks better="lower"` (for latency/size) flips the delta color: improvement = green trend-up, regression = red trend-down; default is `higher`. `note`/children carry caveats.
+
+```mdx
+<Benchmarks title="render bench" better="lower" unit="ms">
+  <Bench name="small doc" before="120" after="98" />
+  <Bench name="large doc" before="820ms" after="910ms" />
+</Benchmarks>
+```
+
+For timing _within_ one operation (span offsets) prefer `<Waterfall>`; `Benchmarks` compares two runs.
+
+### `<DiffStat files adds dels>` — diff size summary
+
+The `+N −M across F files` stat from a PR header, as an inline chip with a proportional green/red bar. All attributes are numbers; `files` is optional.
+
+```mdx
+The PR touched <DiffStat files="12" adds="340" dels="120" /> in the renderer.
+```
+
+### `<Schema title engine>` / `<DbTable name note>` / `<DbField name type pk fk>` / `:::schema`
+
+Database schema documentation. `Schema` is a section wrapper (`engine` shows muted, e.g. `postgres 16`). `DbTable` is a bordered block per table (`name` required, `note` for row counts/engine). `DbField` is one column row: `name` + `type` required, `pk`/`fk="table.col"`/`unique`/`null` render constraint chips, `default` shows `= value`; children are the column description.
+
+```mdx
+<Schema title="Data model" engine="postgres 16">
+  <DbTable name="users" note="core accounts">
+    <DbField name="id" type="uuid" pk />
+    <DbField name="email" type="text" unique />
+    <DbField name="org_id" type="uuid" fk="orgs.id" null />
+  </DbTable>
+</Schema>
+```
+
+### `<EnvVars title>` / `<EnvVar name required secret value default>` / `:::envvars`
+
+Environment-variable reference. `EnvVars` shows a count chip and a copy button that copies all variable names. `EnvVar` needs `name`; `required` adds an amber chip, `value`/`default` display the value (`default:` prefix for defaults), `secret` masks the value as `••••••••` plus a secret chip — never write real secrets, mark them instead. Children are the description.
+
+```mdx
+<EnvVars title="Runtime config">
+  <EnvVar name="DATABASE_URL" required secret>
+    Primary Postgres connection.
+  </EnvVar>
+  <EnvVar name="LOG_LEVEL" default="info" />
+</EnvVars>
+```
+
+### `<StatusPage title updated>` / `<Service name status uptime>` / `:::statuspage`
+
+Service-health summary. `StatusPage` rolls up the worst `<Service>` status into the caption ("All systems operational" / Degraded / Outage / Maintenance); `updated` shows a muted timestamp. `Service` needs `name`; `status` is `operational` (default) / `degraded` / `outage` / `maintenance` with a status dot + pill, `uptime` shows right-aligned, children describe the impact.
+
+```mdx
+<StatusPage title="System status" updated="2m ago">
+  <Service name="API" status="operational" uptime="99.98%" />
+  <Service name="Dashboard" status="degraded">
+    Elevated p95 since the 14:00 deploy.
+  </Service>
+</StatusPage>
+```
+
+### `<Uptime title pct from to>` / `<Day status date note>` / `:::uptime`
+
+Statuspage-style uptime bar — one cell per day. `Uptime` shows `title`, `pct` (`"99.9"` renders `99.9%`), and `from`/`to` end labels under the bar. `Day` status is `up` (green, default) / `degraded` (amber) / `down` (red) / `maint` (sky) / `none` (gray); `date`/`note` compose the hover tooltip.
+
+```mdx
+<Uptime title="API — last 7 days" pct="99.9" from="Sep 12" to="today">
+  <Day status="up" date="Sep 12" />
+  <Day status="degraded" date="Sep 13" note="deploy" />
+  <Day status="down" date="Sep 14" note="INC-12" />
+</Uptime>
+```
+
+### `<Release version date href title>` / `<Entry kind scope>` / `:::release`
+
+Release notes / changelog block. `Release` needs `version` (shown mono in the caption; `date`, compare `href`, optional `title` prefix). `<Entry>` children are **auto-grouped by kind** into headed sections regardless of write order: `breaking` → `added` → `changed` → `deprecated` → `removed` → `fixed` → `security`, each with an icon and count. `scope` adds a `cli:`-style prefix chip; children are the entry text. Non-Entry children render at the bottom.
+
+```mdx
+<Release
+  version="v0.2.0"
+  date="2026-09-19"
+  href="https://github.com/acme/app/compare/v0.1.0...v0.2.0"
+>
+  <Entry kind="breaking" scope="cli">
+    Renamed `--html` to `--format`.
+  </Entry>
+  <Entry kind="added">New report components.</Entry>
+  <Entry kind="fixed">Stdin piping no longer hangs.</Entry>
+</Release>
+```
+
+### `<Pathway title>` / `<Stop label status note current>` / `:::pathway`
+
+Horizontal stepper for migration/rollout paths — version upgrade routes (v17→v18→v19), environment promotion (dev→staging→prod), phased rollouts. `Stop` needs `label`; `status` is `todo|doing|done|blocked` (same icon set as `<StatusBadge>`), `note` a sub-line, `current` rings the active stop. Connectors draw automatically between stops; overflow scrolls.
+
+```mdx
+<Pathway title="Upgrade path">
+  <Stop label="v17" status="done" note="current" />
+  <Stop label="v18" status="doing" note="codemod" current />
+  <Stop label="v19" status="todo" />
+</Pathway>
+```
+
+For dated milestones prefer `<Timeline>`; `Pathway` is for _sequences_ (no dates).
+
+### `<Incident title severity status …>` / `:::incident`
+
+Incident/postmortem header block. `title` is required; `severity` (shared scale) and `status` (`investigating`=orange, `identified`=amber, `monitoring`=sky, `resolved`=emerald) render as pills. `started`/`detected`/`resolved`/`duration` become a labeled meta row, `impact` a red highlighted line. Children are the summary; follow with `<Timeline>` for the event sequence and `<Steps>` for action items.
+
+```mdx
+<Incident
+  title="Production DB wiped"
+  severity="critical"
+  status="resolved"
+  started="09:12 UTC"
+  resolved="09:46 UTC"
+  duration="34m"
+  impact="production DB + backups deleted"
+>
+  An unscoped API token used by the nightly cleanup job had delete permissions.
+</Incident>
+```

package/skill/references/components/shadcn.md

@@ -0,0 +1,19 @@
+# shadcn/ui components (Base UI)
+
+Index: [../components.md](../components.md). MDX attributes are always strings; `children` is Markdown.
+
+The full shadcn/ui set (Base UI primitives) is registered: `Button`, `Badge`, `Card`/`CardHeader`/…, `Alert`, `Tabs`, `Accordion`, `Dialog`, `Input`, `Label`, `Table`, `Progress`, `Skeleton`, `Separator`, `Kbd`, `Spinner`, and more — run `mdxr catalog` for the complete list. Use them as plain MDX elements; attributes are strings (`variant="outline"`, `size="sm"`).
+
+**Note:** rendered documents include a hydration bundle, so stateful primitives (`Dialog`, `Tabs`, `Accordion`, `Tooltip`, `Select`, `Switch`, menus, …) are interactive in the browser — tabs switch, accordions open, switches flip. `mdxr render --no-hydrate` emits purely static HTML where they render their initial state only. Portal-based overlays (`Dialog`, `Tooltip`, `Select`, menus) still render nothing until opened — prefer `Card`, `Alert`, `Badge`, `Table`, `Kbd`, `Separator`, `Progress`, `Skeleton` for always-visible content.
+
+```mdx
+<Alert>
+  <AlertTitle>Heads up</AlertTitle>
+  <AlertDescription>Fully static and safe in documents.</AlertDescription>
+</Alert>
+
+<Badge variant="secondary">beta</Badge>
+<Button variant="outline">Action</Button>
+```
+
+Theme: shadcn CSS variables (`--primary`, `--background`, …) are emitted with the document CSS; `.dark` variants follow `prefers-color-scheme` via a `<html>` class toggle.

package/skill/references/components.md

@@ -0,0 +1,186 @@
+# mdxr component reference
+
+MDX attributes are always strings (`status="done"`). `children` is Markdown.
+
+This file is an index: each group lists what its components do and links to a detail file with full signatures and examples. Read only the detail file(s) the document needs. The syntax cheatsheet at the bottom maps Markdown shorthands (`:::x`, fences, frontmatter) to the component they produce. `mdxr catalog --json` is the machine-readable source of truth for component names and attributes.
+
+**File links.** Components carrying `path` (`FileRef`, `SymbolRef`, `File`, `TraceFrame`, `FlowStep`, `Change`) and fenced-code filename headers become editor links — `vscode://file/…` by default — when the file exists on disk (paths resolve relative to the document). Frontmatter `editor:` or `editor` in `mdxr.config.ts` picks another editor: `cursor`, `zed`, `vscode-insiders`, `windsurf`, `sublime`, `textmate`, `idea`, a custom `{path}`/`{line}` URL template, or `none` to disable. `href="…"` on a component overrides the URL entirely. Inline code works too: `` `src/mdx.ts` `` (optional `:40-52` lines suffix) auto-converts to `<FileRef>` when it resolves to a real file — a bare `mdx.ts` without a `/` stays plain code.
+
+## Document scaffolding — details: [components/document.md](components/document.md)
+
+| Component | What it is |
+| --- | --- |
+| `<Plan>` | Document root — title header, status badge, meta row (auto-built from frontmatter) |
+| `<Meta>` / `<MetaItem>` | Metadata row (`Date · Owner · …`); custom items with an icon |
+| `<Callout>` | Highlighted block — `:::note`/`:::warning`/`:::goal`/`:::decision`/…, `> [!NOTE]` |
+| `<Details>` | Collapsible section on native `<details>` (works without JS) |
+| `<Toc>` | Collapsible, auto-built table of contents — `:::toc` |
+| `<Glossary>` / `<Term>` | Definition list for domain terms |
+| `<Figure>` | Image with a caption |
+| `<Ref>` / `<Issue>` / `<PR>` / `<Commit>` | Linked reference card / inline GitHub chips |
+| `<Cmd>` | Inline command chip with copy button |
+| `<Icon>` | Inline Iconify SVG — `lucide` + `vscode-icons` bundled, no runtime fetch |
+| fenced code / math | Highlighted code block with filename bar and line markers; ` ```mermaid ` diagrams; KaTeX `$…$` |
+
+## Planning & status — details: [components/planning.md](components/planning.md)
+
+| Component | What it is |
+| --- | --- |
+| `<Phase>` | Section heading with a status badge — `:::phase` |
+| `<Steps>` / `<Step>` | Status-aware task list with optional progress bar; owner/effort/priority/due chips |
+| `<Timeline>` / `<Event>` | Dated milestone rail — `:::timeline` |
+| `<Gantt>` / `<Task>` / `<Milestone>` | Date-based schedule chart — `:::gantt` |
+| `<Decision>` | ADR-lite decision record (one-liner → `:::decision` callout) |
+| `<Option>` | Alternative-comparison card (recommended/considered/rejected) |
+| `<Risk>` | Risk block — severity pill + mitigation line |
+| `<Approvals>` / `<Approval>` | Sign-off list |
+| `<Stats>` / `<Stat>` | Metric card grid; `delta` colored by sign |
+| `<Priority>` `<Effort>` `<Due>` `<Owner>` | Inline chips (priority, T-shirt effort, deadline, person) |
+| `<Reqs>` / `<Req>` | Requirement / acceptance-criteria rows |
+| `<Board>` / `<Lane>` / `<BoardCard>` | Interactive kanban — lanes with status dots and card counts; cards drag between lanes, "Copy markdown" copies the updated `<Board>` markup — `:::board` |
+| `<Matrix>` | Comparison grid — nested list rows, `yes`/`no`/`partial`/`✓`/`✗`/`△` cells render as icons — `:::matrix` |
+| `<Summary>` | Progress bar |
+| `<StatusBadge>` | Standalone status pill |
+
+## Code investigation — details: [components/investigation.md](components/investigation.md)
+
+| Component | What it is |
+| --- | --- |
+| `<Findings>` / `<Finding>` | Numbered findings with confidence pills — `:::findings` |
+| `<Hypotheses>` / `<Hypothesis>` | Hypothesis ledger (supported/refuted/untested) — `:::hypotheses` |
+| `<Terminal>` | Command transcript (`$` prompts, output, exit badge) — `:::terminal`, ` ```console ` |
+| `<Trace>` / `<TraceFrame>` | Stack/call trace with error line, dimmed lib frames — `:::trace` |
+| `<Searches>` / `<Search>` | Search-query log (pattern/scope/tool/hits) — `:::searches` |
+| `<Files>` / `<File>` | Related-file inventory — `:::files` |
+| `<Deps>` / `<Dep>` | Dependency-edge list — `:::deps` |
+| `<Changes>` / `<Change>` | Change-set list (add/modify/delete/rename) |
+| `<Flow>` / `<FlowStep>` | Numbered call/execution chain — `:::flow` |
+| `<Tree>` | File tree from a nested list — collapsible folders, `…` placeholders, bold highlights, automatic icons |
+| `<FileRef>` | Inline file-reference chip with copy button |
+| `<SymbolRef>` | Inline symbol chip (fn/type/class/…) |
+| `<CodeFile>` | Embeds a real file from disk as a code block |
+| `<Props>` / `<Prop>` | API/props table for a component or function |
+
+## Output artifacts — details: [components/output.md](components/output.md)
+
+| Component | What it is |
+| --- | --- |
+| ` ```diff ` / ` ```patch ` fence | Structured per-file diff cards — editor links, `+N −M` stats, hunk line numbers |
+| `<Comments>` / `<Comment>` | GitHub-style comment threads anchored to code/diff lines — `lines`/`side`/`file` anchors, MDX bodies — `:::comments` |
+| `<Graph>` / `<Node>` / `<Edge>` | Static node/edge diagram — dagre layout at render time, SVG edges, editor-linked nodes — `:::graph` |
+| `<Tests>` / `<Test>` | Test-run report — status pills, auto counts and duration sum — `:::tests` |
+| `<Endpoints>` / `<Endpoint>` | API route list — method chips, `base` prefix, `auth`/`deprecated` — `:::endpoints` |
+| `<Json>` | Collapsible JSON tree on nested `<details>` — `value` attr or fenced child |
+| `<Waterfall>` / `<Span>` | Timing waterfall (OTel-trace-style bars) — `:::waterfall` |
+| `<Ins>` / `<Del>` | Inline word-level edits — semantic `<ins>`/`<del>` |
+
+## Reports — details: [components/reports.md](components/reports.md)
+
+Review results, verification status, security/dependency scans, metrics, config docs, and ops/release summaries.
+
+| Component | What it is |
+| --- | --- |
+| `<Review>` / `<Comment>` | Code-review report — numbered findings with severity pills, `file:line` links, verdict pill + severity tally — `:::review` |
+| `<Verdict>` | Colored verdict banner — approve/pass/warn/fail/info — `:::verdict` |
+| `<Severity>` | Inline severity pill — critical/high/medium/low/info |
+| `<Checks>` / `<Check>` | CI check list — status icons, required chips, auto counts + duration sum — `:::checks` |
+| `<Audit>` / `<Vuln>` | Vulnerability report — severity tally, CVE/GHSA links, fix versions — `:::audit` |
+| `<Bumps>` / `<Bump>` | Dependency upgrade plan — `from → to`, auto major/minor/patch detection — `:::bumps` |
+| `<Packages>` / `<Package>` | Package inventory — kind/license chips, count caption — `:::packages` |
+| `<Gauges>` / `<Gauge>` | Percent-bar list — coverage/scores with auto pass/fail coloring — `:::gauges` |
+| `<Score>` | 0–100 ring gauge — health/quality scores |
+| `<Spark>` | Inline sparkline for prose trends |
+| `<Benchmarks>` / `<Bench>` | Before/after measurement table — auto % delta, `better="lower"` flips colors — `:::benchmarks` |
+| `<DiffStat>` | Inline `+N −M across F files` chip with proportional bar |
+| `<Schema>` / `<DbTable>` / `<DbField>` | Database schema docs — PK/FK/unique/null chips — `:::schema` |
+| `<EnvVars>` / `<EnvVar>` | Env-var reference — required/secret chips, masked values, name-copy button — `:::envvars` |
+| `<StatusPage>` / `<Service>` | Service-health summary — worst-status rollup, uptime figures — `:::statuspage` |
+| `<Uptime>` / `<Day>` | Statuspage-style daily uptime bar — `:::uptime` |
+| `<Release>` / `<Entry>` | Release notes — entries auto-grouped by kind (breaking/added/…/security) — `:::release` |
+| `<Pathway>` / `<Stop>` | Migration/rollout stepper — version paths, env promotion — `:::pathway` |
+| `<Incident>` | Incident/postmortem header — severity + status pills, timeline meta, impact line — `:::incident` |
+
+## Data visualization — details: [components/charts.md](components/charts.md)
+
+All charts are static SVG/HTML at render time (no client JS); `tone` pins a color, `unit` labels values.
+
+| Component | What it is |
+| --- | --- |
+| `<BarChart>` / `<Bar>` | Category comparison — vertical/horizontal, grouped or stacked series — `:::barchart` |
+| `<LineChart>` / `<Series>` | Trend lines over ordered categories; `area` fill, `dash` series — `:::linechart` |
+| `<PieChart>` / `<Slice>` | Part-of-whole pie/donut with legend — `:::piechart` |
+| `<Scatter>` / `<Point>` | Two-axis correlation; `size` bubbles — `:::scatter` |
+| `<Radar>` / `<Series>` | Spider chart on 3+ shared axes — `:::radar` |
+| `<Funnel>` / `<Stage>` | Stage-by-stage narrowing with conversion percents — `:::funnel` |
+| `<Quadrant>` / `<Pin>` | 2-axis positioning map with labeled regions — `:::quadrant` |
+| `<Bridge>` / `<Delta>` | Running-total waterfall (start→deltas→end) — `:::bridge` |
+| `<Treemap>` / `<Tile>` | Squarified part-of-whole areas — `:::treemap` |
+| `<Sankey>` / `<Link>` / `<Node>` | Flow split/merge across stage columns — `:::sankey` |
+| `<Venn>` / `<Set>` / `<Overlap>` | 2–3 set overlap diagram — `:::venn` |
+
+## Layout — details: [components/layout.md](components/layout.md)
+
+| Component | What it is |
+| --- | --- |
+| `<Columns>` / `<Column>` | Simple side-by-side grid (2–4 columns) |
+| `<Grid>` / `<Cell>` | 12-track grid — spans, dense flow, auto-fit card grids |
+| `<Row>` | Horizontal flex-wrap row — groups inline components (`Button`, `Badge`, …) that MDX would otherwise render glued together |
+| `<Stack>` | Vertical stack with `gap` — for margin-less components (`Input`, `Textarea`, `Progress`, …) |
+| `<Before>` / `<After>` | Red/green compare panels |
+
+## Reader input — details: [components/forms.md](components/forms.md)
+
+| Component | What it is |
+| --- | --- |
+| `<Ask>` / `<Question>` / `<Choice>` | Native-form question blocks; answers show live as Markdown to copy or save |
+
+## shadcn/ui — details: [components/shadcn.md](components/shadcn.md)
+
+The full shadcn/ui (Base UI) set is registered (`Button`, `Card`, `Table`, `Tabs`, …). Rendered documents carry a hydration bundle, so stateful primitives (`Tabs`, `Accordion`, `Switch`, …) are interactive in the browser — pass `--no-hydrate` for purely static output.
+
+## Project-defined components — details: [extending.md](extending.md)
+
+Projects can register their own components via `mdxr.config.ts` + `defineComponent`; a same-name component overrides the built-in.
+
+## Syntax cheatsheet
+
+Markdown shorthands and what they render as — the reverse lookup of the index above.
+
+| Write | Get |
+| --- | --- |
+| `:::note` / `:::warning` / `:::decision` … | `<Callout kind>` |
+| `:::goal` / `:::nongoal` / `:::question` / `:::answer` | goal / non-goal / open-question / conclusion callouts |
+| `> [!NOTE]` GitHub alert | `<Callout>` |
+| `:::phase{title="…" status="doing"}` | `<Phase>` |
+| `:::flow{title="…"}` + `<FlowStep>` | `<Flow>` numbered call/execution chain |
+| `:::findings` + `<Finding confidence>` | findings list with confidence pills |
+| `:::hypotheses` + `<Hypothesis status>` | hypothesis ledger (supported/refuted/untested) |
+| `:::searches` + `<Search pattern hits>` | search-query log |
+| `:::trace` + `<TraceFrame>` | stack/call trace with error line |
+| `:::terminal{cmd="…" exit="…"}` / ` ```console ` fence | terminal transcript |
+| `:::files` / `:::deps` | `<Files>` related-file list / `<Deps>` dependency edges |
+| `:::tests` + `<Test>` / `:::endpoints` + `<Endpoint>` | `<Tests>` run report / `<Endpoints>` API list |
+| `:::review{verdict="changes"}` + `<Comment severity file>` | `<Review>` code-review report |
+| `:::verdict{status="approve"}` | `<Verdict>` conclusion banner |
+| `:::checks` + `<Check status>` / `:::audit` + `<Vuln severity>` | `<Checks>` CI status / `<Audit>` vulnerability report |
+| `:::bumps` + `<Bump from to>` / `:::packages` + `<Package>` | `<Bumps>` upgrade plan / `<Packages>` inventory |
+| `:::gauges` + `<Gauge value>` / `:::benchmarks` + `<Bench before after>` | `<Gauges>` percent bars / `<Benchmarks>` compare table |
+| `:::schema` + `<DbTable>`/`<DbField>` / `:::envvars` + `<EnvVar>` | `<Schema>` DB docs / `<EnvVars>` env reference |
+| `:::statuspage` + `<Service>` / `:::uptime` + `<Day>` | `<StatusPage>` health summary / `<Uptime>` daily bar |
+| `:::release{version="…"}` + `<Entry kind>` / `:::pathway` + `<Stop>` / `:::incident` | `<Release>` notes / `<Pathway>` stepper / `<Incident>` postmortem |
+| `:::board` + `<Lane>`/`<BoardCard>` | `<Board>` kanban |
+| `:::graph` + `<Node>`/`<Edge>` | `<Graph>` static node/edge diagram (dagre layout, no client JS) |
+| `:::waterfall` + `<Span>` / `:::matrix` + list | `<Waterfall>` timing bars / `<Matrix>` comparison grid |
+| `:::timeline{title="…"}` | `<Timeline>` |
+| `:::gantt{title="…"}` + `<Task>`/`<Milestone>` | `<Gantt>` date-based schedule chart |
+| `:::barchart` / `:::linechart` / `:::piechart` / `:::scatter` / `:::radar` / `:::funnel` / `:::quadrant` / `:::bridge` / `:::treemap` / `:::sankey` / `:::venn` | static chart panels — see [components/charts.md](components/charts.md) |
+| frontmatter `status:` / `date:` / `owner:` | document header badge + meta row |
+| `path`-carrying components (`<FileRef>`, `<File>`, `<TraceFrame>`, `<FlowStep>`, `<Change>`, `<SymbolRef path>`) + `title="…"` code headers | `vscode://file/…` editor links when the file exists; frontmatter `editor:` picks the scheme (`cursor`, `zed`, `none`, …) |
+| `` `src/x.ts` `` inline code naming a real file (optional `:L`/`:L-M`) | `<FileRef>` chip — icon, copy button, editor link (a bare `x.ts` stays plain code) |
+| ` ```mermaid ` fenced block | rendered diagram |
+| ` ```diff ` / ` ```patch ` fenced block | structured per-file diff cards |
+| `:::comments` + fence + `<Comment lines>` | line-anchored comment threads on code/diff |
+| ` ```ts title="src/x.ts" ` | highlighted code block + filename bar with file-type icon |
+| `- [ ]` / `- [x]` | styled task list |
+| nested list inside `<Tree>` | file tree |
+| `<Icon name="lucide:rocket">` / `icon-[lucide--rocket]` class | inline Iconify icon |

package/skill/references/extending.md

@@ -0,0 +1,48 @@
+# Project-defined components
+
+Index: [components.md](components.md).
+
+Create `mdxr.config.ts` in the project root:
+
+```ts
+import { defineConfig } from "@suzumiyaaoba/mdxr";
+
+export default defineConfig({
+  components: "./components/index.tsx", // named exports become MDX components
+  theme: "./mdxr.css", // optional: @theme token overrides
+  editor: "vscode", // optional: file-link target — see below
+});
+```
+
+`editor` sets the URL scheme for file links (`path`-carrying components and code-block filename headers): `vscode` (default), `cursor`, `zed`, `vscode-insiders`, `windsurf`, `sublime`, `textmate`, `idea`, a custom template like `"myed://open?f={path}&l={line}"`, or `"none"` to disable. Frontmatter `editor:` overrides it per document.
+
+Define components with `defineComponent` (adds a valibot schema — used for runtime validation **and** `mdxr catalog` documentation):
+
+```tsx
+// components/index.tsx
+import { defineComponent, v } from "@suzumiyaaoba/mdxr";
+
+export const LinkCard = defineComponent(
+  {
+    description: "External reference card",
+    schema: v.looseObject({ href: v.string(), title: v.string() }),
+  },
+  ({ href, title, children }) => (
+    <a
+      href={href}
+      target="_blank"
+      rel="noopener noreferrer"
+      className="block rounded-lg border p-3 no-underline"
+    >
+      <div className="font-medium">{title} ↗</div>
+      {children}
+    </a>
+  )
+);
+```
+
+- Tailwind classes in custom components are compiled automatically.
+- `import { Callout, StatusBadge } from '@suzumiyaaoba/mdxr/components'` to compose built-ins.
+- A project component with the same name as a built-in overrides it (a warning is printed).
+- Project components join the hydration bundle — hooks (`useState`, `useContext`, …) work, so they can be interactive in the rendered HTML (e.g. a counter). With `--no-hydrate` they render initial state only.
+- Components must still be synchronous — no Suspense / data fetching.

package/src/ask-sheet.ts

@@ -0,0 +1,40 @@
+/**
+ * The Markdown answer-sheet format shared by SSR (`<Ask>`'s seeded output)
+ * and the live client (`syncAsk` in doc-events.ts): `# title` followed by
+ * one `- **label**: answer` line per question. A single formatter keeps the
+ * two emitters byte-identical — the client's rewrite must reproduce what
+ * SSR wrote or hydration diffs would flash the pane.
+ */
+
+export interface SheetEntry {
+  /** The answer text; `""` renders as an unanswered (blank) item. */
+  answer: string;
+  /** The raw question label — escaping happens here. */
+  label: string;
+}
+
+// A newline in the label would split the list item — collapse it; `\`/`*`
+// are escaped so they can't break the surrounding `**…**` emphasis.
+const sheetLabel = (raw: string): string =>
+  raw
+    .replaceAll(/\s+/gu, " ")
+    .trim()
+    .replaceAll("\\", "\\\\")
+    .replaceAll("*", "\\*");
+
+const sheetTitle = (raw: string | undefined): string => {
+  const t = (raw ?? "Answers").replaceAll(/\s+/gu, " ").trim();
+  return t === "" ? "Answers" : t;
+};
+
+/** `# title` + `- **label**: answer` lines; multi-line answers indent. */
+export const formatAnswerSheet = (
+  title: string | undefined,
+  entries: readonly SheetEntry[]
+): string => {
+  const lines = entries.map(({ answer, label }) => {
+    const a = answer.replaceAll("\n", "\n  ");
+    return `- **${sheetLabel(label)}**:${a === "" ? "" : ` ${a}`}`;
+  });
+  return `# ${sheetTitle(title)}\n\n${lines.length === 0 ? "(no questions)" : lines.join("\n")}`;
+};