Audit the docs

The docs site is the user's only map of the app, and its failure mode is silent: a setting ships, a node type lands, a surface is renamed, and the page that described it keeps describing the old one. Nothing fails a build over it. This audit is the check.

It covers web/docs/ only. docs/architecture.md, ADRs, and the shipped agent skills are other surfaces with their own skills; step 3 says which change belongs where.

1. Scope the change

git diff main...HEAD --stat
git diff main...HEAD -- internal/app desktop/frontend/src

For a PR that is not checked out, gh pr diff <number>.

2. Inventory what a user can now see, do, or hit

Read the diff for these and write them down before deciding anything:

• a setting: a field on settings.Settings, a new mock mode, a new environment variable read anywhere;
• a node or action type: a connector.Descriptor, a flow node, an entry in actions.Doc, a field on any of their configs, a change to a payload contract;
• a surface: a new view, area, settings section, drawer, dialog, or a rename of one the docs refer to by name (Settings ▸ Integrations, Chats, Code);
• a verb or a key: a command in keybindings/catalog.ts, a default combo, a launcher rule;
• an agent-facing thing: a shipped skill, an MCP catalogue entry, a workspace manifest field;
• a failure a user meets: a new error message, a new precondition (a binary on PATH, a permission, a version floor), a removed fallback.

A refactor, a test, an internal rename, and a change to how something is drawn all inventory to nothing. Say so and stop. An audit that finds nothing is a valid outcome and is reported as one.

3. Decide where each one belongs

A user-facing fact goes on the docs site, on the page that already owns its subject. The site's structure mirrors the app: the sidebar groups of the Getting Started tab are the app's areas (Inbox, Code, Chats), each with its own directory under web/docs/, and the Configuration tab is the reference.

A new page is rare. It is right when a subject has no owner in that table and would not fit as a section of one, not when a feature is big. It goes in the directory and sidebar group of the area it belongs to; a new area is a new directory and a new group. Adding a page is the web-docs skill's procedure: the file, its frontmatter, and its line in the nav in web/zensical.toml. A page left out of the nav builds without a warning and is reachable by URL only, which is the same as not existing.

These are not docs-site changes, and saying so is half the audit:

• How the app is built goes in docs/architecture.md; why a choice was made goes in an ADR. A user page says what a thing does and what it needs, never how it is implemented.
• A change to a config schema also changes what the agent is told. The shipped skills under internal/app/prompts/templates/ and the per-type docs they splice in (flow/docs/*.md, actions/docs/*.md, mcpcatalog/docs/*.md) are the agent's reference. A field documented on the site but not there means the Hive workspace writes it wrong. That is the shipped-skills skill's procedure; run it beside this one.
• A user-visible change owes a release-notes fragment in internal/app/releasenotes/changelog/unreleased/. That is the release-notes skill.
• Developer-only facts (mock modes, launch.env, the devserver) belong on the build page only to the extent a person building the app must know them. The rest is docs/development.md and desktop/AGENTS.md.

4. Write it

The web-docs skill covers the mechanics: frontmatter, the nav, the build. The conventions that keep the pages consistent:

• Write the minimum useful page. Keep instructions, requirements, safety constraints, and recovery steps. Remove implementation details and reasons for ordinary controls.
• Summarize settings and shortcuts. Group visible controls in a sentence or short list. The app owns the complete live list. Show YAML only when a user needs to edit a file manually.
• Avoid generated-sounding prose. Do not use em or en dashes, rhetorical contrast formulas, "Why it matters" headings, staged reveals, or marketing filler. State the fact or instruction directly.
• Keep one owner for each fact. Link to the owner page instead of copying provider lists, action types, settings, or key tables onto another page.
• Name things what the app names them. Settings sections are Settings ▸ Integrations; the areas are Inbox, Code, and Chats; a workspace is a flow. Read sectionMeta.ts and the catalog's group values rather than guessing.
• Say what a thing needs before what it does. tmux 3.2, an agent on PATH, a scope on a token, a permission: the precondition goes first, in an admonition if a user would otherwise discover it by failing.
• Point at the Hive workspace where an agent could do the work. Every config page carries a short !!! tip "Ask the Hive workspace" naming the skill the seeded Hive workspace has for that file. Add one to a page that gains a config surface; do not add one to a page about a thing an agent cannot drive.
• A callout is an admonition: !!! tip "Title" on its own line, body indented four spaces. tip, note, and info are the types in use.
• The body starts with # Title. Add a short task-oriented lede only when the title needs context. The frontmatter is icon: and description: and its description is not repeated in the body.
• Internal links are relative Markdown-file links (../configuration/settings.md#updates), which the strict build validates.
• Do not hand-maintain what is derived. The tabs, the sidebar and its groups, the prev/next footer, search, the sitemap, llms.txt, llms-full.txt, and each page's .md twin all come from the nav and the pages. A page in the nav appears everywhere with no further edit.

A fact you cannot verify in the code does not go on the page. Read the struct, the descriptor, or the component; the docs are reviewed as a spec.

5. Verify

cd web && mise run build

(mise run install first in a fresh worktree; both run from inside web/.) The build runs zensical build --strict and aborts on any warning: a link to a page that does not exist, an anchor that is not a heading on its target, or a nav entry whose file is missing. Then check the two things the build cannot:

1. Every new page is in the nav in web/zensical.toml. The build does not warn about a page that is not.
2. The page says what the code does. Re-read the diff beside the page. A default, a range, a scope name, and a key are the four things most often wrong.

PR CI runs the same build (web-build), so a broken link fails the PR. It cannot tell a wrong default from a right one; only this step can.

Report

Say what you added or changed, page by page, and say what you decided not to document and why. "This is internal shape and belongs in architecture.md", "the shipped skill needs the same field", and "no user can see this" are all conclusions worth writing down, because the next audit re-asks the same questions.