Set up Core Hub framework planning

.claude/rules/architecture.md

@@ -1,8 +1,18 @@
 ## Architecture
 
-<!-- TODO: Describe the key design decisions and component structure.
-     Key modules, data flows, external integrations, state machines, etc. -->
+Core Hub is contract-first. The stable framework surface is defined by specs, schemas, OpenAPI, event catalogs, manifests, fixtures, and compatibility tests before implementation details harden.
+
+Initial component model:
+
+- Contract/IR layer: documented schemas for hubs, capabilities, manifests, widgets, events, workplans, tasks, progress, messages, decisions, and registry facts.
+- Service layer: Python/FastAPI application with Pydantic v2 DTOs, SQLAlchemy async models, Alembic migrations, asyncpg/Postgres persistence, and httpx integrations.
+- Compatibility layer: Inter-Hub `/api/v2` endpoint preservation where ops-hub, activity-core, and existing consumers depend on it.
+- UI layer: operator console and component surfaces aligned with whynot-design patterns; prefer framework-neutral contracts and Lit/custom-element adapters where useful.
+- Migration layer: data import, row-count checks, fixture replay, dual-run smokes, and production cutover gates.
 
 ## Quick Reference
 
-`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference
+- `INTENT.md` - purpose and lineage
+- `docs/research/2026-06-27-core-hub-lineage-and-platform-reset.md` - research artifact
+- `docs/specs/README.md` - spec map
+- `workplans/` - ADR-001 workplans