Docs
Every page of the repository that binds the people and agents who build Loadbudget, as it stands on main. Each page links to its file on GitHub.
The product
What Loadbudget is for, what it looks like, and the words it uses.
- GLOSSARY
docs/GLOSSARY.mdWhat does this training word mean?
- IDENTITY
docs/IDENTITY.mdWhat names does the product own, and what freezes them?
- BRAND
docs/product/BRAND.mdWhat does the product look like?
- JOURNEY
docs/product/JOURNEY.mdWhat training cycle does this product serve?
- LISTING
docs/product/LISTING.mdWhat words and metadata describe the app on the App Store?
- PRODUCT
docs/product/PRODUCT.mdWhat is this product for?
- VOICE
docs/product/VOICE.mdHow does the app talk to the athlete?
Rules for everybody
How this repository writes, plans, checks and lands a change.
- Instructions for an agent
AGENTS.mdHow this repository works binds everybody, and it lives in docs/. Each evergreen page under docs/ and tools/ registers as a skill under .agents/skills/.
- What Claude Code adds
CLAUDE.mdAGENTS.md holds the rules that bind every agent that works here, and the import below loads it. This file holds what only Claude Code can obey: a hook, a tool, and the line that ends a background session.
- DELIVERY_DOMAINS
docs/architecture/DELIVERY_DOMAINS.mdWhich parts deliver on their own, and how does each boundary stay compatible?
- ASSUMPTIONS
docs/development/ASSUMPTIONS.mdWhat earns a place on a page of assumptions, and what does an entry carry?
- CI JOBS
docs/development/CI_JOBS.mdWhich jobs does CI run on a pull request?
- BAZEL
docs/development/code/BAZEL.mdHow does a Bazel target stay small and cacheable?
- GUIDELINES
docs/development/code/GUIDELINES.mdWhich rules does the code follow here, in every language?
- NAMING
docs/development/code/NAMING.mdHow does a name in the code state what it names, in every language?
- PYTHON_TESTING
docs/development/code/PYTHON_TESTING.mdHow is a test of the Python of tools/ written, and how is it measured?
- PYTHON
docs/development/code/PYTHON.mdWhich rules does the Python of tools/ follow?
- SWIFT_LAYERS
docs/development/code/SWIFT_LAYERS.mdWhich role does a type of a Swift app take, and how does its name state it?
- SWIFT_TESTING
docs/development/code/SWIFT_TESTING.mdHow is a test of the Swift of this repository written, and how is it measured?
- SWIFT
docs/development/code/SWIFT.mdWhich rules does the Swift of this repository follow?
- TESTS
docs/development/code/TESTS.mdWhat makes a test worth keeping here, whichever language it is written in?
- COMMITS
docs/development/COMMITS.mdWhat makes a commit, and how is its message written?
- CONTINUOUS INTEGRATION
docs/development/CONTINUOUS_INTEGRATION.mdWhich rules tie two build tools together, and what must a change pass before it lands?
- FILING_AN_ISSUE
docs/development/FILING_AN_ISSUE.mdWhich parts, images and links to other issues does a filed issue carry?
- GITHUB ACTIONS
docs/development/GITHUB_ACTIONS.mdHow is a GitHub Actions workflow written here: its name, its runner, its caches, its secrets and its steps?
- BAZEL
docs/development/howto/BAZEL.mdHow do you repair a broken fetch, add a module, and measure a cache hit?
- GITHUB ACTIONS
docs/development/howto/GITHUB_ACTIONS.mdHow do you test a change to a workflow, free a run that waits on a removed runner, and read the log of a job that still runs?
- LABELLING_AN_ISSUE
docs/development/LABELLING_AN_ISSUE.mdWhich labels does an issue carry, and what does each one say?
- REVIEW
docs/development/REVIEW.mdWhich stage of review does a page bind?
- TAKING_AN_ISSUE
docs/development/TAKING_AN_ISSUE.mdHow do you assign a taken issue, read its images, close it or let it go?
- TECHNOLOGY
docs/development/TECHNOLOGY.mdWhat is the system built with?
- TESTING
docs/development/TESTING.mdHow does this repository place, run and measure its tests?
- TRIAGE
docs/development/TRIAGE.mdHow does an agent rank an open issue, and how does a person correct the rank?
- WORKFLOW
docs/development/WORKFLOW.mdHow does an author plan a change and carry it to a pull request?
- DOCUMENTATION
docs/DOCUMENTATION.mdWhich kinds of pages exist, what is each one for, and where does a fact live?
- GOVERNANCE
docs/GOVERNANCE.mdWhich person holds each role that the other pages name?
- LAYOUT
docs/LAYOUT.mdWhich folder holds which pages in this repository?
- UPGRADES
docs/operations/UPGRADES.mdHow does this repository keep up with the libraries, languages and platforms that it depends on?
- WRITING
docs/WRITING.mdHow does this repository write a sentence?
- loadbudget
README.mdAn iOS and watchOS app that models strength training and running as one budget of training load, spent toward a race date.
ios-app
The iOS and watchOS application codebase
- ARCHITECTURE
ios-app/docs/architecture/ARCHITECTURE.mdWhat are the pieces of the system, and how does each one depend on the others?
- DIAGRAMS
ios-app/docs/architecture/DIAGRAMS.mdWhat does lb docs graph draw, and why does no commit carry the result?
- LAYERS
ios-app/docs/architecture/LAYERS.mdWhich layer holds a rule, and which suite tests it?
- LOGGING_SWIFT
ios-app/docs/architecture/LOGGING_SWIFT.mdWhat does the log of this app hold for the person who reads it?
- PERSISTENCE
ios-app/docs/architecture/PERSISTENCE.mdWhere do the records live, and what carries them between two devices?
- ASSUMPTIONS
ios-app/docs/ASSUMPTIONS.mdWhich beliefs of the app remain unverified?
- ATHLETE_MODEL
ios-app/docs/development/ATHLETE_MODEL.mdWhat does the app know of her running, and what finish time does it state?
- DEPLOYMENT TARGET
ios-app/docs/development/DEPLOYMENT_TARGET.mdWhat SDK builds this, and what OS runs it?
- INTERFACE
ios-app/docs/development/INTERFACE.mdWhich pages of Apple's Human Interface Guidelines bind a screen, and what does this app decide inside them?
- LOAD
ios-app/docs/development/LOAD.mdHow does one session become a number?
- PLAN
ios-app/docs/development/PLAN.mdHow does the app plan the days ahead of the athlete?
- READINESS
ios-app/docs/development/READINESS.mdHow does her readiness cut the run of the day?
- REPLAY
ios-app/docs/development/REPLAY.mdHow does the coach replay against open data, and how do a KPI and a study read it?
- RUN_OF_THE_DAY
ios-app/docs/development/RUN_OF_THE_DAY.mdWhich run does the coach pick today, and how long is it?
- SIGNING
ios-app/docs/development/SIGNING.mdWho signs a build, and why not Release on a laptop?
- TYPOGRAPHY
ios-app/docs/development/TYPOGRAPHY.mdHow does this app control the typeface of its text?
- UI_TESTS
ios-app/docs/development/UI_TESTS.mdHow does a UI test of the app reach one state, check a screen, and wait for it?
- VERSIONING
ios-app/docs/development/VERSIONING.mdWhat carries a version, what does it mean, and what carries none?
- CD
ios-app/docs/operations/CD.mdHow does a commit on main become a release candidate on TestFlight, and what records it?
- RELEASE BRANCH
ios-app/docs/operations/RELEASE_BRANCH.mdHow does a release candidate become a release branch, and what can the branch take?
- RELEASE
ios-app/docs/operations/RELEASE.mdHow does a release branch become a version on the App Store?
- SUBMISSION
ios-app/docs/operations/SUBMISSION.mdWhat does a submission need that no build writes?
- TESTFLIGHT
ios-app/docs/operations/TESTFLIGHT.mdWhat carries a TestFlight build and the feedback that comes back?
- XCODE CLOUD
ios-app/docs/operations/XCODE_CLOUD.mdWhat does Apple run for this repository, and how do we read it back?
- README
ios-app/docs/README.mdWhat does the app give Xcode Cloud, just and the tools?
- DEVICES
ios-app/docs/usage/DEVICES.mdHow does the app reach a simulator, an iPhone and an Apple Watch?
web
The public and the team site of `loadbudget.com`
- WORKFLOW_GRAPH
Web/docs/development/WORKFLOW_GRAPH.mdWhat does the workflow graph read from GitHub Actions workflows, and what does it draw?
- WEB
Web/docs/README.mdWhat is on loadbudget.com and dev.loadbudget.com, and how does each one deploy?
lb
The repository command dispatcher
- AGENT_HOOKS
docs/development/tools/AGENT_HOOKS.mdWhich hook does each agent run, and why does a cell stay empty?
- ASSUMPTIONS
docs/development/tools/ASSUMPTIONS.mdWhich beliefs of the tools and the machines remain unverified?
- AUTO_MODE_RULES
docs/development/tools/AUTO_MODE_RULES.mdHow do the auto mode rules of this repository reach the classifier of Claude Code?
- COMPLEXITY_RATCHET
docs/development/tools/COMPLEXITY_RATCHET.mdHow does a change meet the complexity targets, and which file or page splits first?
- JUSTFILES
docs/development/tools/JUSTFILES.mdWhat is a recipe for, where does it live, and what must it not do?
- PR_GUARD
docs/development/tools/PR_GUARD.mdHow does this repository adopt the review product?
- PREK
docs/development/tools/PREK.mdWhat does each hook check, and how does it run?
app-store-connect-client
Generic App Store Connect API client
- README
tools/app-store-connect-client/docs/README.mdWhat does the client send to App Store Connect, and what does it read back from Xcode Cloud?
apple-app-delivery
Generic Apple app delivery tooling
- README
tools/apple-app-delivery/docs/README.mdWhat does the delivery of an Apple app take from its caller, and what does it write?
- TEST_RESULTS
tools/apple-app-delivery/docs/usage/TEST_RESULTS.mdHow does a person read the stability and the timing of the tests of an app?
ios-app-tools
Developer tools for the Loadbudget application
- ASSUMPTIONS
tools/ios-app-tools/docs/ASSUMPTIONS.mdWhich beliefs of the app tools remain unverified?
- README
tools/ios-app-tools/docs/README.mdWhich commands of lb act on the app, and what do they read from the checkout?
- REPORT_RUN
tools/ios-app-tools/docs/usage/REPORT_RUN.mdWhat does a report run of the app tests state about the reference exports?
cli-tool-runtime-for-git-repos
Shared CLI runtime interfaces
- README
tools/cli-tool-runtime-for-git-repos/docs/README.mdWhich infrastructure interfaces do installed tools share?
commit-review-against-rule-pages
Review engine for changes against rule pages
- PAGES
tools/commit-review-against-rule-pages/docs/architecture/PAGES.mdWhich rule pages does each specialist of a review read?
- PROVIDERS
tools/commit-review-against-rule-pages/docs/architecture/PROVIDERS.mdHow do provider adapters isolate and complete a review?
- ASSUMPTIONS
tools/commit-review-against-rule-pages/docs/ASSUMPTIONS.mdWhich review beliefs remain unverified?
- DEVELOPMENT
tools/commit-review-against-rule-pages/docs/DEVELOPMENT.mdHow does a review run inside: its locks, its stages, its server, its files and its clocks?
- GLOSSARY
tools/commit-review-against-rule-pages/docs/GLOSSARY.mdWhat does this word of the review mean?
- README
tools/commit-review-against-rule-pages/docs/README.mdWhat does the review product accept, expose, and refuse?
plain-english-docs-lint
Plain English documentation linter
- README
tools/plain-english-docs-lint/docs/README.mdWhich prose checks and formatting commands can other products use?
rule-pages-for-docs
Rule page validation and skill pointer generation
- README
tools/rule-pages-for-docs/docs/README.mdWhat is a rule page, which product owns one, and what does the lint refuse?
complexity-ratchet-for-git-repos
Code complexity ratchet
- README
tools/complexity-ratchet-for-git-repos/docs/README.mdWhat does the complexity ratchet measure, and what does it refuse?
pull-request-watch-for-agents
Pull request check watcher
- README
tools/pull-request-watch-for-agents/docs/README.mdWhat does the watch print about a pull request, and what ends the watch?
sandbox-fingerprint-for-bazel
Bazel sandbox cache fingerprint
- ASSUMPTIONS
tools/sandbox-fingerprint-for-bazel/docs/ASSUMPTIONS.mdWhich beliefs of the fingerprint remain unverified?
- README
tools/sandbox-fingerprint-for-bazel/docs/README.mdWhat does the fingerprint cover, and how does it reach the cache key of Bazel?
pytest-for-bazel
Pytest runner and coverage check
- README
tools/pytest-for-bazel/docs/README.mdWhat does the pytest runner take, and what does the coverage check refuse?
stage-refs-for-git-repos
Stage branches that mark the newest passing commit
- README
tools/stage-refs-for-git-repos/docs/README.mdWhat do the stage branches of a repository hold, and what does the product do with them?
agent-session-start-for-git-repos
Worktree sync and hook shims at agent session start
- README
tools/agent-session-start-for-git-repos/docs/README.mdWhat does an agent session start do to a repository, and what does it answer?
justfile-lint
Lint for recipe descriptions in justfiles
- README
tools/justfile-lint/docs/README.mdWhich recipe and module descriptions does the lint refuse, and how does it exit?
pull-request-description-from-commit
Pull request text copied from its sole commit
- README
tools/pull-request-description-from-commit/docs/README.mdWhat does the command write to a pull request, and what makes it refuse?
lb-infrastructure
Setup of each machine that builds this repo
- ASSUMPTIONS
infra/docs/ASSUMPTIONS.mdWhich beliefs about the build machines remain unverified?
- ANSIBLE
infra/docs/development/ANSIBLE.mdHow do the Linux machines keep roles apart from machines in one Ansible project?
- HOST
infra/docs/development/HOST.mdHow does the VM lb-agents run its accounts, its sessions of Remote Control and the tools that every account shares?
- LINUX_WORKER
infra/docs/development/LINUX_WORKER.mdHow does a Linux NativeLink worker get its image, and what can an action on it reach?
- MAC_WORKER
infra/docs/development/MAC_WORKER.mdHow does a Mac run the NativeLink worker, and how does it run each action?
- NATIVELINK
infra/docs/development/NATIVELINK.mdHow do Caddy and the NativeLink scheduler admit a call and send an action to a worker?
- RUNNERS
infra/docs/development/RUNNERS.mdHow does a runner of GitHub Actions on a host of GARM run a job, and what keeps one job apart from the next?
- TOOLCHAIN
infra/docs/development/TOOLCHAIN.mdWhere does each build machine read the release of each tool?
- GLOSSARY
infra/docs/GLOSSARY.mdWhat does this word of the infrastructure mean?
- ACCOUNTS
infra/docs/operations/ACCOUNTS.mdHow does the operator give a new account on a host its logins, so that its Remote Control bridge serves?
- ALERTS
infra/docs/operations/ALERTS.mdWhich alert reaches the operator, and what does the operator do about it?
- HETZNER02
infra/docs/operations/HETZNER02.mdHow does the operator install lb-hetzner02, and how does a merged change reach it?
- MAC_WORKER
infra/docs/operations/MAC_WORKER.mdHow does the operator join a Mac to the build as a worker?
- MINISFORUM
infra/docs/operations/MINISFORUM.mdHow does the operator install Ubuntu on lb-minisforum?
- SECRETS
infra/docs/operations/SECRETS.mdWhere does each secret come from, and how does the operator replace it?
- README
infra/docs/README.mdWhat does each machine that builds this repository give a person, an agent identity and a build client, and what must each one give?
- CLOUD_SESSION
infra/docs/usage/CLOUD_SESSION.mdWhat does a cloud session at claude.ai/code need, and what does it do another way?
- CROSS_HOST_HANDOFFS
infra/docs/usage/CROSS_HOST_HANDOFFS.mdHow does a session hand work to a session on another machine, and how does it read the answer?
- LAPTOP
infra/docs/usage/LAPTOP.mdWhat readies a laptop to run this repository?
- ROOT_SHELL
infra/docs/usage/ROOT_SHELL.mdHow does a session on a laptop run a command as root on a machine?
python-pin-for-uv-and-bazel
One Python version across uv and Bazel
- README
tools/python-pin-for-uv-and-bazel/docs/README.mdWhat do the pin commands read, print, edit and report, and what makes them refuse?
feedback-intake-for-github
Feedback webhooks and app reports that reach GitHub
- ASSUMPTIONS
tools/feedback-intake-for-github/docs/ASSUMPTIONS.mdWhich beliefs of the feedback Worker remain unverified?
- DEVELOPMENT
tools/feedback-intake-for-github/docs/DEVELOPMENT.mdHow does the Worker sign in, how is its code laid out, and how does a person measure and change it?
- DEPLOY
tools/feedback-intake-for-github/docs/operations/DEPLOY.mdHow does the operator deploy the Worker, and set up what it needs once?
- README
tools/feedback-intake-for-github/docs/README.mdWhat does the Worker accept, what does it start on GitHub, and what does it answer?
wait-for-requested-reviewers
Merge held until each requested reviewer approves
- README
tools/wait-for-requested-reviewers/docs/README.mdWhat does the check wait for, and what status does it write?
r2-credentials-for-systemd
Short-lived R2 credentials from a systemd socket
- ASSUMPTIONS
tools/r2-credentials-for-systemd/docs/ASSUMPTIONS.mdWhich beliefs of the signer remain unverified?
- DEVELOPMENT
tools/r2-credentials-for-systemd/docs/DEVELOPMENT.mdHow does the signer build a credential that R2 accepts?
- README
tools/r2-credentials-for-systemd/docs/README.mdWhat does the signer give each caller of its socket, and what does it refuse?
unused-inputs-for-bazel
Declared inputs that an action of Bazel never uses
- ASSUMPTIONS
tools/unused-inputs-for-bazel/docs/ASSUMPTIONS.mdWhich beliefs of the audit remain unverified?
- README
tools/unused-inputs-for-bazel/docs/README.mdWhat does the command build, what does it run again, and what does it report?
firecracker-runners-for-github
Runners of GitHub Actions in Firecracker VMs
- DEVELOPMENT
tools/firecracker-runners-for-github/docs/DEVELOPMENT.mdHow does Bazel build the command, and how does serve make each VM?
- README
tools/firecracker-runners-for-github/docs/README.mdWhat does the command give a host of GitHub Actions runners, and what does it refuse?