Set up Core Hub framework planning

README.md

@@ -1,22 +1,37 @@
 # Core Hub
 
-This is the 3rd Generation Production Interaction Framework for Coulomb / Helixforge
-- It is to superseeds and replace 1st Generation state-hub and 2nd Generation inter-hub with state-hub and others infrastructure.
+Core Hub is the 3rd-generation Production Interaction Framework for Coulomb / Helixforge.
 
+It carries forward the lessons from State Hub and Inter-Hub: workplans and progress need to be durable, domains need typed ways to publish state and evidence, operators need a coherent console, and agents need APIs that are predictable enough to automate against. The rebuild moves that intent onto a lighter production platform.
 
-# repo-seed
+## Generations
 
-A git repository template to bootstrap coulomb projects from.
+- Gen 1: `state-hub` - file-backed workplans, tasks, progress, messages, and read-model synchronization.
+- Gen 2: `inter-hub` - the integrated hub framework idea: manifests, widgets, registries, events, API consumers, and a shared UI, implemented in Haskell/IHP.
+- Gen 3: `core-hub` - the same framework ambition rebuilt contract-first on the natural Coulomb stack.
 
-## Bootstrap a new repo
+## Initial Stack Direction
 
-1. Clone or copy this template into a new repository.
-2. Run `statehub register` from the new repo root (see [docs/statehub-register.md](docs/statehub-register.md)).
-3. Complete the generated bootstrap workplan (`*-0001-statehub-bootstrap.md`).
-4. Sync workplans: `cd ~/state-hub && make fix-consistency REPO=<slug>`.
-5. Validate with [docs/template-validation-checklist.md](docs/template-validation-checklist.md).
+- Python 3.12
+- FastAPI and Pydantic v2
+- SQLAlchemy async, Alembic, asyncpg, Postgres
+- pytest and contract fixtures
+- OpenAPI and JSON Schema for public contracts
+- whynot-design aligned UI components/adapters where operator UI is needed
+- Docker/Kubernetes/ArgoCD on the normal Railiance platform path
 
-## Registry
+## Key Documentation
 
-This repo publishes `capability.infotech.repo-template` — see
-`registry/capabilities/capability.infotech.repo-template.md`.
+- [INTENT.md](INTENT.md) - purpose, lineage, principles, and platform direction
+- [SCOPE.md](SCOPE.md) - repo boundary
+- [Research artifact](docs/research/2026-06-27-core-hub-lineage-and-platform-reset.md) - what we learned from State Hub, Inter-Hub, Haskell/IHP, and whynot-design
+- [Specs index](docs/specs/README.md) - contract and implementation specification map
+- [Workplans](workplans/) - staged implementation plan using ADR-001 workplan files
+
+## Immediate Work
+
+1. Freeze the Core Hub contract and IR.
+2. Build the FastAPI/Postgres foundation.
+3. Preserve critical Inter-Hub `/api/v2` compatibility for current consumers.
+4. Migrate data and cut over production traffic.
+5. Retire the Haskell/IHP build lane only after replacement evidence exists.