allisson · allisson · Feb 19, 2026 · Feb 19, 2026
diff --git a/README.md b/README.md
@@ -13,7 +13,7 @@ Secrets is inspired by **HashiCorp Vault** ❤️, but it is intentionally **muc
 The default way to run Secrets is the published Docker image:
 
 ```bash
-docker pull allisson/secrets:v0.4.0
+docker pull allisson/secrets:v0.4.1
 ```
 
 Use pinned tags for reproducible setups. `latest` is also available for fast iteration.
@@ -29,13 +29,12 @@ Then follow the Docker setup guide in [docs/getting-started/docker.md](docs/gett
 1. 🐳 **Run with Docker image (recommended)**: [docs/getting-started/docker.md](docs/getting-started/docker.md)
 2. 💻 **Run locally for development**: [docs/getting-started/local-development.md](docs/getting-started/local-development.md)
 
-## 🆕 What's New in v0.4.0
+## 🆕 What's New in v0.4.1
 
-- 🎫 Tokenization API for format-preserving token workflows (`/v1/tokenization/*`)
-- 🧰 New tokenization CLI commands: `create-tokenization-key`, `rotate-tokenization-key`, `clean-expired-tokens`
-- 🗄️ Tokenization persistence migrations for PostgreSQL and MySQL (`000002_add_tokenization`)
-- 📈 Tokenization business-operation metrics added to observability
-- 📘 New release notes: [docs/releases/v0.4.0.md](docs/releases/v0.4.0.md)
+- 🐛 Fixed policy path matching for authorization with mid-path wildcards (for example `/v1/transit/keys/*/rotate`)
+- ✅ Added stronger policy-matching coverage for wildcard edge cases and common role templates
+- 📘 Added bugfix release notes: [docs/releases/v0.4.1.md](docs/releases/v0.4.1.md)
+- 📦 Updated pinned Docker docs/examples to `allisson/secrets:v0.4.1`
 
 ## 📚 Docs Map
 
@@ -46,7 +45,7 @@ Then follow the Docker setup guide in [docs/getting-started/docker.md](docs/gett
 - 🧰 **Troubleshooting**: [docs/getting-started/troubleshooting.md](docs/getting-started/troubleshooting.md)
 - ✅ **Smoke test script**: [docs/getting-started/smoke-test.md](docs/getting-started/smoke-test.md)
 - 🧪 **CLI commands reference**: [docs/cli/commands.md](docs/cli/commands.md)
-- 🚀 **v0.4.0 release notes**: [docs/releases/v0.4.0.md](docs/releases/v0.4.0.md)
+- 🚀 **v0.4.1 release notes**: [docs/releases/v0.4.1.md](docs/releases/v0.4.1.md)
 
 - **By Topic**
 - ⚙️ **Environment variables**: [docs/configuration/environment-variables.md](docs/configuration/environment-variables.md)

diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -1,6 +1,32 @@
 # 🗒️ Documentation Changelog
 
-> Last updated: 2026-02-18
+> Last updated: 2026-02-19
+
+## 2026-02-19 (docs v9 - v0.4.1 bugfix release prep)
+
+- Added release notes page: `docs/releases/v0.4.1.md` and promoted it as current in docs indexes
+- Updated docs metadata source (`docs/metadata.json`) to `current_release: v0.4.1`
+- Updated pinned Docker examples from `allisson/secrets:v0.4.0` to `allisson/secrets:v0.4.1`
+- Documented policy path-matching behavior with mid-path wildcard support in `docs/api/policies.md`
+- Updated troubleshooting and failure playbooks to include exact, trailing wildcard, and mid-path wildcard matching
+- Corrected Clients API policy examples to use `decrypt` for `/v1/secrets/*` reads
+- Added transit rotate smoke-test step for `/v1/transit/keys/*/rotate` wildcard validation
+- Added malformed rotate path-shape smoke check and explicit unsupported wildcard pattern notes
+- Added policy matcher quick-reference table to `docs/api/capability-matrix.md`
+- Linked `v0.4.1` release notes from production and smoke-test operator guides
+- Added route-shape vs policy-shape guidance and cross-links between policies and smoke tests
+- Added copy-safe split-role policy snippets for transit rotate-only and secrets read/write separation
+- Added operator quick checklist to `docs/releases/v0.4.1.md` and policy matcher FAQ in troubleshooting
+- Added pre-deploy policy review checklist to `docs/api/policies.md`
+- Added `v0.4.1` documentation migration map with direct section links for operators
+- Added strict CI mode snippet for policy smoke checks and 403-vs-404 false-positive guidance
+- Added canonical wildcard matcher semantics links in auth, clients, secrets, and transit API docs
+- Converted Clients API related references to clickable links for navigation consistency
+- Added policy triage cross-links in Audit Logs API and refreshed stale page update stamps
+- Added docs metadata guard to require `> Last updated: YYYY-MM-DD` marker on all docs pages
+- Added optional strict metadata freshness check via `DOCS_CHANGED_FILES` for changed docs pages
+- Added Docs QA checklist and style baseline guidance to `docs/contributing.md`
+- Added unified operator runbook hub: `docs/operations/runbook-index.md` and linked it from docs indexes
 
 ## 2026-02-18 (docs v8 - docs QA and operations polish)
 

diff --git a/docs/README.md b/docs/README.md
@@ -1,6 +1,6 @@
 # 📚 Secrets Documentation
 
-> Last updated: 2026-02-18
+> Last updated: 2026-02-19
 
 Metadata source for release/API labels: `docs/metadata.json`
 
@@ -19,6 +19,7 @@ Welcome to the full documentation for Secrets. Pick a path and dive in 🚀
 1. Start with Docker guide: [getting-started/docker.md](getting-started/docker.md)
 2. Validate end-to-end setup: [getting-started/smoke-test.md](getting-started/smoke-test.md)
 3. Apply production hardening checklist: [operations/production.md](operations/production.md)
+4. Use runbook hub for rollout and incidents: [operations/runbook-index.md](operations/runbook-index.md)
 
 ## 📖 Documentation by Topic
 
@@ -31,6 +32,7 @@ Welcome to the full documentation for Secrets. Pick a path and dive in 🚀
 - 🏭 [operations/production.md](operations/production.md)
 - 🚑 [operations/failure-playbooks.md](operations/failure-playbooks.md)
 - 🧪 [operations/policy-smoke-tests.md](operations/policy-smoke-tests.md)
+- 🧭 [operations/runbook-index.md](operations/runbook-index.md)
 - 🛠️ [development/testing.md](development/testing.md)
 - 🤝 [contributing.md](contributing.md)
 - 🗒️ [CHANGELOG.md](CHANGELOG.md)
@@ -61,13 +63,14 @@ Welcome to the full documentation for Secrets. Pick a path and dive in 🚀
 
 OpenAPI scope note:
 
-- `openapi.yaml` is a baseline subset for common API flows in `v0.4.0`
+- `openapi.yaml` is a baseline subset for common API flows in `v0.4.1`
 - Full endpoint behavior is documented in the endpoint pages under `docs/api/`
-- Tokenization endpoints are included in `openapi.yaml` for `v0.4.0`
+- Tokenization endpoints are included in `openapi.yaml` for `v0.4.1`
 
 ## 🚀 Releases
 
-- 📦 [releases/v0.4.0.md](releases/v0.4.0.md)
+- 📦 [releases/v0.4.1.md](releases/v0.4.1.md)
+- 📦 [releases/v0.4.0.md](releases/v0.4.0.md) (historical)
 - 📦 [releases/v0.3.0.md](releases/v0.3.0.md) (historical)
 - 📦 [releases/v0.2.0.md](releases/v0.2.0.md) (historical)
 - 📦 [releases/v0.1.0.md](releases/v0.1.0.md) (historical)

diff --git a/docs/api/audit-logs.md b/docs/api/audit-logs.md
@@ -1,6 +1,6 @@
 # 📜 Audit Logs API
 
-> Last updated: 2026-02-18
+> Last updated: 2026-02-19
 > Applies to: API v1
 
 Audit logs capture capability checks and access attempts for monitoring and compliance.
@@ -174,6 +174,8 @@ curl -s "http://localhost:8080/v1/audit-logs?limit=100" \
 - [Authentication API](authentication.md)
 - [Clients API](clients.md)
 - [Policies cookbook](policies.md)
+- [Route shape vs policy shape](policies.md#route-shape-vs-policy-shape)
+- [Policy review checklist before deploy](policies.md#policy-review-checklist-before-deploy)
 - [Capability matrix](capability-matrix.md)
 - [Response shapes](response-shapes.md)
 - [API compatibility policy](versioning-policy.md)

diff --git a/docs/api/authentication.md b/docs/api/authentication.md
@@ -1,6 +1,6 @@
 # 🔐 Authentication API
 
-> Last updated: 2026-02-18
+> Last updated: 2026-02-19
 > Applies to: API v1
 
 All protected endpoints require `Authorization: Bearer <token>`.
@@ -111,6 +111,8 @@ Representative error payloads (exact messages may vary):
 
 - `Bearer` prefix is case-insensitive (`bearer`, `Bearer`, `BEARER`)
 - Tokens are time-limited and should be renewed before expiration
+- For wildcard path matcher semantics used by authorization, see
+  [Policies cookbook / Path matching behavior](policies.md#path-matching-behavior)
 
 ## See also
 

diff --git a/docs/api/capability-matrix.md b/docs/api/capability-matrix.md
@@ -1,6 +1,6 @@
 # 🗂️ Capability Matrix
 
-> Last updated: 2026-02-18
+> Last updated: 2026-02-19
 > Applies to: API v1
 
 This page is the canonical capability-to-endpoint reference used by API docs and policy templates.
@@ -42,6 +42,17 @@ This page is the canonical capability-to-endpoint reference used by API docs and
 
 ## Policy Authoring Notes
 
+Policy matcher quick reference:
+
+| Pattern type | Example | Matching behavior |
+| --- | --- | --- |
+| Exact | `/v1/audit-logs` | Only that exact path |
+| Full wildcard | `*` | Any request path |
+| Trailing wildcard | `/v1/secrets/*` | Prefix + nested paths |
+| Mid-path wildcard | `/v1/transit/keys/*/rotate` | `*` matches one segment |
+
+For complete matcher semantics and unsupported forms, see [Policies cookbook](policies.md#path-matching-behavior).
+
 - Use path scope as narrowly as possible (service + environment prefixes).
 - Avoid wildcard `*` except temporary break-glass workflows.
 - Keep encrypt and decrypt separated across clients when operationally possible.

diff --git a/docs/api/clients.md b/docs/api/clients.md
@@ -1,6 +1,6 @@
 # 👤 Clients API
 
-> Last updated: 2026-02-18
+> Last updated: 2026-02-19
 > Applies to: API v1
 
 Client APIs manage machine identities and policy documents.
@@ -49,7 +49,7 @@ curl -X POST http://localhost:8080/v1/clients \
     "name": "payments-api",
     "is_active": true,
     "policies": [
-      {"path":"/v1/secrets/*","capabilities":["read"]},
+      {"path":"/v1/secrets/*","capabilities":["decrypt"]},
       {"path":"/v1/transit/keys/payment/encrypt","capabilities":["encrypt"]}
     ]
   }'
@@ -117,7 +117,7 @@ curl -s -X POST http://localhost:8080/v1/clients \
   -d '{
     "name": "quickflow-client",
     "is_active": true,
-    "policies": [{"path":"/v1/secrets/*","capabilities":["read"]}]
+    "policies": [{"path":"/v1/secrets/*","capabilities":["decrypt"]}]
   }'
 
 # 2) List clients
@@ -129,12 +129,13 @@ Expected result: create returns `201 Created` with one-time `secret`; list retur
 
 ## Related
 
-- 📘 Policy cookbook: `docs/api/policies.md`
-- 🧪 Curl examples: `docs/examples/curl.md`
-- 🐍 Python examples: `docs/examples/python.md`
-- 🟨 JavaScript examples: `docs/examples/javascript.md`
-- 🐹 Go examples: `docs/examples/go.md`
-- 🧱 Response shapes: `docs/api/response-shapes.md`
+- 📘 [Policy cookbook](policies.md)
+- 🧭 [Wildcard matcher semantics](policies.md#path-matching-behavior)
+- 🧪 [Curl examples](../examples/curl.md)
+- 🐍 [Python examples](../examples/python.md)
+- 🟨 [JavaScript examples](../examples/javascript.md)
+- 🐹 [Go examples](../examples/go.md)
+- 🧱 [Response shapes](response-shapes.md)
 
 ## Use Cases
 

diff --git a/docs/api/policies.md b/docs/api/policies.md
@@ -1,13 +1,16 @@
 # 📘 Authorization Policy Cookbook
 
-> Last updated: 2026-02-18
+> Last updated: 2026-02-19
 > Applies to: API v1
 
 Ready-to-use policy templates for common service roles.
 
 ## 📑 Table of Contents
 
 - [Policy structure](#policy-structure)
+- [Path matching behavior](#path-matching-behavior)
+- [Route shape vs policy shape](#route-shape-vs-policy-shape)
+- [Policy review checklist before deploy](#policy-review-checklist-before-deploy)
 - [1) Read-only service](#1-read-only-service)
 - [2) CI writer](#2-ci-writer)
 - [3) Transit encrypt-only service](#3-transit-encrypt-only-service)
@@ -16,6 +19,7 @@ Ready-to-use policy templates for common service roles.
 - [6) Break-glass admin (emergency)](#6-break-glass-admin-emergency)
 - [7) Key operator](#7-key-operator)
 - [8) Tokenization operator](#8-tokenization-operator)
+- [Copy-safe split-role snippets](#copy-safe-split-role-snippets)
 - [Policy mismatch example (wrong vs fixed)](#policy-mismatch-example-wrong-vs-fixed)
 - [Common policy mistakes](#common-policy-mistakes)
 - [Best practices](#best-practices)
@@ -31,14 +35,55 @@ Ready-to-use policy templates for common service roles.
 ```json
 [
   {
-    "path": "/v1/secrets/*",
+    "path": "/v1/audit-logs",
     "capabilities": ["read"]
   }
 ]
 ```
 
 Capabilities: `read`, `write`, `delete`, `encrypt`, `decrypt`, `rotate`.
 
+## Path matching behavior
+
+Policies are evaluated with case-sensitive matching rules:
+
+- Exact path: no wildcard means full exact match (`/v1/audit-logs` matches only `/v1/audit-logs`)
+- Full wildcard: `*` matches any request path
+- Trailing wildcard: `prefix/*` matches paths starting with `prefix/` (greedy for deeper paths)
+- Mid-path wildcard: `*` inside a path matches exactly one segment
+
+Examples:
+
+- `/v1/secrets/*` matches `/v1/secrets/app`, `/v1/secrets/app/db`, and `/v1/secrets/app/db/password`
+- `/v1/transit/keys/*/rotate` matches `/v1/transit/keys/payment/rotate`
+- `/v1/transit/keys/*/rotate` does not match `/v1/transit/keys/rotate` (missing segment)
+- `/v1/transit/keys/*/rotate` does not match `/v1/transit/keys/payment/extra/rotate` (extra segment)
+- `/v1/*/keys/*/rotate` matches `/v1/transit/keys/payment/rotate`
+
+Unsupported patterns (not shell globs):
+
+- Partial-segment wildcard like `/v1/transit/keys/prod-*`
+- Suffix/prefix wildcard inside one segment like `*prod` or `prod*`
+- Mixed-segment glob forms like `/v1/**/rotate`
+
+## Route shape vs policy shape
+
+- Route shape is validated by the HTTP router first (`404` on non-existent endpoint patterns).
+- Policy shape is evaluated after route resolution (`403` when capability/path policy denies access).
+- Example: `POST /v1/transit/keys/payment/extra/rotate` is a route-shape mismatch (`404`) before policy checks.
+- Example: `POST /v1/transit/keys/payment/rotate` can still return `403` if caller lacks `rotate` on
+  `/v1/transit/keys/*/rotate`.
+
+Use [Policy smoke tests](../operations/policy-smoke-tests.md) to validate both route shape and policy behavior.
+
+## Policy review checklist before deploy
+
+1. Confirm endpoint capability intent for each path (`read`, `write`, `delete`, `encrypt`, `decrypt`, `rotate`).
+2. Confirm wildcard type is intentional (exact, full `*`, trailing `/*`, or mid-path segment `*`).
+3. Reject unsupported patterns (`prod-*`, `*prod`, `prod*`, `**`) before policy rollout.
+4. Run route-shape and allow/deny smoke checks from [Policy smoke tests](../operations/policy-smoke-tests.md).
+5. Review denied audit events after rollout and verify mismatches are expected.
+
 Endpoint capability intent (quick map, condensed from [Capability matrix](capability-matrix.md)):
 
 | Endpoint family | Typical capability |
@@ -166,7 +211,9 @@ Use for teams responsible only for transit key lifecycle.
 ]
 ```
 
-Risk note: scope key names by environment when possible (for example `/v1/transit/keys/prod-*`).
+Risk note: scope key names by environment with supported matchers. Use explicit key-name paths or
+segment wildcards (for example `/v1/transit/keys/*/rotate`), not partial-segment wildcards like
+`prod-*`.
 
 ## 8) Tokenization operator
 
@@ -203,6 +250,41 @@ Use for services that manage tokenization keys and token lifecycle operations.
 
 Risk note: avoid wildcard tokenization access for application clients that only need tokenize or detokenize.
 
+## Copy-safe split-role snippets
+
+Transit rotate-only operator:
+
+```json
+[
+  {
+    "path": "/v1/transit/keys/*/rotate",
+    "capabilities": ["rotate"]
+  }
+]
+```
+
+Secrets read-only workload (`decrypt` only):
+
+```json
+[
+  {
+    "path": "/v1/secrets/*",
+    "capabilities": ["decrypt"]
+  }
+]
+```
+
+Secrets write-only workload (`encrypt` only):
+
+```json
+[
+  {
+    "path": "/v1/secrets/*",
+    "capabilities": ["encrypt"]
+  }
+]
+```
+
 ## Policy mismatch example (wrong vs fixed)
 
 Wrong policy (insufficient capability for secret reads):

diff --git a/docs/api/response-shapes.md b/docs/api/response-shapes.md
@@ -1,6 +1,6 @@
 # 🧱 API Response Shapes
 
-> Last updated: 2026-02-18
+> Last updated: 2026-02-19
 > Applies to: API v1
 
 Use these representative response schemas as a stable reference across endpoint docs.

diff --git a/docs/api/secrets.md b/docs/api/secrets.md
@@ -1,6 +1,6 @@
 # 📦 Secrets API
 
-> Last updated: 2026-02-18
+> Last updated: 2026-02-19
 > Applies to: API v1
 
 Secrets are versioned by path and encrypted with envelope encryption.
@@ -145,6 +145,10 @@ Expected result: write returns `201 Created`; read returns `200 OK` with base64
 - `GET /v1/secrets/*path` -> `decrypt`
 - `DELETE /v1/secrets/*path` -> `delete`
 
+Wildcard matcher semantics reference:
+
+- [Policies cookbook / Path matching behavior](policies.md#path-matching-behavior)
+
 ## Related Examples
 
 - `docs/examples/curl.md`

diff --git a/docs/api/tokenization.md b/docs/api/tokenization.md
@@ -1,6 +1,6 @@
 # 🎫 Tokenization API
 
-> Last updated: 2026-02-18
+> Last updated: 2026-02-19
 > Applies to: API v1
 
 The Tokenization API provides format-preserving token generation for sensitive values,
@@ -14,7 +14,7 @@ with optional deterministic behavior and token lifecycle management.
 
 OpenAPI coverage note:
 
-- Tokenization endpoint coverage is included in `docs/openapi.yaml` for `v0.4.0`
+- Tokenization endpoint coverage is included in `docs/openapi.yaml` for `v0.4.1`
 - This page remains the most detailed contract reference with examples and operational guidance
 
 All endpoints require `Authorization: Bearer <token>`.