Skip to content

Contributing to these docs

This page is for humans extending Bedrock Docs. For the full agent-facing contract — including the worked example of promoting a doc out of a source repo — see AGENTS.md. This page is the short version plus the local workflow.

The routing rule — does a new doc belong here?

Bedrock Docs is the cross-cutting truth for the 8-repo Bedrock system. Before you write or move a page, apply one test:

"Would an agent working in a different repo need this?"

  • No → it is implementation detail for one repo. Keep it there (<repo>/docs/ or that repo's CLAUDE.md) — Android Hilt setup, a service's deploy steps, repo-specific build commands.
  • Yes, or it is system onboarding → it belongs here. Write it once, then replace the duplicate in the source repo with a one-line link. Never leave two copies — that is how the old SECURITY.md drift happened.

When in doubt, prefer local; promote to central only when a second consumer appears. The full contract and a worked promotion example live in AGENTS.md.

Local workflow

The markdown source lives at the repo root so it stays readable on GitHub. Build with the project venv active:

source .venv-mkdocs/bin/activate

bash serve.sh        # live preview at http://127.0.0.1:8000 — edits to the root
                     # source live-reload
bash build.sh        # one-off strict production build (fails on broken links)

Use serve.sh while writing and build.sh to confirm the page is deploy-clean before you push. See Deploying this site for how the build and hosting fit together.

Never edit site_src/ by hand

build.sh (and serve.sh) mirror the root source verbatim into a generated site_src/ directory, which is what MkDocs actually builds from. site_src/, site/, and .venv-mkdocs/ are gitignored and regenerated on every build — editing them does nothing durable and your changes get clobbered. Always edit the root source (security/, protocol/, training/, the top-level *.md files), never the copy.

build.sh runs mkdocs build --strict, and mkdocs.yml promotes broken links and bad anchors to warnings. A dead link or a wrong #anchor therefore fails the build — and because build.sh is the Cloudflare Pages build command, a broken link fails the deploy. There is no separate CI; the strict build is the gate. Run bash build.sh locally before you push.

Verify against source

Pages that describe code carry a footer of the form:

_Verified against `<repo>@<sha>` on <date> — <what was checked>._

That footer is a claim about a specific commit. When you touch such a page, reconcile it against the current code rather than copying stale prose, then update the sha and date to what you actually checked. Drift between the prose and the code is the failure mode these docs exist to prevent (see Anti-drift).

See also