diff --git a/wiki/SKILL.md b/wiki/SKILL.md index 148115d..2d508ca 100644 --- a/wiki/SKILL.md +++ b/wiki/SKILL.md @@ -1,6 +1,6 @@ --- name: wiki -description: Use when writing or editing a wiki article (a Gitea/GitHub repository wiki) — invoked as `/wiki` or when the user asks to write, add, or update a wiki page. Fixes the house rules for wiki content: a wiki holds durable, PROJECT-NEUTRAL knowledge acquisition, never a snapshot of the current codebase (anything that drifts when the code moves belongs in `docs/`, not the wiki); every load-bearing fact is backed by a validated EXTERNAL source (prefer canonical/stable pages); every claim is marked law vs convention vs corrected so a rule-of-thumb is never passed as a law; articles are structured as one overview page plus thematic, cross-linked detail pages, each with a References section, written in English. Also records the mechanics — a wiki is its own `.wiki.git` git repo, pages are `.md` files addressed by slug, editable via web UI / git clone / the API — and the wiki-vs-`docs/` decision rule. A standalone utility skill: manual invocation only, dispatches no agents, runs no pipeline phase. +description: Use when writing or editing a wiki article (a Gitea/GitHub repository wiki) — invoked as `/wiki` or when the user asks to write, add, or update a wiki page. Fixes the house rules for wiki content: a wiki holds durable, PROJECT-NEUTRAL knowledge acquisition, never a snapshot of the current codebase (anything that drifts when the code moves belongs in `docs/`, not the wiki); every load-bearing fact is backed by a validated EXTERNAL source (prefer canonical/stable pages); every claim is marked law vs convention vs corrected so a rule-of-thumb is never passed as a law; articles are structured as one overview page plus thematic, cross-linked detail pages, each with a References section, written in English. Also records the mechanics — a wiki is its own `.wiki.git` git repo, pages are `.md` files addressed by slug, editable via web UI / git clone / the API — and the wiki-vs-`docs/` decision rule. Renders structure and math natively — Mermaid for diagrams, KaTeX (`$...$`) for formulas — validated against the renderer (parse + render-parity), never ASCII art or plain-char formulas. A standalone utility skill: manual invocation only, dispatches no agents, runs no pipeline phase. --- # wiki — write durable, project-neutral wiki articles @@ -113,6 +113,78 @@ Never present a `[C]` as a `[L]`. If a threshold has no authoritative basis, say - **Tone:** state facts and clearly-flagged claims; a wiki page is reference material, not a chat message or a changelog. +## Render diagrams and formulas natively + +A wiki page is read in a browser, not a terminal. Structure and math carry more +when the renderer *draws* them: a **diagram** as a real diagram, a **formula** as +typeset math — never ASCII art or unicode-in-code-font soup. Gitea and GitHub +both render two languages natively through their GFM markdown pipeline, +client-side, with no server configuration: + +- **Mermaid** — a fenced ` ```mermaid ` block becomes a diagram. +- **KaTeX math** — `$...$` inline, `$$...$$` or a ` ```math ` fence for a block, + becomes typeset math. + +(Other diagram languages — PlantUML, Graphviz — need server-side `[markup.*]` +config a hosted instance usually lacks; a committed `.svg`/`.png` always works as +a fallback. Probe a renderer before relying on it: POST a sample to Gitea's +`/api/v1/markdown` with `{"Mode":"gfm"}` and check it hands the block off — see +the render-parity gate below.) + +Default to native rendering — **but not for the sake of it.** A diagram earns its +place only when it carries structure a sentence can't (a topology, a pipeline, a +fork); a formula is typeset only when it is a genuine expression. Decorative +diagrams, single-variable mentions, and threshold tokens stay prose or code. + +### Mermaid + +- Quote every node label and keep labels ASCII; use conservative flowchart + syntax. Don't set theme-fragile colors / `classDef` — let the instance theme + style it (it adapts to light/dark on its own). +- Mind edge semantics: a node arrow back to *itself* reads as the opposite of + "this node never does X" — put that meaning in the caption, not an edge. +- **Validate by real render.** A syntax slip surfaces only as a broken diagram in + the browser, so render each block to an image with `mermaid-cli` against a + system Chrome (`PUPPETEER_SKIP_DOWNLOAD=true` + + `PUPPETEER_EXECUTABLE_PATH=$(which google-chrome-stable)`) and *visually* + inspect the layout-risky ones (dense subgraphs, forks, cycles). + +### KaTeX math + +KaTeX is a **subset of LaTeX math** — fractions, roots, Greek, subscripts, sums, +`\binom` — *not* a LaTeX engine: no TikZ/PGF, no packages, no document +environments. Diagrams stay Mermaid/SVG; KaTeX only sets formulas. + +- **Dollar delimiters only.** `$...$` / `$$...$$` / ` ```math `. The bracket forms + `\[...\]` and `\(...\)` do **not** render in Gitea. +- **Inside a Markdown table cell, never put a literal `|` in `$...$`** — it is read + as a column separator and breaks the table. Use `\lvert ... \rvert` (or `\mid`). + Likewise `%` → `\%` (a bare `%` starts a KaTeX comment). +- **Boundary trap:** a closing `$` glued directly to `/` (or a digit) suppresses + the math handoff — Gitea renders it as literal text. Keep a space or punctuation + after the closing `$`. +- Math color is theme-adaptive (KaTeX uses `currentColor`) — don't hardcode it. +- Convert only genuine formulas; leave threshold tokens (`>0.95`, `1–3`), + single-variable mentions, and descriptive pseudo-expressions as code. + +**Two gates, because valid ≠ correct ≠ rendered.** A snippet can parse cleanly yet +mean the wrong thing or not render at all (`\cdotp` is a real macro that silently +swallows the next `p`; `$...$/x` parses but Gitea drops it). So: + +1. **Parse gate** — run every snippet through a real KaTeX parser + (`katex.renderToString(tex, {throwOnError:true})` / the `katex` CLI). Catches + syntax errors. +2. **Render-parity gate** — POST the whole page to Gitea's `/api/v1/markdown` + (`{"Mode":"gfm"}`) and confirm the count of emitted + `` handoffs equals the number of source `$...$` + spans. Catches the boundary/handoff failures the parser cannot. +3. **Table integrity** — re-render and confirm every table keeps its column count + (a stray `|` drops or adds a column). +4. **Semantic fidelity** — when converting many formulas at once, adversarially + check each typeset result denotes the *same* mathematics as the original + (dropped term, swapped index, sign flip, mis-grouped fraction); the parser only + judges syntax. Then eyeball the gnarliest formula rendered live. + ## Mechanics — a wiki is its own git repo A repository wiki (Gitea, GitHub) is a **separate git repository** living @@ -166,3 +238,7 @@ true; `docs/` is for what tracks the implementation. 3. Every threshold/claim is marked `[L]`/`[C]`/`[CORR]` with a legend. 4. Cross-links resolve (slugs correct; heading anchors verified or avoided). 5. Written in English; reads as reference material. +6. Diagrams render as native Mermaid and formulas as native KaTeX (no ASCII-art + diagrams or unicode-in-code formulas where native rendering fits), each + validated against the renderer — parse gate, render-parity gate, table + integrity.