docs: add transit create vs rotate guidance (#47)

- Clarifies transit key create behavior (returns 409 when key name already exists at version=1) and documents that rotate is required for subsequent versions.
- Adds comprehensive endpoint error matrices, failure playbooks for 401/403/409 incidents, API versioning policy page, glossary, and ADRs for envelope encryption and transit ciphertext contract.
- Introduces executable example shape checks (make docs-check-examples) with CI integration to validate JSON payloads used in documentation.
- Updates all API reference pages with status code quick-reference tables and cross-links.
- Enhances example pages (curl/python/javascript/go) with environment bootstrap sections and common mistakes guidance.
- Transit create usecase now returns ErrTransitKeyAlreadyExists (409) when attempting to create duplicate key names, preventing silent failures in automation workflows.

Author: allisson

.github/workflows/ci.yml

@@ -62,6 +62,9 @@ jobs:
             docs/**/*.md
             .github/pull_request_template.md
 
+      - name: Example shape checks
+        run: python3 docs/tools/check_example_shapes.py
+
       - name: Markdown link check (offline)
         uses: lycheeverse/lychee-action@v2
         with:

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help build run test lint clean migrate-up migrate-down docker-build docker-run mocks docs-lint
+.PHONY: help build run test lint clean migrate-up migrate-down docker-build docker-run mocks docs-lint docs-check-examples
 
 APP_NAME := app
 BINARY_DIR := bin
@@ -70,9 +70,14 @@ mocks: ## Regenerate mock implementations
 	@mockery
 	@echo "Mocks regenerated"
 
+docs-check-examples: ## Validate JSON shapes used by docs examples
+	@echo "Running docs example shape checks..."
+	@python3 docs/tools/check_example_shapes.py
+
 docs-lint: ## Run markdown lint and offline link checks
 	@echo "Running markdownlint-cli2..."
 	@docker run --rm -v "$(PWD):/workdir" -w /workdir davidanson/markdownlint-cli2:v0.18.1 README.md "docs/**/*.md" ".github/pull_request_template.md"
+	@$(MAKE) docs-check-examples
 	@echo "Running lychee offline link checks..."
 	@docker run --rm -v "$(PWD):/input" lycheeverse/lychee:latest --offline --include-fragments --no-progress "/input/README.md" "/input/docs/**/*.md" "/input/.github/pull_request_template.md"
 

README.md

@@ -38,7 +38,9 @@ Then follow the Docker setup guide in [docs/getting-started/docker.md](docs/gett
 - ⚙️ **Environment variables**: [docs/configuration/environment-variables.md](docs/configuration/environment-variables.md)
 - 🏗️ **Architecture concepts**: [docs/concepts/architecture.md](docs/concepts/architecture.md)
 - 🔒 **Security model**: [docs/concepts/security-model.md](docs/concepts/security-model.md)
+- 📘 **Glossary**: [docs/concepts/glossary.md](docs/concepts/glossary.md)
 - 🔑 **Key management operations**: [docs/operations/key-management.md](docs/operations/key-management.md)
+- 🚑 **Failure playbooks**: [docs/operations/failure-playbooks.md](docs/operations/failure-playbooks.md)
 - 🏭 **Production deployment**: [docs/operations/production.md](docs/operations/production.md)
 - 🛠️ **Development and testing**: [docs/development/testing.md](docs/development/testing.md)
 - 🤝 **Docs contributing**: [docs/contributing.md](docs/contributing.md)
@@ -51,6 +53,7 @@ Then follow the Docker setup guide in [docs/getting-started/docker.md](docs/gett
 - 📦 **Secrets API**: [docs/api/secrets.md](docs/api/secrets.md)
 - 🚄 **Transit API**: [docs/api/transit.md](docs/api/transit.md)
 - 📜 **Audit logs API**: [docs/api/audit-logs.md](docs/api/audit-logs.md)
+- 🧩 **API versioning policy**: [docs/api/versioning-policy.md](docs/api/versioning-policy.md)
 
 - **Examples**
 - 🧪 **Curl examples**: [docs/examples/curl.md](docs/examples/curl.md)
@@ -63,7 +66,7 @@ All detailed guides include practical use cases and copy/paste-ready examples.
 ## ✨ What You Get
 
 - 🔐 Envelope encryption (`Master Key -> KEK -> DEK -> Secret Data`)
-- 🚄 Transit encryption (`/v1/transit/keys/*`) for encrypt/decrypt as a service (decrypt input uses `<version>:<base64-ciphertext>`; see [Transit API docs](docs/api/transit.md))
+- 🚄 Transit encryption (`/v1/transit/keys/*`) for encrypt/decrypt as a service (decrypt input uses `<version>:<base64-ciphertext>`; see [Transit API docs](docs/api/transit.md), [create vs rotate](docs/api/transit.md#create-vs-rotate), and [error matrix](docs/api/transit.md#endpoint-error-matrix))
 - 👤 Token-based authentication and policy-based authorization
 - 📦 Versioned secrets by path (`/v1/secrets/*path`)
 - 📜 Audit logs with request correlation (`request_id`) and filtering
@@ -75,7 +78,7 @@ All detailed guides include practical use cases and copy/paste-ready examples.
 - Token issuance: `POST /v1/token`
 - Clients: `GET/POST /v1/clients`, `GET/PUT/DELETE /v1/clients/:id`
 - Secrets: `POST/GET/DELETE /v1/secrets/*path`
-- Transit: `POST /v1/transit/keys`, `POST /v1/transit/keys/:name/rotate`, `POST /v1/transit/keys/:name/encrypt`, `POST /v1/transit/keys/:name/decrypt`, `DELETE /v1/transit/keys/:id`
+- Transit: `POST /v1/transit/keys`, `POST /v1/transit/keys/:name/rotate`, `POST /v1/transit/keys/:name/encrypt`, `POST /v1/transit/keys/:name/decrypt`, `DELETE /v1/transit/keys/:id` ([create vs rotate](docs/api/transit.md#create-vs-rotate), [error matrix](docs/api/transit.md#endpoint-error-matrix))
 - Audit logs: `GET /v1/audit-logs`
 
 ## 📄 License

docs/CHANGELOG.md

@@ -29,6 +29,19 @@
 - Added transit decrypt input contract examples (valid/invalid) and representative `422` payloads
 - Added OpenAPI decrypt request examples and explicit `401`/`403`/`404` responses
 - Added 422 troubleshooting matrix and transit round-trip verification/decode notes in examples
+- Clarified transit key create behavior: duplicate key names now documented as `409 Conflict` and rotate is required for new versions
+- Added transit create-vs-rotate guidance, idempotency notes, endpoint error matrix, and representative `409` conflict payload examples
+- Added transit automation runbook note for handling create `409` by rotating keys
+- Added API status code quick-reference tables to clients, secrets, transit, and audit docs
+- Added glossary page and cross-links from API/reference documentation
+- Added example-page common mistakes sections (curl, python, javascript, go)
+- Added docs contribution policy for breaking vs non-breaking documentation updates
+- Added docs freshness SLA table in docs index
+- Added failure playbooks for 401/403/409 incident triage
+- Added API compatibility/versioning policy page for breaking/non-breaking expectations
+- Added ADRs for envelope encryption model and transit versioned ciphertext contract
+- Added executable example shape checks (`make docs-check-examples`) and CI integration
+- Added environment bootstrap sections to all examples pages
 
 ## See also
 

docs/README.md

@@ -22,12 +22,24 @@ Welcome to the full documentation for Secrets. Pick a path and dive in 🚀
 - ⚙️ [configuration/environment-variables.md](configuration/environment-variables.md)
 - 🏗️ [concepts/architecture.md](concepts/architecture.md)
 - 🔒 [concepts/security-model.md](concepts/security-model.md)
+- 📘 [concepts/glossary.md](concepts/glossary.md)
 - 🔑 [operations/key-management.md](operations/key-management.md)
 - 🏭 [operations/production.md](operations/production.md)
+- 🚑 [operations/failure-playbooks.md](operations/failure-playbooks.md)
 - 🛠️ [development/testing.md](development/testing.md)
 - 🤝 [contributing.md](contributing.md)
 - 🗒️ [CHANGELOG.md](CHANGELOG.md)
 
+## 🧭 Docs Freshness SLA
+
+| Area | Primary owner | Review cadence |
+| --- | --- | --- |
+| Getting started | Maintainers | Monthly |
+| API reference | Maintainers + feature PR author | Every behavior change + monthly |
+| Operations runbooks | Maintainers + on-call | Monthly and after incidents |
+| Examples | Maintainers | Monthly and when API contract changes |
+| Concepts/architecture | Maintainers | Quarterly |
+
 ## 🌐 API Reference
 
 - 🔐 [api/authentication.md](api/authentication.md)
@@ -37,8 +49,14 @@ Welcome to the full documentation for Secrets. Pick a path and dive in 🚀
 - 🚄 [api/transit.md](api/transit.md)
 - 📜 [api/audit-logs.md](api/audit-logs.md)
 - 🧱 [api/response-shapes.md](api/response-shapes.md)
+- 🧩 [api/versioning-policy.md](api/versioning-policy.md)
 - 📄 [openapi.yaml](openapi.yaml)
 
+## 🧠 ADRs
+
+- 🧾 [adr/0001-envelope-encryption-model.md](adr/0001-envelope-encryption-model.md)
+- 🧾 [adr/0002-transit-versioned-ciphertext-contract.md](adr/0002-transit-versioned-ciphertext-contract.md)
+
 ## 🖥️ Supported Platforms
 
 - ✅ Linux and macOS environments for local development and operations

docs/adr/0001-envelope-encryption-model.md

@@ -0,0 +1,30 @@
+# ADR 0001: Envelope Encryption Model
+
+> Status: accepted
+> Date: 2026-02-14
+
+## Context
+
+The system must protect stored secret payloads while supporting key rotation without re-encrypting all historical data at once.
+
+## Decision
+
+Use envelope encryption hierarchy:
+
+`Master Key -> KEK -> DEK -> Secret Data`
+
+- master keys protect KEKs
+- KEKs protect DEKs
+- DEKs encrypt secret payloads
+
+## Consequences
+
+- key rotation can happen incrementally
+- historical versions remain decryptable with prior key material
+- clear separation between root trust, key-wrapping, and data encryption roles
+
+## See also
+
+- [Architecture](../concepts/architecture.md)
+- [Security model](../concepts/security-model.md)
+- [Key management operations](../operations/key-management.md)

docs/adr/0002-transit-versioned-ciphertext-contract.md

@@ -0,0 +1,30 @@
+# ADR 0002: Transit Versioned Ciphertext Contract
+
+> Status: accepted
+> Date: 2026-02-14
+
+## Context
+
+Transit decryption must reliably select the correct transit key version and reject malformed ciphertext early.
+
+## Decision
+
+Adopt transit ciphertext contract:
+
+`<version>:<base64-ciphertext>`
+
+- decrypt requires version prefix and base64 payload
+- malformed input returns validation errors (`422`)
+- callers must pass ciphertext exactly as returned by encrypt
+
+## Consequences
+
+- deterministic key version selection for decrypt
+- stronger input validation with predictable errors
+- simpler client behavior by treating encrypt output as opaque
+
+## See also
+
+- [Transit API](../api/transit.md)
+- [Response shapes](../api/response-shapes.md)
+- [Troubleshooting](../getting-started/troubleshooting.md)

docs/api/audit-logs.md

@@ -18,6 +18,12 @@ Authorization: `read` capability for `/v1/audit-logs`.
 
 - `GET /v1/audit-logs`
 
+## Status Code Quick Reference
+
+| Endpoint | Success | Common error statuses |
+| --- | --- | --- |
+| `GET /v1/audit-logs` | `200` | `401`, `403`, `422` |
+
 Query parameters:
 
 - `offset` (default `0`)
@@ -153,3 +159,5 @@ curl -s "http://localhost:8080/v1/audit-logs?limit=100" \
 - [Clients API](clients.md)
 - [Policies cookbook](policies.md)
 - [Response shapes](response-shapes.md)
+- [API compatibility policy](versioning-policy.md)
+- [Glossary](../concepts/glossary.md)

docs/api/clients.md

@@ -29,6 +29,16 @@ Capability mapping:
 - `PUT /v1/clients/:id` -> `write`
 - `DELETE /v1/clients/:id` -> `delete`
 
+## Status Code Quick Reference
+
+| Endpoint | Success | Common error statuses |
+| --- | --- | --- |
+| `POST /v1/clients` | `201` | `401`, `403`, `409`, `422` |
+| `GET /v1/clients` | `200` | `401`, `403`, `422` |
+| `GET /v1/clients/:id` | `200` | `401`, `403`, `404`, `422` |
+| `PUT /v1/clients/:id` | `200` | `401`, `403`, `404`, `409`, `422` |
+| `DELETE /v1/clients/:id` | `204` | `401`, `403`, `404`, `422` |
+
 ## Create Client
 
 ```bash
@@ -138,3 +148,5 @@ Expected result: create returns `201 Created` with one-time `secret`; list retur
 - [Policies cookbook](policies.md)
 - [Audit logs API](audit-logs.md)
 - [Response shapes](response-shapes.md)
+- [API compatibility policy](versioning-policy.md)
+- [Glossary](../concepts/glossary.md)

docs/api/response-shapes.md

@@ -109,9 +109,20 @@ Common error categories:
 - `not_found`
 - `conflict`
 
+Representative conflict payload (for example duplicate transit key create):
+
+```json
+{
+  "error": "conflict",
+  "message": "transit key already exists"
+}
+```
+
 ## See also
 
 - [Authentication API](authentication.md)
 - [Clients API](clients.md)
 - [Secrets API](secrets.md)
 - [Transit API](transit.md)
+- [API compatibility policy](versioning-policy.md)
+- [Glossary](../concepts/glossary.md)