README.md

@@ -1,13 +1,66 @@
-# hostexecutor
+# jepa-fx-risk
 
-> Generated from `mathias/template-go-web`.
+Research project exploring JEPA (Joint Embedding Predictive Architecture) as a framework for latent representation learning applied to FX trading risk management.
 
-## Bootstrap
+**Primary hypothesis:** JEPA embeddings trained on FX time-series will produce latent market-state representations that are structurally separable by regime without explicit regime labels, measurable by silhouette score on k-means clusters validated against held-out realised-volatility regime labels.
 
-After creating from template, run:
+**Current phase:** Phase 0 — SSL Feasibility Gate (not yet started)
+
+**Brain wing:** `jepa-fx` — query via `brain_query wing=jepa-fx`
+
+---
+
+## Architecture
+
+This is a **Go-first, Python-minimal** research project.
+
+| Layer | Language | Rationale |
+|---|---|---|
+| Data pipeline | Go | Type-safe, fast, no dependency hell |
+| Experiment runner | Go | CLI tooling, reproducible invocations |
+| Evaluation harness | Go | Silhouette, linear probe, collapse diagnostics |
+| Model training | Python + PyTorch | TS-JEPA requires it; kept minimal and isolated |
+
+## Structure
+
+```
+specs/          experiment specs (one per phase)
+src/            Go packages: pipeline, eval, cmd
+model/          Python: TS-JEPA training loop only
+experiments/    one directory per run (gitignored except summaries)
+results/        tracked: metric tables, key figures
+data/           gitignored; see data/README.md for download instructions
+notebooks/      EDA only; outputs stripped before commit
+docs/           ADRs and research notes
+```
+
+## Quick start
 
 ```bash
-go mod tidy       # regenerate go.sum with real module path
-task generate     # generate templ files
-task build        # build the binary
+task data:fetch          # download DUKASCopy G10 tick data
+task pipeline:build      # build Go data pipeline
+task check               # lint + vet + test
+task experiment:run -- --spec specs/phase-0-ssl-feasibility.md
 ```
+
+## Phases
+
+| Phase | Goal | Status |
+|---|---|---|
+| 0 | SSL feasibility gate — MAE baseline on FX data | 🔲 Not started |
+| 1 | JEPA representation PoC — silhouette > 0.35 | 🔲 Not started |
+| 2 | Regime detection validation — recall > 70%, lead > 5d | 🔲 Not started |
+| 3 | Distributional forecasting — VaR passes Kupiec | 🔲 Not started |
+| 4 | Multi-pair transfer — exotic pair improvement | 🔲 Not started |
+
+## Key constraints
+
+- **Training cutoff:** 2023-01-01 — all post-2023 data is sealed for final evaluation
+- **Training data:** 2008–2022, all G10 pairs, DUKASCopy
+- **Out of scope:** options pricing, directional alpha, live trading, exotic pairs (Phases 1–3)
+- **End-state:** publishable research result — not institutional deployment
+
+## Related
+
+- Brain wing: `wiki/jepa-fx/` — decisions, hypotheses, failure modes
+- Synthesis document: `JEPA_FX_Risk_Synthesis.docx` (session 2026-05-27)