docs: make QRAE interview-ready

README.md

@@ -1,29 +1,56 @@
 # QRAE QuantOS
 
-## One sentence
-QRAE QuantOS is a local-first, human-gated kernel for reproducible quantitative-research experiments with no live-trading path.
+QRAE QuantOS is a local-first kernel for reproducible quantitative-research experiments with explicit provenance and human authority gates.
 
-## Result
-No headline result. No in-sample, out-of-sample, profitability, or alpha metric is reported: the included `examples/price_baseline` fixture is synthetic and its work order caps evidence at E0. Configuration values are source-backed by `examples/price_baseline/work_order.json`: 60% training, 20% validation, at least 5 test observations, and 5 basis points registered cost. Sample status: synthetic fixture only; no historical or private dataset is included.
+## Status & honesty
 
-## How it works
-- Hash-bound work orders identify relative datasets, point-in-time cutoffs, and evidence ceilings.
-- Validated historical manifests and catalog snapshots freeze provenance without publishing source data.
-- A lagged baseline runs chronological splits with registered costs and independently recomputed metrics.
-- Immutable manifests and state logs make run and review artifacts tamper-evident.
-- Optional local Codex review uses HMAC-authenticated receipts and cannot alter metrics, research state, capital, or execution authority.
+Active research harness. **No headline performance result; the deliverable is the harness.** The public fixture is synthetic, its work order caps evidence at `E0`, and no in-sample, out-of-sample, profitability, or alpha result is claimed. The quality branch records 228 passed tests and 4 platform-dependent skips; those checks establish software behavior, not investment performance.
+
+## Architecture
+
+- A hash-bound work order identifies the dataset, point-in-time cutoff, registered costs, split policy, and evidence ceiling.
+- `DataCatalog` freezes normalized inputs and manifest evidence as immutable SHA-256-addressed objects; every lookup requires an `as_of` time.
+- The local kernel runs a chronological lagged baseline, independently recomputes metrics, and appends hash-linked state and claim artifacts.
+- The optional Codex broker accepts a bounded read-only task, then HMAC-signs a result receipt outside the workspace; ingestion cannot change metrics, research state, capital, or execution authority.
+
+```mermaid
+flowchart LR
+    A[Work order<br/>dataset hash + as-of] --> B[Point-in-time catalog<br/>immutable objects]
+    B --> C[Deterministic kernel<br/>chronological split + costs]
+    C --> D[Run manifest<br/>metrics + hash-linked state]
+    D --> E[Offline verification]
+    D -. bounded draft request .-> F[Read-only Codex broker]
+    F --> G[HMAC receipt<br/>no state-transition authority]
+    G --> E
+```
 
 ## The interesting decision
-QRAE treats provenance, temporal availability, deterministic replay, and human authority as gating conditions rather than annotations. The tradeoff is additional contracts and immutable artifacts, while observed-at-import and public-metadata paths remain E0 and cannot establish origin, licensing, historical availability, model correctness, or research truth.
+
+Provenance and temporal availability are executable gates rather than report annotations: a run is refused when its hashes, point-in-time contract, evidence ceiling, or authority boundary do not validate. This makes replay and review mechanically checkable; the tradeoff is additional manifests, immutable artifacts, and deliberate refusal to promote observed-at-import or public-metadata inputs beyond `E0`.
+
+## Provenance
+
+The implementation in `src/qrae/` and the synthetic fixture are maintained in this repository. The requirements use **RD-Agent-style** research/development feedback and score terminology, but the tree contains no vendored `microsoft/RD-Agent` source and does not depend on that package. The bounded metadata adapter targets Polymarket's public Gamma API and explicitly records its terms as unverified. No repository license was present at audit time, so reuse rights remain UNKNOWN and no license was inferred.
 
 ## Run it
-```text
+
+From a clean clone with Python 3.10 or newer:
+
+```bash
+python -m venv .venv
+# PowerShell: .\.venv\Scripts\Activate.ps1
+# POSIX: source .venv/bin/activate
 python -m pip install -e ".[dev]"
 python -m pytest -q
+python -m ruff check .
+python -m ruff format --check .
+python -m pyright
 python -m qrae.cli run --work-order examples/price_baseline/work_order.json --workspace . --output-root .quantos
 python -m qrae.cli verify --run-dir .quantos/runs/<run-id>
 ```
-The commands produce only local artifacts. Reproduction of any external-data result requires independently authorized source access, retained inputs, and a documented provenance chain.
 
-## Status
-Active. Source release version `0.14.0` is declared in `pyproject.toml`. This checkout contains a synthetic example and source code, not a public performance record or a licensed dataset. Provider-specific automated historical adapters, walk-forward model selection, portfolio/risk engines, and paper/live execution remain incomplete.
+The last two commands exercise only the committed synthetic fixture and write ignored artifacts under `.quantos/`.
+
+## Limitations
+
+The repository contains no licensed historical dataset or validated alpha record. Manifest validation can prove internal consistency but not legal entitlement or external authenticity. Provider-specific automated historical adapters, walk-forward model selection, portfolio and risk engines, paper execution, and live execution remain incomplete; no LLM output can authorize any of them.