# WaytLog

A training log: a plan of routines laid over a calendar, and the sets actually performed
against it. This file is for an agent that has been given this site's address and a
passphrase, and is expected to work out the rest on its own.

## What you need

The address of this site, and the user's passphrase. The passphrase is not a login — it
is both the address of their space and the key that decrypts it. There is no account, no
token, and nothing to reset: whoever has the phrase has the log, and whoever does not has
ciphertext.

## How to drive it

Download one file from this site and ask it what it can do. Nothing is installed.

    curl -O https://THIS-SITE/agent.mjs
    node agent.mjs help

`help` prints every operation with its full JSON argument schema. That listing is
generated from the code that runs, so it is never out of date — prefer it to anything
written here. Node 18 or newer; no dependencies.

    node agent.mjs overview --url https://THIS-SITE --phrase "the passphrase"

Or put them in `WAYTLOG_URL` and `WAYTLOG_PHRASE` and drop the flags. Results are JSON on
stdout. A failure is a message on stderr and a non-zero exit.

## The operations

Reading: `overview`, `get_plan`, `get_sessions`, `get_exercise_history`, `get_volume`,
`search_exercises`. Writing: `log_sets`, `set_position_exercise`, `set_position_volume`,
`set_microcycle_day`, `set_day_routine`.

Start with `overview`. It says which plan is in force, where the mesocycle stands today,
what the routines and environments are called, and how much has been logged — enough to
know what any other question is about.

## What the model means

- A **routine** (A, B, C, D) is an ordered list of **positions**. A position is a target
  muscle, a rep range, and a set count per mesocycle — not an exercise. The exercise is
  what the position currently resolves to.
- A **microcycle** is the grid of weeks × weekdays that says which routine falls when. A
  **mesocycle** is one pass through that grid; set counts step up at each pass.
- An **environment** (gym, home) is a place with declared equipment. The same position
  resolves to a different exercise in each. An exercise set by hand for one environment
  is a **pin** and always wins.
- A **deload** week multiplies sets and load by the plan's own factors.
- The calendar **suggests**; it never shifts. A day done out of order is recorded with
  `set_day_routine`, which changes that date alone and leaves the plan where it was.

## Things that will otherwise go wrong

- **Never invent an exercise id.** Run `search_exercises` and use an id it returns. The
  database has 833 entries with Polish and English names; a plan position holds an id.
- **The log is keyed by the exercise's Polish name**, because that is what the user sees.
  `log_sets` accepts an id and converts it — pass the id and let it do that, or a second
  history will appear for the same exercise.
- **Volume is counted from the exercise actually performed**, not from the muscle the
  position aimed at. A substitution moves the load; `get_volume` already accounts for it.
- **Weights are kilograms.** Omit the weight for a bodyweight set rather than sending 0.
- **Writes merge, they do not overwrite.** The user's phone syncs into the same document
  while you work, and both survive. Do not attempt to read the whole document, change it,
  and put it back yourself.

## What is on the wire

    GET  /api/space?id=<sha256 of the passphrase>
    PUT  /api/space?id=<sha256 of the passphrase>

The body is `{v, kdf, it, salt, iv, ct}` — AES-GCM ciphertext under a PBKDF2-SHA-256 key
(250 000 iterations) derived from the passphrase, with a fresh salt and nonce per write.
The host stores this and can read none of it. `agent.mjs` handles the envelope; you only
need this if you are writing your own client.

## Interface language

Operation names, arguments and errors are English. Values are the user's own data and
stay Polish: exercise names, environment names, weekday labels. Weekdays are keyed by
number (0 Sunday … 6 Saturday) wherever a tool accepts one.