## Architecture

The repo has two layers:

1. Root framework layer
- `INTENT.md`, `docs/`, `research/`, and `registry/` define the generic
  adaptive-pricing vocabulary, lifecycle model, and roadmap.
- `workplans/` is the repo-native source of truth for tracked work (ADR-001).

2. Project implementation layer
- `projects/coulomb-pricing/` contains the first concrete deployment:
  Coulomb Social's Economic Observatory MVP.
- `observatory/` is a small Python package that reads JSON ledgers and
  registries from `data/`, computes economics snapshots, and serves a local UI.

Current Coulomb data flow:
- `data/*.json` ledgers and registries
- `observatory/load.py` parses JSON into dataclasses
- `observatory/ledger.py` builds monthly cost rows
- `observatory/economics.py` computes liquidity, margins, and snapshots
- `observatory/allocation.py`, `usage.py`, `pricing_context.py`,
  `simulator.py`, `credits.py`, and `recommendations.py` derive higher-level
  pricing views
- `observatory/api.py` assembles the dashboard payload
- `observatory/__main__.py` renders the Markdown report
- `observatory/server.py` exposes `/api/dashboard` and serves `ui/`

External integrations are file-based in MVP:
- Bubble export importer
- Stripe export importer
- OpenRouter export importer

The internal model and ledgers are the source of truth. Provider exports feed
the ledgers; they do not replace them.

## Quick Reference

`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference