Docs drift playbook¶

This playbook enumerates every documentation file in the bernstein repository, points each one at a concrete source of truth in code (or marks it static), and records the drift signal that should trigger a refresh.

Why this exists¶

Code and docs drift apart over time. This playbook gives future agents mechanically discoverable check-points so the gap can be detected and closed without re-reading every file. The companion CI workflow at .github/workflows/docs-drift.yml consumes this file via scripts/check_docs_drift.py and reports drift on every push to main and on every pull request.

How agents pick up drift¶

Convention: when you change code under src/bernstein/<package>/, also update the doc rows in the table below that name that package as their source of truth. The CI workflow will block merges to main on uncorrected drift; on pull requests it posts a non-blocking comment so the change can land in the same PR.

Drift remediation paths used by the rows below:

Doc inventory¶

Root (./)¶

docs/ top-level¶

docs/concepts/¶

Each file in this folder pairs a Bernstein architectural concept with a concrete module path. The drift signal in every row is "the named source module has been moved, renamed, deleted, or its public surface changed."

docs/gui/¶

Source of truth for this group is src/bernstein/gui/ (FastAPI + SPA), web/ (Vite + React + Tailwind), and the GUI mount logic.

docs/sdd/¶

Benchmarks¶

Data-freshness drift (time-stamped metrics)¶

Some docs include time-stamped factual metrics (stars, downloads, dates) that grow stale even when the code does not change. These lines look like as of YYYY-MM-DD: ... or (YYYY-MM-DD) in a table heading. The drift gate here is purely temporal: the underlying numbers were correct on the recorded date and are expected to drift between scheduled refreshes.

To enumerate the known time-stamped lines, run:

rg -n 'as of 20\d\d-\d\d-\d\d|\(20\d\d-\d\d-\d\d\)' README.md docs/

The current inventory is:

Refresh commands¶

For the README intro stats line:

gh api repos/sipyourdrink-ltd/bernstein --jq '{stargazers_count, forks_count}'
curl -sS https://pypistats.org/api/packages/bernstein/recent | jq .data

Staleness policy¶

• An as of YYYY-MM-DD marker older than 30 days is considered stale and emits a soft warning from scripts/check_data_freshness.py.
• A marker older than 60 days is a hard fail only on the weekly scheduled run of the docs-data-freshness job. Instead of failing pushes to main, the scheduled run opens or updates a single marker-tagged tracking issue so a stale marker never reddens unrelated main pushes.
• Pushes to main still run the checker in soft (non-strict) mode for the inline warning, but never fail on staleness.
• The docs-data-freshness check is advisory and is not part of the canary list of required checks.

Cross-repo¶

The public website mirrors some docs pages.

Adding a new doc¶

When you add a new file under docs/ (or a new root-level doc):

1. Add a row to the appropriate table above.
2. Set the source-of-truth column to a concrete module path under src/, or to static if there is no code source.
3. Update scripts/check_docs_drift.py only if the new doc needs a custom check beyond "the named source-of-truth file still exists." The default path-existence check covers the common case.
4. If the new doc is operator-facing, link it from docs/index.md.

Adding a new code module¶

When you add a new top-level package under src/bernstein/ or a new module that becomes a source of truth for a doc:

1. Run uv run bernstein agents-md sync so the canonical AGENTS.md / CLAUDE.md / CONVENTIONS.md / .goosehints / .cursor/rules/*.mdc pick up the new module entry.
2. Run uv run bernstein agents-md verify to confirm all five outputs agree.
3. If the new module has a concept-doc-worthy public surface, add a file under docs/concepts/ and a corresponding row in this playbook.