Set up Core Hub framework planning

docs/specs/core-hub-architecture.md

@@ -0,0 +1,46 @@
+# Core Hub Architecture Spec
+
+## Goal
+
+Build the production interaction framework as a small set of explicit layers rather than a monolith.
+
+## Layers
+
+1. Contract/IR layer
+   - OpenAPI
+   - JSON Schema
+   - Alembic/SQL schema
+   - event, widget, and capability catalogs
+   - fixtures and compatibility examples
+
+2. Runtime service layer
+   - FastAPI app
+   - Pydantic v2 request/response DTOs
+   - SQLAlchemy async persistence
+   - Alembic migrations
+   - asyncpg/Postgres
+   - httpx clients for integration probes
+
+3. Compatibility layer
+   - Inter-Hub `/api/v2` routes required by current consumers
+   - auth/error compatibility
+   - response-shape fixtures
+   - smoke scripts for ops-hub and activity-core
+
+4. Operator UI layer
+   - dashboard/console surfaces
+   - whynot-design aligned tokens/components
+   - adapter-friendly component model
+
+5. Migration and operations layer
+   - import/export tools
+   - row-count and referential checks
+   - dual-run smokes
+   - release/cutover runbook
+
+## Boundary Decisions
+
+- Core Hub owns the framework contract and primary implementation.
+- Domain hubs own their domain data and domain-specific runtime logic.
+- Credential systems keep owning secrets; Core Hub records non-secret evidence and routing metadata only.
+- State Hub remains active until Core Hub has a proven compatibility and migration path.