Repository Source of Truth
Peak Gateway keeps long-lived operational and architecture knowledge in support docs, generated API references, executable tests, or source comments next to the behavior they explain. Dated plans and audit notes are temporary work products. Once they ship, are superseded, or are abandoned, delete them and move only durable guidance into one of the canonical locations below.
Canonical locations
| Knowledge type | Canonical location |
|---|---|
| Runtime architecture, service boundaries, runbooks, and operational policy | websites/support-docs/docs/ |
| Public and internal API shape | OpenAPI YAML, generated OpenAPI docs, and the controller/DTO code that produces them |
| SDK behavior and migration guidance | SDK source/tests plus websites/support-docs/docs/sdks/ |
| Current expected behavior | Executable unit, integration, or E2E tests |
| Local implementation rationale | Short source comments beside the relevant code |
Cleanup rules
- Delete stale planning folders and dated notes instead of archiving them.
- Do not link source, Terraform, runbooks, or tests to deleted planning artifacts.
- Keep tests executable. Remove skipped scaffolds that only encode future intent.
- Prefer generated OpenAPI output over hand-written endpoint narratives when describing request and response shapes.
- Replace historical source comments with the current operational reason for the code.
Enforcement
tools/lint/check_source_truth_refs.sh blocks references to removed planning artifacts and intent-only skipped test scaffolding. The hook is wired into pre-commit as source-truth-cleanup.
Generated OpenAPI pages are checked in so the documentation sites can build predictably. Regenerate them from the YAML specs before editing generated API pages by hand:
pnpm --dir websites/docs run generate:openapi
pnpm --dir websites/support-docs run generate:openapi
Use the drift check to prove the generator has no uncommitted output for the current specs:
scripts/check-docusaurus-openapi-docs.sh all
Docs builds are first-class Bazel targets:
bazel build //websites/docs:build //websites/support-docs:build
Use the direct Docusaurus build only when debugging site-specific output:
./node_modules/.bin/docusaurus build