docs(skill): Generate the tttk reference catalog

Enrich known.ts with element/role details, inline specs, and dice notation, and render them from reference.ts. Add gen:skill-reference and ~ expansion in --out so the skill copy can be regenerated.

The skill's reference.md is now generated; its extra authoring content moved to layout.md, yaml-tag.md, csv.md, and markdown.md.

docs/reference.md

@@ -3,8 +3,18 @@
 Generated from `src/cli/validate/known.ts` by `npm run gen:reference`.
 Do not edit by hand.
 
-Everything not listed here is standard GFM markdown. Element names are
-prefixed `md-` and must match exactly.
+Complete catalog of the custom elements, inline directives, and code block
+roles that `tttk` understands. Everything not listed here is standard GFM
+markdown. Element names are prefixed `md-` and must match exactly.
+
+## Contents
+
+- [Directive syntax](#directive-syntax)
+- [Custom elements](#custom-elements)
+- [Inline directives](#inline-directives)
+- [Code block roles](#code-block-roles)
+- [Dice notation](#dice-notation)
+- [CSV data files](#csv-data-files)
 
 ## Directive syntax
 
@@ -12,9 +22,24 @@ prefixed `md-` and must match exactly.
 :name[content]{key="value" .class #id}
 ```
 
-- `[content]` is the directive body — a path, dice formula, color, etc.
-- `{key="value"}` sets attributes; `{.class}` and `{#id}` are shorthands.
-- Container directives use `::: name` … `:::`; nest with `::::`, `:::::`.
+| Part | Meaning | Example |
+|---|---|---|
+| `:name` | Registered element name | `:md-dice` |
+| `[content]` | Directive body | `[2d6+d8]` |
+| `{attrs}` | Attributes | `{key="attack"}` |
+| `{.class}` | Shorthand for `class` | `{.text-red-500}` |
+| `{#id}` | Shorthand for `id` | `{#my-dice}` |
+
+Container directives:
+
+```markdown
+::: container
+Content here, including nested directives.
+:dice[1d20]
+:::
+```
+
+Nest with more colons (`::::`, `:::::`).
 
 ## Custom elements
 
@@ -36,6 +61,8 @@ prefixed `md-` and must match exactly.
 
 Clickable dice roller; `key` stores the result in the URL.
 
+Clicking the text rolls; clicking the 🎲 resets to the formula. With `key`, the result is stored in the URL as `?dice-<key>=<value>`.
+
 - Body: dice formula
 - Attributes: `key`
 
@@ -55,6 +82,8 @@ Clickable dice roller; `key` stores the result in the URL.
 
 Tab-separated view of a CSV with optional group tabs.
 
+`roll` adds a 🎲 random-tab button; `remix` makes `{{prop}}` references pull from a random row. A `group` column in the CSV produces group tabs automatically.
+
 - Body: CSV path or inline id
 - Attributes: `roll`, `remix`
 
@@ -74,6 +103,8 @@ Tab-separated view of a CSV with optional group tabs.
 
 Card layout from a CSV (legacy; prefer `yaml role=tag`).
 
+Prefer the `yaml role=tag` form — it is the only form that supports template layers, per-layer alignment, and card backs. The directive form is legacy and only supports the compact `layers` string.
+
 - Body: CSV path
 - Attributes: `size`, `grid`, `layers`
 
@@ -99,6 +130,8 @@ Clickable link that expands the target article inline.
 
 Renders the target article or section inline.
 
+`headingBase` shifts the heading levels of the embedded content.
+
 - Body: path, optional #section
 - Attributes: `headingBase`
 
@@ -110,6 +143,8 @@ Renders the target article or section inline.
 
 Sets the surrounding article card background.
 
+`fit` is one of `cover` (default), `contain`, `fill`, `none`, `scale-down`.
+
 - Body: image path or CSS color
 - Attributes: `fit`
 - Body may also be a CSS color (e.g. `#2a1a3a`, `crimson`).
@@ -126,6 +161,8 @@ Sets the surrounding article card background.
 
 Applies a border to the article card.
 
+Body is a CSS color or a border-image path. Class flags select sides (`t b l r all`), style (`solid dashed dotted double groove ridge inset outset none`), and image repeat (`stretch repeat round space`).
+
 - Body: color or border image
 - Attributes: `width`, `slice`
 - Body may also be a CSS color (e.g. `#2a1a3a`, `crimson`).
@@ -142,6 +179,8 @@ Applies a border to the article card.
 
 Sets the article font.
 
+`source` is `google`, `emfont`, or `local` (default).
+
 - Body: font family
 - Attributes: `source`, `weight`, `color`
 
@@ -153,6 +192,8 @@ Sets the article font.
 
 Numbered markers on an image.
 
+`pins` is a space-separated list of `label:x,y` (percent coordinates). `fixed` makes it read-only; otherwise click to add and click a pin to remove. `labelStart` sets the first label (letter or number).
+
 - Body: image path
 - Attributes: `pins`, `fixed`, `labelStart`
 
@@ -168,6 +209,8 @@ Numbered markers on an image.
 
 Interactive command history / tracker panel.
 
+The body is a CSV of command templates (`command,parameter,label,description,insertedText`).
+
 - Body: command template CSV
 - Attributes: `placeholder`, `class`, `height`
 
@@ -179,6 +222,8 @@ Interactive command history / tracker panel.
 
 Runs a Yarn Spinner dialogue file.
 
+`start` names the entry node (default `start`).
+
 - Body: Yarn Spinner file
 - Attributes: `start`
 
@@ -188,24 +233,38 @@ Runs a Yarn Spinner dialogue file.
 
 ## Inline directives
 
-### Icons — `:[name]`
+### `:[name]`
 
 Inserts an icon looked up under `assets/` (searching upward from the file).
-Default extension is `.png`; `.svg`, `.gif`, `.jpg`, `.jpeg`, and `.webp`
-are also supported.
+
+Default extension is `.png`; `.svg`, `.gif`, `.jpg`, `.jpeg`, and `.webp` are also supported. `label` overlays text, `repeat` duplicates N times, and `join` places a tag name between repeats.
+
+- Body: icon name
+- Attributes: `label`, `repeat`, `join`, `class`
 
 ```markdown
 :[attack]  :[shield.svg]  :[potion]
 ```
 
-### Command links — `:cmd[command]{label=...}`
+```markdown
+:[attack]{label=ATK repeat=3 join=br}
+```
+
+### `:cmd[command]`
 
 Renders a clickable span that dispatches a journal command.
 
+- Body: journal command
+- Attributes: `label`
+
 ```markdown
 :cmd[roll 1d20+5]{label=Roll initiative}
 ```
 
+```markdown
+:cmd[spark dungeon room-type]{label=Random room}
+```
+
 ## Code block roles
 
 The `role=` attribute on the info string determines how a fenced block is
@@ -215,6 +274,8 @@ handled.
 
 CSV (or markdown pipe table) rendered as `:md-table`.
 
+The first column header must be a dice formula; each row's first cell is the roll value (a number, or a range like `1-3`). Extra fence attributes are forwarded to the generated `:md-table`, e.g. ` ```csv role=spark-table roll=true `.
+
 ````markdown
 ```csv role=spark-table
 d6,结果
@@ -236,6 +297,8 @@ d6,结果
 
 Reactive variable / tag-modifier definitions.
 
+Columns (any order): `tag`, `threshold`, `key`, `expr`. A row with an empty `tag` declares a variable; a row with a `#tag` applies a modifier when that tag is active.
+
 ````markdown
 ```csv role=declare
 tag,threshold,key,expr
@@ -248,6 +311,8 @@ tag,threshold,key,expr
 
 Stored as inline text content and stripped.
 
+Referenced by the derived inline id, e.g. `:md-embed[./text_<hash>]`.
+
 ````markdown
 ```text role=file
 Stored as inline content.
@@ -258,6 +323,8 @@ Stored as inline content.
 
 YAML rendered as a custom element.
 
+`tag:` names the element, `body:` becomes its content, and any other key becomes an attribute. Fence-line attributes override the YAML body. See `yaml-tag.md`.
+
 ````markdown
 ```yaml role=tag
 tag: md-deck
@@ -272,6 +339,18 @@ grid: 5x5
 No role → a normal visible code block. Unknown role → warned about and
 stripped.
 
+## Dice notation
+
+Used by `:md-dice`, spark-table headers, and the journal `/roll`:
+
+| Notation | Meaning |
+|---|---|
+| `2d6` | two six-sided dice |
+| `1d20+5` | d20 plus modifier |
+| `3d6kh1` | keep highest 1 |
+| `3d6dl2-1` | drop lowest 2, minus 1 |
+| `{d4, d8}` | choose one of the listed dice |
+
 ## CSV data files
 
 Keep CSV files clean — a header row and data rows. Put deck configuration