# Documentation Guide

This repo has many generated reports. Keep durable project knowledge in `docs/`; keep experiment outputs in `reports/`.

## Durable Docs

Use these files for human-maintained project state:

- `README.md`
  - Project entrypoint.
  - Links to the current docs.
  - High-level layout and safety notes.

- `AGENTS.md`
  - Agent-specific operating instructions.
  - Keep it short and stable.

- `docs/current-status.md`
  - Latest live strategy state.
  - Active services and observers.
  - Recent performance readout.
  - Open work and safety boundary.

- `docs/operations.md`
  - Server details.
  - systemd service names.
  - Monitoring and deployment commands.
  - Runtime paths.

- `docs/architecture.md`
  - Code boundaries.
  - Which logic belongs in package modules vs scripts.
  - Current modularization state.

- `docs/documentation-guide.md`
  - This file.

Older dated status docs can remain for audit history, but the new-session handoff should point to `docs/current-status.md`.

## Generated Reports

Reports are outputs, not source-of-truth prose. Keep them under `reports/` by topic:

- `reports/live-recent/`
  - Recent operational snapshots and live strategy comparisons.
  - Current observer summary: `readonly-observers-snapshot.md`.

- `reports/eth-exploration/`
  - ETH-focused backtests, strategy searches, signal intents, and execution research.

- `reports/ultrashort/`
  - Ultra-short and high-frequency strategy research.
  - Current high-frequency observation intent lives here because it is generated.

- `reports/long-short-fusion/`
  - Long/short fusion and calendar fusion research.

- `reports/short-bias/`
  - Short-biased strategy research.

- `reports/recent-regime/`
  - Recent-market and regime adaptation research.

- `reports/strategy-expansion/`
  - Broader non-ultrashort strategy research.

## Naming Rules

For durable docs:

- Use stable names: `current-status.md`, `operations.md`, `architecture.md`.
- Avoid date suffixes unless the file is intentionally historical.

For generated reports:

- Keep the script prefix in the filename when possible.
- Use `*-report.md` for human summaries.
- Use `*-summary.csv`, `*-horizon.csv`, `*-trades.csv`, or `*-equity.csv` for machine outputs.
- Use `*-intent.json` and `*-intent.md` for live/observer signal payload snapshots.

## Update Rules

When live services or observers change:

1. Update `docs/current-status.md`.
2. Update `docs/operations.md` if service names, paths, or commands changed.
3. Generate `reports/live-recent/readonly-observers-snapshot.md`.
4. Keep generated JSON/CSV/MD reports with the script that produced them.

When adding a new strategy search:

1. Put reusable code in `okx_codex_trader/` only if another script needs it now.
2. Put the search entrypoint in `scripts/`.
3. Write outputs under the relevant `reports/<topic>/` directory.
4. Add a short report `.md` that records command, data range, costs, and decision.
5. Update `docs/current-status.md` only if the result changes the operational direction.

When adding a new live or observer service:

1. Add the runner script under `scripts/`.
2. Add the systemd unit under `deploy/`.
3. Add heartbeat and event paths to `docs/operations.md`.
4. Add the service to `scripts/summarize_readonly_observers.py` if it is an observer.
5. Add a regression test for any classification or order-planning logic.

## What Not To Do

- Do not put long generated CSV tables in `docs/`.
- Do not duplicate current status across multiple dated docs.
- Do not make observers submit orders.
- Do not treat local reports as fresher than server-generated live snapshots without checking candle end times.