Normalize repo metadata and sync docs

.claude/rules/architecture.md

@@ -1,7 +1,37 @@
 ## Architecture
 
-<!-- TODO: Describe the key design decisions and component structure.
-     Key modules, data flows, external integrations, state machines, etc. -->
+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
 

.claude/rules/repo-boundary.md

@@ -1,8 +1,12 @@
 ## Repo boundary
 
 This repo owns **adaptive-pricing** only. It does not own:
-
-<!-- TODO: List what belongs in adjacent repos, e.g.:
-- SSH key management → railiance-infra/
-- State hub code     → state-hub/
--->
+- State Hub server code, DB schema, or consistency tooling → `~/state-hub`
+- SSH certificates, login flows, or secret vending → `ops-warden`,
+  `ops-bridge`, OpenBao, Keycloak, and related custody systems
+- Bubble.io, Stripe, or OpenRouter product runtimes themselves; this repo only
+  models or imports their pricing-relevant data
+- Generic whynot-design source assets; this repo only vendors the UI artifacts
+  needed by `projects/coulomb-pricing/ui/`
+- Unrelated Coulomb or marketplace application code outside
+  `projects/coulomb-pricing/`

.claude/rules/repo-identity.md

@@ -2,4 +2,9 @@
 
 **Domain:** financials
 **Repo slug:** adaptive-pricing
+**State Hub topic:** helix-forge
 **Topic ID:** f39fa2a3-c491-414c-a91b-b4c5fcc6139c
+
+Repo classification and hub topic are intentionally separate here:
+- Repo/business domain: `financials`
+- Shared hub topic: `helix-forge` in the hub's `infotech` domain

.claude/rules/session-protocol.md

@@ -13,6 +13,8 @@ Then call the MCP tool for richer cross-domain context when MCP tools are expose
 ```
 get_domain_summary("financials")
 ```
+Repo-specific work tracking still syncs through topic
+`f39fa2a3-c491-414c-a91b-b4c5fcc6139c` (`helix-forge`).
 If MCP tools are unavailable in the current agent session, use the REST API:
 ```bash
 curl -s "http://127.0.0.1:8000/state/summary" | python3 -m json.tool
@@ -44,7 +46,7 @@ For each file with `status: ready`, `active`, or `blocked`, note pending
 
 **Step 4 — Present brief**
 
-1. **Active workstreams** for `financials` — title, task counts, blocking decisions
+1. **Repo-relevant workstreams** under topic `helix-forge` — title, task counts, blocking decisions
 2. **Pending tasks** from `workplans/` + any `[repo:adaptive-pricing]` hub tasks
 3. **Goal guidance** — if `goal_guidance` in summary:
    - `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"*
@@ -73,12 +75,16 @@ curl -s -X POST http://127.0.0.1:8000/progress/ \
 If workplan files were modified, ensure the local copy is up to date first:
 ```bash
 git -C <repo_path> pull --ff-only
-cd ~/state-hub && make fix-consistency REPO=adaptive-pricing
+statehub fix-consistency
 ```
-For repos where implementation runs on a remote machine (e.g. CoulombCore),
-use the combined target which pulls before fixing:
+Fallback when the CLI is unavailable:
 ```bash
-cd ~/state-hub && make fix-consistency-remote REPO=adaptive-pricing
+/home/worsch/state-hub/.venv/bin/python /home/worsch/state-hub/custodian_cli.py \
+  fix-consistency --repo adaptive-pricing --repo-path /home/worsch/adaptive-pricing
+```
+Legacy wrapper:
+```bash
+cd ~/state-hub && make fix-consistency REPO=adaptive-pricing
 ```
 **C-15** (DB task ahead of file) is normal in multi-machine workflows — writeback
 will sync the file to match DB.  **C-16** (repo behind remote) blocks all writes

.claude/rules/stack-and-commands.md

@@ -1,19 +1,28 @@
 ## Stack
 
-<!-- TODO: Fill in language, frameworks, and key dependencies -->
-- **Language:**
-- **Key deps:**
+- **Language:** Markdown-heavy repo with a Python 3 implementation subtree
+- **Key deps:** Python stdlib for the observatory runtime, `pytest` for tests,
+  optional `make` for wrappers, whynot-design vendored UI assets in
+  `projects/coulomb-pricing/ui/vendor/`
 
 ## Dev Commands
 
 ```bash
-# TODO: Fill in the standard commands for this repo
+# Root repo: metadata/workplan sync
+statehub fix-consistency
+/home/worsch/state-hub/.venv/bin/python /home/worsch/state-hub/custodian_cli.py \
+  fix-consistency --repo adaptive-pricing --repo-path /home/worsch/adaptive-pricing
 
-# Install dependencies
+# Project runtime
+cd /home/worsch/adaptive-pricing/projects/coulomb-pricing
+python3 -m observatory --period 2026-06
+python3 -m observatory --period 2026-06 --output reports/economics-2026-06.md
+python3 -m observatory.server
 
-# Run tests
+# Tests
+python3 -m pytest -q
+make test
 
-# Lint / type check
-
-# Build / package (if applicable)
+# UI vendor refresh
+make design
 ```