Skip to content

AGENTS.md — how agents use Bedrock Docs

What this repo is

Cross-cutting truth for the 8-repo Bedrock system (see README.md). If you are an agent working in any repo and you need to understand something that spans repos — the security model, PKI, the wire protocol, the system architecture — it lives here, not in the individual repo.

The routing rule (where does a new doc go?)

When you write or move a doc, decide its home with one test:

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

  • No → it is implementation detail for one repo. Keep it in that repo (<repo>/docs/ or its CLAUDE.md). Examples: Android Hilt setup, MDM config, a service's deploy runbook, repo-specific build steps.
  • Yes, or it is system onboarding → it belongs in this central repo. Write it here, then delete the duplicate in the source repo and replace it with a one-line link to the central page. Do not leave two copies — that is how the current SECURITY.md drift happened.

When in doubt, prefer local; promote to central only when a second consumer appears.

Worked example — promoting a doc

A security model lived in both android/SECURITY.md and web/SECURITY.md and drifted. To promote:

  1. Write the reconciled truth once at security/model.md (verify against current code — see Anti-drift).
  2. Replace each source file's body with a one-line link to the central page.
  3. Keep genuinely repo-specific detail local (e.g. the web bridge's impl pointers) and link to it from the central page's "Where to read the code" section.

Result: one page, two links, no copies. (Already done for security, PKI, wire protocol, outbox, and interop standards.)

Finding a repo's entry point

Each repo's CLAUDE.md is its agent entry point and should link here for shared concerns rather than restating them. Start there for repo-specific build/test/convention rules.

Anti-drift

  • One concept = one page = one repo. No copies.
  • A central page that describes code MUST be reconciled against current code when written — do not copy stale prose. (The stale android/SECURITY.md describes a QUIC transport that the code does not have; reality is Zenoh TLS + verifyAuthEnvelope.)
  • Describe the present, not the past. Every page states what the code is now, or what it must become to close a known gap — never what it was. Do not narrate migrations as history ("previously bound an X.509 serial", "the old QUIC stack is gone"). State current reality ("identity is token-only; bound_cert_serial is reserved/removed") and track in-flight work as remaining steps, not as a changelog — e.g. security/pki.md's "Transitional — being removed" section lists the residual paths still to delete. Past tense is fine only for non-code facts: a principal's runtime state ("the user was revoked") or an external standard's older format.
  • Each repo's CLAUDE.md stays the agent entry point for that repo and should link here for shared concerns rather than restating them.

Contributing docs

Adding or moving a doc: apply the routing rule above. Write the reconciled truth once (verify against current code), replace any source-repo duplicate with a one-line link, and link the new page from README.md and related pages.