Skip to content

Casey System Docs

Internal documentation for Casey Manos's personal infrastructure stack. Single source of truth for "what's where, why, and how to fix it when it breaks." The hand-rolled stuff — not vendor docs.

Why this repo exists

Knowledge about how the system works was scattered across:

  • ~/garmin-warehouse/docs/ — half a dozen specs at varying ages
  • ~/garmin-warehouse/ARCHITECTURE.md — the 8-layer warehouse model
  • ~/garmin-warehouse/findings/_active.md — workstream state mixed with training findings
  • ~/.claude/agents/{coach,librarian,conductor}.md — operational knowledge encoded as subagent context
  • ~/.claude/projects/-Users-caseymanos/memory/*.md — 14+ point-in-time memory entries
  • This repo — none of the above (until now)

Reading any single one gives you a partial view. This repo consolidates the system knowledge (training-content findings stay where they are in ~/garmin-warehouse/findings/).

Layout

Folder Contents
systems/ Per-system overviews — what each system does, where it lives, key files
runbooks/ "Something broke, here's the recipe" — failure modes + recovery
reference/ Tables you grep for — cron schedules, secrets, R2 layout, kb schema
decisions/ ADRs (architecture decision records) — the why behind load-bearing choices
agents/ What each Claude Code subagent owns + when to invoke it

Reading order for someone new

  1. overview.md — the whole stack on one page
  2. systems/garmin-warehouse.md — the training data pipeline (the largest system)
  3. systems/otq-checkin-worker.md — the Telegram bot + Cloudflare Worker
  4. reference/cron-schedules.md — when things fire
  5. decisions/ — read in numeric order; they're the "why" you'll wish you had

Conventions

  • One file per concept. If a doc grows past ~400 lines, split it.
  • Date stamps on assertions about state, not assertions about design. "As of 2026-05-04, kb has 5,555 claims" needs a date; "the kb is keyed by claim hash" doesn't.
  • No screenshots — they go stale. Describe the UI in text or link to live URLs.
  • Link to source files with ~/path/to/file.py:LINE format so it's obvious what to grep for.
  • ADRs are append-only. If a decision changes, write a new ADR that supersedes the old one. Don't edit history in place.

What this repo is NOT

  • Not the warehouse codebase (~/garmin-warehouse/)
  • Not the data-ingestion codebase (~/data-ingestion/)
  • Not training findings (~/garmin-warehouse/findings/)
  • Not Claude Code memory or agent definitions (those live in ~/.claude/); this repo describes them
  • Not vendor docs (Cloudflare, intervals.icu, GarminDB, Anthropic) — those WebFetch on demand

Local serve

For now, just open files in editor. If reading-experience matters later, add MkDocs Material — single mkdocs.yml, deploy via warehouse.caseymanos.com tunnel. Defer until reading the flat repo feels limiting.