docs: separate paper from live, so a figure from one is never read as the other

[eaitbrahim]

Why

Conflating the paper and live accounts is the single most costly confusion in this project. It produced a wrong diagnosis: a paper-run position size was checked against live-account equity, and the conclusion was wrong as a result.

Nothing in the docs made the split explicit, and nothing on the dashboard says which account a number belongs to — paper and live render in an identical layout. This makes the mistake hard to repeat.

What

README.md — new ## Paper vs. live section (placed before ## Before trading live). It leads with the thing that causes errors — two separate accounts, separate databases, separate configs, separate schedules, separate histories, so a figure from one says nothing about the other — then a comparison table of the measured values, then:

• which one am I looking at — equity_state_mode on any dashboard, the --config/--db pair on the command line, and that --db defaults to keel.db, so a live command that omits it silently reads the paper database;
• order gating — paper places freely against synthetic cash; live runs mode: confirm, which asks for a typed y and fails closed headless unless autonomy is armed, cross-referencing Confirm vs. autonomy;
• cadence — "it fires hourly" and "it runs once a day" are both true. Both jobs have hourly triggers plus RunAtLoad; both runners are day-stamped; the trigger count is catch-up breadth, not cadence, because launchd does not re-run an interval that passed while the machine was off. A failed cycle leaves no stamp and is retried next hour. The two differ only in anchor: paper is local-date, live is UTC-date.
• sizing — paper sizes off its own synthetic equity (equity_override); live falls back to caps.max_exposure_usd as a proxy. Same rule, same setup, same day, different quantities.

keel/commands/tui.py — new Which account is this? help section (a few lines, before Live balance): which field disambiguates, and that switching accounts means relaunching with the other --config/--db pair, since there is no in-app switch.

tests/commands/test_tui.py — one test in the existing section-scoped style, pinning that the help names equity_state_mode, both flags, keel-live.db, and the keel.db default.

Notes

• Documentation only. No behaviour, default or config value change. pyproject.toml untouched, nothing under docs/experiments/ touched.
• Branched from origin/main alongside the open docs: explain the dashboard's field names and the four money settings #240. Both files that overlap are edited in separate, non-adjacent sections: this README section sits at the end of the file rather than next to docs: explain the dashboard's field names and the four money settings #240's ### How much money moves (which it cross-references instead of restating), and the TUI section sits before Live balance rather than at docs: explain the dashboard's field names and the four money settings #240's Glossary anchor. No new module-level test helper, so docs: explain the dashboard's field names and the four money settings #240's _help_section() cannot collide.
• One deviation from the brief worth flagging: the live plist explicitly warns against describing the live path as placing nothing unattended, because the deployment runs with autonomy ON. The confirm-mode text is therefore qualified with autonomy rather than stated flat.
• The two plists are not identical in cadence — paper has 12 local triggers (09:00–20:00), live has 24 anchored on UTC at :20. The design is the same; the section says so and names the difference.

Gates

$ uv run ruff check keel tests packages scripts
All checks passed!

$ uv run pytest -q
2665 passed, 1 skipped in 38.56s

$ uv run mypy
Success: no issues found in 221 source files

Baseline on origin/main is 2664 passed / 1 skipped; the +1 is the new test. The single skip is the expected one:

SKIPPED [1] packages/keel-broker-api/keel_broker_api/conformance/suite.py:254: adapter serves no granularity the suite could exercise

🤖 Generated with Claude Code