docs: clarify SCRAPI v09 API-review responses and compatibility boundaries

docs/scitt.md

@@ -25,3 +25,44 @@ scitt-ccf-ledger returns COSE Receipts, either standalone or embedded in Transpa
 ## API
 
 scitt-ccf-ledger implements the [SCITT Reference API (SCRAPI) Draft 09](https://datatracker.ietf.org/doc/draft-ietf-scitt-scrapi/09/).
+
+### API review clarifications (SCRAPI draft 09)
+
+The SCRAPI draft-09 alignment is enabled when clients use `api-version=2026-03-26`.
+Without this api-version (or with unknown versions), legacy behavior is preserved for backward compatibility.
+
+#### Key discovery
+
+- Standard SCRAPI draft-09 endpoints:
+  - `GET /.well-known/scitt-keys`
+  - `GET /.well-known/scitt-keys/{kid_value}`
+- Legacy endpoints (`/jwks` and `/.well-known/transparency-configuration`) are still available for existing clients.
+
+#### Registration and polling
+
+- For `api-version=2026-03-26`:
+  - `POST /entries` async flow returns `303 See Other` with `Location: /entries/{txid}`.
+  - `GET /entries/{txid}` returns `302 Found` while pending, then `200` with the receipt.
+  - `POST /entries?waitForCommit=true` returns `201 Created` with the receipt.
+- For legacy clients:
+  - `POST /entries` returns `202 Accepted` with `Location: /operations/{txid}`.
+  - `GET /operations/{txid}` remains the legacy polling endpoint.
+
+#### Content types
+
+- SCRAPI draft-09 flows use:
+  - `application/scitt-receipt+cose` for receipts.
+  - `application/scitt-statement+cose` for transparent statements.
+- Legacy flows continue to use `application/cose`.
+
+#### Implementation-specific extensions
+
+The following endpoints are kept as implementation-specific extensions and are not part of the SCRAPI draft-09 mandatory surface:
+
+- `/configuration`
+- `/version`
+- `/jwks`
+- `/.well-known/transparency-configuration`
+- `/operations/{txid}`
+- `/entries/{txid}/statement`
+- `/entries/txIds`