docs consolidation work

docs/modules/vexhub/README.md

@@ -0,0 +1,59 @@
+# VexHub
+
+**Status:** Implemented
+**Source:** `src/VexHub/`
+**Owner:** VEX Guild
+
+## Purpose
+
+VexHub aggregates, validates, and distributes VEX statements from multiple upstream sources. Provides the canonical VEX distribution layer with deterministic outputs, conflict detection, and offline-friendly operation for internal services and external tools (Trivy/Grype).
+
+## Components
+
+**Services:**
+- `StellaOps.VexHub.WebService` - Minimal API host for distribution endpoints and admin controls
+- `StellaOps.VexHub.Worker` - Background workers for scheduled ingestion and validation (planned)
+
+**Libraries:**
+- Normalization Pipeline - Canonicalizes statements to OpenVEX-compatible structures
+- Validation Pipeline - Schema validation (OpenVEX/CycloneDX/CSAF) and signature checks
+
+## Configuration
+
+Configuration is typically embedded in module settings.
+
+Key settings:
+- PostgreSQL connection (schema: `vexhub`)
+- Ingestion source connectors
+- Validation policies (schema, signature)
+- Export snapshot settings
+- Conflict detection rules
+
+## API Surface
+
+- `GET /api/v1/vex/cve/{cve-id}` - Query VEX statements by CVE
+- `GET /api/v1/vex/package/{purl}` - Query VEX statements by PURL
+- `GET /api/v1/vex/source/{source-id}` - Query statements from specific source
+- `GET /api/v1/vex/export` - Bulk OpenVEX feed (deterministic)
+- `GET /api/v1/vex/index` - VEX index metadata (vex-index.json)
+
+All responses use deterministic ordering: `timestamp DESC`, then `source_id ASC`, then `statement_hash ASC`.
+
+## Dependencies
+
+- PostgreSQL (schema: `vexhub` with tables: `statement`, `provenance`, `conflict`, `export_cursor`)
+- Authority (authentication)
+- IssuerDirectory (issuer trust registry)
+- VexLens (consumes VexHub data for consensus)
+- Excititor (VEX ingestion source)
+
+## Related Documentation
+
+- Architecture: `./architecture.md`
+- VexLens: `../vex-lens/`
+- IssuerDirectory: `../issuer-directory/`
+- Excititor: `../excititor/`
+
+## Current Status
+
+WebService implemented with distribution API. Normalization and validation pipelines in place. Supports conflict detection and deterministic exports. Worker component planned for scheduled ingestion.