living-docs-kit 0.1.0

package/skills/docs-init/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: docs-init
+description: Set up a human-friendly documentation website (static site with drill-down navigation, clickable diagrams, decision tables, switchable themes) for the current code project, then run the first full generation. Use whenever the user wants to create, initialize, bootstrap or start "living docs", a docs site, a documentation website or a readable overview of their codebase for people, or wants to upgrade an existing docs-site engine. Asks for the design (existing website, palette image, preset or description), drafts the documentation guide, shows it for approval, and only then generates content.
+---
+
+# docs-init
+
+Creates `docs-site/` (or another folder the user picks) inside the project, gives it a design, writes the documentation guide `DOCS-GUIDE.md` together with the user, and runs the initial generation.
+
+This skill is interactive: run it in the main conversation, never inside a subagent. Talk to the user in the language they use with you; the site and the guide default to English unless the user chooses another documentation language.
+
+`<skill-dir>` below means the folder that contains this SKILL.md. The sibling skills live next to it: `<skill-dir>/../docs-design`, `<skill-dir>/../docs-guide`, `<skill-dir>/../docs-write`.
+
+## The finished layout
+
+```
+<project>/docs-site/
+  docs.config.json   site settings: title, default theme, code links, limits, state
+  DOCS-GUIDE.md      what to document and how (owned by docs-guide)
+  content/           the pages (Markdown + frontmatter), written by docs-write
+  themes/            one JSON file per theme (owned by docs-design)
+  engine/            build, dev server, checker, facts, theme and palette tools; never edit per project
+  dist/              built site (git-ignored)
+```
+
+## Step 0 — Preconditions and existing sites
+
+1. Run `node -v`. Node 20 or newer is required; if it is missing or older, tell the user and stop.
+2. Find the project root: the git root if there is one (`git rev-parse --show-toplevel`), else the current folder.
+3. Look for an existing site: any `docs.config.json` next to an `engine/` folder (check `docs-site/` first, then search, skipping `node_modules`). If one exists, ask what to do:
+   - **Continue**: if `state.guideApproved` is false, resume at the step that is not done yet (design → guide → generation).
+   - **Upgrade the engine**: copy `<skill-dir>/assets/site-template/engine/` over the site's `engine/`, merge `scripts` and `dependencies` from the template `package.json`, run `npm install`, build, and stop. Content, themes, config and guide stay untouched.
+   - **New site in another folder**, or **cancel**.
+
+## Step 1 — Basics
+
+Ask these together in one message (use the structured question tool if the client has one) and propose defaults so the user can simply confirm:
+
+- Site folder: `docs-site`.
+- Site title: the project name from the main manifest (`package.json`, `pyproject.toml`, …) or the folder name.
+- Documentation language: English.
+- Editor for code links: `cursor` if the user works in Cursor, `vscode` for VS Code, `none` otherwise.
+
+## Step 2 — Design (always ask)
+
+Ask which design the site should use. Offer exactly these options:
+
+1. **An existing website**: the user gives a URL; the site takes its colours and fonts.
+2. **An image with a palette**: a link or a local file (a palette, a screenshot, a brand sheet).
+3. **One of the included themes**: Fjord (light, very readable sans-serif), Graphite (dark, amber accent), Atlas (light, serif).
+4. **A description in words**, for example "calm, dark blue, technical, compact".
+
+Also ask whether they want a light theme, a dark theme, or both. Carry out the choice in Step 4, following docs-design.
+
+## Step 3 — Create the site
+
+1. Copy `<skill-dir>/assets/site-template/` to `<project>/<folder>/`.
+2. In `docs.config.json` set:
+   - `id` to a slug of the title;
+   - `title`;
+   - `uiLanguage` to `en`, or to `ro` when the documentation language is Romanian;
+   - `codeLinks.editor`.
+   Set `projectRoot` to the relative path from the site folder to the project root (`..` for `docs-site/`).
+3. If `git remote get-url origin` points to GitHub or GitLab, set `codeLinks.webBase` to the blob URL of the default branch (e.g. `https://github.com/org/repo/blob/main/`) and `codeLinks.mode` to `both`, so code links also work when the site is hosted.
+4. Replace `__PROJECT_NAME__` in `content/index.md`.
+5. Run `npm install` inside the site folder.
+
+## Step 4 — Apply the design
+
+Read `<skill-dir>/../docs-design/SKILL.md` and follow its "Create a theme" procedure for the user's choice.
+
+- For an included theme, just set it as default: `node engine/theme-tool.mjs set-default <id>`.
+- Keep the other presets unless the user wants only their own theme.
+- The result must be at least one valid theme set as `defaultTheme` (`node engine/theme-tool.mjs validate` passes).
+
+## Step 5 — Understand the project
+
+Build a factual picture before writing the guide. Delegate the reading to an exploration subagent if the client has one.
+
+1. Run `node engine/facts.mjs` in the site folder. It returns:
+   - languages, structure and manifests;
+   - entry points and tests;
+   - existing README/AGENTS files.
+2. Read the existing READMEs (they are often written for AI; mine them for facts, not style), the manifests, the entry points and the largest source folders.
+3. Identify:
+   - the main modules;
+   - the 3–8 most important user-facing flows;
+   - the business rules and the entities with states;
+   - external systems, the data storage, and the obvious edge cases (validation, errors, limits, concurrency, money, time zones).
+
+## Step 6 — Draft the guide, show it, iterate
+
+1. Copy `<skill-dir>/assets/DOCS-GUIDE.template.md` to `<site>/DOCS-GUIDE.md`. If the documentation language is not English, translate the whole guide into that language, keeping the section structure.
+2. Fill the placeholders:
+   - `{{PROJECT_NAME}}`, `{{LANGUAGE}}`, `{{DATE}}` (today).
+   - `{{AUDIENCE}}`: default "a developer who knows the stack but not this project, and the owner returning after a few weeks away".
+   - `{{DATA_SECTION}}`: `[x]` if the project stores data, otherwise `[ ]`.
+   - `{{TOPICS}}`: 5–12 concrete bullets naming real modules, flows and rules found in Step 5, most important first.
+   - `{{EXCLUDES}}`: extra project-specific bullets (generated folders, vendored code, migrations…), or nothing.
+   - `{{PROJECT_SPECIFIC}}`: stack, domain terms with one-line meanings, conventions noticed in the code, important external systems.
+   - `{{UPDATE_POLICY}}`: default "after every task that changes behaviour (logic, flows, rules, edge cases, data model, public API)".
+   - Also disable sections that clearly do not apply, and say why in your message.
+3. Show the complete guide to the user in the chat, not only a summary, and give its path so they can edit it in the editor. Ask what to change: topics, sections, tone, depth, anything.
+4. Apply changes following `<skill-dir>/../docs-guide/SKILL.md`. Show the changed parts and ask again. Repeat until the user clearly approves ("looks good", "go", "start").
+5. Do not start generating before explicit approval. Then set `state.guideApproved` to `true` in `docs.config.json`.
+
+## Step 7 — Initial generation
+
+Follow the procedure in `<skill-dir>/../docs-write/SKILL.md`, delegating to the `docs-writer` subagent when available:
+
+1. **Plan**: one `docs-writer` run with mode `plan`. It creates the home page, the section index pages and stub pages (frontmatter plus `<!-- stub -->`), and returns the site map.
+2. **Write**: `docs-writer` runs with mode `pages`, one per section, in parallel if the client allows it. Each gets its list of stub files.
+3. **Check**: `npm run check` in the site folder must report 0 errors. Send remaining problems back to a writer.
+4. **Review**: run the `docs-reviewer` subagent on the home page, one section overview and two detail pages. Pass its findings to a writer and fix them.
+5. **Finish**: run `node engine/facts.mjs mark`, then `npm run build`.
+
+Without subagents, do the same steps yourself, one section at a time.
+
+## Step 8 — Hand over
+
+Tell the user, briefly:
+
+- how to view the site: `cd <folder> && npm run dev` opens a live-reloading preview at http://localhost:4321; `dist/index.html` also opens directly from disk;
+- what was generated: the sections and the number of pages;
+- what the checker still warns about.
+
+Then offer two optional extras and do each only if the user says yes:
+
+- **Keep docs up to date automatically.** Append `<skill-dir>/assets/agents-snippet.md` (with `__SITE_DIR__` replaced) to the project's `AGENTS.md` and/or `CLAUDE.md`, creating the file if needed.
+- **Publish on GitHub Pages.** Copy `<skill-dir>/assets/deploy-github-pages.yml` to `.github/workflows/docs.yml` (with `__SITE_DIR__` replaced) and explain the one repository setting it needs. Mention that a public Pages site exposes the documentation; private repos need a plan that supports private Pages, or another host behind authentication.
+
+Also mention the other skills in one line each:
+
+- `docs-design`: add a theme or change the default;
+- `docs-guide`: change what gets written;
+- asking to "update the docs" runs docs-write.

package/skills/docs-init/assets/DOCS-GUIDE.template.md

@@ -0,0 +1,81 @@
+# Documentation guide: {{PROJECT_NAME}}
+
+> This file tells the agent **what** to write on the documentation site and **how**. Edit it directly, or ask the agent ("add to the guide…", "stop documenting…"), which uses the `docs-guide` skill. Rules here take precedence over the general rules of the `docs-write` skill.
+
+## Audience
+
+- Primary reader: {{AUDIENCE}}
+- After five minutes on the site, the reader can explain what the application does, what its main parts are, and where the important logic lives.
+- The reader has not read the code. The reader can program.
+
+## Language and tone
+
+- Documentation language: {{LANGUAGE}}.
+- Direct and calm; short sentences; no superlatives, no marketing.
+- Explain **why** something exists before **how** it works.
+- Code names appear exactly as in the code, in `backticks`, linked to the code on their first mention on a page.
+
+## Site structure
+
+Sections in menu order. `[x]` = enabled, `[ ]` = disabled.
+
+- [x] **Home** (`/`): what the application is in at most 120 words, a system map (one diagram whose nodes link to the sections), and "what to know in 30 seconds" (3–5 points).
+- [x] **Architecture** (`/architecture/`): from the big picture to the details: context (who uses the system, which external systems it talks to), then the large parts (apps, services, databases), then one page per important module.
+- [x] **Flows** (`/flows/`): the main scenarios from the user's point of view, step by step, with a sequence diagram and a code link for each step.
+- [x] **Rules and states** (`/rules/`): business rules as interactive decision tables, state machines of the main entities, and a glossary of domain terms.
+- [x] **Edge cases** (`/edge-cases/`): the catalogue of special situations; each with what happens, why, where it is in the code, and which test covers it (or "not covered").
+- {{DATA_SECTION}} **Data** (`/data/`): the data model (ER diagram), where data comes from and where it goes.
+- [ ] **Decisions** (`/decisions/`): why an option was chosen: context, decision, rejected alternatives, consequences.
+- [x] **What changed** (`/changes/`): one entry per update, written for a person ("rule X now also applies to Y"), not a list of commits.
+- [ ] **Risks and technical debt** (`/risks/`): fragile, untested or hard-to-change parts.
+
+## Priority topics
+
+What must be clear on the site. Proposed at initialization from the code analysis; edit freely.
+
+{{TOPICS}}
+
+## Out of scope
+
+- Generated code, third-party dependencies, trivial configuration files.
+- Complete lists of files, functions or fields that change often and do not help understanding.
+- Individual tests: document only which behaviour they cover and what is missing.
+{{EXCLUDES}}
+
+## Writing rules
+
+- Every page has a `summary` of 1–2 sentences answering "what is this and why does it matter".
+- A page has at most ~600 words. Beyond that it is split into subpages and the parent becomes an overview.
+- A section overview has at most ~200 words; details live in subpages.
+- One paragraph, one idea. Lists only for parallel items.
+- Concrete examples (real values, field names, a typical request) instead of abstract descriptions.
+- Every statement about behaviour links to the code that implements it.
+- Anything that could not be verified in the code is explicitly marked as unverified.
+- Do not retell the code line by line; explain intent, rules and consequences.
+
+## Diagrams
+
+- Home and every section page have a map diagram whose nodes link to the subpages.
+- At most ~12 nodes per diagram. With more, split into levels with drill-down.
+- Flows: sequence diagrams. States: state diagrams. Data: ER diagrams. Structure: flowcharts.
+- Short labels (2–4 words) in the documentation language.
+
+## Edge cases and tests
+
+- Edge cases appear on the page where they matter (an "Edge case" callout) and in the Edge cases catalogue.
+- For each: what happens, why, where in the code, which test covers it.
+- An edge case without a test is marked "not covered by tests".
+
+## Project specifics
+
+{{PROJECT_SPECIFIC}}
+
+## Updating
+
+- When to update: {{UPDATE_POLICY}}
+- Each update changes only the affected pages and adds an entry to "What changed".
+- Refactors that do not change behaviour update the code links but get no "What changed" entry.
+
+## Guide history
+
+- {{DATE}}: created at initialization.

package/skills/docs-init/assets/agents-snippet.md

@@ -0,0 +1,7 @@
+## Living docs
+
+This project has a human-oriented documentation site in `__SITE_DIR__/`, maintained by the `docs-*` skills.
+
+- When a task changes behaviour (logic, flows, business rules, edge cases, data model, public API), update the docs as described in the "Actualizare" section of `__SITE_DIR__/DOCS-GUIDE.md`: delegate to the `docs-writer` subagent with mode `update`, or follow the `docs-write` skill in update mode.
+- Never edit `__SITE_DIR__/engine/`. Never hand-edit `sourcesHash`, `updated` or `commit` in page frontmatter; `node engine/facts.mjs stamp` writes them.
+- Preview: `cd __SITE_DIR__ && npm run dev`, or open `__SITE_DIR__/dist/index.html`.

package/skills/docs-init/assets/deploy-github-pages.yml

@@ -0,0 +1,43 @@
+# Publishes the documentation site to GitHub Pages on every push to the default branch.
+# Copy to .github/workflows/docs.yml and replace __SITE_DIR__ with the site folder (e.g. docs-site).
+# In the repository: Settings → Pages → Source: "GitHub Actions".
+name: docs
+on:
+  push:
+    branches: [main, master]
+  workflow_dispatch:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: pages
+  cancel-in-progress: true
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: __SITE_DIR__
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install --no-audit --no-fund
+      - run: npm run check
+      - run: npm run build:hosted
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: __SITE_DIR__/dist
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

package/skills/docs-init/assets/site-template/content/index.md

@@ -0,0 +1,4 @@
+---
+title: __PROJECT_NAME__
+summary: The documentation has not been generated yet. Run the docs-init skill to start the initial generation.
+---

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

@@ -0,0 +1,36 @@
+{
+  "id": "__SITE_ID__",
+  "title": "__PROJECT_NAME__",
+  "description": "",
+  "uiLanguage": "en",
+  "projectRoot": "..",
+  "defaultTheme": "fjord",
+  "codeLinks": {
+    "mode": "editor",
+    "editor": "cursor",
+    "webBase": ""
+  },
+  "limits": {
+    "summaryMaxChars": 280,
+    "pageMaxWords": 900
+  },
+  "exclude": [
+    "node_modules",
+    "dist",
+    "build",
+    "out",
+    ".git",
+    "vendor",
+    ".venv",
+    "venv",
+    "__pycache__",
+    "coverage",
+    ".next",
+    "target"
+  ],
+  "state": {
+    "guideApproved": false,
+    "lastGeneratedCommit": null,
+    "lastGeneratedAt": null
+  }
+}