r-markdown-cli 0.1.0 → 0.1.2

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.