@zigrivers/scaffold 3.28.0 → 3.30.0

package/README.md

@@ -31,6 +31,10 @@ Either way, Scaffold constructs the prompt and the target AI tool does the work.
 
 **Knowledge base** — 267 domain expertise entries in `content/knowledge/` organized in nineteen categories (core, product, review, validation, finalization, execution, tools, game, web-app, backend, cli, library, mobile-app, data-pipeline, ml, browser-extension, research, data-science, web3) covering testing strategy, domain modeling, API design, security best practices, eval craft, TDD execution, task claiming, worktree management, release management, rendering strategies, data stores, CLI patterns, game engines, library bundling, mobile deployment, batch and streaming pipelines, model training and serving, browser extension manifests and service workers, data-science reproducibility and notebook discipline, smart-contract security and audit workflow, and more. These get injected into prompts based on each step's `knowledge-base` frontmatter field. Knowledge files with a `## Deep Guidance` section are optimized for CLI assembly — only the deep guidance content is loaded, avoiding redundancy with the prompt text. Teams can add project-local overrides in `.scaffold/knowledge/` that layer on top of the global entries.
 
+A daily cron audits entries against their declared authoritative sources and opens refresh PRs when they drift — see `docs/knowledge-freshness/operations.md` for the operator guide (provider selection between Anthropic and DeepSeek, secret setup, manual overrides).
+
+**Reference guides** — Human- and agent-readable reference guides live under `content/guides/<topic>/` (markdown source + generated HTML). Run `scaffold guides` to open the index or `scaffold guides <topic>` to open a specific guide in your browser; agents read the source via `scaffold guides <topic> --markdown` and discover topics with `scaffold guides --list --format json`.
+
 **Methodology presets** — Three built-in presets control which steps run and how deep the analysis goes:
 - **deep** (depth 5) — all steps enabled, exhaustive analysis
 - **mvp** (depth 1) — 7 critical steps, get to code fast
@@ -48,7 +52,7 @@ Either way, Scaffold constructs the prompt and the target AI tool does the work.
 
 ### Required
 
-**Node.js** (v18 or later)
+**Node.js** (v18.17 or later)
 - Install: https://nodejs.org or `brew install node`
 - Verify: `node --version`
 

package/content/guides/AUTHORING.md

@@ -0,0 +1,143 @@
+# 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:
+```
+::::tabs
+:::tab{title=npm}
+`npm install -g @zigrivers/scaffold`
+:::
+:::tab{title=Homebrew}
+`brew install scaffold`
+:::
+::::
+```
+
+### `:::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).