alphaengine 1.0.3__tar.gz → 1.1.1__tar.gz

{alphaengine-1.0.3 → alphaengine-1.1.1}/.github/workflows/publish.yml

@@ -35,7 +35,7 @@ jobs:
           python-version: "3.12"
       - name: Verify git tag matches __version__
         run: |
-          python -c "import os, runpy, sys; v = runpy.run_path('src/alphaengine/_version.py')['__version__']; ref = os.environ.get('GITHUB_REF_NAME') or os.environ.get('GITHUB_REF', '').removeprefix('refs/tags/'); exp = f'v{v}'; sys.exit(f'Tag {ref!r} != {exp!r}' if ref != exp else 0)"
+          python -c "import os, tomllib, sys; v = tomllib.load(open('pyproject.toml', 'rb'))['project']['version']; ref = os.environ.get('GITHUB_REF_NAME') or os.environ.get('GITHUB_REF', '').removeprefix('refs/tags/'); exp = f'v{v}'; sys.exit(f'Tag {ref!r} != {exp!r}' if ref != exp else 0)"
       - run: python -m pip install --upgrade build
       - run: python -m build
       - uses: actions/upload-artifact@v4

alphaengine-1.1.1/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to `alphaengine` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to Semantic Versioning (with computed golden values
+treated as part of the public contract).
+
+## [1.1.1] - 2026-10-24
+
+### Added
+- **Single firm-key choke point (`alphaengine.auth.require_firm_key`):** Used by every gated command (`run`, `show`, `monitor`/`watch`, `validate`, `screen`, `diagnose`, `signal`, `stress`, `overlap`, `size`, `workflows`, `runs`, `gaps`, `tonight`, and the CLI OS: `init`, `log`, `diff`, `rerun`, `data`, `idea`, `seal`, `report`, `remote`, `push`, `pull`, `plugin`, `shell`). Free and keyless forever: `import alphaengine`, `alphaengine demo`, `alphaengine process`, and `ae verify`.
+- **OS keychain support & key redaction:** `auth.py` stores keys in the OS keychain (`keyring`) when available with `~/.config/alphaengine/credentials.json` (`0600`) as fallback, and `redact_secrets()` strips `ae_live_*` tokens from CLI output, error messages, tracebacks, and `--json` envelopes.
+- **Canonical SHA-256 contract & golden fixture (`alphaengine/contracts/hash_golden.json`):** Unified `content_sha256`, study seals, `.alphaengine/objects/` CAS blobs, dataset hashes, and parameter hashes on `canonical_sha256()` (Schema 1.2 sorted-key JSON, `.8f` float formatting, 64-hex SHA-256). Added `verify_study_mode()` so studies sealed under the pre-1.2 legacy format still verify and are labeled `"legacy"`.
+- **Free vs. Firm documentation (`docs/free-vs-firm.md`):** Documents the offline open-source library boundary, firm `ae_live_` Connect keys, and what uses the network.
+- **Socket-blocked offline smoke test:** Replaced the import-only check in `tests/test_smoke.py` with a socket-blocked test (`socket.socket` and `socket.create_connection` patched to raise) that imports `alphaengine` and executes `deflated_sharpe` (DSR), `pbo_cscv` (PBO via CSCV), `combinatorial_oos_stability`, `performance_report`, `compute_var_cvar`, `sweep`, `load_csv`, `from_quantconnect`, and `from_vectorbt`.
+
+### Changed
+- **Cumulative project-wide trials & DSR everywhere:** Project-wide cumulative trial counts (`project_trials` across `.alphaengine/ledger/trials.jsonl`) now feed every DSR — run output, headline `deflated_sharpe` and `n_trials`, `ae push` payloads, and `ae seal` studies — with no per-run or per-family reset.
+- **Identical re-run deduplication:** Re-running an identical configuration (`command`, `params_hash`, and `dataset_hashes` matching a prior run in `.alphaengine/ledger/runs.jsonl`) records `duplicate_of` and adds `0` new trials (`9 -> 9`), whereas distinct configurations always increment cumulative `N` (`9 -> 18`).
+- **Removed bare `except Exception: pass` in `sweep/runner.py`:** `_maybe_record_project_sweep` now raises a descriptive `RuntimeError` when a discovered `.alphaengine/` project ledger cannot be written.
+- **Metadata-driven `__version__` and naming cleanup:** `__version__` is loaded via `importlib.metadata.version("alphaengine")` with no hardcoded version strings; standardized `combinatorial_oos_stability` (with `cpcv_score` emitting `DeprecationWarning`) and `PBO via CSCV` across docs and top-level exports.
+
+### Removed
+- **Retail CLI path (`--retail` and `/api/retail/ledger/import`):** Removed `--retail` from `report` and CLI dispatch. Retail ledger import is performed via web upload in the quantOS portal.
+
+## [1.1.0] - 2026-10-24
+
+### Added
+- **Project workspace (`ae init` and `ae` alias):** Initializes `.alphaengine/` (`project.toml`, `ledger/`, `data/`, `studies/`, `ideas/`, `universes/`, and SHA-256 content-addressed `objects/`). Commands walk up from the current directory to locate the project; documented in `docs/project-format.md`.
+- **Project-wide ledger (`ae log`, `ae show`, `ae diff`, `ae rerun`):** Every run and `sweep()` inside a project writes an append-only run record and accumulates trial counts across runs on the same `idea_id` or `family`.
+- **Dataset registry (`ae data add`, `ae data list`, `ae data show`, `ae data lineage`):** Registers CSV and Parquet datasets locally with full 64-hex SHA-256 hashes, row counts, date ranges, column schemas, and checks for duplicate timestamps, gaps, look-ahead rows (`--asof-col`), and survivorship hints.
+- **Standard result envelope (`v1.0`), pipes, and declarative YAML pipelines:** Added `--json` and `--stdin` support across commands (`ae screen --json | ae validate --stdin | ae size --stdin`), `ae run <pipeline.yaml>`, two example pipelines in `examples/`, and `docs/result-format.md`.
+- **Hypotheses as objects (`ae idea new`, `ae idea list`, `ae idea status`, `ae idea show`):** First-class hypothesis tracking with `--kill-if` rule evaluation, `--idea <id>` run linking, and pre-run prior-work checks.
+- **Extended seal, verify, and committee memos:** `ae seal <run|idea>`, `ae verify <study.json> [--data <file>]`, and `ae report memo <idea|run> --format md|pdf` where every figure cites its `[run_id]`.
+- **Research shell (`ae shell`):** Interactive shell with tab completion over verbs, run IDs, dataset names, and idea IDs, a project status line with cumulative trial count, inline ledger/idea commands, and automatic ledger recording of agent proposals.
+- **Entry-point plugin system (`alphaengine.plugins`, `ae plugin list`):** Supports `loader`, `method`, and `template` plugins, with `quantconnect`, `vectorbt`, `csv`, `deflated_sharpe`, `combinatorial_oos_stability`, and `committee_memo` registered as built-ins (`docs/plugins.md`).
+- **Local file watcher & live drift monitor:** `ae watch <pipeline.yaml>` re-runs pipelines when watched datasets change on disk; `ae monitor <run> --live <file>` compares live returns against the backtest's bootstrapped 95% intervals.
+- **Opt-in workspace sync (`ae remote`, `ae push [--dry-run]`, `ae pull`):** Syncs sealed studies, allowlisted ledger runs, and ideas to `POST /api/workspace/sync` (with 404 fallback to `POST /api/me/runs/ingest`), enforcing the 512-element series cap and never uploading dataset rows.
+
+## [1.0.3] - 2026-10-24
+
+### Added
+- **Sealed studies (Schema 1.2):** Canonical-JSON SHA-256 content hash (`content_sha256` with sorted keys and fixed 8-decimal float formatting), full 64-hex `data_hash`, and optional per-trial ledger export (`SweepResult.ledger()`, `include_ledger=True`).
+- **CLI study verbs:** `alphaengine seal <study.json>` (writes `content_sha256` and verifies on re-run) and `alphaengine report <study.json> [--retail]` (reports to `/api/me/runs/ingest` by default or `/api/retail/ledger/import` with `--retail`).
+- **Complete study ingest payload:** `study/report.py` `_payload()` now includes `selection` (PBO), `psr_vs_zero`, `sr0_expected_max`, `min_track_record_length`, `grid_keys`, `n_failed_trials`, `content_sha256`, and optional `assignment_id` and `thesis_id`.
+- **Interop loaders (`alphaengine.io`):** `from_quantconnect(path)` and `from_vectorbt(portfolio_or_csv)` construct a `Study` with returns, performance metrics, data hash, and trial-count provenance (`"asserted"` when provided/present, `"not_recorded"` with verdict refusal when absent).
+- **Credentials purge:** `alphaengine logout --purge` removes `~/.config/alphaengine/credentials.json`, cleans up its config directory, and clears managed keys from the current process.
+- **API URL override:** `ALPHAENGINE_API_URL` environment variable and unified `DEFAULT_API_URL` constant across CLI and study reporting.
+- **Security & governance:** Weekly Dependabot configuration (pip + GitHub Actions), Python CodeQL workflow, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and GitHub issue templates.
+
+### Changed
+- **Opt-in series sharing on `/traces`:** `_report_trace` sends scalar figures only by default. Uploading full series to `/api/harness/runs/{id}/traces` requires `--share-series` or `ALPHAENGINE_SHARE_SERIES=1`; any payload sent without opt-in is guarded at most 512 elements.
+- **Deliberate math & golden updates:**
+  - `deflated_sharpe(..., n_trials=1)` no longer silently deflates as `N=2`. At `n_trials=1`, `sr0_expected_max` is `0.0` (was `0.037` on the `rets(9, 200)` golden) and `deflated_sharpe` equals `psr_vs_zero` (`0.8434`, was `0.6875` on the golden), with an explicit note that no multiple-testing deflation applies.
+  - `SweepResult.verdict()` passes the cross-trial Sharpe dispersion across valid grid trials into `deflated_sharpe` per Bailey & López de Prado (2014), falling back to single-series sampling error only when fewer than 2 valid trials exist.
+  - Renamed `cpcv_score` to `combinatorial_oos_stability` (keeping `cpcv_score` as a deprecated alias) to accurately describe single-stream purged/embargoed sub-sample stability.
+  - `pbo_cscv` validates `n_splits` (even integer $\ge 2$) and raises a clear `ValueError`.
+- **Neutral framing:** Added *"Research tool, not investment advice"* disclaimer to README, `--help`, and the boot screen; renamed user-facing bakeoff `survivor` / `survivor_weights` to `top_ranked_config` / `model_weights` while preserving backward-compatible dictionary keys.
+- **Release guard:** `.github/workflows/publish.yml` verifies that the git tag matches `v{__version__}` before building.
+
+## [1.0.2] - 2026-10-20
+
+### Added
+- **Four-pass adversarial GAN bakeoff:** `run_bakeoff` and `core.bakeoff.referee` run four passes (eight candidate proposals across `equal`, `hrp`, `risk_parity`, `inverse_vol`, `var_sorted`, `low_vol`, `momentum`, and `reversion` against eight regime, tail, rate, and crash-cluster attacks) under a hard 12-call, 60-second ceiling.
+- **Multi-pass bakeoff scorecard in PDF reports:** Cumulative wealth across passes, in-sample vs. post-attack Sharpe comparison, and candidate scorecard table.
+
+## [1.0.1] - 2026-10-19
+
+### Added
+- **Harness simulation tools:** Added `monte_carlo` and `scenarios` to the local session tool stack.
+- **Multi-page PDF & text reports:** Accepted session traces render multi-panel portfolio, scenario stress, Monte Carlo fan, and bakeoff reports to the user's `Downloads` folder.
+
+### Fixed
+- **Ledoit-Wolf sample-count divisor:** Fixed sample covariance scaling in `ledoit_wolf_cov` so `hrp_weights` and `risk_parity_weights` differentiate weights across wide panels.
+
+## [1.0.0] - 2026-10-18
+
+### Added
+- **Interactive terminal simulator (`alphaengine`):** Full-screen Textual session where plain-English questions execute as a deterministic stack of local tool calls (`profile`, `align`, `regime`, `price`, `reprice`, `correlation`, `covariance`, `cointegration`, `portfolio`, `overlap`, `performance`, `var`, `process`, `workflow`, `bakeoff`) with citation guarding.
+- **Pinned cash rate & statistical refinements:** Default risk-free rate pinned to the H.15 3-month Treasury constant maturity (`4.21%` as of `2026-10-06`, `DGS3MO`; pass `0` for excess of zero), automatic Newey-West HAC lag selection in factor regressions, and Benjamini-Hochberg FDR survivors in cointegration screening.

{alphaengine-1.0.3 → alphaengine-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: alphaengine
-Version: 1.0.3
+Version: 1.1.1
 Summary: Validated research tooling for investment strategies: deflation, overfitting detection, and honest trial counts.
 Project-URL: Homepage, https://qosai.app
 Project-URL: Documentation, https://github.com/quantOSC/alphaengine#readme
@@ -170,16 +170,15 @@ Each is useful without the one above it. `login` lights the next one.
 
 | Rung | What you need | What you get |
 |---|---|---|
-| **The maths** | nothing | `alphaengine demo`, `alphaengine process`, and the full Python API (`import alphaengine`, `sweep`, `core`), offline, forever. No account. |
-| **Workflows** | a portal-issued `ae_live_` key (`login` or `QUANTOS_API_KEY`; request access at [https://qosai.app/access](https://qosai.app/access)) | The eight workflow commands (`diagnose`, `screen`, `signal`, `validate`, `stress`, `overlap`, `size`, `monitor`) plus `workflows`, `runs`, `gaps`, `tonight`, and `run <workflow>`. |
+| **The maths** | nothing | `alphaengine demo`, `alphaengine process`, `ae verify`, and the full Python API (`import alphaengine`, `sweep`, `core`), offline, forever. No account. |
+| **Firm workflows & CLI OS** | a firm `ae_live_` key from **Connect** in your firm's quantOS portal (`login` or `QUANTOS_API_KEY`; see [docs/free-vs-firm.md](docs/free-vs-firm.md)) | The eight workflow commands (`diagnose`, `screen`, `signal`, `validate`, `stress`, `overlap`, `size`, `monitor`), `workflows`, `runs`, `gaps`, `tonight`, `run <workflow>`, and the Research OS (`init`, `log`, `show`, `diff`, `rerun`, `watch`, `data`, `idea`, `seal`, `report`, `remote`, `push`, `pull`, `plugin`, `shell`). |
 | **Ask anything** | your OWN model key (`login anthropic`) | Plain English in. Runs under your account, not ours. |
 
-The eight workflow commands (`diagnose`, `screen`, `signal`, `validate`,
-`stress`, `overlap`, `size`, `monitor`) and `workflows` / `runs` require a
-portal-issued `ae_live_` key because the workflow graph and account record live
-on the server (request access at [https://qosai.app/access](https://qosai.app/access)).
-`alphaengine demo`, `alphaengine process`, and the Python library (`import alphaengine`)
-work completely offline without an account or key.
+The workflow commands and Research OS require a firm `ae_live_` key issued through
+**Connect** in your firm's quantOS portal (see [docs/free-vs-firm.md](docs/free-vs-firm.md)).
+There is no retail CLI key. `alphaengine demo`, `alphaengine process`, `ae verify`,
+and the Python library (`import alphaengine`) work completely offline without an
+account or key.
 
 **How credentials are handled.** QuantOS never receives your LLM provider key:
 it goes directly from this process to your chosen provider. By default, keys can
@@ -197,7 +196,7 @@ at `login`). To delete the stored file at any time, run
 flowchart LR
   A["demo / import<br/>offline maths"] --> B["login<br/>QuantOS key"]
   B --> C["login anthropic<br/>your model"]
-  A -.->|"no account"| D["DSR · PBO · ICIR · HRP"]
+  A -.->|"no account"| D["DSR · PBO (CSCV) · ICIR · HRP"]
   B -.->|"ae_live_"| E["screen · validate · runs"]
   C -.->|"BYOK"| F["plain English in"]
 ```
@@ -249,10 +248,89 @@ distinction is the whole of the data boundary below.
 
 ---
 
+## Quickstart: Offline First, Then Connect for Firms
+
+### 1. Free and offline (no account, no API key)
+
+The Python library (`import alphaengine`), every validation and portfolio math primitive, `alphaengine demo`, `alphaengine process`, and `ae verify` run 100% offline with no key (see [Free vs. Firm](docs/free-vs-firm.md)):
+
+```bash
+pip install alphaengine
+
+# Run the built-in 9-trial parameter sweep and inspect the surface & DSR verdict
+alphaengine demo
+
+# Fit OU, GBM, jump-diffusion, and GARCH(1,1) processes and run DGP stress offline
+alphaengine process
+
+# Verify any sealed Study artifact (Schema 1.2 or legacy) without an account
+ae verify study.json
+```
+
+### 2. Connect for firms (`ae_live_` key from the quantOS portal)
+
+CLI workflows and the local-first Research OS (`ae init`, project ledgers, dataset registry, hypothesis tracking, sealing, memos, and workspace sync) require a firm `ae_live_` key issued through **Connect** in your firm's [quantOS portal](https://qosai.app). There is no retail CLI key or `--retail` flag.
+
+Both `alphaengine` and the short alias `ae` run the same entry point (see [Free vs. Firm](docs/free-vs-firm.md), [project format](docs/project-format.md), [result envelope](docs/result-format.md), and [plugins](docs/plugins.md)):
+
+```bash
+# Sign in with your firm's Connect key (stored in OS keychain or 0600 fallback)
+ae login
+
+# 1. Initialize a local .alphaengine/ workspace
+ae init --name equity-momentum
+
+# 2. Register a local CSV (or Parquet) dataset and run hygiene checks
+ae data add prices.csv --name equities --asof-col date
+ae data show equities
+
+# 3. Record a falsifiable hypothesis with an explicit kill rule
+ae idea new "Cross-sectional 20d momentum holds net of costs" --kill-if "DSR < 0.9" --family mom_20d
+
+# 4. Run a validation, declarative YAML pipeline, or Unix JSON pipe
+ae validate --project alphaengine.demo --idea idea_1
+ae run examples/screen_validate_size.yaml
+ae screen --data equities --json | ae validate --stdin --json | ae size --stdin
+
+# 5. Inspect the append-only project ledger, cumulative trials, and diffs
+ae log --family mom_20d
+ae show HEAD
+ae rerun HEAD
+
+# 6. Seal into a Schema 1.2 Study, verify against data (keyless), and export a committee memo
+ae seal HEAD
+ae verify .alphaengine/studies/HEAD.json
+ae report memo HEAD --format md
+```
+
+---
+
+## What's new in 1.1.1
+
+- **Single firm-key choke point (`require_firm_key()`):** Every gated CLI workflow (`run`, `validate`, `screen`, `diagnose`, `signal`, `stress`, `overlap`, `size`, `monitor`) and Research OS command (`init`, `log`, `show`, `diff`, `rerun`, `watch`, `data`, `idea`, `seal`, `report`, `remote`, `push`, `pull`, `plugin`, `shell`) validates a firm `ae_live_` key upfront via `alphaengine.auth.require_firm_key()`. The library, `alphaengine demo`, `alphaengine process`, and `ae verify` remain free and keyless.
+- **OS keychain storage & secret redaction:** `auth.py` stores credentials in the OS keychain (`keyring`) when available with `~/.config/alphaengine/credentials.json` (`0600`) as fallback, and automatically redacts `ae_live_*` tokens from CLI output, errors, tracebacks, and `--json` envelopes.
+- **Retail CLI path removed:** Removed `--retail` and `/api/retail/ledger/import` from the CLI; retail ledger import happens via web upload in the quantOS portal.
+- **Unified canonical SHA-256 contract & golden fixture:** `canonical_sha256()` (Schema 1.2 sorted-key JSON with fixed `.8f` float formatting and full 64-hex SHA-256) powers `content_sha256`, study seals, CAS objects, dataset hashes, and parameter hashes. Legacy seals still verify and are labeled `"legacy"`. Shipped `alphaengine/contracts/hash_golden.json` in the wheel for cross-repo verification.
+- **Project-wide cumulative trials & DSR everywhere (with re-run deduplication):** The project-wide cumulative trial ledger feeds every DSR — run output, headline `deflated_sharpe` and `n_trials`, push payloads, and sealed studies — with no per-run or per-family reset. Re-running an identical configuration (`command` + `params_hash` + `dataset_hashes`) records `duplicate_of` and adds `0` new trials (`9 -> 9`), while distinct configurations increment cumulative `N` (`9 -> 18`).
+- **Metadata versioning & socket-blocked offline test:** `__version__` is read from `importlib.metadata.version("alphaengine")` with no hardcoded version strings, `combinatorial_oos_stability` and `PBO via CSCV` naming is standardized throughout, and `tests/test_smoke.py` enforces zero socket calls across DSR, PBO via CSCV, `combinatorial_oos_stability`, metrics, `sweep`, and loaders.
+- **Free vs. Firm guide:** Added [`docs/free-vs-firm.md`](docs/free-vs-firm.md).
+
+---
+
+## What's new in 1.1.0
+
+- **Local-first project workspace (`ae init`):** Creates `.alphaengine/` (`project.toml`, `ledger/`, `data/`, `studies/`, `ideas/`, `universes/`, and SHA-256 content-addressed `objects/`). Commands walk up from the current directory to find the project; outside a project, every command behaves as a standalone call.
+- **Project-wide ledger & cumulative trial counting (`ae log`, `ae show`, `ae diff`, `ae rerun`):** Runs and sweeps inside a project automatically record parameter hashes, dataset hashes, and figures, accumulating trial counts across runs on the same `idea_id` or `family`.
+- **Dataset registry (`ae data add|list|show|lineage`):** Tracks local CSV and Parquet datasets by full SHA-256, row count, date range, column schema, and hygiene diagnostics (duplicate timestamps, missing/calendar gaps, `--asof-col` look-ahead hints, and survivorship hints).
+- **Versioned `v1.0` JSON result envelope, `--stdin` pipes, & YAML pipelines:** Every command supports `--json` and `--stdin` (`ae screen --json | ae validate --stdin | ae size --stdin`), plus declarative multi-step recipes (`ae run pipeline.yaml`).
+- **Hypotheses as objects (`ae idea new|list|status|show`):** Link runs with `--idea <id>`, evaluate `--kill-if` rules against cumulative figures, and receive automatic prior-work warnings before running overlapping parameter sets.
+- **Seal, verify, & cited committee memos:** `ae seal <run|idea>`, `ae verify <study.json> [--data <file>]`, and `ae report memo <idea|run> --format md|pdf` (where every figure cites `[run_id]`).
+- **Research shell (`ae shell`), plugins (`ae plugin list`), watcher (`ae watch`), live drift monitor (`ae monitor <run> --live <file>`), & opt-in sync (`ae remote`, `ae push [--dry-run]`, `ae pull`).**
+
 ## What's new in 1.0.3
 
 - **Opt-in series sharing & 512-element wire guard:** By default, workflow step traces (`/api/harness/runs/{id}/traces`) report scalar figures only; full series are shared only when you pass `--share-series` or set `ALPHAENGINE_SHARE_SERIES=1`.
-- **Sealed studies (schema 1.2) & CLI reporting:** Studies now carry a canonical-JSON SHA-256 seal (`content_sha256`), a full 64-hex `data_hash`, and an optional per-trial ledger (`include_ledger=True`). Use `alphaengine seal <study.json>` to seal or verify a study file, and `alphaengine report <study.json> [--retail]` to ingest into quantOS or the retail experiment ledger.
+- **Sealed studies (schema 1.2) & CLI reporting:** Studies now carry a canonical-JSON SHA-256 seal (`content_sha256`), a full 64-hex `data_hash`, and an optional per-trial ledger (`include_ledger=True`). Use `alphaengine seal <study.json>` to seal or verify a study file, and `alphaengine report <study.json>` to ingest into quantOS.
 - **Math fixes:** `SweepResult.verdict()` passes cross-trial Sharpe dispersion into `deflated_sharpe` per Bailey & López de Prado (2014); `deflated_sharpe(n_trials=1)` returns `psr_vs_zero` with `sr0_expected_max = 0.0` instead of deflating as `N=2`; `combinatorial_oos_stability` replaces `cpcv_score` (kept as a deprecated alias); and `pbo_cscv` validates that `n_splits` is an even integer $\ge 2$.
 - **Interop loaders (`alphaengine.io`):** `from_quantconnect(path)` and `from_vectorbt(portfolio_or_csv)` build a `Study` with returns and preserve trial-count provenance (`"asserted"` vs. `"not_recorded"`).
 
@@ -273,7 +351,7 @@ A portal that rejects the trace does not fail the run.
 ## What's new in 0.8.0
 
 Named processes, Grinold, and a frozen chart contract. Existing goldens
-(deflated Sharpe, PBO, performance, screen) are byte-identical. New figures
+(deflated Sharpe, PBO via CSCV, performance, screen) are byte-identical. New figures
 are a public contract from this release. The study schema is **1.1**: optional
 `process` and `charts` fields; 1.0 studies still load.
 
@@ -302,7 +380,7 @@ a = grinold_alpha(panel, ic=0.05, vols=vols)  # alpha stays here; missing vols a
 ## What's new in 0.7.0
 
 The daily modelling morning, and the overnight book, without a third
-dependency. Existing goldens (deflated Sharpe, PBO, performance, screen) are
+dependency. Existing goldens (deflated Sharpe, PBO via CSCV, performance, screen) are
 byte-identical. New figures are a public contract from this release.
 
 | You have | You get | Module |
@@ -339,9 +417,13 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 
 | Command | Does | Where |
 |---|---|---|
+| `init [--name NAME]` | initialize a local .alphaengine/ research project in this directory | shell + session |
 | `demo` | run the built-in example offline, with no account and no data | shell + session |
 | `process [ou \| gbm \| jump \| garch]` | fit a named process to a series and stress it, offline | shell + session |
 | `runs [--limit N]` | your own week: what ran, what it decided, what it filed | shell + session |
+| `log [--idea ID] [--family FAMILY] [--since DATE] [--verdict VERDICT]` | list local project ledger runs, trial counts, and verdicts | shell + session |
+| `show <run>` | inspect one recorded project run, its hashes, trials, and figures | shell + session |
+| `diff <run-a> <run-b>` | compare data, parameter, trial, and figure changes between two runs | shell + session |
 | `gaps` | what your record says is UNANSWERED, and what closes each one | shell + session |
 | `tonight [--budget N]` | what would run unattended tonight, without running any of it | shell + session |
 | `workflows` | what the server offers, what each needs, and which reproduce | shell + session |
@@ -365,8 +447,11 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 | `size` | what sizing does the risk model imply? | shell + session |
 | `monitor` | still inside the lines? | shell + session |
 | `run <workflow>` | run one workflow exactly as written | shell + session |
-| `seal <study.json>` | write canonical content_sha256 into a study and verify on re-run | shell |
-| `report <study.json> [--retail]` | send a saved study to quantOS (/api/me/runs/ingest or --retail ledger) | shell |
+| `rerun <run>` | reproduce a recorded project run from its inputs and check figures | shell + session |
+| `watch <pipeline.yaml> [--interval SECONDS]` | re-run a declarative pipeline whenever a registered dataset file changes | shell + session |
+| `seal <study.json \| run \| idea>` | write canonical content_sha256 into a study (or seal a project run/idea) | shell + session |
+| `verify <study.json> [--data FILE]` | verify a study.json content_sha256 seal and optionally re-check figures | shell + session |
+| `report <study.json> \| memo <idea \| run> [--format md \| pdf]` | send a study to quantOS (/api/me/runs/ingest), or export a cited committee memo | shell + session |
 | `<anything else>` | ask in plain English; your model picks a workflow and drives it | session |
 | `status` | the current run, and what is loaded | session |
 
@@ -376,19 +461,25 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 |---|---|---|
 | `book [<name> \| status]` | show or load sleeves on the multi-strategy book | session |
 | `load <file \| module \| universe>` | a CSV, a project module, or a portal universe | session |
+| `idea new "<thesis>" --kill-if "<rule>" [--family FAMILY] \| list \| status <id> <state> \| show <id>` | create, list, update, and evaluate local research hypotheses | shell + session |
 | `thesis [<name> \| clear]` | choose a portal thesis for the next run | session |
 | `correlation` | the correlation of every loaded name with every other name | session |
 | `covariance` | the sample covariance of every loaded name with every other name | session |
 | `cointegration` | which loaded names are cointegrated | session |
 | `portfolio` | weights for the names already loaded | session |
 | `universe <name>` | same as load: a universe registered in the portal | session |
-| `data <file>` | same as load: a local CSV or parquet | session |
+| `data add <file> [--name NAME] [--asof-col COL] \| list \| show <name> \| lineage <run>` | register, inspect, and trace local CSV/Parquet datasets | shell + session |
 | `project <module>` | same as load: a module with data and backtest_fn | session |
 
 ### Session
 
 | Command | Does | Where |
 |---|---|---|
+| `remote add <name> [url] \| list` | configure or list remote sync endpoints in .alphaengine/project.toml | shell + session |
+| `push [remote] [--dry-run] [--share-series]` | sync sealed studies, ledger runs, and ideas to quantOS (opt-in network) | shell + session |
+| `pull [remote]` | pull team runs and ideas from quantOS into the local ledger (read-only) | shell + session |
+| `plugin list` | list installed loader, method, and report template plugins | shell + session |
+| `shell` | open the interactive research shell with project completion and status | shell |
 | `logout [--purge]` | remove stored credentials from this machine | shell + session |
 | `version` | print the version | shell |
 | `help` | the short list: demo, login, load, then a question | session |
@@ -421,7 +512,20 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 | `--limit N` | how many rows to show (default 25) |
 | `--budget N` | how many runs a night is worth (default 3) |
 | `--purge` | remove ~/.config/alphaengine/credentials.json and clean up its config directory |
-| `--retail` | send the study to the retail experiment ledger (/api/retail/ledger/import) |
+| `--name NAME` | name for the initialized project or registered dataset |
+| `--idea ID` | attach the run or filter the log to a local hypothesis id |
+| `--family FAMILY` | strategy or experiment family for cumulative trial counting |
+| `--since DATE` | filter project log to runs on or after YYYY-MM-DD |
+| `--verdict VERDICT` | filter project log by verdict (e.g. robust, marginal, likely_noise) |
+| `--asof-col COL` | as-of column name or cutoff date for look-ahead checks in data add |
+| `--json` | emit a versioned v1.0 JSON result envelope to stdout |
+| `--stdin` | read an upstream JSON result envelope from standard input |
+| `--kill-if RULE` | kill rule for a hypothesis, e.g. 'DSR < 0.9' |
+| `--format FMT` | output format for report memo: md or pdf (default md) |
+| `--dry-run` | print the exact sync payload without making a network call |
+| `--live FILE` | live return series CSV to compare against a recorded backtest run |
+| `--interval SECONDS` | polling interval in seconds for watch (default 1.0) |
+| `--cycles N` | number of polling cycles for watch before exiting (0 means continuous) |
 
 ### Examples
 
@@ -434,11 +538,17 @@ alphaengine stress
 alphaengine overlap
 alphaengine size
 alphaengine monitor
+alphaengine init
+alphaengine init --name momentum
 alphaengine demo
 alphaengine process
 alphaengine process ou
 alphaengine runs
 alphaengine runs --limit 50
+alphaengine log
+alphaengine log --family momentum --verdict likely_noise
+alphaengine show HEAD
+alphaengine diff run_a run_b
 alphaengine gaps
 alphaengine tonight
 alphaengine tonight --budget 5
@@ -448,12 +558,33 @@ alphaengine commands
 alphaengine run screen_universe --universe sp500
 alphaengine run size_position --data returns.csv
 alphaengine run validate_study --project research.momentum
+alphaengine run examples/screen_validate_size.yaml
+alphaengine rerun HEAD
+alphaengine watch examples/screen_validate_size.yaml
 alphaengine seal study.json
+alphaengine seal HEAD
+alphaengine verify study.json
+alphaengine verify study.json --data prices.csv
 alphaengine report study.json
-alphaengine report study.json --retail
+alphaengine report memo HEAD --format md
 alphaengine models
 alphaengine trace
+alphaengine idea new "Cross-sectional momentum holds" --kill-if "DSR < 0.9" --family momentum
+alphaengine idea list
+alphaengine idea status idea_1 testing
+alphaengine idea show idea_1
 alphaengine run screen_universe --thesis momentum
+alphaengine data add prices.csv --name equities
+alphaengine data list
+alphaengine data show equities
+alphaengine data lineage HEAD
+alphaengine remote add quantos
+alphaengine remote add quantos https://qosai.app
+alphaengine push --dry-run
+alphaengine push
+alphaengine pull
+alphaengine plugin list
+alphaengine shell
 alphaengine logout
 alphaengine logout --purge
 alphaengine version
@@ -489,7 +620,7 @@ above exists to copy:
 per-period returns themselves. `sweep` does `np.asarray(list(raw))`, so a dict
 of results iterates its *keys* and fails on the first string.
 
-**Return the same length for every combination.** PBO splits the trial matrix
+**Return the same length for every combination.** PBO via CSCV splits the trial matrix
 into time blocks and compares configurations within each block, which only means
 anything if they line up in time. Ragged output is refused rather than truncated,
 because silently trimming produces a confident number over series that do not
@@ -541,7 +672,7 @@ diffable, and versioned so it still parses in two years.
 
 | Module | Contents |
 |---|---|
-| `alphaengine.core` | deflated Sharpe, PSR, PBO via CSCV, CPCV, minimum track record length, performance and risk |
+| `alphaengine.core` | deflated Sharpe, PSR, PBO via CSCV, `combinatorial_oos_stability`, minimum track record length, performance and risk |
 | `alphaengine.core.panel` | cross-sectional rank, z-score, winsorize, neutralize |
 | `alphaengine.core.signals` | IC, ICIR, quantile returns, decay |
 | `alphaengine.core.cross_section` | Fama-MacBeth, quantile book with turnover |
@@ -580,14 +711,15 @@ Study.from_sweep(r, label="momentum, 9 configs").report()
 What crosses is an explicit allowlist: the trial count and how it was obtained,
 a content hash of the data, the verdict, the shape of the neighbourhood, the
 performance figures. Computation runs locally; when you are signed in to
-quantOS, summary figures are reported to your account, and full series are
-shared only if you opt in (`--share-series` or `ALPHAENGINE_SHARE_SERIES=1`).
-Without opt-in, a guard keyed on length (at most 512 elements) refuses to send
+quantOS, summary figures are reported to your account, and full return series
+upload only with `--share-series` (or `ALPHAENGINE_SHARE_SERIES=1`). Without
+`--share-series`, a guard keyed on length (at most 512 elements) refuses to send
 anything series-shaped whatever it is called.
 
-Reporting is the only part of this package that touches a network, so it is the
-only part that is not imported until you call it. `import alphaengine` still
-makes no network call.
+### What uses the network
+
+- **Zero network calls (completely offline):** `import alphaengine`, `sweep()`, `Study.save()`, `Study.load()`, every math primitive in `alphaengine.core` (`deflated_sharpe`, `pbo_cscv`, `combinatorial_oos_stability`, performance, risk, covariance, allocation, process calibration/stress, Grinold), local loaders (`load_csv`, `from_quantconnect`, `from_vectorbt`), `alphaengine demo`, `alphaengine process`, and `ae verify`.
+- **Uses the network (requires a firm `ae_live_` key from Connect):** `login` / `whoami`, CLI workflows (`validate`, `screen`, `diagnose`, `decompose`, `pairs`, `walkforward`, `compare`, `size`, `run`, `workflows`, `runs`, `gaps`, `tonight`), `Study.report()` / `ae report`, and workspace sync (`ae seal` key check, `ae push`, `ae pull`). Full return series upload **only** when `--share-series` is passed.
 
 ## Where this sits in QuantOS