living-docs-kit 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# living-docs kit
+
+Skills and subagents that give a code project a documentation website written for people. The site has:
+
+- a concise overview with drill-down into detail pages;
+- clickable, zoomable diagrams;
+- interactive decision tables;
+- links from the docs straight into the code;
+- labels that mark pages whose code has changed since they were checked;
+- switchable themes and fonts.
+
+It works in **Claude Code** and **Cursor**. Cursor also loads skills and subagents from the `.claude/` folders.
+
+## Install
+
+Run this from the root of the project you want to document:
+
+```sh
+npx living-docs-kit          # only this project (./.claude)
+npx living-docs-kit --all    # all your projects (~/.claude)
+```
+
+The same commands work on macOS, Linux and Windows. Update with `npx living-docs-kit@latest` (add `--all` for the user-level copy). Remove with `--uninstall`.
+
+A project-level install can be committed with the project, so everyone who clones it gets the same skills. If both exist, the project copy takes precedence over the user-level one.
+
+Requirements: Node.js 20+ and git (recommended, used for change tracking).
+
+## Use
+
+| You say (or type) | What runs |
+|---|---|
+| "set up living docs for this project", `/docs-init` | **docs-init**: asks for the design, creates `docs-site/`, drafts `DOCS-GUIDE.md`, shows it to you, iterates until you approve, then generates the site |
+| "update the docs", "document the refund flow" | **docs-write**, usually through the **docs-writer** subagent |
+| "make a theme from https://…", "use this palette image", "keep the text at 120%", "make Graphite the default" | **docs-design** |
+| "the docs should also cover X", "write shorter pages", "show me the docs guide" | **docs-guide** |
+| "are the docs correct?" | the **docs-reviewer** subagent (read-only) |
+
+To view the site, run `cd docs-site && npm run dev` and open http://localhost:4321; it rebuilds and reloads on every change. You can also open `docs-site/dist/index.html` straight from disk.
+
+## What is in the kit
+
+```
+skills/
+  docs-init/     setup + first generation; carries the site template, the guide template,
+                 an AGENTS.md snippet and an optional GitHub Pages workflow
+  docs-design/   themes: create from a URL, image or description; edit; set default; save a font size
+  docs-guide/    maintains DOCS-GUIDE.md (topics, sections, tone, limits, update policy)
+  docs-write/    how to write the pages; modes plan / pages / update / topic
+agents/
+  docs-writer.md    writes pages in its own context (several can run in parallel)
+  docs-reviewer.md  read-only accuracy and readability review
+```
+
+## Inside a project after setup
+
+```
+docs-site/
+  docs.config.json   title, default theme, code-link editor and web base, limits, state
+  DOCS-GUIDE.md      the brief for the writer; edit it by hand or via docs-guide
+  content/           the pages (Markdown + frontmatter)
+  themes/            one JSON per theme; each one appears in the site's theme picker
+  engine/            build, dev server, checker, facts/stamp, theme and palette tools
+```
+
+Useful commands (run in `docs-site/`):
+
+| Command | What it does |
+|---|---|
+| `npm run dev` | live preview |
+| `npm run build` | build `dist/` |
+| `npm run build:hosted` | build with code links pointing to GitHub/GitLab instead of the local editor |
+| `npm run check` | broken links, missing code files or lines, length limits, stale pages |
+| `npm run facts` | what the tools know about the project and the docs coverage |
+| `npm run theme -- list` | list themes; `validate`, `fix`, `set`, `set-default` are also available |
+
+## Behaviour of the site controls
+
+- **Theme picker.** The choice is remembered in the reader's browser until they pick "Default". The default for everyone is `defaultTheme` in `docs.config.json`, set by docs-design.
+- **A− / A+.** Temporary text size; it resets on reload. To keep a size, ask the agent (docs-design writes it into a theme, or into a new variant of it).
+- **"Possibly outdated" label.** It appears when the files a page describes changed after the page was last verified. The `/_status/` page lists all such pages.
+
+## Updating the engine
+
+Ask "upgrade the docs-site engine". docs-init replaces `engine/` from the installed kit and leaves content, themes, the guide and the config untouched.

package/agents/docs-reviewer.md

@@ -0,0 +1,33 @@
+---
+name: docs-reviewer
+description: Read-only reviewer for the living-docs documentation site. Checks pages for accuracy against the code, readability for a human newcomer, compliance with DOCS-GUIDE.md, navigability (drill-down links, clickable diagrams) and staleness, and returns a prioritized list of concrete fixes. Use after initial generation, after large updates, or when the user asks whether the docs are correct or good.
+model: inherit
+tools: Read, Grep, Glob, Bash
+readonly: true
+---
+
+You review a documentation website written for people. It lives in the project folder that has `docs.config.json` next to `engine/` (usually `docs-site/`). You never modify files.
+
+Prepare:
+
+1. Read `DOCS-GUIDE.md` in the site folder.
+2. Read the references of the `docs-write` skill (`references/authoring.md` and `references/page-types.md`). The skill is in `.claude/skills/docs-write/`, `~/.claude/skills/docs-write/`, `.cursor/skills/docs-write/`, `~/.cursor/skills/docs-write/`, `.agents/skills/docs-write/` or `~/.agents/skills/docs-write/`.
+3. Run `npm run check` and `node engine/facts.mjs` in the site folder for the mechanical problems and the coverage numbers.
+
+Review the pages you were given, or, if none were named, the home page, every section overview and a sample of detail pages. For each page, judge:
+
+1. **Accuracy.** Open the files in `sources` and the `code:` links. Check at least three concrete claims per page against the code: names, conditions, limits, status codes, order of steps. Wrong claims are the most important findings.
+2. **First-read clarity.** Could a developer new to the project understand the summary and the first screen without reading the code? Flag jargon, missing definitions, walls of text and retold code.
+3. **Guide compliance.** Check language, tone, length limits, required sections for the page type, edge cases with tests, and diagram rules.
+4. **Navigation.** The page should be reachable from its parent overview and its map diagram. Diagram nodes should link where detail exists, and related pages should link to each other.
+5. **Freshness.** Look for stale or unverified pages, and for code changed since the last stamp.
+6. **Gaps.** Look for priority topics from the guide with no page, and for important code with no coverage (`uncoveredCodeFiles`).
+
+Return a prioritized list, most important first. Each item has:
+
+- the page path;
+- the problem, quoting at most one short fragment;
+- the evidence, with a file and line when it is about accuracy;
+- the concrete fix.
+
+End with one line of overall assessment. Keep it compact; a writer will act on it.

package/agents/docs-writer.md

@@ -0,0 +1,31 @@
+---
+name: docs-writer
+description: Writes and updates pages of the living-docs documentation site (docs-site/content) for human readers, verified against the code. Use for the plan, pages, update and topic modes of the docs-write skill - initial generation of the docs site, filling stub pages (one writer per section can run in parallel), refreshing pages after code changes, or documenting a specific module, flow or rule. Not for changing themes or the documentation guide.
+model: inherit
+skills: docs-write
+---
+
+You maintain a documentation website written for people, not for AI. It lives in the project folder that has `docs.config.json` next to `engine/` (usually `docs-site/`).
+
+Your first action in every run is to read the `docs-write` skill completely and follow it. It is in the first of these locations that exists:
+
+- `.claude/skills/docs-write/SKILL.md` or `~/.claude/skills/docs-write/SKILL.md`
+- `.cursor/skills/docs-write/SKILL.md` or `~/.cursor/skills/docs-write/SKILL.md`
+- `.agents/skills/docs-write/SKILL.md` or `~/.agents/skills/docs-write/SKILL.md`
+
+Then read `DOCS-GUIDE.md` in the site folder completely. Its rules override the skill's defaults.
+
+Your task message tells you:
+
+- the **mode**: `plan`, `pages`, `update` or `topic`;
+- for `pages`, the list of page files you own;
+- for `topic`, what to document.
+
+If the mode is missing, infer it as the skill describes. Rules for this run:
+
+- Work only on the pages you were given, plus the minimal link fixes elsewhere they require. Other writers may be editing other sections at the same time.
+- Read the code before you describe it. Never state behaviour you did not verify; use an `> [!UNVERIFIED]` callout instead.
+- Stamp only the pages you actually verified: `node engine/facts.mjs stamp <files>`.
+- Do not edit `engine/`, `themes/` or `DOCS-GUIDE.md`.
+- You cannot ask the user questions. When something is ambiguous, choose the reading best supported by the code, and mention it in your report.
+- Finish with `npm run check` (0 errors) and the short report the skill describes. Return only that report.

package/bin/cli.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// Installs the living-docs skills and subagents.
+//   npx living-docs-kit              current project  (./.claude/)
+//   npx living-docs-kit --all        all projects     (~/.claude/)
+//   npx living-docs-kit --uninstall  remove them again (combine with --all for the user-level copy)
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const KIT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SKILLS = ['docs-init', 'docs-design', 'docs-guide', 'docs-write'];
+const AGENTS = ['docs-writer.md', 'docs-reviewer.md'];
+const args = process.argv.slice(2);
+const has = (...f) => f.some((x) => args.includes(x));
+const version = JSON.parse(fs.readFileSync(path.join(KIT, 'package.json'), 'utf8')).version;
+
+if (has('-h', '--help')) {
+  console.log(`living-docs-kit ${version}
+
+Usage:
+  npx living-docs-kit              install into the current project (./.claude/)
+  npx living-docs-kit --all        install for all your projects (~/.claude/)
+  npx living-docs-kit --uninstall  remove from the current project (add --all for ~/.claude/)
+  npx living-docs-kit --version
+
+Claude Code and Cursor both load skills and subagents from these .claude folders.
+Run the project install from the root of the project you want to document.`);
+  process.exit(0);
+}
+if (has('-v', '--version')) { console.log(version); process.exit(0); }
+
+const unknown = args.filter((a) => !['--all', '--uninstall'].includes(a));
+if (unknown.length) { console.error(`✗ unknown option: ${unknown.join(' ')}  (see --help)`); process.exit(1); }
+
+const all = has('--all');
+const base = all ? path.join(os.homedir(), '.claude') : path.join(process.cwd(), '.claude');
+
+if (!all && process.cwd() === os.homedir()) {
+  console.error('✗ You are in your home folder. Run this from a project root, or use --all to install for all projects.');
+  process.exit(1);
+}
+
+try {
+  if (has('--uninstall')) {
+    let n = 0;
+    for (const s of SKILLS) { const p = path.join(base, 'skills', s); if (fs.existsSync(p)) { fs.rmSync(p, { recursive: true, force: true }); n++; } }
+    for (const a of AGENTS) { const p = path.join(base, 'agents', a); if (fs.existsSync(p)) { fs.rmSync(p); n++; } }
+    console.log(n ? `✓ removed ${n} items from ${base}` : `nothing to remove in ${base}`);
+    console.log('Existing docs-site/ folders in your projects are not touched.');
+    process.exit(0);
+  }
+  fs.mkdirSync(path.join(base, 'skills'), { recursive: true });
+  fs.mkdirSync(path.join(base, 'agents'), { recursive: true });
+  for (const s of SKILLS) {
+    const dest = path.join(base, 'skills', s);
+    fs.rmSync(dest, { recursive: true, force: true });
+    fs.cpSync(path.join(KIT, 'skills', s), dest, { recursive: true });
+  }
+  for (const a of AGENTS) fs.copyFileSync(path.join(KIT, 'agents', a), path.join(base, 'agents', a));
+  console.log(`✓ living-docs-kit ${version}: installed 4 skills and 2 subagents into ${base}`);
+  console.log(all ? '  Available in all your projects.' : '  Available in this project. You can commit .claude/ so everyone who clones it gets them.');
+  console.log('\nNext: restart Claude Code or reload Cursor, then ask "set up living docs for this project" (or /docs-init).');
+  console.log('To update later: npx living-docs-kit@latest' + (all ? ' --all' : ''));
+} catch (e) {
+  console.error('✗ ' + e.message);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "living-docs-kit",
+  "version": "0.1.0",
+  "description": "Skills and subagents for Claude Code and Cursor that build and maintain a human-friendly documentation website for a code project.",
+  "type": "module",
+  "bin": {
+    "living-docs-kit": "bin/cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "agents/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": ["claude-code", "cursor", "agent-skills", "subagents", "documentation", "static-site", "mermaid"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  }
+}

package/skills/docs-design/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: docs-design
+description: Create, change and manage the visual design of the living-docs documentation site - colour palettes, fonts, base font size, line height, widths and extra CSS - and choose which theme is the default. Use whenever the user wants a new theme or palette for the docs site (from a website URL, an image or screenshot, or a description), wants to tweak colours or fonts, wants to make a theme the default, or wants to save the font size they picked in the site (e.g. "keep the text at 120%"), even if they do not say "theme".
+---
+
+# docs-design
+
+Themes live in `<site>/themes/<id>.json`, one file per theme. Every theme appears automatically in the site's theme picker. The default theme is `defaultTheme` in `<site>/docs.config.json`.
+
+How the reader-side controls behave (explain this when relevant):
+
+- **Theme picker in the site.** A choice there is remembered in that browser only, until the reader picks "Default: …" again. It never changes files. The default for everyone is the one set in `docs.config.json`.
+- **A−/A+ buttons in the site.** They change the text size temporarily and nothing is saved; it resets on reload. The indicator shows a percentage of the theme's base size. To keep a size, the user asks for it and this skill writes it into a theme (see "Save a font size").
+
+This skill is interactive; run it in the main conversation. Talk to the user in their language. Theme labels are shown in the site, so write them in the documentation language.
+
+## Locate the site
+
+Use the folder that has `docs.config.json` next to `engine/` (usually `docs-site/`). If none exists, tell the user to run the `docs-init` skill first. Run every command below from the site folder.
+
+## Tools
+
+```bash
+node engine/theme-tool.mjs list                       # themes; ★ marks the default
+node engine/theme-tool.mjs show <id>                  # theme with all derived values filled in
+node engine/theme-tool.mjs validate [id]              # schema + WCAG contrast; exit 1 on errors
+node engine/theme-tool.mjs fix <id>                   # repair failing contrast (changes lightness only)
+node engine/theme-tool.mjs new <id> --from <base> --label "Label"
+node engine/theme-tool.mjs set <id> <path> <value>    # e.g. set fjord typography.baseSize 19
+node engine/theme-tool.mjs set-default <id>
+node engine/theme-tool.mjs remove <id>
+node engine/palette.mjs --url <website>               # CSS variables, colours by usage, fonts
+node engine/palette.mjs --image <file-or-url>         # dominant colours with share and contrast
+```
+
+Read `references/theme-schema.md` before writing or editing a theme file. It lists every token and explains how to map a raw palette onto tokens.
+
+## Create a theme
+
+1. **Get the raw material.**
+   - **Website:** run `palette.mjs --url`. If it reports very few colours (sites rendered by JavaScript), take a screenshot with a browser tool if one is available, save it, and run `--image` on it. Look at the site or the screenshot yourself when you can; usage counts alone do not reveal which colour is the brand accent.
+   - **Image:** if it is a URL, `palette.mjs --image` downloads it. Also look at the image yourself, because the order of the swatches often carries meaning.
+   - **Description:** choose the colours yourself.
+   - **Variant of an existing theme:** `theme-tool.mjs new <id> --from <base>`.
+2. **Map to tokens** following the mapping rules in the reference. Decide `mode` (light/dark) from the background.
+   - If the user asked for both modes, make two themes (e.g. `acme-light` and `acme-dark`) sharing the same accent hue.
+3. **Pick fonts.**
+   - Reuse the source's fonts when they exist on Google Fonts.
+   - Otherwise choose the closest readable Google Font and say so.
+   - Always add a fallback stack ending in a generic family.
+   - Build a `googleFontsUrl` (css2 API) that loads only the weights you use, typically 400, 600 or 700, and italic 400.
+   - Body text must be highly readable. Display-only fonts may be used for `heading` only.
+4. **Write** `themes/<id>.json`. Use a lowercase-hyphen `id`, a human `label`, and `source` saying where it came from (URL, file name, "description").
+5. **Validate:** run `theme-tool.mjs validate <id>`.
+   - On contrast errors, run `theme-tool.mjs fix <id>`, then validate again.
+   - Tell the user which colours were adjusted and why, e.g. "the link colour was darkened slightly to be readable on the background".
+   - Never ship a theme that fails validation.
+6. **Preview:** run `npm run build`, and suggest `npm run dev` if the preview is not already running. Point the user to the theme picker.
+7. **Ask whether it becomes the default.** If yes, run `set-default <id>`.
+
+## Change a theme
+
+- Small changes: `theme-tool.mjs set <id> <path> <value>`. It validates before saving. Examples:
+  - `set graphite colors.accent "#4fb3a9"`
+  - `set atlas layout.contentMaxWidth 820`
+  - `set fjord fonts.body "'Inter', system-ui, sans-serif"`
+- Several changes: edit the JSON file, then validate.
+- When a font family changes, update `googleFontsUrl` too.
+- If the user wants to keep the original, create a variant with `new … --from …` instead of editing.
+- Anything the tokens cannot express goes into `extraCss`, always scoped with `:root[data-theme="<id>"]` (see the reference).
+
+## Save a font size
+
+The user picked a size in the site (the indicator shows e.g. `120%`) and wants to keep it.
+
+1. Get the percentage. Ask for it if they did not say it.
+2. Find which theme they were viewing. It is usually the default; ask if unclear.
+3. Compute the new base size: `new baseSize = round(theme's baseSize × percentage / 100)`. Example: 17 px × 120% = 20 px. Values must stay between 12 and 28.
+4. Ask one question: change this theme, or create a new variant (e.g. `fjord-large`, labelled "Fjord (large text)")?
+   - To change: `set <id> typography.baseSize <px>`.
+   - For a variant: `new <id>-large --from <id> --label "…"`, then the `set` command on the new id.
+5. If the theme should also become the default, run `set-default`.
+6. Build, and tell the user to reset the site control to 100%. Otherwise the scale applies on top of the new base.
+
+## Set the default
+
+Run `theme-tool.mjs set-default <id>`, then build. Readers who picked a theme in their browser keep their choice until they select "Default" again. Mention this if the user expects everyone to see the change immediately.
+
+## Remove a theme
+
+Run `theme-tool.mjs remove <id>`. The default theme cannot be removed; set another default first.

package/skills/docs-design/references/theme-schema.md

@@ -0,0 +1,108 @@
+# Theme schema
+
+A theme is `themes/<id>.json`. The build turns every theme into CSS variables under `:root[data-theme="<id>"]`; `engine/assets/base.css` uses only these variables. All colours must be 6-digit hex.
+
+## Full example
+
+```json
+{
+  "id": "acme-light",
+  "label": "Acme (light)",
+  "mode": "light",
+  "source": "https://acme.example — extracted palette",
+  "colors": {
+    "bg": "#f7f8fa",
+    "surface": "#ffffff",
+    "surfaceAlt": "#eef1f5",
+    "text": "#1d2733",
+    "textMuted": "#566271",
+    "heading": "#111a24",
+    "border": "#d6dde5",
+    "accent": "#0f766e",
+    "accentText": "#ffffff",
+    "link": "#0d6a63",
+    "codeBg": "#eef1f5",
+    "codeText": "#1d2733",
+    "highlight": "#d7ece9",
+    "success": "#1f7a4d",
+    "warning": "#8a5a00",
+    "danger": "#b42318"
+  },
+  "fonts": {
+    "body": "'Source Sans 3', 'Segoe UI', system-ui, sans-serif",
+    "heading": "'Source Sans 3', 'Segoe UI', system-ui, sans-serif",
+    "mono": "'JetBrains Mono', ui-monospace, Menlo, Consolas, monospace",
+    "googleFontsUrl": "https://fonts.googleapis.com/css2?family=Source+Sans+3: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 },
+  "diagram": { "nodeBg": "#eef1f5", "nodeBorder": "#0f766e" },
+  "extraCss": ""
+}
+```
+
+## Tokens
+
+| Token | Required | Used for |
+|---|---|---|
+| `id` | yes | file name and `data-theme` value; lowercase letters, digits, hyphens |
+| `label` | yes | name in the theme picker, in the documentation language |
+| `mode` | yes | `light` or `dark`; sets `color-scheme` and diagram dark mode |
+| `source` | no | where the palette came from (shown by `theme-tool list`) |
+| `colors.bg` | yes | page background |
+| `colors.surface` | yes | cards, tables, callouts, search box, diagrams |
+| `colors.surfaceAlt` | no | hover states, default diagram nodes (derived from surface) |
+| `colors.text` | yes | body text |
+| `colors.textMuted` | yes | secondary text: breadcrumbs, captions, summaries of child pages |
+| `colors.heading` | no | headings (default: text) |
+| `colors.border` | yes | all hairlines |
+| `colors.accent` | yes | summary bar, active states, diagram borders, focus ring |
+| `colors.accentText` | yes | text placed on the accent colour |
+| `colors.link` | yes | links |
+| `colors.codeBg` / `codeText` | no | inline code and code blocks |
+| `colors.highlight` | no | current page in the menu, search selection, matched decision rule |
+| `colors.success` / `warning` / `danger` / `info` | no | badges ("verified", "possibly outdated") and callouts |
+| `fonts.body` / `heading` / `mono` | no | CSS font stacks; end with a generic family |
+| `fonts.googleFontsUrl` | no | one css2 URL loading every family used; loaded only when the theme is active |
+| `typography.baseSize` | no | root font size in px (12–28); everything scales from it |
+| `typography.lineHeight` | no | body line height (1.5–1.8 for reading) |
+| `typography.headingWeight` | no | 600 or 700 usually |
+| `layout.contentMaxWidth` | no | reading column in px (680–820 keeps lines under ~80 characters) |
+| `layout.sidebarWidth` | no | menu width in px |
+| `layout.radius` | no | corner radius in px (0–12) |
+| `diagram.nodeBg` / `nodeBorder` / `nodeText` / `lineColor` / `clusterBg` / `noteBg` | no | Mermaid colours (derived from colors when absent) |
+| `extraCss` | no | extra CSS; must be scoped with `:root[data-theme="<id>"]` |
+
+Contrast rules checked by `validate`:
+
+- **At least 4.5:1:** text, headings, links and code on their backgrounds; accentText on accent; text on highlight; text inside diagram nodes.
+- **At least 3:1:** badge colours and the accent on the background.
+
+## Mapping a raw palette onto tokens
+
+1. **Background.**
+   - Light mode: the lightest large-area colour, usually near white.
+   - Dark mode: the darkest large-area colour. Avoid pure `#000000`; a deep tinted grey reads better.
+2. **Surface.** A step away from `bg`: white on an off-white `bg`, or slightly lighter than `bg` in dark mode. If the source has only one background, derive the surface by mixing bg with 3–5% of the text colour.
+3. **Text.** The darkest neutral (light mode) or the lightest neutral (dark mode). Aim for 10:1 or more on `bg`.
+4. **textMuted.** A mid neutral between text and bg that still reaches 4.5:1.
+5. **Accent.** The most saturated, most "brand" colour; `themeColorMeta` or a CSS variable named like `--brand`, `--primary` or `--accent` is a strong hint. Only one accent.
+6. **Link.** The accent if it reaches 4.5:1 on `bg`; otherwise a darker (light mode) or lighter (dark mode) shade of the same hue.
+7. **accentText.** White or near-black, whichever contrasts more with the accent.
+8. **Border.** `bg` mixed with about 12–15% of the text colour.
+9. **Highlight.** `bg` mixed with about 15–25% of the accent.
+10. **Status colours.** Keep the defaults unless the source defines its own green, amber and red; they carry meaning, so keep them recognisable.
+11. **Diagram nodes.** `surfaceAlt` fill with an accent border works for most palettes.
+
+Keep hue changes minimal when fixing contrast; change lightness first. `theme-tool fix` does exactly that.
+
+## extraCss example
+
+```json
+"extraCss": ":root[data-theme=\"acme-light\"] .summary { border-left-width: 5px; }\n:root[data-theme=\"acme-light\"] h1 { letter-spacing: -0.02em; }"
+```
+
+Useful selectors in `base.css`:
+
+- page regions: `.topbar`, `.sidebar`, `.page`, `h1`, `.summary`, `.prose`;
+- components: `.callout-edge`, `.diagram`, `.decision`, `.children`, `.badge-stale`, `.footer`.

package/skills/docs-guide/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: docs-guide
+description: Maintain DOCS-GUIDE.md, the file that tells the documentation writer what topics to cover on the living-docs site, how to write them, which sections exist and when to update. Use whenever the user wants to change what the docs site covers or how it is written - add or drop a topic, enable or disable a section, change tone, language, depth, length limits or diagram rules, add project terms or conventions, change when docs get updated - or says things like "the docs should also explain X", "stop documenting Y", "write shorter pages", or "show me the docs guide".
+---
+
+# docs-guide
+
+`<site>/DOCS-GUIDE.md` is the brief for everything written on the documentation site. The `docs-write` skill and the `docs-writer` subagent read it before every run, and its rules override their defaults. Keeping it accurate is the cheapest way to get better documentation.
+
+This skill is interactive; run it in the main conversation. Talk to the user in their language. Write the guide in the documentation language: the language the guide already uses, English by default.
+
+## Locate the guide
+
+It lives in the folder that has `docs.config.json` next to `engine/` (usually `docs-site/`). If the site exists but the guide is missing, recreate it:
+
+1. Start from `<skill-dir>/../docs-init/assets/DOCS-GUIDE.template.md`.
+2. Fill in its placeholders from the project, the same way docs-init Step 6 does.
+3. Show the result to the user for approval.
+
+If there is no site at all, point the user to `docs-init`.
+
+## Structure to preserve
+
+The writer relies on these sections, in this order. Keep their headings; the text under them is free.
+
+| Section | Holds |
+|---|---|
+| Audience | who reads the site and what they must be able to do after five minutes |
+| Language and tone | documentation language, voice, naming conventions |
+| Site structure | checklist of sections `- [x] **Name** (`/path/`): what goes there`; `[ ]` disables a section |
+| Priority topics | concrete bullets naming real modules, flows and rules, most important first |
+| Out of scope | what must not be documented |
+| Writing rules | page and summary length, paragraph rules, examples, code links, unverified marking |
+| Diagrams | when and which diagrams, node limits, label style |
+| Edge cases and tests | how edge cases are recorded and linked to tests |
+| Project specifics | stack, domain glossary, conventions, external systems |
+| Updating | when updates happen and what an update includes |
+| Guide history | dated one-line entries, newest last |
+
+A translated guide keeps the same sections with translated headings. Match sections by meaning, not by exact wording.
+
+## Operations
+
+- **Show the guide.** Print it in full, or print only the section the user asks about.
+- **Add a topic.** Add a bullet to Priority topics, placed by importance. Make it concrete and checkable. "The retry policy for failed payments (`PaymentRetryJob`): limits, backoff, what the user sees" is good. "Payments" is not.
+- **Remove or deprioritize a topic.** Delete it, or move it lower. If the user wants it gone from the site too, also add it to Out of scope.
+- **Enable, disable or rename a section.** Edit the checklist line.
+  - A new section needs a path, a one-line description of its content, and a position.
+  - Paths are lowercase with hyphens and should stay stable once pages exist.
+- **Change a rule.** Edit the matching bullet instead of adding a contradicting one. Keep rules short, imperative and testable. For example, "a page has at most ~400 words" is testable; "keep pages short" is not.
+- **Add project knowledge.** Put domain terms (with a one-line meaning), conventions and external systems under Project specifics.
+- **Change the update policy.** Edit Updating. Typical choices:
+  - after every behaviour-changing task (the default);
+  - only when asked;
+  - at the end of each working session.
+
+After every change:
+
+1. Add a line to Guide history: `- YYYY-MM-DD: <what changed, in one sentence>`.
+2. Show the user the changed lines, not the whole file.
+3. Say which existing pages are affected. Look at the section paths, the `sources` in page frontmatter, and search `content/` for the topic.
+4. Offer to update those pages now. If the user says yes, run the `docs-write` skill (or the `docs-writer` subagent) in mode `pages` for those files. Do not regenerate without the user's go-ahead.
+
+During docs-init, approval of the first version is what starts the generation. There, apply edits and show the result again until the user approves; docs-init handles the rest.
+
+## Learning from corrections
+
+If the user corrects documentation output in a way that will recur, propose a guide rule in one sentence and add it if they agree. Examples of recurring corrections:
+
+- "don't explain what a REST API is";
+- "always show the HTTP status codes";
+- "call it *tenant*, not *customer*".
+
+This keeps the fix from being lost the next time pages are written.
+
+## Consistency checks
+
+Before saving, check:
+
+- The file is still valid Markdown.
+- Every enabled section has a path.
+- No two rules contradict each other.
+- The length limits agree with `limits` in `docs.config.json`. If the guide says "at most ~500 words", set `limits.pageMaxWords` a little above that, so `npm run check` warns at the same point.