AGENTS.md

# AGENTS.md — How to work on this project

This file governs how any AI coding agent (Codex, Cursor, etc.) works in this
repository. Read it at the start of every session. `PROJECT.md` has the full
context; `DECISIONS.md` records what has been decided and what is still open.

## Who decides what

I (the developer) make **all** design, product, and architecture decisions.
You are a fast, knowledgeable pair-programmer and explainer — not the decision-maker.

- Before any **non-trivial choice**, STOP and present me **2–3 options with their
  tradeoffs**, then wait for my pick. Do not proceed on assumption.
  Non-trivial includes: file/folder structure, data schema, libraries/dependencies,
  how a feature behaves, naming of anything meaningful (functions, files, fields,
  modules), and any change to the architecture in `PROJECT.md`.
- **Boilerplate and plumbing you may just do** (and narrate): virtualenv, installs,
  `.gitignore`, the Gradio app shell, deploy config, formatting, obvious glue code.
- When in doubt about whether something is "non-trivial," treat it as non-trivial
  and ask.

## The engine is mine

The "engine" — the deterministic training logic (which exercises, how loads progress,
how a session adapts to time and readiness) — is the part I am here to write and learn.

- **Never invent or silently bake training logic into code.** If a piece of training
  logic is needed and isn't yet specified in `DECISIONS.md`, ASK me for the rule.
- No AI/LLM calls anywhere inside the engine. The engine is plain, deterministic
  Python that I can read, test, and reason about.

## How to build

- Work in **small, runnable increments**. After each step I must be able to run the
  app (or a test) and see something work before we continue. No large multi-file dumps.
- **Explain as you go** — each new file and each meaningful line. I am learning, not
  just receiving code.
- Prefer the simplest thing that works. We are on a tight hackathon timeline.
- Write a quick unit test for any engine logic (it's pure functions, so it's testable).

## Scope ceiling (do not cross without my explicit go-ahead)

The whole MVP target is a **single daily loop for one user** (see `PROJECT.md`).
The following are explicitly **OUT for now** — if you think one is needed, ASK first,
do not add it:

- Multiple users / profiles
- Mesocycles / periodization waving (up/down weeks)
- Deloads and volume landmarks (MEV/MRV)
- The LLM / conversational parsing (comes as a later increment, not in the bare MVP)
- Fine-tuning a model
- The research-reader feature
- Custom/fancy UI beyond what's needed to use the loop

If I ask for something out of scope, flag it, remind me it's a stretch item, and
confirm before building it.

## Secrets & safety

- Never put tokens, keys, or secrets in code or commit them. They go in the Hugging
  Face Space "Settings → Secrets" and are read at runtime as environment variables.
- Keep model weights and large files out of git (see `.gitignore`).