Docs, submodule SWIFT_DOT-FIN, data pipelines, and module updates

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -2,6 +2,31 @@
 
 A unified institutional framework for monetary, fiscal, financial, and open-economy dynamics. This codebase implements the full FQBM from the white paper: simulation workbook (eight sheets), Monte Carlo stress engine, differential system model, and empirical regression suite.
 
+## Table of contents
+
+- [Quick start](#quick-start)
+- [Install](#install)
+- [Run](#run)
+- [Test](#test)
+- [Optional features](#optional-features)
+- [IPSAS compliance](#ipsas-compliance)
+- [Submodule (SWIFT DOT-FIN)](#submodule-swift-dot-fin)
+- [Framework and docs](#framework-and-docs)
+
+## Quick start
+
+```python
+from fqbm.workbook.runner import run_workbook
+from fqbm.state import FQBMState
+
+state = FQBMState(B=100, R=50, C=20, Loans=800, Deposits=700, E_cb=30, E_b=100)
+result = run_workbook(initial_state=state, mc_runs=50, export_path="out.xlsx")
+# Or use a scenario:
+run_workbook(scenario="asia_1997", mc_runs=100, export_path="asia.xlsx")
+```
+
+See [docs/USER_GUIDE.md](docs/USER_GUIDE.md) for a full walkthrough.
+
 ## Install
 
 ```bash
@@ -11,7 +36,7 @@ source .venv/bin/activate   # Windows: .venv\Scripts\activate
 pip install -e .
 ```
 
-Optional: `pip install pytest` for tests.
+Optional: `pip install pytest` for tests; `pip install streamlit` for the dashboard.
 
 ## Run
 
@@ -28,25 +53,31 @@ Optional: `pip install pytest` for tests.
 pytest tests/ -v
 ```
 
-## Optional: Streamlit dashboard
+## Optional features
 
-```bash
-pip install streamlit
-streamlit run scripts/streamlit_dashboard.py
-```
-
-## Optional: Historical scenarios (Part XI)
-
-Use preset scenarios in code: `run_workbook(scenario="asia_1997")` or `"gfc_2008"`, `"pandemic_2020"`, `"rate_shock_2022"`. See `fqbm.scenarios`.
+- **Streamlit dashboard**: `pip install streamlit` then `streamlit run scripts/streamlit_dashboard.py`
+- **Historical scenarios (Part XI)**: `run_workbook(scenario="asia_1997")` or `"gfc_2008"`, `"pandemic_2020"`, `"rate_shock_2022"`; `get_case_narrative(name)` for narrative and coded outputs
+- **CBDC / CCP / repo**: `run_workbook(cbdc_params=..., ccp_params=..., shadow_params=...)`; state has `cbdc_liability` after CBDC shift; repo multiplier is in `result["dashboard"]["repo_multiplier"]`
+- **Real data**: `from fqbm.data.pipelines import fetch_fed_h41, fetch_bis_series, fetch_imf_series` (Fed H.4.1, BIS bulk CSV, IMF with optional api_key)
 
 ## References
 
-See [docs/REFERENCES.md](docs/REFERENCES.md) for Chicago Author–Date references (Adrian & Shin, BIS, Dornbusch, Fed H.4.1, IMF, McLeay et al., Obstfeld & Rogoff, etc.).
+See [docs/REFERENCES.md](docs/REFERENCES.md) for Chicago Author–Date references and optional weblinks (IPSASB, BIS, IMF, Fed H.4.1).
 
 ## IPSAS compliance
 
-The framework includes an **IPSAS-aligned presentation layer** (IPSAS 1 statement of financial position, IPSAS 24 budget vs actual structure). Use `fqbm.ipsas.presentation.statement_of_financial_position(state, entity="central_bank"|"commercial_bank"|"consolidated")` and `budget_vs_actual_structure()`. Excel export adds IPSAS-style sheets when available. See [docs/IPSAS_COMPLIANCE.md](docs/IPSAS_COMPLIANCE.md) for the compliance assessment. **[docs/GAPS_AND_MISSING.md](docs/GAPS_AND_MISSING.md)** lists IPSAS standards and FQBM gaps. Additional helpers: **notes_to_financial_statements_structure**, **statement_of_financial_position_comparative**, **maturity_risk_disclosure_structure**, **cash_flow_from_state_changes**, **fx_translate**. Part VII: **repo_multiplier**, **margin_spiral_simulation**. Part VIII: **variation_margin_flow**, **ccp_clearing_simulation**.
+The framework includes an **IPSAS-aligned presentation layer** (IPSAS 1 statement of financial position, IPSAS 24 budget vs actual, and structures for IPSAS 2, 3, 4, 5, 9, 10, 14, 19, 20, 23, 29/41, 38, 46, 48, cash basis, RPG 2, functional/presentation currency). Use `fqbm.ipsas.presentation.statement_of_financial_position(state, entity="central_bank"|"commercial_bank"|"consolidated")`, `budget_vs_actual_structure()`, `budget_actual_from_state(state, budget)`, and other helpers. Excel export adds IPSAS-style sheets when available. See [docs/IPSAS_COMPLIANCE.md](docs/IPSAS_COMPLIANCE.md) and [docs/GAPS_AND_MISSING.md](docs/GAPS_AND_MISSING.md).
 
-## Framework
+## Submodule (SWIFT DOT-FIN)
 
-See [docs/framework_summary.md](docs/framework_summary.md) and the white paper for the theoretical foundation (Parts I–XVI).
+This repo includes **SWIFT_DOT-FIN** as a submodule (ledger entries and payloads, creation to transfers). Clone with submodules: `git clone --recurse-submodules <repo>`, or after clone run `git submodule update --init --recursive`. The submodule lives at `SWIFT_DOT-FIN/`; its source path is `/home/intlc/projects/SWIFT_DOT-FIN` (or `../SWIFT_DOT-FIN` relative to this project).
+
+## Framework and docs
+
+- [docs/framework_summary.md](docs/framework_summary.md) — Parts I–XVI and module mapping
+- [docs/WHITE_PAPER.md](docs/WHITE_PAPER.md) — Placeholder for canonical white paper
+- [docs/USER_GUIDE.md](docs/USER_GUIDE.md) — Tutorial and usage
+- [docs/API_REFERENCE.md](docs/API_REFERENCE.md) — Public API
+- [docs/DATA_DICTIONARY.md](docs/DATA_DICTIONARY.md) — State variables, sheet I/O, regression columns
+- [docs/MISSING_COMPONENTS_AND_DOCUMENTATION.md](docs/MISSING_COMPONENTS_AND_DOCUMENTATION.md) — Consolidated gap list and documentation checklist
+- [docs/RECOMMENDATIONS.md](docs/RECOMMENDATIONS.md) — Additional recommendations and suggestions