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.
2026-09-12 17:13:42 +08:00
parent 71542e7453
commit 6d94a99b42
7 changed files with 433 additions and 45 deletions
@@ -0,0 +1,164 @@
+# tttk skill reference — reorganization plan
+
+Status: **implemented.** Follows the `tttk check` work that made
+`docs/reference.md` a generated artifact (see `docs/check-plan.md` §7.11).
+
+Landed: `known.ts` carries element/role `details`, inline specs, and dice
+notation; `reference.ts` renders them; `scripts/generate-reference.ts` expands
+`~` in `--out`; `npm run gen:skill-reference` refreshes the skill copy. The
+skill's `reference.md` is now generated and byte-identical to
+`docs/reference.md`, with the extra content moved to `layout.md`, `yaml-tag.md`,
+`csv.md`, and `markdown.md`.
+
+## 1. Goal
+
+Make the `tttk-authoring` skill's `reference.md` a **generated** file — the same
+catalog the validator uses — and relocate the authoring content it does not
+cover into focused companion files. One source of truth (`known.ts`), no
+hand-maintained element list, and no content lost in the swap.
+
+## 2. Current state
+
+The skill (`~/.agents/skills/tttk-authoring/`) has a hand-written
+`reference.md` (~465 lines) and `SKILL.md`. The repo now generates
+`docs/reference.md` from `src/cli/validate/known.ts` via `npm run
+gen:reference`.
+
+What the generated doc already covers:
+
+- Directive syntax (brief)
+- Custom elements: table + per-element summary, body, attrs, examples
+- Inline directives: icons, `:cmd` (brief)
+- Code block roles: `spark-table`, `declare`, `file`, `tag` (brief)
+- CSV data files (brief)
+
+What only the hand-written skill copy has (the "extra content"):
+
+| # | Section | Notes |
+|---|---|---|
+| A | Directive syntax table + container example | richer than generated |
+| B | Per-element prose | md-dice behavior, md-table `roll`/`remix`/`group`, md-deck legacy layer syntax, md-bg `fit` values, md-border class flags, md-font `source` values, md-pins behavior, md-commander CSV columns |
+| C | Icon attributes | `label`, `repeat`, `join`, `class` |
+| D | Column layout | `\|---` / `-\|-` / `--\|` markers |
+| E | `role=declare` column semantics | `tag`/`threshold`/`key`/`expr` |
+| F | YAML tag blocks | `data-config`, layers, `back_layers`, fence-line overrides |
+| G | CSV authoring | clean-CSV guidance, `label`/`body`, front matter (avoid) |
+| H | Alerts and mermaid | GitHub alerts, mermaid diagrams |
+| I | Dice notation | notation table |
+| J | Validation codes | already duplicated in `SKILL.md` |
+
+## 3. Target skill layout
+
+```
+tttk-authoring/
+├── SKILL.md          # workflow, rules, validation codes, links
+├── reference.md      # GENERATED from known.ts — elements, roles, inline, dice, CSV basics
+├── layout.md         # column layout
+├── yaml-tag.md       # role=tag, data-config, deck layers and backs
+├── csv.md            # CSV authoring and front matter
+├── markdown.md       # alerts and mermaid
+└── examples/         # unchanged
+```
+
+`reference.md` is the only generated file; the rest are hand-written and linked
+from `SKILL.md`.
+
+## 4. Content mapping
+
+| Source | Destination |
+|---|---|
+| A directive syntax | generator (`reference.ts`) — add the part/meaning table + container example |
+| B per-element prose | `known.ts` `details` field → rendered into `reference.md` |
+| C icon attributes | `known.ts` inline specs → rendered into `reference.md` |
+| E declare semantics | `known.ts` `RoleSpec.details` → rendered into `reference.md` |
+| I dice notation | `known.ts` `DICE_NOTATION` → rendered into `reference.md` |
+| D column layout | `layout.md` |
+| F YAML tag blocks | `yaml-tag.md` |
+| G CSV authoring | `csv.md` |
+| H alerts and mermaid | `markdown.md` |
+| J validation codes | dropped — `SKILL.md` owns the code tables |
+
+**Decision (recommended):** fold B/C/E/I into `known.ts` rather than a separate
+`components.md`. It keeps the generated reference self-sufficient and avoids a
+second, drifting description of the same elements. The alternative — a
+hand-written `components.md` — is rejected because it reintroduces the drift the
+generator exists to prevent.
+
+## 5. Generator changes
+
+`src/cli/validate/known.ts`:
+
+- `ElementSpec.details?: string` — one paragraph of authoring prose.
+- `ElementSpec.attrs` → optional richer `{ name, description }[]` so the
+  reference can render an attribute table (keep the plain list if not worth it).
+- `InlineSpec` for `:[icon]` and `:cmd` with body/attrs/summary/examples.
+- `RoleSpec.details?: string` for `declare` column semantics.
+- `DICE_NOTATION: { notation, meaning }[]`.
+
+`src/cli/validate/reference.ts`:
+
+- Render `details`, the attribute table, inline specs, and dice notation.
+- Add a `Contents` TOC.
+- Upgrade the directive-syntax section (table + container example).
+
+`scripts/generate-reference.ts`:
+
+- Expand a leading `~` in `--out` to `os.homedir()` so the skill copy can be
+  regenerated cross-platform.
+
+`package.json`:
+
+- `gen:reference` — unchanged (writes `docs/reference.md`).
+- `gen:skill-reference` — `gen:reference -- --out ~/.agents/skills/tttk-authoring/reference.md`.
+
+## 6. New skill file outlines
+
+- **`layout.md`** — column markers, the `-N` width suffix, a worked example.
+- **`yaml-tag.md`** — `role=tag` shape (`tag:`, `body:`, other keys as attrs),
+  fence-line overrides, `data-config` layer fields (`prop`/`template`, `pos`,
+  `font`/`fontSize`, `orientation`, `align`, `visible`), `back_layers`, and the
+  legacy `:md-deck` compact layer syntax.
+- **`csv.md`** — clean-CSV guidance, `label`/`body` conventions, `group` tabs,
+  `{{prop}}` interpolation, quoting rules, and the discouraged front-matter form.
+- **`markdown.md`** — GitHub alerts and mermaid (standard markdown, not tttk
+  syntax).
+
+## 7. SKILL.md changes
+
+- Update the "Reference" section to link `reference.md` plus the four new files.
+- Keep the validation code tables in `SKILL.md` (they are the agent's quick
+  reference); `reference.md` no longer carries them.
+- Reword "check `reference.md` when unsure" to point at the right file per topic.
+
+## 8. Steps
+
+1. Enrich `known.ts` (details, inline specs, role details, dice notation).
+2. Update `reference.ts` and `generate-reference.ts`; regenerate
+   `docs/reference.md`; keep the `known.test.ts` drift guard green.
+3. Extract D/F/G/H from the old skill `reference.md` into `layout.md`,
+   `yaml-tag.md`, `csv.md`, `markdown.md`.
+4. Regenerate the skill's `reference.md` with `npm run gen:skill-reference`.
+5. Update `SKILL.md` links.
+6. Verify (§9).
+
+## 9. Verification
+
+- `npm run gen:reference` leaves `docs/reference.md` unchanged (idempotent).
+- `npx jest` passes, including the reference drift guard.
+- Diff the old skill `reference.md` against the new file set and confirm every
+  section in §2's table has a destination — no content silently dropped.
+- `npx tttk check ./content` still runs clean (the catalog changes are
+  documentation-only, but the drift guard protects `known.ts`).
+
+## 10. Risks
+
+- **Content loss during extraction.** Mitigate with the §4 mapping as a
+  checklist and a manual diff before deleting the old file.
+- **`known.ts` bloat.** Keep `details` to one paragraph per element; long-form
+  material belongs in the companion files.
+- **Skill path portability.** `~` expansion in the generator; the skill lives
+  outside the repo, so the drift guard cannot cover it — document that
+  `gen:skill-reference` is the refresh command.
+- **Two references.** `docs/reference.md` and the skill copy are both generated
+  from `known.ts`; they must be regenerated together. Note this in
+  `docs/check-plan.md` §9.