Beads Documentation Style Guide

5. Prose doctrine — cut words, sharpen points

Most bloat is information stored in the wrong medium. Move it to a cheaper carrier, then delete what isn't pulling weight. Every page must stand alone — a reader landing cold needs a one-line setup, not a previous page.

Convert (move load off prose):

• A relationship or sequence → a diagram (mermaid renders natively; richer diagrams follow the Excalidraw pipeline — see §7).
• Parallel options/fields/comparisons → a table.
• "you run X, which does Y" narration → an annotated CLI snippet (show the command and its output, comment the interesting lines).
• Edge cases and deep mechanics → an <Accordion>, or a reference page. Keep the 80% case on the page.

Delete (the load was fake): throat-clearing openers ("In this section we'll…"), hedge chains ("generally / typically / in most cases"), restatement, narrating an artifact a snippet already shows, and adjectives standing in for evidence.

When you run a deliberate simplification pass, follow references/simplification.md — the per-page loop and the two guardrails that keep a trim honest: a loss-check (never drop a fact that lives nowhere else) and a fact-check (trimmed prose must not drift from the code).

6. Emphasis and formatting

• Bold names a term, on first mention only. Italic marks a property or contrast. ~1–2 marks per paragraph; never re-emphasize a term already introduced; never give one phrase both treatments.
• No body # H1 — the frontmatter title is the H1. Use ##/###.
• Links are root-relative and extensionless (/getting-started/quickstart). Links out of the site (engdocs/, repo files) use full GitHub URLs.
• Mintlify parses .md as MDX: no HTML comments ({/* … */} instead), and angle-bracket placeholders like <id> must stay inside backticks or code fences.
• Mintlify components (<Note>, <Tip>, <Warning>, <Accordion>) sparingly — they lose force with repetition.

7. Diagrams

Mermaid fences render natively — prefer them for graphs and flows. For richer diagrams use the Excalidraw pipeline: author the .excalidraw source under docs/diagrams/excalidraw/, render with make diagrams-excalidraw (source and rendered .svg are both committed), embed as /diagrams/excalidraw-rendered/<name>.svg with descriptive alt text, and keep labels short (a two-line "Name / role" beats a sentence crammed in a box). Two non-negotiables:

• Rasterize and look at every rendered diagram — text overflow and layout problems are invisible in a text diff.
• Diagrams and images cannot be reviewed in a diff. Render them and get the maintainer's approval before committing.

8. Generated content is edited at its source

Never hand-edit a generated file. The generated surfaces are:

• docs/cli-reference/*.md and the CLI Reference pages array inside docs/docs.json — bd emits vendor-neutral pages (bd help --docs-root, from the Cobra command strings in cmd/bd/*.go) into an uncommitted staging tree, and tools/docsmint post-processes them into the committed Mintlify form. bd itself never emits Mintlify (or any site-generator) specifics; that lives in docsmint.
• docs/CLI_REFERENCE.md — the single-file reference, emitted directly by bd help --docs-root.

To change wording in any of them, edit the Go source (Short:, Long:, Example: strings) and run ./scripts/generate-cli-docs.sh (which runs both stages). To change the Mintlify page form itself (comment markers, link style, nav), edit tools/docsmint and its tests. The drift gates (generate-cli-docs.sh --check, scripts/check-cli-docs-drift.sh in PR CI, and the docs-autofix bot) fail or auto-fix any hand edit.

The docs describe the pinned release, not main. docs/cli-docs.pin names the release tag the whole docs corpus targets; the pipeline builds bd from that tag and validates against it, so a Go-source edit on main shows up in the committed docs only after the pin is bumped (at release time, followed by a regeneration). Hand-written pages follow the same policy: document what the pinned release does, never main-only features. See engdocs/decisions/2026-07-17-docs-release-pin.md.

9. Verify before you call it done

Run the gates in references/verification.md. The short list: go test ./test/docsync (nav↔file sync + link conventions), ./scripts/generate-cli-docs.sh --check (generated docs fresh), ./scripts/check-doc-freshness.sh (Last reviewed markers), and a live preview with make docs-dev (or ./mint.sh dev) at localhost:3000.

When you move or remove a page: add a redirect to the redirects array in docs/docs.json, rewrite inbound links repo-wide (README, engdocs/, examples/, npm-package/, plugin resources — grep, don't guess), and check whether bd prints the old path (if so, fix the Go source and regenerate — never a pointer stub; decision 6 covers old routes with redirects).

10. Review and commit discipline

• Author → the maintainer reviews → commit on explicit approval. This matters most for diagrams and images, which can't be reviewed in a text diff.
• Group commits by audience: user docs (docs/) separate from contributor docs (engdocs/, AGENTS.md) separate from generator/Go changes.
• Track docs work as bd issues per AGENTS.md.