git:20261001.02c28cd to git:20261008.d4dcb14

6 added, 0 removed. Audit A to A.

# docs/AGENTS.md

This directory is the public docs site: VitePress, deployed to GitHub Pages by

`.github/workflows/docs.yml` on every push to `main` that touches `docs/`.

```bash

cd docs && npm ci && npm run dev # preview with live reload

npm run build # must pass before a push

```

## Pages

- `cli-reference.md` is generated from the CLI's command definitions. Never edit it by hand; change

the help text in `src/dotbrain/cli.py` or the groups in `src/dotbrain/_cli_reference.py`, then

regenerate with `uv run python -m dotbrain._cli_reference`.

- `configuration.md` is tested: `tests/test_configuration_docs.py` loads the first YAML block under

``## `config.yaml` `` and ``## `project.yaml` `` through the real config loader. Keep those

headings exact, keep the fences plain ```` ```yaml ````, and keep every key the test reads.

+ - `zh/` holds the Simplified Chinese pages, one per English page with the same file name. They are

+ hand-maintained, best effort: write natural Chinese, keep commands, code, diagrams and terms

+ developers know in English (Agent, Coding Agent, PR, worktree, checkout) as is. When translating a

+ heading that is a link target, keep the English slug with `{#english-slug}`. `zh/cli-reference.md`

+ is a hand translation, not generated. Chinese nav and sidebar live under `locales.zh` in

+ `.vitepress/config.mts`.

- Name a code block's file in a `# path` comment on its first line. A `[title]` after the language

only renders inside a `::: code-group`.

- Use `::: code-group` for alternatives (Claude Code / Codex, macOS / Windows, uv / pipx).

- Check every claim against the code before writing it. Say what dotbrain does, not what a

neighbouring tool does (Beads, the agent runtime).

- Add a new page to the sidebar in `.vitepress/config.mts` and to the index in `README.md`.

## Diagrams

Follow the dotbrain Mermaid guide,

[`plugin/skills/brain-site/references/mermaid.md`](../plugin/skills/brain-site/references/mermaid.md):

diagram type, label style (bold name over a plain line, italic paths, verb arrow labels), fit, and

pitfalls. It is the convention for every project dotbrain wires; this site follows it too.

What is specific to this site:

- Diagrams are drawn by `.vitepress/theme/Mermaid.vue`. Font, size, and colours live there and in

`.vitepress/theme/style.css`; never style a single diagram.

- The content column is 688px. Preview the page and confirm each diagram draws, fits without

scrolling, and has no clipped label.

- A list of steps with no branches is the HTML step strip, `<ol class="flow-steps">`.