living-docs-kit 0.1.0

package/skills/docs-init/assets/site-template/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "living-docs-site",
+  "private": true,
+  "type": "module",
+  "description": "Static documentation site maintained by the living-docs skills.",
+  "scripts": {
+    "build": "node engine/build.mjs",
+    "build:hosted": "node engine/build.mjs --hosted",
+    "dev": "node engine/dev.mjs",
+    "check": "node engine/check.mjs",
+    "facts": "node engine/facts.mjs",
+    "theme": "node engine/theme-tool.mjs",
+    "palette": "node engine/palette.mjs"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "jimp": "^1.6.0",
+    "js-yaml": "^4.1.0",
+    "marked": "^15.0.12"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/skills/docs-init/assets/site-template/themes/atlas.json

@@ -0,0 +1,40 @@
+{
+  "id": "atlas",
+  "label": "Atlas (serif, light)",
+  "mode": "light",
+  "source": "preset",
+  "colors": {
+    "bg": "#f4f6f1",
+    "surface": "#fcfdfa",
+    "surfaceAlt": "#e9eee5",
+    "text": "#252f29",
+    "textMuted": "#56625a",
+    "heading": "#18231d",
+    "border": "#d3dacf",
+    "accent": "#2e6b4f",
+    "accentText": "#ffffff",
+    "link": "#245f86",
+    "codeBg": "#ebefe6",
+    "codeText": "#252f29",
+    "highlight": "#dce9df",
+    "success": "#2b7148",
+    "warning": "#855a06",
+    "danger": "#a83221"
+  },
+  "fonts": {
+    "body": "'Literata', Georgia, 'Times New Roman', serif",
+    "heading": "'Literata', Georgia, 'Times New Roman', serif",
+    "mono": "'Fira Code', ui-monospace, Menlo, Consolas, monospace",
+    "googleFontsUrl": "https://fonts.googleapis.com/css2?family=Literata:ital,opsz,wght@0,7..72,400;0,7..72,700;1,7..72,400&family=Fira+Code:wght@400;500&display=swap"
+  },
+  "typography": {
+    "baseSize": 17,
+    "lineHeight": 1.75,
+    "headingWeight": 700
+  },
+  "layout": {
+    "contentMaxWidth": 720,
+    "sidebarWidth": 280,
+    "radius": 4
+  }
+}

package/skills/docs-init/assets/site-template/themes/fjord.json

@@ -0,0 +1,40 @@
+{
+  "id": "fjord",
+  "label": "Fjord (light)",
+  "mode": "light",
+  "source": "preset",
+  "colors": {
+    "bg": "#f6f8f9",
+    "surface": "#ffffff",
+    "surfaceAlt": "#eaf0f3",
+    "text": "#1c2830",
+    "textMuted": "#52606a",
+    "heading": "#0f1d26",
+    "border": "#d3dce1",
+    "accent": "#1d5f86",
+    "accentText": "#ffffff",
+    "link": "#1a5a82",
+    "codeBg": "#edf2f5",
+    "codeText": "#1c2830",
+    "highlight": "#d8e8f2",
+    "success": "#1f7a4d",
+    "warning": "#8a5a00",
+    "danger": "#b42318"
+  },
+  "fonts": {
+    "body": "'Atkinson Hyperlegible', 'Segoe UI', system-ui, sans-serif",
+    "heading": "'Atkinson Hyperlegible', 'Segoe UI', system-ui, sans-serif",
+    "mono": "'JetBrains Mono', ui-monospace, Menlo, Consolas, monospace",
+    "googleFontsUrl": "https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible:ital,wght@0,400;0,700;1,400&family=JetBrains+Mono:wght@400;600&display=swap"
+  },
+  "typography": {
+    "baseSize": 17,
+    "lineHeight": 1.65,
+    "headingWeight": 700
+  },
+  "layout": {
+    "contentMaxWidth": 760,
+    "sidebarWidth": 280,
+    "radius": 8
+  }
+}

package/skills/docs-init/assets/site-template/themes/graphite.json

@@ -0,0 +1,45 @@
+{
+  "id": "graphite",
+  "label": "Graphite (dark)",
+  "mode": "dark",
+  "source": "preset",
+  "colors": {
+    "bg": "#1b2027",
+    "surface": "#222932",
+    "surfaceAlt": "#2b333e",
+    "text": "#e3e8ee",
+    "textMuted": "#a6b0bc",
+    "heading": "#f4f7fa",
+    "border": "#3a4450",
+    "accent": "#e0a43a",
+    "accentText": "#1b2027",
+    "link": "#8fc6f0",
+    "codeBg": "#161a20",
+    "codeText": "#dfe6ee",
+    "highlight": "#3b3526",
+    "success": "#6cc79a",
+    "warning": "#e8b454",
+    "danger": "#f08a8a"
+  },
+  "fonts": {
+    "body": "'IBM Plex Sans', 'Segoe UI', system-ui, sans-serif",
+    "heading": "'IBM Plex Sans', 'Segoe UI', system-ui, sans-serif",
+    "mono": "'IBM Plex Mono', ui-monospace, Menlo, Consolas, monospace",
+    "googleFontsUrl": "https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:ital,wght@0,400;0,600;1,400&family=IBM+Plex+Mono:wght@400;500&display=swap"
+  },
+  "typography": {
+    "baseSize": 16,
+    "lineHeight": 1.65,
+    "headingWeight": 600
+  },
+  "layout": {
+    "contentMaxWidth": 760,
+    "sidebarWidth": 280,
+    "radius": 6
+  },
+  "diagram": {
+    "nodeBg": "#2b333e",
+    "nodeBorder": "#e0a43a",
+    "clusterBg": "#1f252d"
+  }
+}

package/skills/docs-write/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: docs-write
+description: Write and maintain the pages of the living-docs documentation site for people - overviews, architecture drill-downs, flows, business rules, state machines, edge cases, data model, change log - verified against the code, with clickable diagrams and code links. Use whenever the user asks to generate, update, refresh or fix the docs site, to document a module, flow, rule or feature there, after code changes that alter behaviour when the project's AGENTS.md or DOCS-GUIDE.md asks for it, and whenever the docs-writer subagent runs.
+---
+
+# docs-write
+
+Writes `<site>/content/**/*.md`. The build turns these pages into the documentation site. The readers are people, so every page must be quick to scan, correct, and one click away from both more detail and the code.
+
+## Before anything
+
+1. **Locate the site.** It is the folder with `docs.config.json` next to `engine/`, usually `docs-site/`. Run all commands from there.
+2. **Check the guide is approved.** If `state.guideApproved` in `docs.config.json` is not `true`, stop and say that `docs-init` (or `docs-guide`) must finish first.
+3. **Read `DOCS-GUIDE.md` completely.** Its sections, topics, limits, language and tone override everything below.
+4. **Read the references.** Read `references/authoring.md` (page syntax: frontmatter, links, code links, callouts, diagrams, decision tables) and `references/page-types.md` (what each kind of page contains) the first time in a session.
+
+Do not edit `engine/`, `themes/` (owned by docs-design) or `DOCS-GUIDE.md` (owned by docs-guide). If the guide seems to be missing something, say so in your report.
+
+## Principles
+
+- **Top-down.** Home says what the system is in a few sentences, with a map. Section pages give an overview and a map. Detail pages explain one thing. The reader chooses how deep to go.
+- **One page, one subject.** When a page grows past the guide's limit, split it and turn the parent into an overview.
+- **Verified, not imagined.** Read the code before describing it. Every statement about behaviour links to the code that implements it with a `code:` link. If you could not confirm something, write it inside an `> [!UNVERIFIED]` callout rather than stating it.
+- **Intent and consequences over mechanics.** Say why something exists, what rule it enforces and what happens in each case. Do not narrate the code line by line.
+- **Pick the right form.**
+  - A flow is a sequence diagram plus numbered steps.
+  - A rule with conditions is a decision table.
+  - Anything with statuses is a state diagram.
+  - Structure is a flowchart with clickable nodes.
+  - Only what is left is prose.
+- **Concrete over abstract.** Use real field names, real values and a typical example request or record.
+- **Edge cases are first-class.** Put each one on the page where it matters and in the edge-case catalogue, linked to the code and to its test (or marked "not covered by tests").
+- **Write for a newcomer.** Define domain terms on first use or link the glossary. Avoid internal jargon from the AI-oriented READMEs.
+
+## Tools
+
+```bash
+node engine/facts.mjs              # stack, structure, entry points, tests, docs coverage (JSON)
+node engine/facts.mjs changes      # files changed since the last generation and the pages they affect
+node engine/facts.mjs stamp <page.md> [...]   # mark pages as verified against their current sources
+node engine/facts.mjs mark         # record HEAD as the last generation point (end of plan+pages or update)
+npm run check                      # frontmatter, broken links, missing code files and lines, limits
+npm run build                      # build dist/ (the dev server rebuilds on its own)
+```
+
+**Stamping.** `stamp` writes `sourcesHash`, `updated` and `commit` into a page. It is how the site knows whether a page is still current: when the files listed in `sources` change, the page shows "possibly outdated". So:
+
+- Stamp a page only after you have actually checked it against those sources.
+- Never write those three fields by hand.
+
+## Modes
+
+The caller (docs-init, the user, or the main agent delegating to `docs-writer`) says which mode to use. If none is given, infer it: no pages yet means `plan` and then `pages`, "update the docs" means `update`, and "document X" means `topic`.
+
+### plan: build the skeleton
+
+1. Run `facts.mjs`. Read the entry points, the manifests, the existing READMEs and the main folders until you can name the modules, the main flows, the rules, the stateful entities and the data stores.
+2. Design the site map from the guide's enabled sections and priority topics:
+   - C4-style drill-down for Architecture: context, then containers, then components.
+   - One page per main flow, rule set, state machine and important module.
+   - Section paths come from the guide; page file names are short lowercase-hyphen slugs.
+3. Write the home page and every section `index.md` completely, including their map diagrams with `click` links to the planned pages. They are short, and writing them first fixes the vocabulary.
+4. Create every other page as a stub. The frontmatter holds `title`, `summary`, `order` and `sources` (the files or folders the page will describe), and the body is only `<!-- stub -->`. Summaries matter even for stubs: they appear in overviews and search.
+5. Run `npm run check`. Broken links to planned pages must not exist, because the stubs exist.
+6. Return the site map as an indented list (path, title, sources) grouped by section. That lets the caller split the `pages` work.
+
+### pages: write or rewrite given pages
+
+For each file you are given:
+
+1. Read its frontmatter, then read every file in `sources` completely, plus whatever they call that matters for the page's subject. Extend `sources` if the page really depends on more files, and trim it if it lists files the page does not describe.
+2. Write the body following the page type in `references/page-types.md` and the guide's limits.
+3. Add links to related pages (site-absolute paths such as `/flows/checkout/`), and make sure the parent overview links here, either through its map diagram or through the automatic "Go deeper" list.
+4. Stamp the page: `node engine/facts.mjs stamp content/<path>.md`.
+
+When all pages are done, run `npm run check` and fix every error. Warnings about length should also be fixed by splitting the page.
+
+### update: bring the site in line with the code
+
+1. **Collect the changes.** Run `facts.mjs changes`. It lists the changed files, the affected pages (by `sources`), stale pages, changes not covered by any page, and deleted files. Read `git log` and `git diff <since>` for the affected files to understand what changed in behaviour.
+2. **Handle affected and stale pages.** Re-read the sources and update only what changed: text, diagrams, decision tables, code links (line numbers move!) and edge cases. If nothing about behaviour changed, fix the code links only. Stamp every page you verified, even when its text did not change.
+3. **Handle uncovered changes.** If a change adds a module, flow, rule or edge case worth documenting under the guide, add it to an existing page's `sources` and content, or create a new page and link it from its parent. Ignore changes the guide puts out of scope.
+4. **Handle deleted files.** Remove or rewrite the pages that described them, and fix the links pointing to them.
+5. **Record the change.** If the guide enables "What changed", add one entry at the top of `content/changes/index.md`. Use the date as the heading, then 1–5 bullets in plain language about behaviour, each linking to the updated page. Skip it for pure refactors.
+6. **Finish.** Run `npm run check` with no errors, then `facts.mjs mark`.
+
+### topic: document one thing the user asked for
+
+Find where the topic belongs in the existing site map. Then extend that page, or add a page and link it from the parent and from related pages. After that, continue as in `pages`. Mention in your report if the topic deserves a line under Priority topics in the guide.
+
+## Quality bar before you finish
+
+- Home still gives the whole picture in under a minute of reading, and its map is up to date.
+- Every page has a `summary` that works on its own in search results and overview lists.
+- Every behaviour statement has a code link. No `code:` link points to a missing file or line (the checker verifies this).
+- The diagrams stay under ~12 nodes each, use the guide's language, and link their nodes to detail pages where those exist.
+- Edge cases have an `> [!EDGE]` callout and a catalogue entry.
+- `npm run check` reports 0 errors.
+
+## Report
+
+End with a short report for the caller:
+
+- pages created, updated and stamped, as paths;
+- checker warnings left and why;
+- anything you could not verify;
+- suggested guide changes, if any.
+
+Keep it brief. The caller will show it to the user.

package/skills/docs-write/references/authoring.md

@@ -0,0 +1,125 @@
+# Authoring reference
+
+Pages are Markdown (GitHub-flavoured) with YAML frontmatter, stored under `content/`. The URL follows the file path:
+
+- `content/index.md` → `/`
+- `content/flows/index.md` → `/flows/`
+- `content/flows/checkout.md` → `/flows/checkout/`
+
+A folder without `index.md` gets an empty generated section page (and a checker warning), so always write one.
+
+## Frontmatter
+
+```yaml
+---
+title: Checkout                 # required; menu, breadcrumbs, search
+summary: How a cart becomes a paid order, and what can stop it.   # required; 1–2 sentences
+order: 2                        # optional; position among siblings (lower first, default 1000)
+sources:                        # optional but expected on every page describing code
+  - src/checkout/               #   folders include all files inside
+  - src/payments/charge.ts
+nav: false                      # optional; hide from the menu (page still built and searchable)
+navOpen: true                   # optional; top-level section expanded in the menu by default
+children: false                 # optional; hide the automatic "Go deeper" list on an index page
+search: false                   # optional; exclude from search
+# written by `facts.mjs stamp`, never by hand:
+sourcesHash: 1d67b83b63b72b0c
+updated: '2026-09-23'
+commit: b3cbaab
+---
+```
+
+The page title is rendered as the `<h1>` and the summary right under it, so the body starts at `##`.
+
+## Links
+
+- **Other pages.** Always use site-absolute paths: `[Checkout](/flows/checkout/)`, or with an anchor, `[limits](/rules/discounts/#limits)`. The build rewrites them to relative links, so the site works from any host path and straight from disk. Relative paths like `../x/` are flagged by the checker.
+- **Code.** Use `code:` links:
+  - `[createOrder](code:src/orders/order.ts#L12)`: one line (`:12` also works);
+  - `[the retry loop](code:src/jobs/retry.ts#L40-58)`: a range;
+  - `[](code:src/api/server.ts)`: empty text shows the path as the label.
+
+  They open the file in the editor (Cursor/VS Code) locally and on GitHub/GitLab when the site is hosted, depending on `codeLinks` in `docs.config.json`. The checker fails on missing files and on line numbers past the end of the file. Re-check line numbers during updates.
+- **External.** Normal Markdown links; they open in a new tab.
+
+## Callouts
+
+```markdown
+> [!EDGE] Empty cart
+> A cart without items cannot become an order; `createOrder` throws `EmptyCart`. Covered by [order.test.ts](code:tests/order.test.ts#L8).
+```
+
+Types: `NOTE`, `TIP`, `WARNING`, `EDGE` (edge case), `RISK`, `UNVERIFIED`, `DECISION`. Text after the marker on the first line becomes the callout title.
+
+## Diagrams (Mermaid)
+
+````markdown
+```mermaid
+%% caption: System map. Click a box for details.
+flowchart LR
+  U([Customer]) --> W[Web app]
+  W --> A[Orders API]
+  A --> DB[(Postgres)]
+  A --> P[Payment provider]
+  click A "/architecture/orders-api/" "Orders API"
+  click P "/architecture/payments/" "Payments"
+```
+````
+
+Rules:
+
+- The first line is the diagram type: `flowchart LR|TD`, `sequenceDiagram`, `stateDiagram-v2`, `erDiagram`, `classDiagram`, `journey`, `timeline`, `mindmap`, …
+- `%% caption: …` adds a caption above the diagram.
+- `click NodeId "/site/path/" "tooltip"` makes a flowchart node open another page. This is the main drill-down device: use it on every map. The checker verifies the targets exist.
+- Keep diagrams at ~12 nodes or fewer; split into levels instead of drawing everything at once. Readers can enlarge any diagram with the ⤢ button (zoom and pan).
+- Node ids are short ASCII (`A`, `api`); labels are human text in the documentation language. Quote labels with special characters: `A["Orders API (v2)"]`.
+- Colours come from the active theme; do not add `style`/`classDef` colours.
+
+Useful shapes:
+
+| Syntax | Use for |
+|---|---|
+| `id([Label])` | people and actors |
+| `id[(Label)]` | databases |
+| `id{{Label}}` | external systems |
+| `id{Label?}` | decisions in flows |
+
+Use `subgraph Name … end` to group parts.
+
+## Decision tables (interactive)
+
+A fenced block with language `decision` and YAML inside. Readers pick values and see which rule applies. Rules are listed in the order the code evaluates them; the first match wins. A condition left out of `when` means "any value".
+
+````markdown
+```decision
+title: Which discount applies
+inputs:
+  - id: customer
+    label: Customer type
+    values: [new, loyal, occasional]   # optional; values used in rules are added automatically
+  - id: total
+    label: Order total
+    values: ["> 100", "≤ 100"]
+output: Discount
+rules:
+  - when: { customer: new, total: "> 100" }
+    then: "10%"
+    code: src/pricing/discount.ts#L2
+  - when: { customer: loyal }
+    then: "5%"
+    note: Any total
+    code: src/pricing/discount.ts#L3
+  - when: {}
+    then: "0%"
+    note: Everything else
+```
+````
+
+Put the important boundary cases in `EDGE` callouts under the table, for example what happens at exactly 100.
+
+## Other Markdown
+
+- **Tables:** these scroll horizontally on small screens.
+- **Collapsible details:** use `<details><summary>Full payload example</summary> … </details>` for long examples that most readers skip.
+- **Images and attachments:** put them under `content/` (e.g. `content/flows/img/checkout.png`) and link them site-absolutely: `![Checkout screen](/flows/img/checkout.png)`.
+- **Code blocks:** use fenced blocks with a language. Keep them short: a signature, a sample payload, a config snippet. Link to the code for the rest.

package/skills/docs-write/references/page-types.md

@@ -0,0 +1,104 @@
+# Page types
+
+Each type lists what the page must contain, in order. Section paths come from DOCS-GUIDE.md; the defaults are shown. Adapt the headings to the documentation language.
+
+## Home (`content/index.md`)
+
+1. **Summary** in the frontmatter: what the application does, for whom, in 1–2 sentences.
+2. **A short paragraph** (≤120 words in total with the summary): the main capabilities and the main technical shape (e.g. "a Next.js app and a Python worker sharing a Postgres database").
+3. **System map.** A `flowchart LR` with the actors, the main parts and the external systems, each clickable to its page. At most ~10 nodes.
+4. **What to know in 30 seconds.** 3–5 bullets with the things people most often get wrong or need first, each linking deeper.
+5. **Where to start.** 2–4 links, for example: to understand a request, read [Checkout](/flows/checkout/).
+
+The build appends the section cards ("Go deeper") and "Recently updated".
+
+## Section overview (`content/<section>/index.md`)
+
+- `summary` plus at most ~200 words saying what this section covers and how its pages relate.
+- A map diagram when the section has structure (modules, flow families, entity lifecycles), with clickable nodes.
+- No detail content: that goes into child pages. The build lists the children with their summaries.
+- Set `order` so the sections follow the guide's order.
+
+## Architecture pages
+
+- **Context** (`/architecture/context/` or inside the section index): the system as one box, the people and external systems around it, with arrows labelled by purpose ("sends invoices", "reads prices").
+- **Containers**: the deployable or runnable parts (apps, services, workers, databases, queues). For each part, give its responsibility in one line, its technology, and how it talks to the others (protocol, sync or async). Include one diagram.
+- **Module or component page** (one per important module):
+  1. **Purpose.** What it is responsible for, and just as important, what it is not responsible for.
+  2. **Public surface.** The functions, endpoints, events or commands other code uses, each with a code link. Show a table for endpoints: method, path, purpose, auth.
+  3. **How it works.** The key idea in a few paragraphs, with a small diagram if it helps.
+  4. **Dependencies.** What it calls and what calls it, linked to those pages.
+  5. **Edge cases and limits**, as `EDGE` callouts.
+  6. **Where to change things.** For typical modifications, the files to touch.
+
+## Flow page (`/flows/<name>/`)
+
+1. **Trigger and outcome** in the summary: who starts it, and what is true at the end.
+2. **Sequence diagram** of the main path, with 4–8 participants.
+3. **Numbered steps**, one per meaningful action, each with a code link. Numbering fits here because a flow is a sequence.
+4. **Alternative and failure paths.** What happens when validation fails, a dependency is down, a timeout hits, or the user retries. Use `EDGE` callouts for the non-obvious ones.
+5. **Side effects.** Data written, events emitted, emails sent, and whether they are idempotent.
+6. **Related.** Links to the rules and states that the flow uses.
+
+## Rule page (`/rules/<name>/`)
+
+- A summary stating the rule in one sentence.
+- A **decision table** (a `decision` block) when the rule depends on two or more conditions. Otherwise, one clear sentence plus an example.
+- Boundary values and precedence as `EDGE` callouts: exactly at the limit, conflicting rules, missing data.
+- Where the rule lives in the code, and which tests cover it.
+
+## State machine page (`/rules/<entity>-states/`)
+
+- A `stateDiagram-v2` whose transitions are labelled with the triggering action or event.
+- A table with the columns state, meaning, allowed next states, and who or what triggers the move.
+- Forbidden transitions and what happens if they are attempted.
+- Timeouts or automatic transitions, if any.
+
+## Glossary (`/rules/glossary/`)
+
+One line per domain term: the term, its meaning in this system, and where it appears in the code (entity, table, module). Link other pages to glossary anchors (`/rules/glossary/#tenant`).
+
+## Edge-case catalogue (`/edge-cases/`)
+
+A table, grouped with `##` headings by area:
+
+| Situation | What happens | Why | Code | Test |
+|---|---|---|---|---|
+| Empty cart at checkout | Request rejected with 422 `EMPTY_CART` | An order needs at least one item | [createOrder](code:src/orders/order.ts#L2) | [order.test.ts](code:tests/order.test.ts#L8) |
+| Payment provider timeout | Order stays `pending`; retried 3× | Avoid double charges | [retry](code:src/jobs/retry.ts#L40) | not covered by tests |
+
+Every edge case mentioned on another page appears here too, and each row links back to that page.
+
+## Data page (`/data/`)
+
+- An `erDiagram` of the main entities with their key fields only.
+- One subsection per entity that matters: what it represents, its important fields and constraints, and who writes it and who reads it.
+- Data flow: where data enters (forms, imports, APIs), how it is transformed, and where it goes (exports, analytics, other systems).
+- Retention, deletion and privacy rules, if they exist.
+
+## Decision record (`/decisions/NNNN-title/`)
+
+Sections: Context, Decision, Alternatives considered (and why they were rejected), Consequences, Status (accepted, superseded by …). Keep it under 400 words. Use `sources` for the code the decision shaped.
+
+## What changed (`/changes/index.md`)
+
+Newest entries first:
+
+```markdown
+## 2026-09-23
+
+- New customers now get 10% only above 100 (it was 50). See [Discounts](/rules/discounts/).
+- Added the [refund flow](/flows/refund/).
+```
+
+Write about behaviour, in plain language. Skip pure refactors.
+
+## Risks page (`/risks/`)
+
+One entry per risk:
+
+- where it is (with a code link);
+- why it is risky: no tests, high complexity, frequent changes, an implicit contract;
+- what would reduce it.
+
+Rank the entries by impact.