docs/README.md

# Hermes Futures Desk Developer Documentation

This directory is the canonical developer documentation for the repository snapshot.

## Reading order

1. [Complete Developer Guide](DEVELOPER_GUIDE.md) — single-document overview.
2. [Architecture](ARCHITECTURE.md) — runtime, module boundaries, and control flow.
3. [API Reference](API_REFERENCE.md) — authenticated routes and payload contracts.
4. [Datasource Pipeline and Contracts](DATA_PIPELINE_AND_CONTRACTS.md) — DS4, Binance, DS2, normalization, provenance, and readiness.
5. [Frontend Guide](FRONTEND_GUIDE.md) — UI state, charting, local workspace features, and execution controls.
6. [Environment Configuration](ENVIRONMENT_CONFIGURATION.md) — supported variables and secret handling.
7. [Deployment Runbook](DEPLOYMENT_RUNBOOK.md) — build, overlay installation, Space deployment, verification, and rollback.
8. [Security and Safety](SECURITY_AND_SAFETY.md) — non-negotiable safety model and threat boundaries.
9. [Operations and Troubleshooting](OPERATIONS_AND_TROUBLESHOOTING.md) — common failures and diagnostic workflow.
10. [Testing and Verification](TESTING_AND_VERIFICATION.md) — focused tests, runtime audit, browser verification, and acceptance checklist.
11. [Contributing](CONTRIBUTING.md) — change discipline and review checklist.
12. [Project Status](PROJECT_STATUS.md) — implemented work and remaining production verification.

## Documentation principles

- Source code is authoritative when documentation and implementation disagree.
- API examples are representative; clients must tolerate additive fields.
- Browser-derived values are informational and never authorize execution.
- Runtime verification requires evidence from hashes, authenticated API responses, and browser Console/Network inspection.
- “Application online” is not equivalent to “market data healthy” or “trading ready.”