core-hub/docs/specs/README.md

# Core Hub Specs

This directory is the specification map for Core Hub. The specs are intentionally ahead of implementation so the framework contract stays stable while the runtime is rebuilt.

## Spec Set

- [Architecture](core-hub-architecture.md) - component model and boundaries
- [Contract and IR](contract-ir.md) - canonical framework contract, schemas, fixtures, and adapter rules
- [API v2 Compatibility](api-v2-compatibility.md) - Inter-Hub compatibility surface to preserve during transition
- [Inter-Hub Legacy Inventory](interhub-legacy-inventory.md) - initial route/data/consumer inventory for migration
- [Contract Governance](contract-governance.md) - how contract changes are reviewed and recorded
- [Data Model](data-model.md) - initial entity model and migration posture
- [Event and Registry Model](event-and-registry-model.md) - event catalogs, manifests, widgets, and capability registries
- [Auth, Access, and Custody](auth-access-and-custody.md) - API auth semantics and secret routing rules
- [Workplan Coordination](workplan-coordination.md) - file-first workplans, tasks, progress, messages, decisions
- [UI and Operator Console](ui-operator-console.md) - whynot-design aligned UI direction
- [whynot UI Adapter](whynot-ui-adapter.md) - design-system consumption and adapter rules
- [Testing, Release, and Migration](testing-release-and-migration.md) - verification, deployment, and cutover gates

## Contract Artifacts

Implementation-neutral artifacts live in `contracts/`:

- `contracts/schemas/`
- `contracts/catalogs/`
- `contracts/fixtures/`
- `contracts/openapi/`

## Contract Rule

The implementation may change. The contract changes only through a workplan and a compatibility note.

Any route, schema, event type, or manifest field used by existing consumers must have one of:

- preserved behavior;
- documented replacement and migration path;
- explicit cancellation decision with affected consumers listed.