Add a reader-facing statement of what this repository can and cannot do

[stefan-jansen]

What this is

docs/what-this-is.md sorts the repository into four levels — reproduce with one command, modify with a config edit, needs real infrastructure, not promised — so a reader can decide what to attempt before installing anything. Linked from the README's Quick Start as the first of three onboarding docs.

Rebuilt, not merged

The original docs/reader-experiments branch was 20 commits behind main and its diff against main was 96 files / 14,768 deletions — almost all staleness. The real delta is two files. main's own README changes (61 skills, the Maven workshop link, cover.png) are untouched; the two sides edit different regions and merged cleanly.

Two claims softened from the draft

Both because the stronger form is not true:

• Was: "every case-study result printed in the book can be reproduced without training anything."
  Now: the results download, so you can reach them without training.
• Was: the analysis notebooks "read real registered results rather than recomputing them."
  Now: they read registered results instead of retraining, but several still recompute cost cascades, risk overlays and portfolio statistics from the downloaded artifacts — so a figure there can differ from the printed one with nothing retrained.

sp500_options/14_costs is a live example of exactly that. Overstating this is the failure mode a page like this has, so it is worth being narrow.

This follows three earlier overstatements a review already caught on this page (that every book result reproduces without training, that GPU families run on CPU, and that any listed preset gets trained).

Verification

Every path, flag and cross-reference checked against main, because each one is something a reader will type:

• docs/running-notebooks.md, docs/installation.md, envs/README.md, data/README.md all resolve; the #experimenting-without-changing-the-release-baseline anchor exists (running-notebooks.md:297).
• --free-only, --skip-firm-characteristics, --cs are all real flags.
• 01_process_is_edge/factor_regimes.py, scripts/download_artifacts.py, case_studies/etfs/13_model_analysis.py, 18_strategy_analysis.py exist.
• The three config paths match the actual layout (case_studies/{cs}/config/setup.yaml, config/training/{label}.yaml, case_studies/config/{model_type}/).
• The GPU claims match what CI measures: the four named crypto_perps_funding notebooks do hard-raise without CUDA, and the us_firm_characteristics deep notebooks are GPU-marked (Mark the us_firm GPU notebooks GPU-only and skip the cache-only IPCA replay #415).

Docs only — no CI job's result should move.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.