# Financial markets: long-rate regime workspace

This folder holds one working question and the tools for tracking it: **where are US long-term interest rates heading from 2026, and how will I know if the regime has changed?**

The work has three parts:

- a **framework**: how to think about the question;
- a **data room**: the numbers, collected and checked automatically;
- a **journal and back-tests**: what I forecast, and whether the method would have worked in the past.

> **One-sentence status (1 Oct 2026).** The 30-year Treasury is at 5.67%, its highest since 2002. The 3-year regime probabilities in the 1 Oct 2026 journal are B (higher real rates) 50%, C (fiscal or inflation) 35%, A (disinflation) 15% by gut, and 55/30/15 from the data. The data room's headline vote reads A1 B2 C0, which is not a call. The 2002 back-test shows the vote is a *lagging* indicator, so hold the probabilities loosely (see [`03-backtests/02-confidence-for-2026.md`](03-backtests/02-confidence-for-2026.md)).

---

## 1. Start here

| If you want to … | Open |
|---|---|
| Understand the folder in 10 minutes | This page, then [`00-overview/02-how-it-was-built.md`](00-overview/02-how-it-was-built.md) |
| Read everything essential in one file (print or share) | [`00-overview/essentials.pdf`](00-overview/essentials.pdf): what was done and what it shows, with a table of contents. Rebuild with `make essentials-pdf` in `dataroom/` |
| Answers to the 2 Oct 2026 questions (UK 2022, Japan YCC, the 4–5.5% range, regimes, drivers by country) | [`00-overview/04-answers-2026-10-02.pdf`](00-overview/04-answers-2026-10-02.pdf) · [`.md`](00-overview/04-answers-2026-10-02.md). Rebuild with `make research-2026-10-02 answers-pdf` |
| See the data downloaded for those answers | `dataroom/research/2026-10-02/data_report.pdf` (wide tables and charts, one section per publisher); `make research-data-pdf` |
| Print every series with its audit trail | `dataroom/report/dataroom-audit.pdf` (list of all tables); `make report-pdf` |
| See series side by side, or what changed since the last commit | `make show KEYS="ust10y tips10y" ARGS="--freq M"` · `make changes` |
| Update the data, write a journal entry or review the view | [`00-overview/01-how-to-update.md`](00-overview/01-how-to-update.md) (step by step) |
| Read the framework | [`02-framework/rates-regime-framework-2026.md`](02-framework/rates-regime-framework-2026.md) · [`.html`](02-framework/rates-regime-framework-2026.html) |
| See today's numbers | `dataroom/report/dataroom.html` (rebuilt on every refresh; not in git) |
| Read the latest forecast | [`dataroom/journal/2026-10-01-onepage.html`](dataroom/journal/2026-10-01-onepage.html) (one page) · [`2026-10-01.html`](dataroom/journal/2026-10-01.html) (full, with appendix) |
| See whether the framework would have worked in 2002 | [`03-backtests/backtest-2002.html`](03-backtests/backtest-2002.html) · [how it was done](03-backtests/01-how-the-backtest-was-done.md) · [what it means for 2026](03-backtests/02-confidence-for-2026.md) |
| Look up a term (5y5y, ACM, TIPS …) | [`00-overview/03-glossary.md`](00-overview/03-glossary.md) |
| See what changed and when | [`CHANGELOG.md`](CHANGELOG.md) |

Every document has a Markdown master (`.md`). The `.html` files are self-contained copies for reading, printing and sharing, styled with the plain-html kit in `../workingtools/plain-html/`.

---

## 2. Tree

```
financialmarkets/
├── README.md                     ← you are here
├── CHANGELOG.md                  ← what changed, by date
├── .gitignore                    ← keeps the venv, raw downloads and rebuilt outputs out of git
│
├── 00-overview/                  ← start here
│   ├── 01-how-to-update.md       ← step-by-step: daily, monthly, quarterly, annual
│   ├── 02-how-it-was-built.md    ← how the framework, data room and journal were made
│   ├── 03-glossary.md            ← terms and abbreviations
│   ├── 04-answers-2026-10-02.md / .pdf ← answers to ten questions; PDF built by `make answers-pdf`
│   ├── essentials-intro.md       ← introduction to the essentials PDF
│   └── essentials.pdf            ← the essential reports in one PDF; built by `make essentials-pdf`
│
├── 01-source-notes/              ← the inputs the framework was synthesised from (read-only)
│   ├── claude_treasury-yields-2002-vs-2026.md
│   ├── gemini_interest_rates_macro_analysis.md
│   ├── openaa_interest-rate-regimes-2002-vs-2026.md
│   └── 10year_30year_US_treasury_yield.png   (CNBC chart, 1 Oct 2026)
│
├── 02-framework/                 ← the thinking
│   └── rates-regime-framework-2026.md / .html
│
├── 03-backtests/                 ← does the method work?
│   ├── 01-how-the-backtest-was-done.md
│   ├── 02-confidence-for-2026.md
│   └── backtest-2002.md / .html  ← generated by `make backtest-2002`; do not edit by hand
│
├── dataroom/                     ← the engine (code + data); see dataroom/README.md
│   ├── catalog/series.yaml       ← the contract: every series, its source and checks
│   ├── catalog/signoff.yaml      ← your sign-offs
│   ├── src/dataroom/             ← fetchers, checks, storage, charts, report
│   ├── journal/                  ← dated forecast entries + forecasts.csv (never edit past entries)
│   ├── backtest/                 ← back-test code, narrative template, CSVs and charts
│   ├── register/                 ← audit register, cross-checks, regime votes (CSV)
│   ├── data/                     ← Parquet store (mostly rebuilt; see .gitignore)
│   ├── research/2026-10-02/      ← fetch.py + analysis.py, downloads, tables and charts behind the answers
│   ├── report/, charts/          ← rebuilt on every refresh (dataroom-audit.pdf by `make report-pdf`)
│   ├── scripts/                  ← refresh.sh, launchd job, journal HTML builder
│   ├── tests/                    ← catalog, parser and anchor tests
│   └── Makefile                  ← every command: `make help`
│
└── .cursor/rules/dataroom.mdc    ← tells an agent how to refresh and what never to touch
```

`dataroom/` keeps its name (no number) because the scheduled job and the Python environment refer to its absolute path. Renaming it means re-running `make setup` and `make schedule-install`.

---

## 3. The three layers in one picture

```
01-source-notes ──► 02-framework ──► dataroom/catalog ──► dataroom (daily refresh) ──► report + regime votes
                       │                                                   │
                       └──────────────► journal (my calls, dated) ◄────────┘
                                             │
                     03-backtests ──► "would this have worked?" ──► revise the framework (new version, never overwrite)
```

---

## 4. Rules that keep this trustworthy

1. **The FRED API key lives only in `dataroom/.env`.** It is git-ignored and never printed.
2. **Past journal entries and `forecasts.csv` rows are never edited.** A revision is a new dated entry.
3. **Sign-off is a person's act.** `make signoff KEYS="..." BY="ml"`. Changing a series' definition voids its sign-off.
4. **Don't edit data files by hand.** Change the catalog or the code, then refresh.
5. **Generated files say so at the top.** Edit their source (named in the header or footer), not the output.
6. **Git is local-only.** There is no remote; see [`00-overview/01-how-to-update.md`](00-overview/01-how-to-update.md#9-commit-to-git) for what is committed.