Skip to content

AGENTS.md

Guidance for agents maintaining Bedrock's cross-repository documentation.

Purpose and authority

This repository is the shared source for architecture, security, protocol, design, and operator guidance used by more than one Bedrock component. Keep single-repository implementation details and build instructions with that repository.

MANIFESTO.md is a human-owned governance artifact. Read it and align other documentation to it, but do not edit, reword, move, or reconcile it unless the user explicitly asks to change that file in the current conversation. An authorized Manifesto change belongs in its own reviewed PR.

For technical claims, verify the current contract and implementation rather than treating existing prose as proof. Shared schemas, cryptography, key names, and authorization decisions live in common; component behavior lives in the relevant repository. Surface a conflict with the Manifesto instead of silently changing the governing text.

Place information once

Before adding or moving documentation, ask whether a developer in another repository needs it:

  • If no, keep it in the component repository.
  • If yes, or it is system onboarding, put it here.

Do not maintain parallel copies. When promoting content here, reconcile one central page against current sources, replace source-repository copies with a short link, and retain genuinely local implementation detail locally. Prefer a local home until a second consumer exists.

Editing rules

  • Edit root source files and directories such as architecture/, security/, protocol/, design/, and training/. Never edit generated site_src/ or site/; build.sh recreates them.
  • Add, move, or rename a published page in the nav section of mkdocs.yml. Update the relevant index and related-page links at the same time.
  • Use relative links within this repository. Use full GitHub URLs for files in other repositories; relative paths that escape this repository fail the strict build.
  • Describe current behavior in present tense. State unmet requirements as explicit gaps or remaining work, not migration history.
  • Preserve the distinction between implemented, transitional, planned, and not started behavior. Do not turn a roadmap requirement into a claim that code already ships.
  • When editing a page with a _Verified against ..._ footer, inspect the named source repository and update the commit SHA, date, and scope to what you actually verified.
  • Use Mermaid fenced blocks for diagrams and follow the existing heading, admonition, table, and link style in nearby pages.
  • Keep repository-agent guidance here. CLAUDE.md is only a compatibility pointer to this file.

Repository map

  • README.md: site landing page and system routing map.
  • MANIFESTO.md: protected product and trust brief.
  • architecture/: system boundaries, flows, topology, and roadmap.
  • security/: security, authorization, and PKI models.
  • protocol/: wire, command, ingest, export, snapshot, and interop contracts.
  • training/: deployment guidance and operator runbooks.
  • design/: cross-component design and architecture proposals.
  • mkdocs.yml: navigation, rendering, and strict link validation.
  • build.sh: production build and generated-source synchronization.
  • serve.sh: local live-preview wrapper.
  • skill/ and build-skill.sh: downloadable Claude skill packaging; this is a published product feature, not repository-agent configuration.

Verification

Set up the pinned toolchain when needed:

python3 -m venv .venv-mkdocs
.venv-mkdocs/bin/pip install -r requirements.txt
source .venv-mkdocs/bin/activate

Before handing off any documentation change, run:

bash build.sh

This executes mkdocs build --strict; broken links, bad anchors, missing nav targets, and rendering warnings fail the build. Use bash serve.sh for live preview when visual review is useful. Do not commit site_src/, site/, the virtual environment, or the generated skill archive.