okx-codex-trader/docs/documentation-guide.md

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.