up

docs/api/EPIC_17_SDKS_OPENAPI.md

@@ -41,8 +41,9 @@ Net result: partners and internal teams integrate quickly without reverse‑engi
 
 ### 3.1 Source of truth and layout
 
-* Each service owns a **module‑scoped OAS** file: `src/StellaOps.Api.OpenApi/<service>/openapi.yaml`.
-* An aggregate spec `src/StellaOps.Api.OpenApi/stella.yaml` is produced by build tooling that composes per‑service specs, resolves `$ref`s, and validates cross‑service schemas.
+* Each service owns a **module-scoped OAS** file: `src/StellaOps.Api.OpenApi/<service>/openapi.yaml`.
+  * Authority authentication/token surface now lives at `src/StellaOps.Api.OpenApi/authority/openapi.yaml`, covering `/token`, `/introspect`, `/revoke`, and `/jwks` flows with examples and scope catalog metadata.
+* An aggregate spec `src/StellaOps.Api.OpenApi/stella.yaml` is produced by build tooling that composes per-service specs, resolves `$ref`s, and validates cross-service schemas.
 * JSON Schema dialect: 2020‑12 (OpenAPI 3.1). No vendor‑specific features for core models.
 * Every response and error has at least one **validated example**.
 

docs/api/policy.md

@@ -10,7 +10,7 @@ This document is the canonical reference for the Policy Engine REST surface desc
 ## 1 · Authentication & Headers
 
 - **Auth:** Bearer tokens (`Authorization: Bearer <token>`) with the following scopes as applicable:
-  - `policy:read`, `policy:write`, `policy:submit`, `policy:approve`, `policy:run`, `policy:activate`, `policy:archive`, `policy:simulate`, `policy:runs`
+- `policy:read`, `policy:author`, `policy:review`, `policy:approve`, `policy:operate`, `policy:run`, `policy:activate`, `policy:archive`, `policy:simulate`, `policy:runs`
   - `findings:read` (for effective findings APIs)
   - `effective:write` (service identity only; not exposed to clients)
 - **Service identity:** Authority marks the Policy Engine client with `properties.serviceIdentity: policy-engine`. Tokens missing this marker cannot obtain `effective:write`.
@@ -53,7 +53,7 @@ All errors use HTTP semantics plus a structured payload:
 
 ```
 POST /api/policy/policies
-Scopes: policy:write
+Scopes: policy:author
 ```
 
 **Request**
@@ -106,7 +106,7 @@ Returns full DSL, metadata, provenance, simulation artefact references.
 
 ```
 PUT /api/policy/policies/{policyId}/versions/{version}
-Scopes: policy:write
+Scopes: policy:author
 ```
 
 Body identical to create. Only permitted while `status=draft`.
@@ -119,7 +119,7 @@ Body identical to create. Only permitted while `status=draft`.
 
 ```
 POST /api/policy/policies/{policyId}/versions/{version}:submit
-Scopes: policy:submit
+Scopes: policy:author
 ```
 
 **Request**
@@ -196,7 +196,7 @@ Request includes `reason` and optional `incidentId`.
 
 ```
 POST /api/policy/policies/{policyId}/versions/{version}:compile
-Scopes: policy:write
+Scopes: policy:author
 ```
 
 **Response 200**
@@ -221,7 +221,7 @@ Scopes: policy:write
 
 ```
 POST /api/policy/policies/{policyId}/lint
-Scopes: policy:write
+Scopes: policy:author
 ```
 
 Slim wrapper used by CLI; returns 204 on success or `ERR_POL_001` payload.