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

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-23 00:22:29 -08:00
parent abed763a4f
commit 8df772fab0
26 changed files with 1419 additions and 192 deletions
--- a/docs/API_REFERENCE.md
+++ b/docs/API_REFERENCE.md
@@ -0,0 +1,40 @@
+# FQBM API Reference
+
+Public functions and classes, with main parameters and return types. For full docstrings, see the source.
+
+## State and matrix
+
+**fqbm.state**
+- `FQBMState`: Dataclass (B, R, C, Loans, Deposits, E_cb, E_b, S, K, Spread, O, L_cb, cbdc_liability, reporting_date, functional_currency, presentation_currency). Methods: to_vector(), from_vector(), copy().
+- `open_economy_view(A_dom, A_ext, L_dom, L_ext, E)`: Returns dict with totals and identity_holds.
+
+**fqbm.matrix**
+- `four_quadrant_matrix(state, L_cb=None)`: pd.DataFrame (Assets Dr/Cr, Liabilities Dr/Cr).
+- `four_quadrant_summary(state, L_cb=None)`: dict (total_assets_dr, total_liabilities_dr, total_liabilities_cr, identity_A_eq_L_plus_E).
+- `cross_sector_consistency_check(state, L_cb=None)`: dict (consistent, cb_balance, bank_balance, matrix_identity, message, sector/matrix totals).
+
+## Workbook and sheets
+
+**fqbm.workbook.runner**
+- `run_workbook(initial_state=None, scenario=None, mc_runs=100, export_path=None, include_ipsas=True, cbdc_params=None, ccp_params=None)`: Returns dict (state, stress_tables, fx_parity, sovereign, commodity, monte_carlo, dashboard, ipsas).
+- `main()`: CLI entry point.
+
+**fqbm.sheets**: CentralBankParams/central_bank_step; CommercialBankParams/commercial_bank_step; StressParams/stress_tables; FXParams/fx_parity_step; SovereignParams/sovereign_debt_step; CommodityParams/commodity_step; ShockSpec/run_n_simulations; dashboard_aggregate (includes repo_multiplier when computed); ShadowBankingParams/repo_multiplier, margin_spiral_simulation; CCPParams/variation_margin_flow, ccp_clearing_simulation; CBDCParams/deposit_to_cbdc_shift.
+
+**fqbm.data.pipelines**: fetch_fed_h41(url?, date_col?); fetch_bis_series(dataset?, country?, api_key?) — dataset in credit_gap, debt_service, property, total_credit, cb_assets; fetch_imf_series(database_id?, indicator?, country?, api_key?) — optional api_key for IMF API.
+
+## IPSAS presentation (fqbm.ipsas.presentation)
+
+Statement of financial position; budget_vs_actual_structure; budget_actual_from_state; cash flow structure and cash_flow_from_state_changes; statement of financial performance; statement of changes in net assets; fx_translate; notes template; comparative; maturity_risk_disclosure; accounting_policies (IPSAS 3); borrowing_costs (5); revenue_recognition (9/47); hyperinflation_restatement (10); events_after_reporting_date (14); provisions_contingencies (19); related_party_disclosure (20); revenue_non_exchange (23); financial_instruments_measurement (29/41); interests_in_other_entities (38); measurement_basis (46); transfer_expenses (48); cash_basis_statement; fs_discussion_and_analysis (RPG 2); functional_presentation_currency.
+
+## Scenarios (fqbm.scenarios.presets)
+
+- `list_scenarios()`: list of names.
+- `get_scenario(name)`: ScenarioPreset or None.
+- `get_case_narrative(name)`: dict (name, description, narrative, state_summary, key_drivers, suggested_shocks) or None.
+
+## System and empirical
+
+**fqbm.system.differential_model**: DifferentialParams; solve_trajectory(x0, t_span, params); check_stability(params).
+
+**fqbm.empirical.regressions**: generate_synthetic_inflation, run_inflation_pass_through; generate_synthetic_spread, run_sovereign_spread; generate_synthetic_capital_flow, run_capital_flow_sensitivity. Required columns: see [DATA_DICTIONARY.md](DATA_DICTIONARY.md). Further suggestions: [RECOMMENDATIONS.md](RECOMMENDATIONS.md).
--- a/docs/DATA_DICTIONARY.md
+++ b/docs/DATA_DICTIONARY.md
@@ -0,0 +1,25 @@
+# FQBM Data Dictionary
+
+Definitions of state variables, sheet inputs/outputs, and regression variables.
+
+## 1. State vector (FQBMState)
+
+- **B**: Government securities (CB assets). **R**: Reserve balances. **C**: Currency in circulation. **Loans**: Commercial bank loans. **Deposits**: Commercial bank deposits. **E_cb**, **E_b**: Central bank and bank net assets/equity. **S**: Exchange rate (domestic per foreign). **K**: Capital flows. **Spread**: Sovereign spread. **O**: Oil/commodity index. **L_cb**: Central bank loans. **cbdc_liability**: CBDC liability (Part IX). **reporting_date**, **functional_currency**, **presentation_currency**: Optional.
+
+Identities: B + L_cb = R + C + E_cb; Loans = Deposits + E_b; Total assets (Dr) = Total liab (Dr) + Total liab (Cr).
+
+## 2. Sheet I/O
+
+Central bank / commercial bank: state + params -> updated state. Capital stress: state + StressParams -> stress_tables. FX parity: state + FXParams -> fx_parity. Sovereign: state + SovereignParams -> spread, sustainability. Commodity: state + CommodityParams -> commodity. Monte Carlo: state + ShockSpec, n_runs -> list of states. Dashboard: state + optional stress/mc -> dashboard_aggregate. IPSAS: state (and prior) -> presentation DataFrames.
+
+## 3. Regression columns (Part X)
+
+Model 1 (inflation pass-through): d_fx, pi/inflation; synthetic: generate_synthetic_inflation(n). Model 2 (sovereign spread): debt_gdp, reserves_gdp, fx_vol, growth_differential, spread; synthetic: generate_synthetic_spread(n). Model 3 (capital flow): spread/r_dom/r_foreign, growth, capital_flow; synthetic: generate_synthetic_capital_flow(n).
+
+## 4. Four-quadrant matrix
+
+Assets (Dr): B, L_cb, Loans. Liabilities (Dr): C, R, Deposits. Liabilities (Cr): E_cb, E_b. cross_sector_consistency_check(state) returns consistent, cb_balance, bank_balance, matrix_identity, message.
+
+## 5. Real data pipelines (fqbm.data.pipelines)
+
+fetch_fed_h41: Fed H.4.1 CSV (optional url, date_col). fetch_bis_series: BIS bulk CSV (dataset in credit_gap, debt_service, property, total_credit, cb_assets; optional country). fetch_imf_series: IMF data (optional api_key for API). Pipelines can be extended (e.g. more series, caching, retries). See RECOMMENDATIONS.md.
--- a/docs/GAPS_AND_MISSING.md
+++ b/docs/GAPS_AND_MISSING.md
@@ -1,152 +1,46 @@
-# Complete IPSAS and FQBM Matrix — Gaps and Missing
+# IPSAS and FQBM — Gaps and Missing

-This document lists **all remaining IPSAS standards** and **all FQBM/Matrix gaps and missing elements** as of the current codebase. It extends [IPSAS_COMPLIANCE.md](IPSAS_COMPLIANCE.md).
+Short summary of **remaining gaps** and **FQBM/Matrix status**. Full scope: [IPSAS_COMPLIANCE.md](IPSAS_COMPLIANCE.md). Suggestions: [RECOMMENDATIONS.md](RECOMMENDATIONS.md).

 ---

-## Part A — IPSAS: Full standards list and status
+## 1. IPSAS: Summary by status

-| # | Standard | Status | Gap / note |
-|---|----------|--------|-------------|
-| **CF** | Conceptual Framework | Partial | A = L + E aligned; no revenue/expense/definition of surplus. |
-| **1** | Presentation of Financial Statements | Supported | Structure + current/non-current in `fqbm.ipsas.presentation`. |
-| **2** | Cash Flow Statements | Structure only | Template in `cash_flow_statement_structure()`; no activity classification from FQBM. |
-| **3** | Accounting Policies, Changes in Estimates and Errors | **Missing** | No policy note, prior-period adjustment, or error correction. |
-| **4** | Effects of Changes in Foreign Exchange Rates | Partial | S and pass-through only; no translation of FC assets/liabilities, no FX gain/loss disclosure. |
-| **5** | Borrowing Costs | **Missing** | No borrowing-cost capitalisation or expense classification. |
-| **6** | Consolidated and Separate Financial Statements | Partial | Sectoral (CB, bank) and consolidated view in presentation; no control definition or full consolidation mechanics. |
-| **7** | Investments in Associates | **Missing** | Not applicable to core FQBM; no equity method. |
-| **8** | Interests in Joint Ventures | **Missing** | Not applicable; no joint arrangement. |
-| **9** | Revenue from Exchange Transactions | **Missing** | No revenue recognition or measurement. |
-| **10** | Financial Reporting in Hyperinflationary Economies | **Missing** | No hyperinflation restatement (FQBM has inflation π but not restatement). |
-| **11** | Construction Contracts | **Missing** | Not applicable to monetary/financial core. |
-| **12** | Inventories | **Missing** | Not applicable. |
-| **13** | Leases | **Missing** | Not applicable to core; no right-of-use asset/lease liability. |
-| **14** | Events After the Reporting Date | **Missing** | No adjustment vs disclosure classification. |
-| **15** | Financial Instruments: Disclosure and Presentation | Partial | Presentation only; no disclosure (maturity, risk). |
-| **16** | Investment Property | **Missing** | Not applicable. |
-| **17** | Property, Plant, and Equipment | **Missing** | Not applicable; no PP&E or depreciation. |
-| **18** | Segment Reporting | **Missing** | No segment definition or segment P&L. |
-| **19** | Provisions, Contingent Liabilities and Contingent Assets | **Missing** | No provisions or contingencies. |
-| **20** | Related Party Disclosures | **Missing** | No related party identification or disclosure. |
-| **21** | Impairment of Non-Cash-Generating Assets | **Missing** | Not applicable to financial core. |
-| **22** | Disclosure of Financial Information About the General Government Sector | Partial | Sectoral structure supported; GGS boundary and entity list external. |
-| **23** | Revenue from Non-Exchange Transactions | **Missing** | No tax/transfer revenue. |
-| **24** | Presentation of Budget Information in Financial Statements | Structure only | Template in `budget_vs_actual_structure()`; budget data external. |
-| **25** | Employee Benefits | **Missing** | Not applicable to core. |
-| **26** | Impairment of Cash-Generating Assets | **Missing** | No impairment model. |
-| **27** | Agriculture | **Missing** | Not applicable. |
-| **28** | Financial Instruments: Presentation | Partial | Asset/liability split in statement of financial position. |
-| **29** | Financial Instruments: Recognition and Measurement | **Missing** | No measurement basis (amortised cost, FVOCI, FVPL) or ECL. |
-| **30** | Financial Instruments: Disclosures | **Missing** | No risk or maturity disclosure. |
-| **31** | Intangible Assets | **Missing** | Not applicable. |
-| **32** | Service Concession Arrangements: Grantor | **Missing** | Not applicable. |
-| **33** | First-Time Adoption of Accrual Basis IPSAS | **Missing** | Not applicable (no full IPSAS adoption). |
-| **34** | Separate Financial Statements | Partial | Entity-level (CB, bank) supported. |
-| **35** | Consolidated Financial Statements | Partial | Consolidated layout; no full consolidation rules. |
-| **36** | Investments in Associates and Joint Ventures | **Missing** | Not applicable. |
-| **37** | Joint Arrangements | **Missing** | Not applicable. |
-| **38** | Disclosure of Interests in Other Entities | **Missing** | No disclosure. |
-| **39** | Employee Benefits | **Missing** | Not applicable. |
-| **40** | Public Sector Combinations | **Missing** | Not applicable. |
-| **41** | Financial Instruments | **Missing** | No classification, measurement, or ECL. |
-| **42** | Social Benefits | **Missing** | Not applicable. |
-| **43** | Leases | **Missing** | Not applicable. |
-| **44** | Non-Current Assets Held for Sale and Discontinued Operations | **Missing** | Not applicable. |
-| **45** | Property, Plant, and Equipment | **Missing** | Not applicable. |
-| **46** | Measurement | **Missing** | No measurement basis (historical, FV, etc.). |
-| **47** | Revenue | **Missing** | No revenue model. |
-| **48** | Transfer Expenses | **Missing** | No transfer expense. |
-| **49** | Retirement Benefit Plans | **Missing** | Not applicable. |
-| **50** | Exploration for and Evaluation of Mineral Resources | **Missing** | Not applicable. |
-| **Cash basis** | Financial Reporting Under the Cash Basis | **Missing** | No cash-basis statement. |
-| **RPG 1** | Long-Term Sustainability of an Entity's Finances | Partial | Debt sustainability (r−g) in sovereign module; no full RPG 1 disclosure. |
-| **RPG 2** | Financial Statement Discussion and Analysis | **Missing** | No narrative. |
-| **RPG 3** | Reporting Service Performance Information | **Missing** | Not applicable. |
-| **SRS 1** | Climate-related Disclosures | **Missing** | Not applicable. |
+| Status | Count | Notes |
+|--------|--------|--------|
+| **Supported** | 1 | IPSAS 1 (statement of financial position: structure, current/non-current). |
+| **Structure** | 20+ | Templates in `fqbm.ipsas.presentation`: 3, 5, 9, 10, 14, 19, 20, 23, 24 (+ budget_actual_from_state), 29/30/41, 38, 46, 47, 48, cash basis, RPG 2, functional/presentation currency. |
+| **Partial** | 6 | CF (no revenue/expense); 2 (no activity classification); 4 (S, pass-through only); 6, 22, 28, 34, 35 (sectoral/consolidated layout only); 15 (maturity_risk_disclosure_structure); RPG 1 (r−g in sovereign module). |
+| **Missing / N/A** | 25+ | Not applicable to monetary/financial core: 7, 8, 11–13, 16–18, 21, 25–27, 31–33, 36–37, 39–45, 49–50, RPG 3, SRS 1. 26: no impairment model. |
+
+**Main gaps for entity-level IPSAS:** Cash flow by activity (IPSAS 2); FX translation of FC positions and gain/loss disclosure (4); measurement basis and ECL (41); full consolidation rules (6, 35). Budget data is external; use `budget_actual_from_state(state, budget)` for actuals.

 ---

-## Part B — FQBM / Four-Quadrant Matrix: Gaps and missing
+## 2. FQBM / Matrix: What’s implemented

-### B.1 State vector and identities
-
-| Item | Status | Note |
-|------|--------|------|
-| **L_cb (central bank loans)** | **Added** | `FQBMState.L_cb` (default 0); central_bank_step updates L_cb; matrix uses state.L_cb. |
-| **Open-economy split A_dom / A_ext, L_dom / L_ext** | **Added** | `open_economy_view(A_dom, A_ext, L_dom, L_ext, E)` in `fqbm.state` returns identity check and totals. |
-| **Reporting period / reporting date** | **Added** | `FQBMState.reporting_date` (optional); `statement_of_financial_position(..., reporting_date=)` uses state.reporting_date when not passed. |
-
-### B.2 Four-quadrant matrix (Part I)
-
-| Item | Status | Note |
-|------|--------|------|
-| **Explicit four-quadrant layout** | **Added** | `fqbm.matrix.four_quadrant_matrix(state)` and `four_quadrant_summary(state)` return the 4-column matrix and identity check. |
-| **Quadrant balance checks** | **Added** | Summary includes `identity_A_eq_L_plus_E`. |
-| **Cross-sector consistency** | Partial | CB and bank identities implemented; no automatic check that matrix totals equal sectoral sums. |
-
-### B.3 White paper parts not implemented
-
-| Part | Topic | Status | Gap |
-|------|--------|--------|-----|
-| **VII** | Shadow banking and leverage | **Integrated** | `leverage_ratio()` in dashboard ratios; `margin_spiral_risk()` available; repo multiplier not modeled. |
-| **VIII** | Derivatives clearing and CCP | **Integrated** | `run_workbook(ccp_params=CCPParams(...))` returns `result["ccp"]` with identity and waterfall flag. |
-| **IX** | CBDC and digital reserve architecture | **Integrated** | `run_workbook(cbdc_params=CBDCParams(...))` applies deposit/reserve shift; `result["cbdc"]` has cbdc_liability. |
-| **XI** | Historical case expansion | **Partial** | Presets (1997, 2008, 2020, 2022) in scenarios; no narrative or coded “case” outputs. |
-
-### B.4 IPSAS presentation structures added (templates only where no FQBM data)
-
-| Item | Status | Location |
-|------|--------|----------|
-| Statement of financial position (IPSAS 1) | Supported | `statement_of_financial_position()` |
-| Budget vs actual (IPSAS 24) | Structure | `budget_vs_actual_structure()` |
-| Cash flow statement (IPSAS 2) | Structure | `cash_flow_statement_structure()` |
-| Statement of financial performance | Structure | `statement_of_financial_performance_structure()` |
-| Four-quadrant matrix | Supported | `fqbm.matrix.four_quadrant_matrix()` |
-
-### B.5 Other missing
-
-| Item | Status |
-|------|--------|
-| **Statement of changes in net assets/equity** | **Added** | `statement_of_changes_in_net_assets_structure()`. |
-| **Notes to the financial statements** | **Added** | `notes_to_financial_statements_structure()`. |
-| **Comparative period** | **Added** | `statement_of_financial_position_comparative(state_prior, state_current, entity)`. |
-| **Functional currency / presentation currency** | **Missing**. |
-| **Financial instrument maturity breakdown** | **Added** | `maturity_risk_disclosure_structure()` (maturity buckets, interest rate +100bp, credit exposure, ECL). |
-| **Interest rate sensitivity** | **Partial** | Column in maturity_risk_disclosure_structure. |
-| **Credit risk / ECL disclosure** | **Partial** | Columns in maturity_risk_disclosure_structure. |
-| **FX translation of FC positions** | **Added** | `fx_translate(fc_amount, S_prev, S_curr)`. |
-| **Cash flow from balance sheet changes** | **Added** | `cash_flow_from_state_changes(state_prev, state_curr)`. |
+- **State:** L_cb, cbdc_liability, reporting_date, functional_currency, presentation_currency. **Open economy:** `open_economy_view(A_dom, A_ext, L_dom, L_ext, E)`.
+- **Matrix:** `four_quadrant_matrix()`, `four_quadrant_summary()`, `cross_sector_consistency_check()`.
+- **Parts VII–IX, XI:** Shadow banking (repo_multiplier in dashboard, margin_spiral_simulation); CCP (ccp_params, result["ccp"]); CBDC (cbdc_liability in state and IPSAS); scenarios + `get_case_narrative()`.
+- **IPSAS layer:** Statement of financial position (CB, bank, consolidated), budget vs actual (template + budget_actual_from_state), cash flow from Δstate, comparative, notes, maturity/risk, FX translate, and all structure templates above.

 ---

-## Part C — Implementation checklist (done vs to do)
+## 3. Remaining gaps (concise)

-### Done
-
- IPSAS 1 statement of financial position (CB, bank, consolidated); uses state.L_cb and state.reporting_date.
- IPSAS 24 budget vs actual template.
- IPSAS 2 cash flow statement template; **cash_flow_from_state_changes(state_prev, state_curr)** infers amounts from Δstate.
- Statement of financial performance template.
- **Statement of changes in net assets** template.
- **FX translation**: **fx_translate(fc_amount, S_prev, S_curr)**.
- Four-quadrant matrix and summary; **L_cb** from state.
- **L_cb in state**: `FQBMState.L_cb` and `reporting_date`; central_bank_step updates L_cb; differential model 12-element vector.
- **Open economy**: **open_economy_view(A_dom, A_ext, L_dom, L_ext, E)**.
- **Part VII**: Leverage ratio in dashboard; **run_workbook** exposes shadow metrics.
- **Part VIII**: **run_workbook(ccp_params=CCPParams(...))** returns result["ccp"].
- **Part IX**: **run_workbook(cbdc_params=CBDCParams(...))** applies deposit/reserve shift; result["cbdc"].
-
-### Optional work (completed)
-
-1. **Part VII**: **repo_multiplier(initial_collateral, haircut, rounds)** and **margin_spiral_simulation(...)** in `fqbm.sheets.shadow_banking`.
-2. **Part VIII**: **variation_margin_flow(mark_to_market_change)** and **ccp_clearing_simulation(vm_calls_per_period, liquidity_buffer_start)** in `fqbm.sheets.ccp`.
-3. **IPSAS**: **notes_to_financial_statements_structure()**; **statement_of_financial_position_comparative(state_prior, state_current, entity)**; **maturity_risk_disclosure_structure()** in `fqbm.ipsas.presentation`.
+| Area | Gap |
+|------|-----|
+| **Part VIII** | Full clearing balance sheet not modeled (margin/waterfall only). |
+| **IPSAS 2** | No operating/investing/financing classification of cash flows. |
+| **IPSAS 4** | No translation of FC assets/liabilities or FX gain/loss in performance statement. |
+| **IPSAS 41 / 46** | No measurement basis or ECL model; use templates + user data. |
+| **RPG 1** | Full long-term sustainability disclosure not implemented. |
+| **GGS** | Sectoral structure only; boundary and entity list set by jurisdiction. |

 ---

-## References
+## 4. References

- [IPSAS_COMPLIANCE.md](IPSAS_COMPLIANCE.md) — Scope and how to use the IPSAS layer.
- IPSASB (2025). *Handbook of International Public Sector Accounting Pronouncements*. IFAC.
- White paper: Four-Quadrant Balance Sheet Matrix, Parts I–XVI.
+- [IPSAS_COMPLIANCE.md](IPSAS_COMPLIANCE.md) — Scope and use of the IPSAS layer.
+- [RECOMMENDATIONS.md](RECOMMENDATIONS.md) — Further suggestions.
+- [MISSING_COMPONENTS_AND_DOCUMENTATION.md](MISSING_COMPONENTS_AND_DOCUMENTATION.md) — Checklist.
--- a/docs/IPSAS_COMPLIANCE.md
+++ b/docs/IPSAS_COMPLIANCE.md
@@ -39,7 +39,7 @@ IPSAS 1 requires **current** and **non-current** classification for assets and l

 | IPSAS 1-style line item | FQBM variable | Suggested classification | Notes |
 |-------------------------|---------------|---------------------------|--------|
-| Financial assets (at amortised cost / FV) | B (government bonds), L_cb (loans) | Non-current (hold-to-maturity / policy portfolio) or split by maturity | L_cb not in state; can be added. |
+| Financial assets (at amortised cost / FV) | B (government bonds), L_cb (loans) | Non-current (hold-to-maturity / policy portfolio) or split by maturity | L_cb is in state (`FQBMState.L_cb`). |
 | Cash and cash equivalents / Reserves | R | Current | |
 | Currency in circulation | C | Liability (current) | |
 | Liabilities (reserve accounts) | R (bank reserves) | Current | |
@@ -75,7 +75,7 @@ See `fqbm.ipsas.presentation.budget_vs_actual_structure()`.

 - **Presentation**: Financial assets vs liabilities, and (where applicable) current vs non-current — supported by the IPSAS 1-style layout.
 - **Recognition and measurement**: FQBM does not implement measurement bases (amortised cost, FVOCI, FVPL) or impairment (e.g. ECL). **Gap** for full IPSAS 41 compliance.
- **Disclosure**: No maturity breakdown, interest rate sensitivity, or credit risk disclosure. **Gap**; can be extended with user-supplied data.
+- **Disclosure**: Maturity and risk templates in `maturity_risk_disclosure_structure()`; extend with user-supplied data for full interest rate sensitivity and credit risk/ECL disclosure.

 ---

@@ -105,7 +105,11 @@ See `fqbm.ipsas.presentation.budget_vs_actual_structure()`.
 | Financial instrument measurement (IPSAS 41) | **Not supported** | No measurement basis or ECL |
 | FX translation (IPSAS 4) | **Partial** | Exchange rate and pass-through only |
 | Disclosure of GGS (IPSAS 22) | **Partial** | Sectoral structure supported |
-| Reporting period / reporting date | **Not defined** | FQBM is period-agnostic; user must set |
+| Reporting period / reporting date | **Supported** | `FQBMState.reporting_date`; `statement_of_financial_position(..., reporting_date=)` |
+| Comparative period (prior/current) | **Supported** | `statement_of_financial_position_comparative()` |
+| Notes and maturity/risk disclosure | **Structure** | `notes_to_financial_statements_structure()`, `maturity_risk_disclosure_structure()` |
+| Cash flow from balance sheet changes | **Supported** | `cash_flow_from_state_changes()`; FX: `fx_translate()` |
+| Additional IPSAS structures (3, 5, 9, 10, 14, 19, 20, 23, 29/41, 38, 46, 48, cash basis, RPG 2, functional/presentation currency) | **Structure** | Templates in `fqbm.ipsas.presentation`; budget vs actual from state: `budget_actual_from_state()` |

 ---

@@ -123,7 +127,7 @@ For **full IPSAS compliance** at entity level, the reporting entity must:
 - Populate budget information (IPSAS 24) and provide variance analysis.
 - Apply IPSAS 4 for FX and other standards as applicable.

-The FQBM IPSAS layer supports **presentation consistency** and **structural alignment** with IPSAS 1 and IPSAS 24, not end-to-end compliance by itself.
+The FQBM IPSAS layer supports **presentation consistency** and **structural alignment** with IPSAS 1 and IPSAS 24, not end-to-end compliance by itself. For a consolidated list of recommendations (e.g. full CCP balance sheet, FX disclosure, white paper), see [RECOMMENDATIONS.md](RECOMMENDATIONS.md).

 ---

--- a/docs/MISSING_COMPONENTS_AND_DOCUMENTATION.md
+++ b/docs/MISSING_COMPONENTS_AND_DOCUMENTATION.md
@@ -0,0 +1,121 @@
+# Missing Components and Required Documentation
+
+Consolidated list of **missing components** (code/IPSAS/FQBM) and **documentation that is required** or recommended for the FQBM project. Derived from [GAPS_AND_MISSING.md](GAPS_AND_MISSING.md) and [IPSAS_COMPLIANCE.md](IPSAS_COMPLIANCE.md).
+
+---
+
+## 1. Missing components (code / functionality)
+
+### 1.1 IPSAS standards (missing or partial)
+
+| Component | Standard / area | Required for |
+|-----------|------------------|--------------|
+| Accounting policies, prior-period adjustments, error correction | IPSAS 3 | Full IPSAS 3 compliance |
+| Borrowing costs capitalisation / expense | IPSAS 5 | Borrowing cost treatment |
+| Revenue recognition and measurement | IPSAS 9, 47 | Statement of financial performance |
+| Hyperinflation restatement | IPSAS 10 | High-inflation reporting |
+| Events after the reporting date (adjust vs disclose) | IPSAS 14 | Post–reporting-date events |
+| Provisions and contingent liabilities/assets | IPSAS 19 | Provisions note |
+| Related party identification and disclosure | IPSAS 20 | Related party note |
+| Revenue from non-exchange (taxes, transfers) | IPSAS 23 | Government revenue |
+| Financial instrument recognition/measurement (amortised cost, FVOCI, FVPL, ECL) | IPSAS 29, 41 | Full instrument accounting |
+| Disclosure of interests in other entities | IPSAS 38 | Consolidation disclosure |
+| Measurement basis (historical cost, FV, etc.) | IPSAS 46 | Measurement policy |
+| Transfer expenses | IPSAS 48 | Transfer expense classification |
+| Cash-basis financial statement | Cash basis IPSAS | Cash-basis reporters |
+| Financial Statement Discussion and Analysis (narrative) | RPG 2 | Management commentary |
+| Functional currency / presentation currency | General | Multi-currency reporting |
+
+### 1.2 FQBM / matrix (missing or partial)
+
+| Component | Description | Required for |
+|-----------|-------------|---------------|
+| Cross-sector consistency check | Automatic check that four-quadrant matrix totals equal sectoral (CB + bank) sums | Matrix validation |
+| Budget / appropriation model | Internal representation of budget and appropriations (not only template) | IPSAS 24 actual vs budget from FQBM |
+| Historical case narrative / coded outputs | Part XI: structured narrative or coded “case” outputs for 1997, 2008, 2020, 2022 | Case study reporting |
+| Real data pipelines | Automated download of Fed H.4.1, BIS, IMF (e.g. for regressions) | Empirical use without manual data |
+
+### 1.3 White paper / framework (out of scope but listed for completeness)
+
+| Component | Note |
+|-----------|------|
+| Full CCP balance-sheet dynamics | Part VIII: margin flows and default waterfall exist; full clearing balance sheet not modeled. |
+| CBDC in state vector | **Done**: `FQBMState.cbdc_liability`; workbook updates it on CBDC shift; IPSAS presentation shows it. |
+| Repo multiplier in workbook | **Done**: wired into `run_workbook` (optional `shadow_params`); dashboard includes `repo_multiplier`. |
+
+---
+
+## 2. Required or recommended documentation
+
+### 2.1 Documentation that does not exist (required or recommended)
+
+| Document | Purpose | Priority |
+|----------|---------|----------|
+| **White paper (canonical source)** | The full FQBM white paper as a single file (e.g. `docs/WHITE_PAPER.md` or PDF) so the framework is versioned with the code | High – README and framework_summary refer to “the white paper” but it is not in the repo |
+| **User guide / tutorial** | Step-by-step: install, run workbook, run Monte Carlo, interpret stress tables, use scenarios, export Excel, use IPSAS layer | High – README is short; no walkthrough |
+| **API reference** | Documented list of public functions/classes, parameters, and return types (e.g. Sphinx or MkDocs, or a single `API.md`) | Medium – only docstrings in code |
+| **Data dictionary** | Definition of every state variable (B, R, C, Loans, …), sheet inputs/outputs, and regression variables (columns for Model 1–3) | Medium – scattered in docstrings |
+| **Changelog** | `CHANGELOG.md` or release notes for versions (e.g. 0.1.0, 0.2.0) | Low |
+| **Contributing / development** | How to add a sheet, add a scenario, run tests, code style | Low |
+
+### 2.2 Documentation that exists but could be extended
+
+| Document | Status / remaining gap |
+|----------|------------------------|
+| **README.md** | No “Quick start” example with copy-paste code; no table of contents; Streamlit and scenarios could be in a single “Optional features” section. |
+| **docs/framework_summary.md** | One sentence per Part (I–XVI) and module mapping in place. |
+| **docs/IPSAS_COMPLIANCE.md** | Section 3 still says “L_cb not in state” – should say L_cb is in state. Compliance checklist could reference new helpers (comparative, notes, maturity/risk). |
+| **docs/GAPS_AND_MISSING.md** | B.3 table says “repo multiplier not modeled” but `repo_multiplier()` exists – could say “repo multiplier implemented; not in dashboard”. |
+| **docs/REFERENCES.md** | Weblinks added (IPSASB, Handbook, BIS, BIS bulk, IMF, Fed H.4.1, Fed Data Download). |
+| **docs/RECOMMENDATIONS.md** | Created: consolidated list of recommendations and suggestions. |
+| **Inline docstrings** | Some modules lack “Part X” references or “Required columns” for regression DataFrames. |
+
+---
+
+## 3. Summary checklist
+
+Implementation status: structures and code listed below have been added (templates for IPSAS; cross-sector check; budget_actual_from_state; get_case_narrative; docs added or updated). Real data pipelines remain optional.
+
+### Missing components (to implement if targeting full IPSAS / completeness)
+
+- [x] IPSAS 3: Accounting policies / prior-period adjustment / error correction — `accounting_policies_structure()`
+- [x] IPSAS 5: Borrowing costs — `borrowing_costs_structure()`
+- [x] IPSAS 9/47: Revenue recognition — `revenue_recognition_structure()`
+- [x] IPSAS 10: Hyperinflation restatement — `hyperinflation_restatement_structure()`
+- [x] IPSAS 14: Events after the reporting date — `events_after_reporting_date_structure()`
+- [x] IPSAS 19: Provisions and contingencies — `provisions_contingencies_structure()`
+- [x] IPSAS 20: Related party disclosure — `related_party_disclosure_structure()`
+- [x] IPSAS 23: Revenue from non-exchange transactions — `revenue_non_exchange_structure()`
+- [x] IPSAS 29/41: Financial instrument measurement and ECL — `financial_instruments_measurement_structure()`
+- [x] IPSAS 38: Disclosure of interests in other entities — `interests_in_other_entities_structure()`
+- [x] IPSAS 46: Measurement basis — `measurement_basis_structure()`
+- [x] IPSAS 48: Transfer expenses — `transfer_expenses_structure()`
+- [x] Cash-basis statement — `cash_basis_statement_structure()`
+- [x] RPG 2: Financial Statement Discussion and Analysis (narrative) — `fs_discussion_and_analysis_structure()`
+- [x] Functional / presentation currency — state fields + `functional_presentation_currency_structure()`
+- [x] Cross-sector matrix consistency check — `cross_sector_consistency_check()` in fqbm.matrix
+- [x] Budget/appropriation model (optional) — `budget_actual_from_state()` in presentation
+- [x] Historical case narrative or coded outputs (Part XI) — `get_case_narrative(name)` in scenarios.presets
+- [x] Real data pipelines (optional) — `fqbm.data.pipelines`: fetch_fed_h41, fetch_bis_series, fetch_imf_series
+
+### Required documentation (to add)
+
+- [x] **White paper** in repo — `docs/WHITE_PAPER.md` (placeholder)
+- [x] **User guide / tutorial** — `docs/USER_GUIDE.md`
+- [x] **API reference** — `docs/API_REFERENCE.md`
+- [x] **Data dictionary** — `docs/DATA_DICTIONARY.md`
+- [x] **Changelog** — `CHANGELOG.md`
+- [x] **Contributing / development** — `CONTRIBUTING.md`
+- [x] Update **IPSAS_COMPLIANCE.md** (L_cb in state; new helpers)
+- [x] Update **GAPS_AND_MISSING.md** (repo_multiplier in dashboard note)
+- [x] Extend **framework_summary.md** (module mapping)
+
+---
+
+## 4. References
+
+- [GAPS_AND_MISSING.md](GAPS_AND_MISSING.md) – Full IPSAS and FQBM gap list
+- [IPSAS_COMPLIANCE.md](IPSAS_COMPLIANCE.md) – Scope and use of the IPSAS layer
+- [RECOMMENDATIONS.md](RECOMMENDATIONS.md) – Additional recommendations and suggestions
+- [framework_summary.md](framework_summary.md) – Core identity and Parts I–XVI
+- [REFERENCES.md](REFERENCES.md) – Chicago Author–Date references and weblinks
--- a/docs/RECOMMENDATIONS.md
+++ b/docs/RECOMMENDATIONS.md
@@ -0,0 +1,82 @@
+# FQBM Recommendations and Suggestions
+
+Consolidated list of **additional recommendations and suggestions** for the FQBM project. See also [GAPS_AND_MISSING.md](GAPS_AND_MISSING.md) and [MISSING_COMPONENTS_AND_DOCUMENTATION.md](MISSING_COMPONENTS_AND_DOCUMENTATION.md).
+
+---
+
+## 1. Code and framework (white paper / FQBM)
+
+| Item | Status / note |
+|------|----------------|
+| **Full CCP balance-sheet dynamics** | Part VIII: margin flows and default waterfall exist; full clearing balance sheet is not modeled. Future work. |
+| **Full IPSAS compliance at entity level** | FQBM provides presentation structures; the reporting entity must maintain recognition/measurement per IPSAS (e.g. 41, 46), prepare cash flow statement (IPSAS 2) and statement of financial performance, populate budget (IPSAS 24) with variance analysis, and apply IPSAS 4 for FX. See [IPSAS_COMPLIANCE.md](IPSAS_COMPLIANCE.md) §9. |
+| **Cash flow by activity (IPSAS 2)** | No classification of cash flows by operating/investing/financing from FQBM; use `cash_flow_from_state_changes()` for inferred amounts and templates for disclosure. |
+| **FX translation and disclosure** | Add explicit translation of foreign-currency assets/liabilities and FX gain/loss in a performance statement; `fx_translate()` and state `S` support analysis. |
+| **Financial instrument measurement and ECL** | No measurement bases (amortised cost, FVOCI, FVPL) or impairment model; use `financial_instruments_measurement_structure()` and `maturity_risk_disclosure_structure()`; extend with user-supplied data. |
+| **Budget data** | Budget columns (original/final) must be supplied by the reporting entity; use `budget_actual_from_state(state, budget)` to fill actuals from state. |
+| **GGS boundary** | General government sector boundary and entity list to be defined by the reporting jurisdiction; FQBM supports sectoral structure. |
+| **RPG 1 (long-term sustainability)** | Partial (e.g. debt sustainability r−g in sovereign module); full RPG 1 disclosure not implemented. |
+
+---
+
+## 2. Documentation
+
+| Item | Priority / note |
+|------|-----------------|
+| **Canonical white paper in repo** | High. Replace [WHITE_PAPER.md](WHITE_PAPER.md) placeholder with full FQBM white paper (Markdown or PDF) versioned with the code. |
+| **Sphinx or MkDocs API docs** | Medium (optional). [API_REFERENCE.md](API_REFERENCE.md) exists; automated API docs could be added via Sphinx or MkDocs. |
+| **README** | Quick start and table of contents in place; Optional features in a single section. |
+| **framework_summary** | One sentence per Part (I–XVI) and module mapping in place; can be expanded. |
+| **REFERENCES weblinks** | IPSASB, IPSASB Handbook, BIS, BIS bulk, IMF, IMF Data, Fed H.4.1, Fed Data Download linked in [REFERENCES.md](REFERENCES.md). |
+| **Inline docstrings** | Add “Part X” references and “Required columns” for regression DataFrames where missing. |
+
+---
+
+## 3. Contributing and process
+
+| Item | Location |
+|------|----------|
+| Keep PRs focused; prefer smaller, reviewable changes | [CONTRIBUTING.md](../CONTRIBUTING.md) |
+| Ensure tests pass; add coverage where practical | CONTRIBUTING |
+| Update USER_GUIDE, API_REFERENCE, DATA_DICTIONARY when adding public API | CONTRIBUTING |
+| Update IPSAS_COMPLIANCE and GAPS_AND_MISSING when adding IPSAS/matrix features | CONTRIBUTING |
+| Add changelog entry under [Unreleased] in CHANGELOG.md | CONTRIBUTING |
+| When adding a sheet: optionally add Excel export for the new result key | CONTRIBUTING |
+| When adding a scenario: optionally add narrative in `get_case_narrative()` | CONTRIBUTING |
+
+---
+
+## 4. Data and empirical
+
+| Item | Note |
+|------|------|
+| **Real data pipelines** | `fqbm.data.pipelines`: fetch_fed_h41, fetch_bis_series, fetch_imf_series. Can be extended (e.g. more series, caching, retries). See [USER_GUIDE.md](USER_GUIDE.md) and [DATA_DICTIONARY.md](DATA_DICTIONARY.md). |
+| **IMF API key** | Optional; programmatic IMF fetch benefits from registration and api_key. |
+
+---
+
+## 5. IPSAS and reporting (entity-level)
+
+| Item | Note |
+|------|------|
+| Recognition and measurement per IPSAS (e.g. 41, 46) | Reporting entity responsibility. |
+| Prepare cash flow statement (IPSAS 2) and statement of financial performance | Reporting entity; FQBM provides structure and cash flow from Δstate. |
+| Populate budget (IPSAS 24) and provide variance analysis | Reporting entity; FQBM provides template and budget_actual_from_state. |
+| Apply IPSAS 4 for FX and other standards | Reporting entity. |
+| Disclosure: extend maturity, interest rate sensitivity, credit risk with user-supplied data | Use maturity_risk_disclosure_structure() and related templates. |
+
+---
+
+## 6. White paper
+
+| Item | Note |
+|------|------|
+| Publish full white paper in repo (Markdown or PDF) and link from README and framework_summary | See [WHITE_PAPER.md](WHITE_PAPER.md); link already in README. |
+
+---
+
+## References
+
+- [GAPS_AND_MISSING.md](GAPS_AND_MISSING.md) — Full IPSAS and FQBM gap list
+- [IPSAS_COMPLIANCE.md](IPSAS_COMPLIANCE.md) — Scope and use of the IPSAS layer
+- [MISSING_COMPONENTS_AND_DOCUMENTATION.md](MISSING_COMPONENTS_AND_DOCUMENTATION.md) — Checklist and documentation status
--- a/docs/REFERENCES.md
+++ b/docs/REFERENCES.md
@@ -15,3 +15,14 @@ International Monetary Fund (IMF). 2014. *Government Finance Statistics Manual*.
 McLeay, Michael, Amar Radia, and Ryland Thomas. 2014. "Money Creation in the Modern Economy." *Bank of England Quarterly Bulletin*.

 Obstfeld, Maurice, and Kenneth Rogoff. 1995. *Foundations of International Macroeconomics*.
+
+## Weblinks (optional)
+
+- IPSASB: https://www.ifac.org/ipsasb — International Public Sector Accounting Standards.
+- IPSASB Handbook: https://www.ifac.org/ipsasb/standards — Handbook of International Public Sector Accounting Pronouncements.
+- BIS: https://www.bis.org — Statistics and manuals.
+- BIS Statistics (bulk download): https://www.bis.org/statistics/full_data_sets.htm — Credit gaps, debt service, CB assets, etc.
+- IMF: https://www.imf.org — Data and Government Finance Statistics.
+- IMF Data: https://www.imf.org/en/Data — Data portal and API.
+- Fed H.4.1: https://www.federalreserve.gov/releases/h41/ — Factors Affecting Reserve Balances.
+- Fed Data Download (H.41): https://www.federalreserve.gov/datadownload/Choose.aspx?rel=H41 — CSV download.
--- a/docs/USER_GUIDE.md
+++ b/docs/USER_GUIDE.md
@@ -0,0 +1,161 @@
+# FQBM User Guide and Tutorial
+
+This guide walks you through installing, running, and interpreting the Four-Quadrant Balance Sheet Matrix (FQBM) framework.
+
+---
+
+## 1. Install
+
+```bash
+cd FOUR-QUADRANT_BALANCE_SHEET_MATRIX
+python3 -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e .
+```
+
+Optional: `pip install pytest` for tests; `pip install streamlit` for the Streamlit dashboard.
+
+---
+
+## 2. Quick start: run the workbook
+
+The workbook runs all eight sheets (central bank, commercial bank, capital stress, FX parity, sovereign debt, commodity, Monte Carlo, dashboard) in one go:
+
+```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 from the command line:
+
+```bash
+python -m fqbm.workbook.runner
+```
+
+This produces a result dictionary (and optionally an Excel file) with keys such as `state`, `stress_tables`, `fx_parity`, `sovereign`, `commodity`, `monte_carlo`, `dashboard`, and `ipsas` (if requested).
+
+---
+
+## 3. Using scenarios (Part XI)
+
+Use built-in historical scenarios instead of building state by hand:
+
+```python
+from fqbm.workbook.runner import run_workbook
+
+run_workbook(scenario="asia_1997", mc_runs=100, export_path="asia_1997.xlsx")
+run_workbook(scenario="gfc_2008", mc_runs=100)
+run_workbook(scenario="pandemic_2020", mc_runs=50)
+run_workbook(scenario="rate_shock_2022", mc_runs=50)
+```
+
+List scenarios and get structured narrative:
+
+```python
+from fqbm.scenarios.presets import list_scenarios, get_scenario, get_case_narrative
+
+print(list_scenarios())  # ['asia_1997', 'gfc_2008', 'pandemic_2020', 'rate_shock_2022']
+preset = get_scenario("gfc_2008")
+case = get_case_narrative("gfc_2008")  # narrative, state_summary, key_drivers, suggested_shocks
+```
+
+---
+
+## 4. Interpreting stress tables and Monte Carlo
+
+- **Capital stress** (`result["stress_tables"]`): capital and leverage under different shock assumptions; see Sheet 3.
+- **Monte Carlo** (`result["monte_carlo"]`): distribution of outcomes (e.g. equity, deposits) over many runs; use percentiles for VaR-style analysis.
+- **Dashboard** (`result["dashboard"]`): aggregated view of key ratios and totals.
+
+---
+
+## 5. IPSAS layer and export
+
+Generate IPSAS-style outputs from state:
+
+```python
+from fqbm.state import FQBMState
+from fqbm.ipsas.presentation import (
+    statement_of_financial_position,
+    budget_vs_actual_structure,
+    budget_actual_from_state,
+    cash_flow_from_state_changes,
+    statement_of_financial_position_comparative,
+)
+
+state = FQBMState(B=100, R=50, C=20, Loans=800, Deposits=700, E_cb=30, E_b=100)
+df = statement_of_financial_position(state, entity="central_bank")
+# Comparative: prior vs current
+state_prior = state.copy()
+state_prior.B = 80
+comparative = statement_of_financial_position_comparative(state_prior, state, entity="central_bank")
+# Budget vs actual from state
+budget_df = budget_actual_from_state(state, budget={"Total assets": 900, "Total liabilities": 650})
+# Cash flow from balance sheet changes
+cashflow = cash_flow_from_state_changes(state_prior, state)
+```
+
+Excel export (when `export_path` is set) includes IPSAS-style sheets when available.
+
+---
+
+## 6. Matrix and cross-sector check
+
+```python
+from fqbm.state import FQBMState
+from fqbm.matrix import four_quadrant_matrix, four_quadrant_summary, cross_sector_consistency_check
+
+state = FQBMState(B=100, R=50, C=20, Loans=800, Deposits=700, E_cb=30, E_b=100)
+matrix_df = four_quadrant_matrix(state)
+summary = four_quadrant_summary(state)
+check = cross_sector_consistency_check(state)  # consistent, cb_balance, bank_balance, message
+```
+
+---
+
+## 7. Differential model and stability (Part XIV)
+
+```python
+from fqbm.system.differential_model import solve_trajectory, check_stability, DifferentialParams
+import numpy as np
+
+params = DifferentialParams()
+x0 = [100, 50, 20, 800, 700, 30, 100, 1.0, 0.0, 0.02, 1.0, 0.0]
+t_span = (0, 10)
+sol = solve_trajectory(x0, t_span, params)
+stable = check_stability(params)
+```
+
+---
+
+## 8. Empirical regressions (Part X)
+
+Synthetic data and regression helpers for inflation pass-through, sovereign spread, and capital flow sensitivity:
+
+```python
+from fqbm.empirical.regressions import (
+    run_inflation_pass_through,
+    run_sovereign_spread,
+    run_capital_flow_sensitivity,
+)
+
+df_inf = run_inflation_pass_through(n=100)
+df_spread = run_sovereign_spread(n=100)
+df_cap = run_capital_flow_sensitivity(n=100)
+```
+
+Required columns for each model are documented in the [Data dictionary](DATA_DICTIONARY.md) and in the module docstrings.
+
+---
+
+## 9. Optional features
+
+- **Streamlit dashboard**: `streamlit run scripts/streamlit_dashboard.py`
+- **CBDC / CCP / repo**: workbook accepts `cbdc_params`, `ccp_params`, `shadow_params`. State has `cbdc_liability` after a CBDC shift; IPSAS presentation shows it. Repo multiplier is always in `result["dashboard"]["repo_multiplier"]` (optional `shadow_params` to customize haircut/rounds).
+- **Real data**: `from fqbm.data.pipelines import fetch_fed_h41, fetch_bis_series, fetch_imf_series` for Fed H.4.1, BIS bulk CSV (e.g. credit_gap, total_credit), and IMF (optional api_key). Pipelines can be extended (e.g. more series, caching, retries); see [DATA_DICTIONARY.md](DATA_DICTIONARY.md) and [RECOMMENDATIONS.md](RECOMMENDATIONS.md).
+- **FX parity**: Sheet 4 and `fqbm.sheets.fx_parity` (CIP, UIP, Dornbusch, pass-through).
+
+For more detail on the API, see [API_REFERENCE.md](API_REFERENCE.md) and [DATA_DICTIONARY.md](DATA_DICTIONARY.md). For additional recommendations (full CCP, FX disclosure, white paper), see [RECOMMENDATIONS.md](RECOMMENDATIONS.md).
--- a/docs/WHITE_PAPER.md
+++ b/docs/WHITE_PAPER.md
@@ -0,0 +1,23 @@
+# FQBM White Paper — Placeholder
+
+This file is a **placeholder** for the canonical Four-Quadrant Balance Sheet Matrix (FQBM) white paper. The full theoretical foundation (Parts I–XVI) is referenced in [framework_summary.md](framework_summary.md) and in the codebase docstrings.
+
+---
+
+## Intended content (when published here)
+
+- **Part I**: Accounting foundation (A = L + E), four-quadrant matrix, open-economy identity.
+- **Part II**: Closed-economy monetary dynamics (central bank, commercial bank).
+- **Part III–IV**: Open-economy extension, BoP, parity conditions, capital flows, FX dynamics.
+- **Part V–VI**: Sovereign risk and CDS; commodity shock channel.
+- **Part VII–IX**: Shadow banking and leverage; derivatives clearing and CCP; CBDC and digital reserve architecture.
+- **Part X**: Empirical regression appendix.
+- **Part XI**: Historical case expansion (1997, 2008, 2020, 2022–23).
+- **Part XII–XIV**: Quantitative stress tables; Monte Carlo framework; full system differential model.
+- **Part XV–XVI**: Policy implications; simulation workbook architecture (eight sheets).
+
+---
+
+## Versioning
+
+When the white paper is added to this repository (as Markdown or PDF), it will be versioned with the code and linked from the README and framework_summary. Until then, the framework is implemented and documented in the codebase and in [framework_summary.md](framework_summary.md). For other suggestions (e.g. full CCP balance sheet, FX disclosure), see [RECOMMENDATIONS.md](RECOMMENDATIONS.md).
--- a/docs/framework_summary.md
+++ b/docs/framework_summary.md
@@ -13,25 +13,25 @@ Every financial asset is someone else’s liability (within or across borders).

 All monetary operations must balance across this structure.

-## Parts of the white paper
+## Parts of the white paper (one sentence each)

-| Part | Topic |
-|------|--------|
-| I | Accounting foundation |
-| II | Closed-economy monetary dynamics (CB, commercial bank) |
-| III | Open-economy extension (BoP, parity) |
-| IV | Capital flows and FX dynamics |
-| V | Sovereign risk and CDS |
-| VI | Commodity shock channel |
-| VII | Shadow banking and leverage |
-| VIII | Derivatives clearing and CCP |
-| IX | CBDC and digital reserve architecture |
-| X | Empirical regression appendix |
-| XI | Historical case expansion |
-| XII | Quantitative stress tables |
-| XIII | Monte Carlo simulation framework |
-| XIV | Full system differential model |
-| XV | Policy implications |
-| XVI | Simulation workbook architecture (eight sheets) |
+| Part | Topic | Implementation |
+|------|--------|-----------------|
+| **I** | Accounting foundation: A = L + E, four-quadrant matrix, open-economy identity. | `fqbm.state`, `fqbm.matrix` (four_quadrant_matrix, cross_sector_consistency_check). |
+| **II** | Closed-economy monetary dynamics: central bank and commercial bank balance sheets. | `fqbm.sheets.central_bank`, `fqbm.sheets.commercial_bank`; state B, R, C, Loans, Deposits, E_cb, E_b, L_cb. |
+| **III** | Open-economy extension: BoP, parity conditions. | `open_economy_view()`; state S, K. |
+| **IV** | Capital flows and FX dynamics: CIP, UIP, Dornbusch, pass-through. | `fqbm.sheets.fx_parity`; Part X regressions (capital flow sensitivity). |
+| **V** | Sovereign risk and CDS: spread, debt sustainability. | `fqbm.sheets.sovereign_debt`; run_sovereign_spread. |
+| **VI** | Commodity shock channel: inflation composite, oil/commodity. | `fqbm.sheets.commodity`; state O. |
+| **VII** | Shadow banking and leverage: repo multiplier, margin spiral. | `fqbm.sheets.shadow_banking`; run_workbook(shadow_params=...); dashboard repo_multiplier. |
+| **VIII** | Derivatives clearing and CCP: margin flows, default waterfall. | `fqbm.sheets.ccp`; run_workbook(ccp_params=...). Full clearing balance sheet not modeled (see RECOMMENDATIONS.md). |
+| **IX** | CBDC and digital reserve architecture: deposit shift, funding gap. | `fqbm.sheets.cbdc`; FQBMState.cbdc_liability; run_workbook(cbdc_params=...). |
+| **X** | Empirical regression appendix: inflation pass-through, sovereign spread, capital flow. | `fqbm.empirical.regressions`; synthetic generators and run_*; required columns in DATA_DICTIONARY. |
+| **XI** | Historical case expansion: 1997, 2008, 2020, 2022 presets and narrative. | `fqbm.scenarios.presets`; get_case_narrative(name). |
+| **XII** | Quantitative stress tables: liquidity and capital stress. | `fqbm.sheets.capital_stress`; stress_tables. |
+| **XIII** | Monte Carlo simulation framework: shock draws, outcome distribution. | `fqbm.sheets.monte_carlo`; run_n_simulations. |
+| **XIV** | Full system differential model: trajectory and stability. | `fqbm.system.differential_model`; solve_trajectory, check_stability. |
+| **XV** | Policy implications: discussed in white paper; framework supports policy experiments. | Scenarios and parameters. |
+| **XVI** | Simulation workbook architecture: eight sheets, dashboard, export. | `fqbm.workbook.runner`; run_workbook. |

-This codebase implements the simulation workbook (Part XVI), Monte Carlo (XIII), differential model (XIV), and empirical regressions (Part X).
+This codebase implements the simulation workbook (Part XVI), Monte Carlo (XIII), differential model (XIV), empirical regressions (Part X), IPSAS presentation (fqbm.ipsas), scenario presets with get_case_narrative (Part XI), and data pipelines (fqbm.data.pipelines).