Alyson Docs

0002 — Single Central Docs Repo

Status: accepted

Context

Alyson AI code is split across multiple repositories: alyson-frontend, alyson-backend, alyson-experiment-manager, alyson-ds-models, and others. We need to decide where documentation lives:

  1. One central docs repo
  2. Per-repo docs/ folders, aggregated centrally at build
  3. Per-repo docs/ folders, no aggregation (each repo has its own site)

A key constraint: AI coding agents (Claude Code, Cursor, etc.) need access to all docs even when working inside a single repo. Humans hop between repos and shouldn't have to remember which repo's docs they need.

Decision

All documentation lives in one central repo, alyson-docs. Code repos contain no documentation beyond a README.md (build/run instructions) and an AGENTS.md (pointing agents at the docs repo).

Agents reading a code repo are instructed to clone alyson-docs as a sibling directory and reference it when working on substantive changes.

Alternatives Considered

Per-repo docs, aggregated centrally (git submodules or build-time pull)

  • Pros: Docs live next to the code they describe.
  • Cons: Submodules are notoriously painful. Build-time pull is complex. Cross-cutting product docs have no natural home. AI agents working in one repo still don't see other repos' docs without extra setup.
  • Rejected: Complexity > benefit at our scale (~4-5 repos, ~1-2 doc maintainers).

Per-repo docs, no aggregation

  • Pros: Maximum locality.
  • Cons: No central knowledge hub. Product/concept docs (which span repos) have nowhere to live. Multiple doc sites to maintain. AI agents have fragmented context.
  • Rejected: Defeats the purpose of building this.

Consequences

Positive

  • One place to look. One site to deploy. One repo to grep.
  • AI agents get unified context with a single clone.
  • Cross-cutting product docs, ADRs, and runbooks have an obvious home.
  • Templates and conventions are enforced once.

Negative / trade-offs

  • Docs and code can drift; addressed by the staleness checker.
  • A doc update for a backend change happens in a different PR than the code change (unless the engineer opens both). Lighter-weight than CI-gating, accepted explicitly.

Neutral / things we'll need to track

  • If a section of docs ever becomes so tightly coupled to one repo that it's harder to maintain centrally, we'll consider moving it back. Not preempting that.

Implementation Notes

  • Each code repo gets:
    • AGENTS.md — pointer to docs repo + repo-specific notes
    • CLAUDE.md — thin shim that imports AGENTS.md
    • .cursor/rules/main.mdc — thin shim referencing AGENTS.md
  • Convention: developers clone alyson-docs as a sibling of code repos.
  • The staleness checker watches code-repo commits via the GitHub API.