A documentation site for BAM, updated with every change
Date: 2026-11-05 · Status: Accepted
Context
Section titled “Context”The 2026 refresh produced the knowledge an operator needs: the design of the new hosting, decisions, runbooks, the follow-ups found at each step. It sat in planning notes and in chat, where it evaporates. ba-api, ba-client and ba-infrastructure each have a docs/ tree that drifts when nobody owns the update.
Decision
Section titled “Decision”A new repository, bam-documentation: a Starlight site in the shape of tep-documentation, one build, hosted on Cloudflare Pages behind Cloudflare Access. It holds architecture, operations, decisions and development setup. Repository-level docs/ stay where they are and are linked, not moved.
Every step that changes behaviour or operation updates the documentation it makes stale, in the same pull request: the repository’s docs/, its README, and the page here. The walkthrough process asks the question at its commit step. Findings and defects go to Linear, never to the docs.
Consequences
Section titled “Consequences”One more file per change while the context is fresh, which is cheap. The first page written under the rule was the alerts runbook, with the monitoring layer. No customer-facing build until there is a customer to read it.