save progress

docs/modules/api/README.md

@@ -0,0 +1,48 @@
+# API (OpenAPI Contracts)
+
+**Status:** Implemented
+**Source:** `src/Api/`
+**Owner:** API Contracts Guild
+
+## Purpose
+
+API contains OpenAPI 3.1 specifications for all StellaOps services and governance rules for API consistency. This is a specifications repository, not a code module.
+
+## Components
+
+**OpenAPI Specs:**
+- `StellaOps.Api.OpenApi/` - Per-service OpenAPI 3.1 YAML specifications
+  - `authority/openapi.yaml`
+  - `scanner/openapi.yaml`
+  - `scheduler/openapi.yaml`
+  - `policy/openapi.yaml`
+  - `graph/openapi.yaml`
+  - `export-center/openapi.yaml`
+  - `orchestrator/openapi.yaml`
+
+**Shared Components:**
+- `_shared/schemas/` - Common schema definitions
+- `_shared/parameters/` - Shared parameters (paging, tenant)
+- `_shared/responses/` - Standard response definitions
+
+**Aggregate Spec:**
+- `stella.yaml` - Composed aggregate specification
+
+**Governance:**
+- `StellaOps.Api.Governance/` - API governance rules and standards
+
+## Usage
+
+```bash
+# Compose aggregate spec
+node src/Api/StellaOps.Api.OpenApi/compose.mjs
+
+# Lint OpenAPI specs
+npm run api:lint
+```
+
+## Related Documentation
+
+- Developer Portal: `../devportal/` (consumes these specs)
+- Gateway: `../gateway/` (routes based on these contracts)
+- Platform: `../platform/architecture-overview.md`