docs(wiki): render diagrams and formulas natively — Mermaid + KaTeX, validated

Add a 'Render diagrams and formulas natively' section to the wiki skill:
prefer native Mermaid for diagrams and KaTeX ($...$) for formulas over ASCII
art / unicode-in-code, as the default (but not for the sake of it). Records the
mechanics learned in practice — Mermaid label/colour discipline and real-render
validation; KaTeX as a LaTeX-math subset, dollar-only delimiters, the table
pipe/percent escapes, and the closing-$-glued-to-slash boundary trap — plus the
two-gate validation discipline (parser gate + Gitea render-parity, table
integrity, adversarial semantic-equivalence), since valid != correct != rendered.
Also a checklist item and a description clause.

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 `<repo>.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 `<repo>.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
+   `<code class="language-math">` 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.