r-markdown-cli 0.1.0 → 0.1.1

package/dist/cli.js

@@ -11975,7 +11975,7 @@ async function createPreviewServer(file, options = {}) {
 
 // packages/cli/src/index.js
 var USAGE = `
-Rich Markdown (rmd) CLI v0.2.0
+Rich Markdown (rmd) CLI v0.1.1
 
 Usage:
   rmd <command> [options]
@@ -12045,7 +12045,7 @@ async function main(argv = process.argv.slice(2), io = defaultIo()) {
       return 0;
     }
     if (command === "--version" || command === "-v") {
-      io.stdout(`rmd v0.2.0
+      io.stdout(`rmd v0.1.1
 `);
       return 0;
     }
@@ -12131,8 +12131,9 @@ function parseInitArgs(args) {
 function resolveSkillSource(platform) {
   const __dirname2 = dirname2(fileURLToPath2(import.meta.url));
   const candidates = [
-    resolve2(__dirname2, "../assets/skills", platform),
-    resolve2(__dirname2, "../../../skills", platform)
+    resolve2(__dirname2, "../skills", platform),
+    resolve2(__dirname2, "../../../skills", platform),
+    resolve2(__dirname2, "../assets/skills", platform)
   ];
   return candidates.find((candidate) => existsSync(candidate));
 }

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "r-markdown-cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "bin": {
     "rmd": "dist/cli.js"
   },
   "files": [
     "dist",
+    "skills",
     "README.md"
   ],
   "workspaces": [

package/skills/claude/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: rich-markdown
+description: Generate Rich Markdown (.rmd) source and self-contained interactive HTML artifacts. Use when the user asks for rmd, Rich Markdown, rich interactive Markdown, token-efficient rich docs, shareable AI documents, charts, sliders, copy/export blocks, flow diagrams, timelines, kanban boards, collapsible details, carousels, embeds, math blocks, comparison reports, PR explainers, tunable prototypes, project status reports, or any rich document that should remain readable as Markdown but render as a polished interactive HTML page.
+---
+
+# Rich Markdown
+
+Use this skill when the user wants a rich, readable, interactive document
+instead of plain Markdown or hand-written HTML. The local renderer
+(`packages/cli`) turns `.rmd` source into a self-contained HTML artifact that
+renders in Claude's chat / desktop sandbox, in any browser, or as an offline file.
+
+## Why .rmd over plain Markdown or HTML
+
+- Source stays close to Markdown — diff-friendly, AI-friendly, low-token.
+- The renderer adds charts, layouts, sliders, exports, flows, timelines, etc.
+  without forcing you to write SVG/CSS/JS.
+- One source file, one self-contained HTML. No external assets needed for
+  Claude-rendered artifacts.
+
+## Output Choice (decide before writing)
+
+| User intent | What to produce |
+|---|---|
+| Wants source only | `.rmd` file, no HTML build |
+| Wants something to view / share / archive | `.rmd` + `--mode self-contained` HTML |
+| Wants smallest artifact + has network | `.rmd` + `--mode cdn` HTML |
+| Wants inspectable assets they can host themselves | `.rmd` + `--mode split` directory |
+| Wants to demo locally during the session | `rmd open` preview server |
+
+When unsure, default to source `.rmd` plus a `self-contained` HTML build.
+
+## Workflow
+
+1. Decide the smallest useful block set from `references/blocks.md`. Use
+   plain Markdown for narrative; use `:::` blocks only when they add density,
+   structure, or interaction.
+
+2. Write the `.rmd` file. Always include a YAML frontmatter with at least
+   `title`. Suggested location: `examples/<short-name>.rmd`.
+
+3. Validate the source with the Bash tool:
+
+   ```bash
+   npm run rmd -- validate path/to/doc.rmd
+   ```
+
+   If validation fails, fix the source. Do not return a file that fails
+   validation.
+
+4. Build the artifact:
+
+   ```bash
+   # Default: single self-contained HTML
+   npm run rmd -- build path/to/doc.rmd --mode self-contained --out path/to/doc.html
+
+   # CDN-loaded variant (small artifact, requires network at view time)
+   npm run rmd -- build path/to/doc.rmd --mode cdn --version 0.1.0 --out path/to/doc.html
+
+   # Split directory (HTML + JS + CSS as separate files)
+   npm run rmd -- build path/to/doc.rmd --mode split --out path/to/dist/index.html
+   ```
+
+5. (Optional) Local preview during the session:
+
+   ```bash
+   npm run rmd -- open path/to/doc.rmd --port 0 --host 127.0.0.1 --no-open true
+   ```
+
+   The CLI prints the bound URL. Use `--no-open true` so the agent does not
+   try to launch a desktop browser.
+
+6. Return the generated HTML file path to the user. If self-contained, the
+   file alone is the deliverable.
+
+## Rules (these are hard constraints)
+
+- **No styling in source.** Never write colors, pixel sizes, fonts, or layout
+  CSS into `.rmd`. Use semantic attributes like `emphasis=primary` and let
+  the theme decide visuals. (Themes can change; source must not.)
+
+- **Diff-clean edits.** One semantic change should touch only nearby lines.
+  Don't reorder unrelated attributes or rewrite a whole file for a small fix.
+
+- **Validate before shipping.** Validation failures are not warnings. Fix
+  the source before returning the artifact.
+
+- **Plain Markdown for fragile content.** Use plain Markdown — code blocks,
+  tables, blockquotes — for anything you're unsure how to express in `.rmd`.
+  Don't invent block names.
+
+- **Self-contained for sandboxes.** If the user will view the artifact inside
+  Claude's sandbox, in email, or anywhere external assets can't be fetched,
+  use `--mode self-contained`. `split` mode will not load in those contexts.
+
+## Block Selection Cheatsheet
+
+Map the user's intent to the smallest block set that delivers value:
+
+| Intent | Blocks |
+|---|---|
+| Compare options / approaches | `grid` + `chart` + `callout` |
+| PR / code review explainer | `diff` + `tabs` + `callout` |
+| Tunable prototype (params + copy back to chat) | `slider` + `export` |
+| Release / workflow | `flow` + `callout` + `timeline` |
+| Project status report | `chart` + `timeline` + `kanban` |
+| Research brief | `chart` + `grid` + `details` |
+| Showcase / gallery | `carousel` + `grid layout=masonry` |
+| Long doc with collapsible appendix | `details` + `tabs` |
+| Math / formal explanation | `math` + `callout` |
+
+The 14 supported blocks (v0.2): `chart`, `grid`, `callout`, `slider`,
+`export`, `flow`, `diff`, `tabs`, `timeline`, `kanban`, `details`, `carousel`,
+`embed`, `math`. Full reference: `references/blocks.md`.
+
+## Default Recipe
+
+For Claude-visible rich output:
+
+1. Write `examples/<short-name>.rmd` with appropriate blocks.
+2. `npm run rmd -- validate examples/<short-name>.rmd`
+3. `npm run rmd -- build examples/<short-name>.rmd --mode self-contained --out examples/<short-name>.html`
+4. Return `examples/<short-name>.html` as the deliverable.
+
+See `examples/` in this skill for two ready-to-study patterns:
+- `examples/decision-report.rmd` — comparison + chart + callout
+- `examples/tunable-config.rmd` — slider + export + flow
+
+## References
+
+- `references/blocks.md` — all 14 block types with attributes and examples
+- `references/artifacts.md` — build modes, validation, frontmatter tips

package/skills/claude/examples/decision-report.rmd

@@ -0,0 +1,64 @@
+---
+title: "Storage Tier Decision Report"
+theme: default
+share: team
+description: "Comparison of hot/warm/cold storage strategies for the analytics pipeline."
+---
+
+# Storage Tier Decision Report
+
+We need to pick a storage strategy for the analytics pipeline that handles
+~3 TB/day. Three candidates evaluated against latency, cost, and operational
+complexity.
+
+## Candidates
+
+:::grid 3
+### Hot only
+All data on NVMe SSD.
+**Pros**: lowest read latency (≈2 ms).
+**Cons**: $$$ per TB; capacity ceiling reached in ~6 months.
+---
+### Tiered (hot + cold)
+Recent 7 days on SSD, older on object storage.
+**Pros**: 70% cost reduction, latency unchanged for typical queries.
+**Cons**: needs lifecycle automation; cold-restore latency 30-60 s.
+---
+### Cold only
+Everything on object storage with index cache.
+**Pros**: cheapest; effectively unlimited.
+**Cons**: P95 read latency 1.5 s, breaks the SLA for live dashboards.
+:::
+
+## Cost vs Latency
+
+:::chart bar title="Monthly cost (k$) vs P95 read latency (ms)" y="cost(k$)" y2="P95(ms)" legend=top
+HotOnly      48 2
+Tiered       14 2
+ColdOnly     3  1500
+:::
+
+## Recommendation
+
+:::callout tip title="Pick Tiered"
+Tiered storage hits the SLA, costs roughly a third of hot-only, and the
+lifecycle automation is a one-time investment we already use for backups.
+:::
+
+## Rollout Plan
+
+:::flow direction=lr
+Spec -> Review -> Migrate cold path -> Enable lifecycle -> Monitor
+Migrate cold path -> Issue -> Pause and audit
+:::
+
+## Risk Register
+
+:::details title="Operational risks and mitigations"
+1. **Cold restore stalls during peak query**: cap concurrent restore jobs;
+   surface a "restoring" badge in the UI so users don't retry.
+2. **Lifecycle policy misfires and deletes hot data**: dry-run mode for first
+   7 days; alert on >1% delta vs expected size.
+3. **Object storage region outage**: keep last 24h of cold data mirrored to a
+   second region; documented failover runbook.
+:::

package/skills/claude/examples/tunable-config.rmd

@@ -0,0 +1,53 @@
+---
+title: "Rate Limiter Config — Tune & Copy"
+theme: default
+share: private
+description: "Adjust the token-bucket parameters and copy the resulting YAML."
+---
+
+# Rate Limiter Config — Tune & Copy
+
+Drag the sliders to tune the token-bucket rate limiter. The export button
+below copies the matching YAML config straight to your clipboard.
+
+## Parameters
+
+:::slider name=capacity label="Bucket capacity" min=10 max=2000 step=10 default=200 unit=req
+:::
+
+:::slider name=refill_rate label="Refill rate" min=1 max=500 step=1 default=50 unit=req/s
+:::
+
+:::slider name=burst_window label="Burst window" min=1 max=120 step=1 default=10 unit=s
+:::
+
+## Generated YAML
+
+:::export label="Copy YAML config" format=text
+rate_limiter:
+  type: token_bucket
+  capacity: {{capacity | int}}
+  refill_rate: {{refill_rate | int}}
+  burst_window_seconds: {{burst_window | int}}
+:::
+
+## How requests flow
+
+:::flow direction=lr
+Request -> Bucket has token? -> Allow
+Bucket has token? -> Refill check -> Allow
+Bucket has token? -> Refill check -> Reject 429
+:::
+
+## Tradeoffs
+
+:::callout warning title="Watch the burst window"
+A wide burst window smooths short spikes but lets sustained overload through
+longer. If your downstream is fragile, prefer narrow windows even at the cost
+of more 429s.
+:::
+
+:::callout tip title="Sane starting point"
+For most APIs, capacity ≈ 4× refill rate, burst window ≈ 10 s. Adjust from
+there based on observed P99 incident shape.
+:::

package/skills/claude/references/artifacts.md

@@ -0,0 +1,118 @@
+# Rich Markdown Artifacts
+
+## Source First
+
+Always write `.rmd` source first. It is the canonical artifact and must remain
+readable in plain Markdown tools. The HTML build is a derived view that can
+be regenerated any time.
+
+## Three Build Modes
+
+The CLI supports three output modes via `--mode`. Pick based on where the
+artifact will be viewed.
+
+### self-contained (default)
+
+```bash
+npm run rmd -- build path/to/doc.rmd --mode self-contained --out path/to/doc.html
+```
+
+Single HTML file with the renderer, theme CSS, runtime, and `.rmd` source all
+inlined. Zero external dependencies. Best for:
+
+- Claude desktop / chat sandbox (the artifact has to be self-contained)
+- Email attachments
+- Offline / archival
+- S3 / static-host one-click sharing
+- Any place where the consumer cannot install or fetch the renderer
+
+Tradeoff: file size is larger (~50–150 KB) because the renderer is inlined.
+
+### cdn
+
+```bash
+npm run rmd -- build path/to/doc.rmd --mode cdn --version 0.1.0 --out path/to/doc.html
+```
+
+Small HTML shell containing only the `.rmd` source plus a script tag pointing
+at a pinned CDN version of the renderer. Best for:
+
+- Blog posts, Notion, web pages where the renderer can be fetched from CDN
+- When the artifact itself must be small (token economy)
+
+Requires `--version` to be a complete semver (e.g. `0.1.0`); `latest` is rejected
+because sandboxed viewers must not depend on a moving CDN target.
+
+### split
+
+```bash
+npm run rmd -- build path/to/doc.rmd --mode split --out path/to/dist/index.html
+```
+
+Writes the HTML alongside `rmd.min.js` and `themes/<theme>.css` as separate
+files in the same directory. Best for:
+
+- Local development / hot reload
+- Custom hosting where you want to serve the renderer from your own origin
+- Inspecting the generated assets
+
+Cannot be opened in sandboxed environments (Claude artifact, email) because
+the relative asset paths will 404.
+
+## Validation
+
+Always validate before building or returning to the user:
+
+```bash
+npm run rmd -- validate path/to/doc.rmd
+```
+
+Validation prints `ok` on success or a list of `path: message` lines on failure.
+If validation fails, fix the source and re-run. Do not ship a file that fails
+validation — the renderer may degrade silently to plain code blocks.
+
+## Recommended Default
+
+For most Claude-driven requests:
+
+```bash
+npm run rmd -- validate examples/my-doc.rmd
+npm run rmd -- build examples/my-doc.rmd --mode self-contained --out examples/my-doc.html
+```
+
+Return the path `examples/my-doc.html`.
+
+## Local Preview During the Session
+
+When the user wants to interact with the artifact while you iterate:
+
+```bash
+npm run rmd -- open path/to/doc.rmd --port 0 --host 127.0.0.1 --no-open true
+```
+
+The CLI prints the bound URL. Use `--no-open true` so the agent does not try
+to launch a desktop browser.
+
+## Frontmatter Tips
+
+Every `.rmd` should start with a frontmatter block. Useful fields:
+
+```yaml
+---
+title: Quarterly Roadmap        # Required for sharing & metadata
+theme: default                  # Theme id; only `default` ships today
+share: private                  # private / team / public
+description: Short summary...   # Used by share cards / OG
+lang: zh-CN                     # BCP 47 — affects type/font defaults
+---
+```
+
+Unknown fields are kept but ignored. Custom fields should use the `x-` prefix
+to mark them as non-core (e.g. `x-team: backend`).
+
+## Iteration Loop
+
+When the user asks for revisions, re-run validate and build only — do not
+rewrite unrelated parts of the source. The skill optimizes for clean diffs;
+preserve the user's existing block structure unless they explicitly ask
+otherwise.

package/skills/claude/references/blocks.md

@@ -0,0 +1,334 @@
+# Rich Markdown Blocks (v0.2)
+
+Complete reference for the 14 blocks supported by the current renderer
+(`packages/blocks-core`). Use the smallest set that conveys meaning. Prefer
+plain Markdown for narrative.
+
+Identifiers are case-sensitive. Attribute order does not matter; positional
+arguments come immediately after the block name.
+
+---
+
+## chart
+
+Compact data visualization. Each line is `{label} {value} [{value2} ...]`,
+space-separated. Multi-value rows become multi-series.
+
+```rmd
+:::chart bar title="P99 latency (ms)" emphasis=primary
+TokenBucket 23
+LeakyBucket 19
+SlidingWindow 41
+:::
+```
+
+Types (positional, required): `bar`, `line`, `pie`, `scatter`, `radar`, `area`,
+`donut`, `heatmap`. `pie` requires single value per row.
+
+| attribute | values | default | notes |
+|---|---|---|---|
+| `title` | string | empty | chart title |
+| `x` / `y` / `y2` | string | null | axis labels (use `y2` for dual axis) |
+| `legend` | `top` / `bottom` / `left` / `right` / `none` | `bottom` | legend position |
+| `tooltip` | `true` / `false` | `true` | hover tooltip |
+| `emphasis` | `primary` / `secondary` / `none` | `none` | theme-controlled accent |
+
+Multi-series + dual axis:
+
+```rmd
+:::chart area title="Revenue vs MAU" y="Revenue($M)" y2="MAU(K)" legend=top
+Q1_2025 120 40
+Q2_2025 150 45
+Q3_2025 180 60
+Q4_2025 240 85
+:::
+```
+
+---
+
+## grid
+
+Multi-column layout. Cells separated by `---` on their own line.
+
+```rmd
+:::grid 3
+### Option A
+Fast, simple.
+---
+### Option B
+Flexible, heavier.
+---
+### Option C
+Safe, slower.
+:::
+```
+
+Positional: column count (1–12) or comma-separated responsive breakpoints
+(e.g. `1,2,4` for mobile/tablet/desktop).
+
+| attribute | values | default | notes |
+|---|---|---|---|
+| `gap` | `sm` / `md` / `lg` | `md` | column spacing |
+| `layout` | `default` / `masonry` | `default` | masonry uses CSS columns (no JS) |
+
+`grid` cannot nest inside another `grid`. Maximum 12 cells.
+
+---
+
+## callout
+
+Emphasized note, decision, or warning.
+
+```rmd
+:::callout tip title="Recommendation"
+Pick token bucket for burst-friendly traffic.
+:::
+```
+
+Positional kind: `info` / `tip` / `warning` / `danger` / `success`.
+Optional `title`.
+
+---
+
+## slider
+
+Reader-adjustable number. Pair with `export` to copy the tuned value back.
+
+```rmd
+:::slider name=capacity min=10 max=1000 step=10 default=200 unit=req
+:::
+```
+
+Range slider (two values):
+
+```rmd
+:::slider name=qps_range label="QPS window" min=10 max=1000 step=10 default=100,500 scale=log marks=10,100,500,1000
+:::
+```
+
+Required: `name` (matches `^[a-zA-Z_][a-zA-Z0-9_]*$`), `min`, `max` (`max > min`).
+
+| attribute | type | default | notes |
+|---|---|---|---|
+| `step` | number > 0 | `1` | |
+| `default` | number or `n,m` | `min` | range slider when comma value |
+| `unit` | string | empty | suffix shown after value |
+| `label` | string | name | display label |
+| `scale` | `linear` / `log` / `pow` | `linear` | |
+| `marks` | comma-separated numbers | empty | discrete snap points |
+
+Slider names must be unique per document. Block body must be empty.
+
+---
+
+## export
+
+Copy/export template. References slider values with `{{name}}` and supports
+`{{name | int}}` formatting.
+
+```rmd
+:::export label="Copy config" format=text
+rate_limiter:
+  capacity: {{capacity | int}}
+  refill_rate: {{refill_rate | int}}
+:::
+```
+
+| attribute | values | default | notes |
+|---|---|---|---|
+| `label` | string | `复制` | button text |
+| `format` | `text` / `markdown` / `json` | `text` | clipboard MIME |
+
+Unknown variables render as `[未定义:name]` and warn in the console.
+
+---
+
+## flow
+
+Directed flow with linear and branching paths.
+
+```rmd
+:::flow direction=lr
+Design -> Review -> Canary -> Full rollout
+Canary -> Incident -> Rollback
+:::
+```
+
+Each line: `Node -> Node -> ...`. Same-name nodes merge.
+`direction`: `lr` (default) or `tb`.
+
+---
+
+## diff
+
+Unified-diff style. `+` add, `-` remove, leading space context.
+`@注: ...` adds an inline note (placed at end of `+`/`-` line).
+
+```rmd
+:::diff lang=python title="Limiter change"
+- @rate_limit(window=60, max=100)
++ @token_bucket(capacity=200, refill=50) @注: adds burst protection
+:::
+```
+
+---
+
+## tabs
+
+Multiple views in one area. `@label` on its own line starts a panel.
+
+```rmd
+:::tabs default=Summary
+@Summary
+Plain-language explanation.
+@Details
+Implementation details.
+:::
+```
+
+Cannot nest inside another `tabs`.
+
+---
+
+## timeline
+
+Vertical or horizontal sequence of dated events.
+
+```rmd
+:::timeline
+@ 2026-01-01 [title="Kickoff"] [status="success"]
+Initial planning done, team formed.
+
+@ 2026-03-15 [title="v0.1"] [status="success"]
+Core parser shipped.
+
+@ 2026-05-10 [title="v0.2"] [status="pending"]
+Advanced blocks + masonry grid.
+:::
+```
+
+Each item begins with `@ {time} [title="..."] [status="..."]` on its own line.
+Body is normal Markdown until the next `@`.
+
+`status`: `success` / `warning` / `danger` / `pending` / `default`.
+`direction`: `vertical` (default) or `horizontal`.
+
+---
+
+## kanban
+
+Columns of cards. `@ {column title}` on its own line starts a column.
+
+```rmd
+:::kanban
+@ Todo
+- [ ] Write the report
+- [ ] Run perf tests
+
+@ In progress
+- [x] Update parser
+- [x] Refactor theme
+
+@ Done
+* All conformance tests pass
+* Carousel uses pure CSS
+:::
+```
+
+Use lists (Markdown task lists or bullets) for cards.
+
+---
+
+## details
+
+Collapsible block. Wraps a native `<details>`.
+
+```rmd
+:::details title="Architecture changelog" open=true
+1. Parser: custom rule dispatch on top of markdown-it.
+2. Validator: 20+ new rules for new tree shapes.
+3. Renderer: pure HTML output, no React/Vue dependency.
+:::
+```
+
+| attribute | values | default |
+|---|---|---|
+| `title` | string | empty |
+| `open` | `true` / `false` | `false` |
+
+---
+
+## carousel
+
+Touch / scroll-snap carousel. Cells separated by `---`.
+
+```rmd
+:::carousel autoplay=true interval=4000
+### Slide 1
+First content
+---
+### Slide 2
+Second content
+:::
+```
+
+| attribute | values | default |
+|---|---|---|
+| `autoplay` | `true` / `false` | `false` |
+| `interval` | number (ms) | `3000` |
+
+---
+
+## embed
+
+Embed external media (video, map, app). Aspect ratio is theme-controlled.
+
+```rmd
+:::embed type=video id="https://www.youtube.com/embed/XXXX" aspect-ratio="16/9"
+:::
+```
+
+| attribute | values | default |
+|---|---|---|
+| `type` | `video` / `map` / `iframe` | `unknown` |
+| `id` | URL or external id | empty |
+| `aspect-ratio` | `16/9` / `4/3` / etc. | null |
+
+Block body is ignored.
+
+---
+
+## math
+
+LaTeX math block. Renderer outputs as math container; the active theme
+decides whether to typeset (KaTeX/MathJax) or fall back to monospace.
+
+```rmd
+:::math
+\mathcal{L} = \sum_{i=1}^{N} \left( y_i \log(\hat{y}_i) + (1-y_i) \log(1-\hat{y}_i) \right)
+:::
+```
+
+---
+
+## Choosing Blocks
+
+| Goal | Suggested blocks |
+|---|---|
+| Compare options | `grid` + `chart` + `callout` |
+| Explain a PR | `diff` + `tabs` + `callout` |
+| Tunable prototype | `slider` + `export` |
+| Release / workflow | `flow` + `callout` + `timeline` |
+| Status report | `chart` + `timeline` + `kanban` |
+| Research brief | `chart` + `grid` + `callout` + `details` |
+| Long doc with appendix | `details` + `tabs` |
+| Visual gallery | `carousel` + `grid layout=masonry` |
+| Math / formal | `math` + `callout` |
+
+## Don't
+
+- Don't add CSS, color, pixel, or font attributes — they belong to the theme.
+- Don't nest `grid` in `grid`, or `tabs` in `tabs`.
+- Don't put body content inside `:::slider` or `:::embed`.
+- Don't invent positional arguments beyond what's listed here.
+- Don't use experimental block names that aren't in this file.

package/skills/codex/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: rich-markdown
+description: Generate Rich Markdown (.rmd) documents and self-contained Rich Markdown HTML artifacts for AI-authored reports, plans, comparisons, PR explanations, prototypes, research briefs, timelines, kanbans, and tunable interactive demos. Use when the user asks for rmd, Rich Markdown, rich interactive Markdown, token-efficient rich docs, shareable AI documents, charts, sliders, export/copy blocks, flow diagrams, timelines, kanban boards, collapsible details, carousels, embeds, math blocks, or wants a Codex response rendered with the local Rich Markdown renderer.
+---
+
+# Rich Markdown
+
+Use this skill when the user wants a rich, readable, interactive document
+instead of plain Markdown or hand-written HTML. The local renderer
+(`packages/cli`) turns `.rmd` source into a self-contained HTML artifact.
+
+## Output Choice
+
+- User wants a file or artifact: write a `.rmd` file first, then build HTML.
+- User wants something viewable inside Codex or shareable as one file:
+  build a self-contained HTML artifact from the `.rmd`.
+- User wants source only: output `.rmd` source, do not build HTML.
+- User wants a multi-file site (assets they can inspect or host): use `--mode split`.
+
+## Workflow
+
+1. Choose the smallest useful block set from `references/blocks.md`.
+   Plain Markdown for narrative, `:::` blocks only when they add density,
+   structure, or interaction.
+2. Write the `.rmd` to a sensible path under `examples/` (or wherever the
+   user asks). Always include a YAML frontmatter with at least `title`.
+3. Validate the source. Fail fast if the parser reports issues:
+
+   ```bash
+   npm run rmd -- validate path/to/doc.rmd
+   ```
+
+4. Build for the chosen consumption mode:
+
+   ```bash
+   # Single self-contained HTML — best default for Codex Desktop / sharing
+   npm run rmd -- build path/to/doc.rmd --mode self-contained --out path/to/doc.html
+
+   # CDN-loaded variant — small artifact, requires network at view time
+   npm run rmd -- build path/to/doc.rmd --mode cdn --version 0.1.0 --out path/to/doc.html
+
+   # Split mode — index.html + rmd.min.js + themes/<name>.css for inspection / hosting
+   npm run rmd -- build path/to/doc.rmd --mode split --out path/to/dist/index.html
+   ```
+
+5. For local interactive preview (will start a local HTTP server):
+
+   ```bash
+   npm run rmd -- open path/to/doc.rmd --port 0 --no-open true
+   ```
+
+6. Report the generated HTML path back to the user.
+
+## Rules
+
+- Never put colors, pixels, fonts, or layout styling into `.rmd`. Use
+  `emphasis=primary|secondary|none` and let the theme decide visuals.
+- Keep source diff clean: one semantic edit should touch only nearby lines.
+  Do not reorder unrelated attributes or rewrite whole files for tiny changes.
+- Unknown or fragile content (rare formats, edge cases) must fall back to
+  plain Markdown rather than invented block names.
+- Use `:::slider` + `:::export` whenever the reader should tune values and
+  copy the result back to Codex or to code.
+- Validation failures are not warnings: fix the source, do not ship the file.
+
+## Block Selection Cheatsheet
+
+Map the user's intent to the smallest block set that delivers value:
+
+| Intent | Blocks |
+|---|---|
+| Compare options / approaches | `grid` + `chart` + `callout` |
+| PR / code review explainer | `diff` + `tabs` + `callout` |
+| Tunable prototype | `slider` + `export` |
+| Release / workflow | `flow` + `callout` + `timeline` |
+| Project status report | `chart` + `timeline` + `kanban` |
+| Research brief | `chart` + `grid` + `details` |
+| Showcase / gallery | `carousel` + `grid layout=masonry` |
+| Long doc with appendix | `details` + `tabs` |
+| Math / formal explanation | `math` + `callout` |
+
+Full block reference: `references/blocks.md`.
+Build mode reference: `references/artifacts.md`.
+
+## Default Recipe
+
+For Codex-visible rich output:
+
+1. Write `examples/<short-name>.rmd` with appropriate blocks.
+2. `npm run rmd -- validate examples/<short-name>.rmd`
+3. `npm run rmd -- build examples/<short-name>.rmd --mode self-contained --out examples/<short-name>.html`
+4. Return `examples/<short-name>.html` as the deliverable.

package/skills/codex/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Rich Markdown"
+  short_description: "Generate interactive .rmd documents"
+  brand_color: "#2563EB"
+  default_prompt: "Use $rich-markdown to create a self-contained interactive .rmd HTML report."
+
+policy:
+  allow_implicit_invocation: true

package/skills/codex/references/artifacts.md

@@ -0,0 +1,107 @@
+# Rich Markdown Artifacts
+
+## Source First
+
+Always write `.rmd` source first. It is the canonical artifact and must remain
+readable in plain Markdown tools. The HTML build is a derived view.
+
+## Three Build Modes
+
+The CLI supports three output modes via `--mode`. Pick based on where the
+artifact will be viewed.
+
+### self-contained (default)
+
+```bash
+npm run rmd -- build path/to/doc.rmd --mode self-contained --out path/to/doc.html
+```
+
+Produces a single HTML file with the renderer, theme CSS, runtime, and `.rmd`
+source all inlined. Zero external dependencies. Best for:
+
+- Codex Desktop (loads inside the app sandbox)
+- Email attachments
+- Offline / archival
+- S3 / static-host one-click sharing
+- Any place where the consumer cannot install or fetch the renderer
+
+Tradeoff: file size is larger (~50–150 KB) because the renderer ships in-line.
+
+### cdn
+
+```bash
+npm run rmd -- build path/to/doc.rmd --mode cdn --version 0.1.0 --out path/to/doc.html
+```
+
+Produces a small HTML shell containing only the `.rmd` source and a script tag
+pointing at a pinned CDN version. Best for:
+
+- Blog posts / Notion / web pages where the renderer can be fetched from CDN
+- Cases where token economy of the artifact itself matters most
+
+Requires `--version` to be a complete semver (e.g. `0.1.0`); `latest` is rejected
+because sandboxed viewers must not depend on a moving CDN target.
+
+### split
+
+```bash
+npm run rmd -- build path/to/doc.rmd --mode split --out path/to/dist/index.html
+```
+
+Writes the HTML alongside `rmd.min.js` and `themes/<theme>.css` as separate
+files. Best for:
+
+- Local development / hot reload
+- Custom hosting where you want to serve the renderer from your own origin
+- Inspecting the generated assets
+
+Cannot be opened in sandboxed environments (Codex Desktop artifact, email)
+because relative asset paths will 404.
+
+## Validation
+
+Always validate before building or returning to the user:
+
+```bash
+npm run rmd -- validate path/to/doc.rmd
+```
+
+If validation fails, fix the source. Do not ship a file that fails validation.
+
+## Recommended Default for Codex
+
+For most Codex-driven requests:
+
+```bash
+npm run rmd -- validate examples/my-doc.rmd
+npm run rmd -- build examples/my-doc.rmd --mode self-contained --out examples/my-doc.html
+```
+
+Return the path `examples/my-doc.html`.
+
+## Local Preview
+
+When the user wants to interact with the artifact during the session:
+
+```bash
+npm run rmd -- open path/to/doc.rmd --port 0 --host 127.0.0.1 --no-open true
+```
+
+The CLI prints the bound URL. Use `--no-open true` so the agent does not try
+to launch a desktop browser.
+
+## Frontmatter Tips
+
+Every `.rmd` should start with a frontmatter block. Useful fields:
+
+```yaml
+---
+title: Quarterly Roadmap        # Required for sharing & metadata
+theme: default                  # Theme id; only `default` ships today
+share: private                  # private / team / public
+description: Short summary...   # Used by share cards / OG
+lang: zh-CN                     # BCP 47 — affects type/font defaults
+---
+```
+
+Unknown fields are kept but ignored; custom fields should use `x-` prefix.

package/skills/codex/references/blocks.md

@@ -0,0 +1,321 @@
+# Rich Markdown Blocks (v0.2)
+
+These are the blocks supported by the current renderer (`packages/blocks-core`).
+Use the smallest set that conveys meaning. Prefer plain Markdown for narrative.
+
+Identifiers (block names, slider variable names) are case-sensitive.
+Attribute order does not matter; positional arguments come immediately after the
+block name.
+
+## chart
+
+Compact data visualization. Each line is `{label} {value} [{value2} ...]`.
+Values are space-separated. Multi-value rows become multi-series.
+
+```rmd
+:::chart bar title="P99 latency (ms)" emphasis=primary
+TokenBucket 23
+LeakyBucket 19
+SlidingWindow 41
+:::
+```
+
+Types (positional, required): `bar`, `line`, `pie`, `scatter`, `radar`, `area`,
+`donut`, `heatmap`. `pie` requires single value per row.
+
+Attributes:
+
+| name | values | default | notes |
+|---|---|---|---|
+| `title` | string | empty | chart title |
+| `x` / `y` / `y2` | string | null | axis labels (use `y2` for dual axis) |
+| `legend` | `top` / `bottom` / `left` / `right` / `none` | `bottom` | legend position |
+| `tooltip` | `true` / `false` | `true` | hover tooltip |
+| `emphasis` | `primary` / `secondary` / `none` | `none` | theme-controlled accent |
+
+Multi-series example:
+
+```rmd
+:::chart area title="Revenue vs MAU" y="Revenue($M)" y2="MAU(K)" legend=top
+Q1_2025 120 40
+Q2_2025 150 45
+Q3_2025 180 60
+Q4_2025 240 85
+:::
+```
+
+## grid
+
+Multi-column layout. Cells separated by `---` on their own line.
+
+```rmd
+:::grid 3
+### Option A
+Fast, simple.
+---
+### Option B
+Flexible, heavier.
+---
+### Option C
+Safe, slower.
+:::
+```
+
+Positional: column count (1–12) or comma-separated responsive breakpoints
+(e.g. `1,2,4` for mobile/tablet/desktop).
+
+Attributes:
+
+| name | values | default | notes |
+|---|---|---|---|
+| `gap` | `sm` / `md` / `lg` | `md` | column spacing |
+| `layout` | `default` / `masonry` | `default` | masonry uses CSS columns (no JS) |
+
+`grid` cannot nest inside another `grid`. Maximum 12 cells.
+
+## callout
+
+Emphasized note, decision, or warning.
+
+```rmd
+:::callout tip title="Recommendation"
+Pick token bucket for burst-friendly traffic.
+:::
+```
+
+Positional kind: `info` / `tip` / `warning` / `danger` / `success`.
+Optional `title` attribute.
+
+## slider
+
+Reader-adjustable number with optional range/log/marks. Pair with `export`.
+
+```rmd
+:::slider name=capacity min=10 max=1000 step=10 default=200 unit=req
+:::
+```
+
+Range slider (two values):
+
+```rmd
+:::slider name=qps_range label="QPS window" min=10 max=1000 step=10 default=100,500 scale=log marks=10,100,500,1000
+:::
+```
+
+Required: `name` (matches `^[a-zA-Z_][a-zA-Z0-9_]*$`), `min`, `max` (`max > min`).
+
+Attributes:
+
+| name | type | default | notes |
+|---|---|---|---|
+| `step` | number > 0 | `1` | |
+| `default` | number or `n,m` | `min` | range slider when comma value |
+| `unit` | string | empty | suffix shown after value |
+| `label` | string | name | display label |
+| `scale` | `linear` / `log` / `pow` | `linear` | |
+| `marks` | comma-separated numbers | empty | discrete snap points |
+
+Slider names must be unique per document. Block body must be empty.
+
+## export
+
+Copy/export template. References slider values with `{{name}}` and supports
+`{{name | int}}` formatting.
+
+```rmd
+:::export label="Copy config" format=text
+rate_limiter:
+  capacity: {{capacity | int}}
+  refill_rate: {{refill_rate | int}}
+:::
+```
+
+Attributes:
+
+| name | values | default | notes |
+|---|---|---|---|
+| `label` | string | `复制` | button text |
+| `format` | `text` / `markdown` / `json` | `text` | clipboard MIME |
+
+Unknown variables render as `[未定义:name]` and warn in the console.
+
+## flow
+
+Directed flow with linear and branching paths.
+
+```rmd
+:::flow direction=lr
+Design -> Review -> Canary -> Full rollout
+Canary -> Incident -> Rollback
+:::
+```
+
+Each line: `Node -> Node -> ...`. Same-name nodes merge.
+`direction`: `lr` (default) or `tb`.
+
+## diff
+
+Unified-diff style. `+` add, `-` remove, leading space context.
+`@注: ...` adds an inline note (placed at end of `+`/`-` line).
+
+```rmd
+:::diff lang=python title="Limiter change"
+- @rate_limit(window=60, max=100)
++ @token_bucket(capacity=200, refill=50) @注: adds burst protection
+:::
+```
+
+## tabs
+
+Multiple views in one area. `@label` on its own line starts a panel.
+
+```rmd
+:::tabs default=Summary
+@Summary
+Plain-language explanation.
+@Details
+Implementation details.
+:::
+```
+
+Cannot nest inside another `tabs`.
+
+## timeline
+
+Vertical or horizontal sequence of dated events.
+
+```rmd
+:::timeline
+@ 2026-01-01 [title="Kickoff"] [status="success"]
+Initial planning done, team formed.
+
+@ 2026-03-15 [title="v0.1"] [status="success"]
+Core parser shipped.
+
+@ 2026-05-10 [title="v0.2"] [status="pending"]
+Advanced blocks + masonry grid.
+:::
+```
+
+Each item begins with `@ {time} [title="..."] [status="..."]` on its own line.
+Body is normal Markdown until the next `@`.
+
+`status`: `success` / `warning` / `danger` / `pending` / `default`.
+`direction`: `vertical` (default) or `horizontal`.
+
+## kanban
+
+Columns of cards. `@ {column title}` on its own line starts a column.
+
+```rmd
+:::kanban
+@ Todo
+- [ ] Write the report
+- [ ] Run perf tests
+
+@ In progress
+- [x] Update parser
+- [x] Refactor theme
+
+@ Done
+* All conformance tests pass
+* Carousel uses pure CSS
+:::
+```
+
+Use lists (Markdown task lists or bullets) for cards.
+
+## details
+
+Collapsible block. Wraps a native `<details>`.
+
+```rmd
+:::details title="Architecture changelog" open=true
+1. Parser: custom rule dispatch on top of markdown-it.
+2. Validator: 20+ new rules for new tree shapes.
+3. Renderer: pure HTML output, no React/Vue dependency.
+:::
+```
+
+Attributes:
+
+| name | values | default |
+|---|---|---|
+| `title` | string | empty |
+| `open` | `true` / `false` | `false` |
+
+## carousel
+
+Touch / scroll-snap carousel. Cells separated by `---`.
+
+```rmd
+:::carousel autoplay=true interval=4000
+### Slide 1
+First content
+---
+### Slide 2
+Second content
+---
+### Slide 3
+Third content
+:::
+```
+
+Attributes:
+
+| name | values | default |
+|---|---|---|
+| `autoplay` | `true` / `false` | `false` |
+| `interval` | number (ms) | `3000` |
+
+## embed
+
+Embed external media (video, map, app). Theme-controlled aspect ratio.
+
+```rmd
+:::embed type=video id="https://www.youtube.com/embed/XXXX" aspect-ratio="16/9"
+:::
+```
+
+Attributes:
+
+| name | values | default |
+|---|---|---|
+| `type` | `video` / `map` / `iframe` | `unknown` |
+| `id` | URL or external id | empty |
+| `aspect-ratio` | `16/9` / `4/3` / etc. | null |
+
+Block body is ignored.
+
+## math
+
+LaTeX math block. Renderer outputs as math container; the active theme decides
+whether to typeset (KaTeX/MathJax) or fall back to monospace.
+
+```rmd
+:::math
+\mathcal{L} = \sum_{i=1}^{N} \left( y_i \log(\hat{y}_i) + (1-y_i) \log(1-\hat{y}_i) \right)
+:::
+```
+
+## Choosing Blocks
+
+| Goal | Suggested blocks |
+|---|---|
+| Compare options | `grid` + `chart` + `callout` |
+| Explain a PR | `diff` + `tabs` + `callout` |
+| Tunable prototype | `slider` + `export` |
+| Release / workflow | `flow` + `callout` + `timeline` |
+| Status report | `chart` + `timeline` + `kanban` |
+| Research brief | `chart` + `grid` + `callout` + `details` |
+| Long doc with collapsible appendix | `details` + `tabs` |
+| Visual gallery / showcase | `carousel` + `grid masonry` |
+| Math / formal explanation | `math` + `callout` |
+
+## Don't
+
+- Don't add CSS, color, pixel, or font attributes — they belong to the theme.
+- Don't nest `grid` in `grid`, or `tabs` in `tabs`.
+- Don't put body content inside `:::slider` or `:::embed`.
+- Don't invent new positional arguments beyond what's listed here.
+- Don't use experimental block names that aren't in this file.