docs: consolidate and restructure documentation for improved navigation

.github/pull_request_template.md

@@ -14,6 +14,6 @@
 
 - [ ] Documentation updated for behavior/contract changes
 - [ ] `Last updated` metadata refreshed in changed docs pages
-- [ ] `docs/CHANGELOG.md` updated for significant docs changes
+- [ ] `CHANGELOG.md` updated for significant docs changes
 - [ ] `make docs-lint` passes locally
 - [ ] Examples/commands were validated or reviewed for accuracy

.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Docs changelog guard (docs-only PRs)
+      - name: Changelog guard (docs-only PRs)
         if: github.event_name == 'pull_request'
         run: |
           set -euo pipefail
@@ -33,10 +33,12 @@ jobs:
           while IFS= read -r file; do
             [ -z "$file" ] && continue
 
-            if [ "$file" = "docs/CHANGELOG.md" ]; then
+            # Check if root CHANGELOG.md was updated
+            if [ "$file" = "CHANGELOG.md" ]; then
               changelog_updated=true
             fi
 
+            # Determine if this PR is docs-only
             case "$file" in
               docs/*|README.md)
                 ;;
@@ -49,14 +51,15 @@ jobs:
           EOF
 
           if [ "$docs_only" = true ] && [ "$changelog_updated" = false ]; then
-            echo "docs-only PRs must update docs/CHANGELOG.md"
+            echo "Documentation-only PRs must update CHANGELOG.md"
             exit 1
           fi
 
       - name: API docs consistency guard (PRs)
         if: github.event_name == 'pull_request'
         run: |
           set -euo pipefail
+          # Requires Bash 4.0+ for ** glob patterns (GitHub Actions uses Bash 5.2.21)
 
           CHANGED_FILES="$(git diff --name-only "${{ github.event.pull_request.base.sha }}" "${{ github.sha }}")"
           if [ -z "$CHANGED_FILES" ]; then
@@ -69,14 +72,28 @@ jobs:
           while IFS= read -r file; do
             [ -z "$file" ] && continue
 
+            # API/runtime implementation changes
             case "$file" in
               internal/*/http/*.go|cmd/app/commands/*.go|migrations/*/*.sql)
                 api_changed=true
                 ;;
             esac
 
+            # Documentation files that should be updated when API changes
+            # Note: docs/api/*.md matches root files, docs/api/**/*.md matches subdirectories
             case "$file" in
-              docs/api/*|docs/openapi.yaml|docs/examples/*|docs/operations/*|docs/getting-started/*|docs/cli/commands.md|docs/releases/*|docs/CHANGELOG.md|docs/README.md|docs/metadata.json|README.md)
+              docs/api/*.md|docs/api/**/*.md|\
+              docs/openapi.yaml|\
+              docs/examples/*.md|\
+              docs/operations/*.md|docs/operations/**/*.md|\
+              docs/getting-started/*.md|\
+              docs/cli-commands.md|\
+              docs/releases/*.md|\
+              docs/configuration.md|\
+              docs/README.md|\
+              docs/metadata.json|\
+              CHANGELOG.md|\
+              README.md)
                 docs_changed=true
                 ;;
             esac
@@ -86,7 +103,7 @@ jobs:
 
           if [ "$api_changed" = true ] && [ "$docs_changed" = false ]; then
             echo "API/runtime changes detected but no related docs updates found"
-            echo "Update docs/api, openapi/examples/runbooks/release notes as needed"
+            echo "Update docs/api/*/, openapi.yaml, examples/, operations/*/, or release notes/changelog as needed"
             exit 1
           fi
 

.markdownlint.json

@@ -1,4 +1,7 @@
 {
   "default": true,
-  "MD013": false
+  "MD013": false,
+  "MD024": {
+    "siblings_only": true
+  }
 }

CHANGELOG.md

@@ -38,7 +38,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Documentation
 - Added `docs/releases/v0.6.0.md` release notes and `docs/releases/v0.6.0-upgrade.md` upgrade guide
-- Added KMS operations guide: `docs/operations/kms-setup.md`
+- Added KMS operations guide: `docs/operations/kms/setup.md`
 - Updated CLI and environment variable docs for KMS configuration and master key rotation workflows
 
 ## [0.5.1] - 2026-02-19
@@ -60,7 +60,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Per-client rate limiting for authenticated endpoints (default: 10 req/sec, burst 20)
 - Configurable CORS support (disabled by default)
-- Comprehensive security hardening documentation (`docs/operations/security-hardening.md`)
+- Comprehensive security hardening documentation (`docs/operations/security/hardening.md`)
 - Rate limiting configuration via `RATE_LIMIT_ENABLED`, `RATE_LIMIT_REQUESTS_PER_SEC`, `RATE_LIMIT_BURST`
 - CORS configuration via `CORS_ENABLED`, `CORS_ALLOW_ORIGINS`
 
@@ -78,7 +78,7 @@ If you rely on the previous default token expiration of 24 hours, explicitly set
 Ensure your client applications handle token refresh before expiration. The shorter default expiration improves security but may require updating client-side token refresh logic if you were relying on the previous 24-hour default.
 
 **Database SSL/TLS:**
-If you are using `sslmode=disable` (PostgreSQL) or `tls=false` (MySQL) in production, this is insecure. Update your `DB_CONNECTION_STRING` to use `sslmode=require` or `sslmode=verify-full` (PostgreSQL) or `tls=true` or `tls=custom` (MySQL). See `docs/operations/security-hardening.md` for guidance.
+If you are using `sslmode=disable` (PostgreSQL) or `tls=false` (MySQL) in production, this is insecure. Update your `DB_CONNECTION_STRING` to use `sslmode=require` or `sslmode=verify-full` (PostgreSQL) or `tls=true` or `tls=custom` (MySQL). See `docs/operations/security/hardening.md` for guidance.
 
 ### Security
 - Added database SSL/TLS configuration warnings in documentation
@@ -87,7 +87,7 @@ If you are using `sslmode=disable` (PostgreSQL) or `tls=false` (MySQL) in produc
 - Added metrics endpoint protection recommendations
 
 ### Documentation
-- Added `docs/operations/security-hardening.md` with comprehensive security guidance
+- Added `docs/operations/security/hardening.md` with comprehensive security guidance
 - Updated `docs/configuration/environment-variables.md` with new variables and security warnings
 - Updated `.env.example` with security warnings for development-only configurations
 - Updated `docs/getting-started/docker.md` and `docs/getting-started/local-development.md` with security warnings
@@ -133,7 +133,7 @@ If you are using `sslmode=disable` (PostgreSQL) or `tls=false` (MySQL) in produc
 - Cryptographic operation metrics (secret operations, transit operations, audit log operations)
 
 ### Documentation
-- Added `docs/operations/monitoring.md` with Prometheus and Grafana quickstart
+- Added `docs/operations/observability/monitoring.md` with Prometheus and Grafana quickstart
 - Added metrics naming contract and endpoint documentation
 - Added production hardening guidance for securing `/metrics` endpoint
 

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.7.0
+docker pull allisson/secrets
 ```
 
 Use pinned tags for reproducible setups. `latest` is available for dev-only fast iteration.
@@ -29,20 +29,18 @@ 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.7.0
+## 🆕 What's New in v0.8.0
 
-- 🛡️ Added IP-based rate limiting for unauthenticated token issuance (`POST /v1/token`)
-- ⚙️ Added token endpoint configuration: `RATE_LIMIT_TOKEN_ENABLED`, `RATE_LIMIT_TOKEN_REQUESTS_PER_SEC`, `RATE_LIMIT_TOKEN_BURST`
-- 🚦 Added token endpoint `429` + `Retry-After` behavior for burst/abuse control
-- 📘 Added release notes: [docs/releases/v0.7.0.md](docs/releases/v0.7.0.md)
-- ⬆️ Added upgrade guide: [docs/releases/v0.7.0-upgrade.md](docs/releases/v0.7.0-upgrade.md)
-- 📦 Updated pinned Docker docs/examples to `allisson/secrets:v0.7.0`
+- 📚 Major documentation consolidation: 77 → 47 files (39% reduction)
+- 🏛️ Established 8 new Architecture Decision Records (ADR 0003-0010)
+- 📂 Restructured API docs with themed organization (auth/, data/, observability/)
+- 📖 Consolidated operations documentation with centralized runbook hub
+- 🔗 Comprehensive cross-reference updates throughout documentation
+- 📘 See [v0.8.0 release notes](docs/releases/RELEASES.md#080---2026-02-20)
 
-Release history quick links:
+Release history:
 
-- Current: [v0.7.0 release notes](docs/releases/v0.7.0.md)
-- Previous: [v0.6.0 release notes](docs/releases/v0.6.0.md)
-- Previous upgrade guide: [v0.6.0 upgrade guide](docs/releases/v0.6.0-upgrade.md)
+- All releases: [Release notes](docs/releases/RELEASES.md)
 
 ## 📚 Docs Map
 
@@ -52,46 +50,41 @@ Release history quick links:
 - 💻 **Getting started (local)**: [docs/getting-started/local-development.md](docs/getting-started/local-development.md)
 - 🧰 **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.7.0 release notes**: [docs/releases/v0.7.0.md](docs/releases/v0.7.0.md)
-- ⬆️ **v0.7.0 upgrade guide**: [docs/releases/v0.7.0-upgrade.md](docs/releases/v0.7.0-upgrade.md)
+- 🧪 **CLI commands reference**: [docs/cli-commands.md](docs/cli-commands.md)
+- 📦 **All release notes**: [docs/releases/RELEASES.md](docs/releases/RELEASES.md)
 - 🔁 **Release compatibility matrix**: [docs/releases/compatibility-matrix.md](docs/releases/compatibility-matrix.md)
 
 - **By Topic**
-  - ⚙️ **Environment variables**: [docs/configuration/environment-variables.md](docs/configuration/environment-variables.md)
+  - ⚙️ **Environment variables**: [docs/configuration.md](docs/configuration.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)
-  - ☁️ **KMS setup guide**: [docs/operations/kms-setup.md](docs/operations/kms-setup.md)
-  - ✅ **KMS migration checklist**: [docs/operations/kms-migration-checklist.md](docs/operations/kms-migration-checklist.md)
-  - 🔐 **Security hardening**: [docs/operations/security-hardening.md](docs/operations/security-hardening.md)
-  - 📊 **Monitoring and metrics**: [docs/operations/monitoring.md](docs/operations/monitoring.md)
-  - 🧯 **Operator drills**: [docs/operations/operator-drills.md](docs/operations/operator-drills.md)
-  - 🚀 **Production rollout golden path**: [docs/operations/production-rollout.md](docs/operations/production-rollout.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 architecture map**: [docs/development/docs-architecture-map.md](docs/development/docs-architecture-map.md)
+  - 📘 **Glossary**: [docs/concepts/architecture.md#glossary](docs/concepts/architecture.md#glossary)
+  - 🔑 **Key management operations**: [docs/operations/kms/key-management.md](docs/operations/kms/key-management.md)
+  - ☁️ **KMS setup guide**: [docs/operations/kms/setup.md](docs/operations/kms/setup.md)
+  - ✅ **KMS migration checklist**: [docs/operations/kms/setup.md#migration-checklist](docs/operations/kms/setup.md#migration-checklist)
+  - 🔐 **Security hardening**: [docs/operations/security/hardening.md](docs/operations/security/hardening.md)
+  - 📊 **Monitoring and metrics**: [docs/operations/observability/monitoring.md](docs/operations/observability/monitoring.md)
+  - 🧯 **Operator drills**: [docs/operations/runbooks/README.md#operator-drills-quarterly](docs/operations/runbooks/README.md#operator-drills-quarterly)
+  - 🚀 **Production rollout golden path**: [docs/operations/deployment/production-rollout.md](docs/operations/deployment/production-rollout.md)
+  - 🚨 **Incident response guide**: [docs/operations/observability/incident-response.md](docs/operations/observability/incident-response.md)
+  - 🏭 **Production deployment**: [docs/operations/deployment/production.md](docs/operations/deployment/production.md)
+  - 🛠️ **Development and testing**: [docs/contributing.md#development-and-testing](docs/contributing.md#development-and-testing)
+  - 🗺️ **Docs architecture map**: [docs/contributing.md#docs-architecture-map](docs/contributing.md#docs-architecture-map)
   - 🤝 **Docs contributing**: [docs/contributing.md](docs/contributing.md)
-  - 🗒️ **Docs changelog**: [docs/CHANGELOG.md](docs/CHANGELOG.md)
 
 Release note location:
 
-- Project release notes are in [CHANGELOG.md](CHANGELOG.md)
-- Documentation process/history notes are in [docs/CHANGELOG.md](docs/CHANGELOG.md)
+- Project release notes (including documentation changes) are in [CHANGELOG.md](CHANGELOG.md)
 
 - **API Reference**
-- 🔐 **Auth API**: [docs/api/authentication.md](docs/api/authentication.md)
-- 👤 **Clients API**: [docs/api/clients.md](docs/api/clients.md)
-- 📘 **Policy cookbook**: [docs/api/policies.md](docs/api/policies.md)
-- 🗂️ **Capability matrix**: [docs/api/capability-matrix.md](docs/api/capability-matrix.md)
-- 🚨 **Error decision matrix**: [docs/api/error-decision-matrix.md](docs/api/error-decision-matrix.md)
-- 📦 **Secrets API**: [docs/api/secrets.md](docs/api/secrets.md)
-- 🚄 **Transit API**: [docs/api/transit.md](docs/api/transit.md)
-- 🎫 **Tokenization API**: [docs/api/tokenization.md](docs/api/tokenization.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)
+  - 🔐 **Auth API**: [docs/api/auth/authentication.md](docs/api/auth/authentication.md)
+  - 👤 **Clients API**: [docs/api/auth/clients.md](docs/api/auth/clients.md)
+  - 📘 **Policy cookbook**: [docs/api/auth/policies.md](docs/api/auth/policies.md)
+  - 📦 **Secrets API**: [docs/api/data/secrets.md](docs/api/data/secrets.md)
+  - 🚄 **Transit API**: [docs/api/data/transit.md](docs/api/data/transit.md)
+  - 🎫 **Tokenization API**: [docs/api/data/tokenization.md](docs/api/data/tokenization.md)
+  - 📜 **Audit logs API**: [docs/api/observability/audit-logs.md](docs/api/observability/audit-logs.md)
+  - 🧩 **API fundamentals**: [docs/api/fundamentals.md](docs/api/fundamentals.md) - Error triage, capabilities, rate limits, versioning
 
 - **Examples**
 - 🧪 **Curl examples**: [docs/examples/curl.md](docs/examples/curl.md)
@@ -105,7 +98,7 @@ All detailed guides include practical use cases and copy/paste-ready examples.
 
 - 🔐 Envelope encryption (`Master Key -> KEK -> DEK -> Secret Data`)
 - 🔑 **KMS Integration** for master key encryption at rest (supports Google Cloud KMS, AWS KMS, Azure Key Vault, HashiCorp Vault, and local secrets for testing)
-- 🚄 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))
+- 🚄 Transit encryption (`/v1/transit/keys/*`) for encrypt/decrypt as a service (decrypt input uses `<version>:<base64-ciphertext>`; see [Transit API docs](docs/api/data/transit.md), [create vs rotate](docs/api/data/transit.md#create-vs-rotate), and [error matrix](docs/api/data/transit.md#endpoint-error-matrix))
 - 🎫 Tokenization API (`/v1/tokenization/*`) for token generation, detokenization, validation, and revocation
 - 👤 Token-based authentication and policy-based authorization
 - 📦 Versioned secrets by path (`/v1/secrets/*path`)
@@ -119,7 +112,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` ([create vs rotate](docs/api/transit.md#create-vs-rotate), [error matrix](docs/api/transit.md#endpoint-error-matrix))
+- 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/data/transit.md#create-vs-rotate), [error matrix](docs/api/data/transit.md#endpoint-error-matrix))
 - Tokenization: `POST /v1/tokenization/keys`, `POST /v1/tokenization/keys/:name/rotate`, `DELETE /v1/tokenization/keys/:id`, `POST /v1/tokenization/keys/:name/tokenize`, `POST /v1/tokenization/detokenize`, `POST /v1/tokenization/validate`, `POST /v1/tokenization/revoke`
 - Audit logs: `GET /v1/audit-logs`
 - Metrics: `GET /metrics` (available when `METRICS_ENABLED=true`)
@@ -132,5 +125,5 @@ MIT. See `LICENSE`.
 
 - [Documentation index](docs/README.md)
 - [Docker getting started](docs/getting-started/docker.md)
-- [API authentication](docs/api/authentication.md)
-- [Production operations](docs/operations/production.md)
+- [API authentication](docs/api/auth/authentication.md)
+- [Production operations](docs/operations/deployment/production.md)

cmd/app/main.go

@@ -15,7 +15,7 @@ func main() {
 	cmd := &cli.Command{
 		Name:    "app",
 		Usage:   "Go project template application",
-		Version: "1.0.0",
+		Version: "0.8.0",
 		Commands: []*cli.Command{
 			{
 				Name:  "server",