@zigrivers/scaffold 3.29.0 → 3.31.0

package/content/guides/AUTHORING.md

@@ -0,0 +1,146 @@
+# Authoring Scaffold Guides
+
+This is the single source of truth for the **guides markdown dialect** — the
+frontmatter, directives, and citation syntax used by every guide under
+`content/guides/<topic>/index.md`. Markdown is the source of truth; the HTML is
+generated. Agents read the markdown, so everything here must degrade to readable
+prose.
+
+> **Where guides live.** A guide is a directory `content/guides/<topic>/` with an
+> `index.md`. The directory name **must** equal the frontmatter `topic`. This
+> file (`content/guides/AUTHORING.md`) is not a guide and is not rendered or
+> gated — its examples below are illustrative only.
+
+## Build & check
+
+| Command | What it does |
+|---|---|
+| `scaffold guides --build` | Render every `index.md` → self-contained `index.html` + the index page. |
+| `scaffold guides --list --format json` | Discovery (for agents). |
+| `make check-all` | Runs `guides-check` (lint + build freshness) **and** `check-reference-citations` (citation drift, incl. all guides). |
+
+Regenerate and commit `index.html` after editing any `index.md` — the drift gate
+enforces freshness.
+
+## Frontmatter (required)
+
+```yaml
+---
+title: Build Observability          # display title
+topic: observability                # MUST equal the directory name
+description: One-line scope shown in the guide index
+category: tools                     # concepts | reference | workflows | tools
+order: 40                           # sort order in the index (lower first)
+---
+```
+
+Optional: `escape_scripts: [name.js]` — allowlist of script files an `:::embed`
+may reference.
+
+## Citations — `:cite` (the provenance contract)
+
+Cite the code that backs a claim so the **citation-drift gate**
+(`scripts/check-reference-citations.mjs`) can verify the file:line still exists.
+Guides are discovered by the gate automatically — no registration needed.
+
+| Syntax | Renders | Gate behavior |
+|---|---|---|
+| `:cite[src/observability/engine/api.ts:42]` | `<span class="fp" data-path="…">src/observability/engine/api.ts:42</span>` | **Blocking** — drift fails `make check-all` |
+| `:cite[src/foo.ts:42-58]` | range citation | **Blocking** |
+| `:cite[docs/git-workflow.md:120]{mode=advisory}` | `<span class="cite-advisory" …>` | **Advisory** — warns, never blocks |
+
+**P0-a — when to use which:**
+- Use **`:cite[…]`** (blocking) for a citation that **backs a normative claim**
+  ("the worker transitions to `PAGED_PASSED` — `:cite[…]`"). If the line moves or
+  the file shrinks, the gate fails so you re-anchor it.
+- Use **`:cite[…]{mode=advisory}`** for "see also" pointers where exact-line
+  drift shouldn't break CI.
+
+The gate verifies the **line exists**, not that it still points at the right
+symbol — semantic drift needs human review.
+
+## Directives
+
+All directives are first-class (parsed, rendered, sanitized). Prefer them over
+raw HTML.
+
+### `:::callout{type=…}`
+Types: `note` (default), `tip`, `warning`, `danger`, `info`. Unknown → `note`.
+```
+:::callout{type=warning}
+Teardown harvests the ledger **before** `git worktree remove`.
+:::
+```
+
+### `::::tabs` / `:::tab{title="…"}`
+Use a **4-colon** outer fence wrapping 3-colon tabs. **Always quote the title** —
+an unquoted title with parentheses, slashes, or other punctuation (e.g.
+`{title=mvp (depth 1)}` or `{title=CLI / library}`) fails to parse and leaks the
+raw `:::tab{…}` text into the page:
+```
+::::tabs
+:::tab{title="npm"}
+`npm install -g @zigrivers/scaffold`
+:::
+:::tab{title="CLI / library"}
+…
+:::
+::::
+```
+
+### `:::filter-table`
+Wraps a GFM table and prepends a client-side filter box. Body is a normal GFM
+table.
+
+### `:::chart{type=bar}`
+Renders proportional bars **from a GFM table** and keeps the table. The **label**
+is the first column; the **value** is the **last column and must be numeric**.
+This is the stable, non-HTML target a generator emits for baked numeric data
+(e.g. live host counts):
+```
+:::chart{type=bar}
+
+| Host | Citations |
+|---|---|
+| github.com | 40 |
+| npmjs.com | 10 |
+:::
+```
+**Error:** a `:::chart` without a GFM table fails the build.
+
+### `:sev[label]{level=…}`
+Inline severity chip. Levels: `p0`, `p1`, `p2` (default), `p3`, `pass`. Unknown → `p2`.
+`A :sev[P0]{level=p0} finding.`
+
+### Mermaid
+Fenced ```` ```mermaid ```` blocks render to inline SVG for humans and stay
+readable as text for agents. Default to mermaid for diagrams.
+
+## Escape hatch — `:::embed{…}` (narrow, discouraged)
+
+For genuinely one-off interactivity a first-class directive can't express. Every
+`:::embed` **must contain a text-equivalent** (the word "text-equivalent" in the
+body) or the build **errors** — agents must still understand the content. Using
+**more than 3** embeds in a guide emits a warning: prefer first-class directives.
+
+## Proposing a new directive
+
+A new directive is warranted only when content recurs across guides and the
+escape hatch can't serve it without losing agent-readability. To propose one:
+1. Add a `remark<Name>` transform in `src/guides/directives.ts` (mirror the
+   existing `textDirective`/`containerDirective` patterns).
+2. Allow any new attributes/elements in `src/guides/sanitize.ts`.
+3. Register it in the plugin list in `src/guides/build.ts`.
+4. TDD: add `src/guides/directives-<name>.test.ts` (render via `renderGuideBody`).
+5. Document it here.
+
+## Authoring checklist (required reading for Phase 3 authors)
+
+- [ ] Frontmatter complete; `topic` == directory name.
+- [ ] Code-backed claims carry a blocking `:cite`; "see also" links use
+      `{mode=advisory}` or relative markdown links.
+- [ ] Inter-guide links are relative and resolve (the relative-link validator runs in `guides-check`).
+- [ ] Diagrams use mermaid; data uses `:::chart`/GFM/`:::filter-table`; no raw HTML.
+- [ ] `:::embed` only where unavoidable, with a text-equivalent.
+- [ ] `scaffold guides --build` run and `index.html` committed.
+- [ ] `make check-all` green (citations resolve; build clean).