Skip to content

Contributing

These rules apply to everyone who writes here, people and agents alike.

Who the site is for

Readers include people who have never used this setup. Explain a term the first time it appears on a page, or link to the word list in the Overview. Write in plain English, in short sentences.

What belongs on a page

  • What, why and how, at a high level. Say what a part does, why it exists, and in outline how it is built. Leave the details to the repository that owns the part, and link to it.
  • Name the owner. Start each page with an Owner line that links the owning repository.
  • Check before you write. Read the claim in the owning repository, or measure it on a running device, before you write it down. Remembered or summarised facts are not enough. When a page is written against a specific commit, say which.
  • Avoid numbers that go stale. Versions, counts, sizes and digests change without anyone editing this site. Say where to find the current value, such as the build manifest, the changelog or the owning README, instead of copying it. Dates of decisions and events are fine.
  • Mechanisms, not inventory. Describe how things work. Host addresses, ports, key fingerprints and account details belong in fleet-ops. Never put a secret value on a page, even an expired one.

Diagrams

Use Mermaid code blocks. Keep each node to at most two short lines and put the detail in the text below the diagram; longer labels get cut off when they render. Check a page with the mermaid-diagrams skill's checker:

~/.agents/skills/mermaid-diagrams/check-mermaid.sh docs/<page>.md

Build and check locally

You need uv. It installs the pinned Zensical version from uv.lock.

uv run zensical serve           # live preview at http://localhost:8000
uv run zensical build --strict  # what CI runs; fails on broken links
gitleaks dir .                  # secret scan, also run by CI

Adding a page

  1. Create the Markdown file under docs/.
  2. Add it to nav in zensical.toml.
  3. Run the strict build.
  4. For a decision, add a record under docs/decisions/ and list it on the Decisions page.