docs: prepare v0.1.0 release documentation (#50)

allisson · web-flow · commit 848343e22dd9 · 2026-02-14T14:17:42.000-03:00
Add comprehensive v0.1.0 release preparation including CLI reference,
release notes, and updated getting started guides. This commit finalizes
documentation for the first public release.

Changes:
- Add CLI commands reference (docs/cli/commands.md) with server runtime,
  key management, and client management commands
- Add v0.1.0 release notes (docs/releases/v0.1.0.md) with API surface,
  operational notes, and known limitations
- Update Docker guide with pinned v0.1.0 image tag and first-client
  bootstrap flow using create-client command
- Update local development guide with create-client bootstrap flow
- Clarify OpenAPI coverage scope in versioning policy and docs index
- Update root README and docs index with CLI reference and release notes links
- Add create-client prerequisite note to curl examples
- Update CHANGELOG with v0.1.0 release prep activities
diff --git a/README.md b/README.md
@@ -13,9 +13,11 @@ 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:latest
+docker pull allisson/secrets:v0.1.0
 ```
 
+Use pinned tags for reproducible setups. `latest` is also available for fast iteration.
+
 Then follow the Docker setup guide in [docs/getting-started/docker.md](docs/getting-started/docker.md).
 
 ⚠️ After rotating a master key or KEK, restart API server instances so they load the updated key material.
@@ -33,6 +35,8 @@ Then follow the Docker setup guide in [docs/getting-started/docker.md](docs/gett
 - 💻 **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.1.0 release notes**: [docs/releases/v0.1.0.md](docs/releases/v0.1.0.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
@@ -2,6 +2,16 @@
 
 > Last updated: 2026-02-14
 
+## 2026-02-14 (docs v2 - v0.1.0 release prep)
+
+- Added first-client bootstrap flow to Docker and local development guides using `create-client`
+- Added CLI reference page with runtime, key management, and client management commands
+- Linked CLI docs and release notes from root README and docs index
+- Switched Docker release guide examples to pinned image tag `allisson/secrets:v0.1.0`
+- Added explicit OpenAPI coverage note: `docs/openapi.yaml` is baseline subset for common flows
+- Clarified API v1 compatibility expectations relative to pre-1.0 app releases
+- Added release notes page: `docs/releases/v0.1.0.md`
+
 ## 2026-02-14 (docs v1)
 
 - Split large root README into focused docs under `docs/`
diff --git a/docs/README.md b/docs/README.md
@@ -10,6 +10,7 @@ Welcome to the full documentation for Secrets. Pick a path and dive in 🚀
 - 💻 [getting-started/local-development.md](getting-started/local-development.md)
 - 🧰 [getting-started/troubleshooting.md](getting-started/troubleshooting.md)
 - ✅ [getting-started/smoke-test.md](getting-started/smoke-test.md)
+- 🧪 [cli/commands.md](cli/commands.md)
 
 ## 🛣️ First-Time Operator Path
 
@@ -52,6 +53,15 @@ Welcome to the full documentation for Secrets. Pick a path and dive in 🚀
 - 🧩 [api/versioning-policy.md](api/versioning-policy.md)
 - 📄 [openapi.yaml](openapi.yaml)
 
+OpenAPI scope note:
+
+- `openapi.yaml` is a baseline subset for common API flows in `v0.1.0`
+- Full endpoint behavior is documented in the endpoint pages under `docs/api/`
+
+## 🚀 Releases
+
+- 📦 [releases/v0.1.0.md](releases/v0.1.0.md)
+
 ## 🧠 ADRs
 
 - 🧾 [adr/0001-envelope-encryption-model.md](adr/0001-envelope-encryption-model.md)
diff --git a/docs/api/versioning-policy.md b/docs/api/versioning-policy.md
@@ -11,6 +11,18 @@ This page defines compatibility expectations for HTTP API changes.
 - Existing endpoint paths and JSON field names are treated as stable unless explicitly deprecated
 - OpenAPI source of truth: `docs/openapi.yaml`
 
+## OpenAPI Coverage (v0.1.0)
+
+- `docs/openapi.yaml` is a baseline subset focused on high-traffic/common integration flows
+- Endpoint pages in `docs/api/*.md` define full public behavior for covered operations
+- Endpoints may exist in runtime before they are expanded in OpenAPI detail
+
+## App Version vs API Version
+
+- Application release `v0.1.0` is pre-1.0 software and may evolve quickly
+- API v1 path contract (`/v1/*`) remains the compatibility baseline for consumers
+- Breaking API behavior changes require explicit documentation and migration notes
+
 ## Breaking Changes
 
 Treat these as breaking:
diff --git a/docs/cli/commands.md b/docs/cli/commands.md
@@ -0,0 +1,141 @@
+# 🧪 CLI Commands Reference
+
+> Last updated: 2026-02-14
+
+Use the `app` CLI for server runtime, key management, and client lifecycle operations.
+
+## Binary and Docker forms
+
+Local binary:
+
+```bash
+./bin/app <command> [flags]
+```
+
+Docker image (v0.1.0):
+
+```bash
+docker run --rm --env-file .env allisson/secrets:v0.1.0 <command> [flags]
+```
+
+## Core Runtime
+
+### `server`
+
+Starts the HTTP API server.
+
+```bash
+./bin/app server
+```
+
+### `migrate`
+
+Runs database migrations.
+
+```bash
+./bin/app migrate
+```
+
+## Key Management
+
+### `create-master-key`
+
+Generates a new 32-byte master key and prints `MASTER_KEYS` / `ACTIVE_MASTER_KEY_ID` values.
+
+Flags:
+
+- `--id`, `-i`: master key ID
+
+```bash
+./bin/app create-master-key --id default
+```
+
+### `create-kek`
+
+Creates an initial KEK from the active master key.
+
+Flags:
+
+- `--algorithm`, `--alg`: `aes-gcm` (default) or `chacha20-poly1305`
+
+```bash
+./bin/app create-kek --algorithm aes-gcm
+```
+
+### `rotate-kek`
+
+Rotates KEK to a new version.
+
+Flags:
+
+- `--algorithm`, `--alg`: `aes-gcm` (default) or `chacha20-poly1305`
+
+```bash
+./bin/app rotate-kek --algorithm aes-gcm
+```
+
+After master key or KEK rotation, restart API server instances so they load updated key material.
+
+## Client Management
+
+### `create-client`
+
+Creates an API client and returns `client_id` plus one-time `secret`.
+
+Flags:
+
+- `--name`, `-n` (required): client name
+- `--active`, `-a` (default `true`): whether client can authenticate immediately
+- `--policies`, `-p`: JSON array of policy documents (omit to use interactive mode)
+- `--format`, `-f`: `text` (default) or `json`
+
+Non-interactive example:
+
+```bash
+./bin/app create-client \
+  --name bootstrap-admin \
+  --active \
+  --policies '[{"path":"*","capabilities":["read","write","delete","encrypt","decrypt","rotate"]}]' \
+  --format json
+```
+
+Interactive example:
+
+```bash
+./bin/app create-client --name bootstrap-admin
+```
+
+### `update-client`
+
+Updates client name, active state, and policies.
+
+Flags:
+
+- `--id`, `-i` (required): client UUID
+- `--name`, `-n` (required): client name
+- `--active`, `-a` (default `true`): whether client can authenticate
+- `--policies`, `-p`: JSON array of policy documents (omit to use interactive mode)
+- `--format`, `-f`: `text` (default) or `json`
+
+```bash
+./bin/app update-client \
+  --id <client-uuid> \
+  --name payments-api \
+  --active=true \
+  --policies '[{"path":"/v1/secrets/*","capabilities":["read","encrypt"]}]' \
+  --format json
+```
+
+## Output and Safety Notes
+
+- `create-client` secret is shown once and cannot be retrieved later
+- Prefer `--format json` for automation
+- Store client secrets in a secure secret manager
+- Use least-privilege policies per workload and path
+
+## See also
+
+- [Docker getting started](../getting-started/docker.md)
+- [Local development](../getting-started/local-development.md)
+- [Authentication API](../api/authentication.md)
+- [Policies cookbook](../api/policies.md)
diff --git a/docs/examples/curl.md b/docs/examples/curl.md
@@ -6,6 +6,9 @@
 
 End-to-end shell workflow.
 
+Need first credentials? Create an API client with `app create-client` first.
+See [CLI commands reference](../cli/commands.md).
+
 ## Bootstrap
 
 Prerequisites:
diff --git a/docs/getting-started/docker.md b/docs/getting-started/docker.md
@@ -4,12 +4,15 @@
 
 This is the default way to run Secrets.
 
+For release reproducibility, this guide uses the pinned image tag `allisson/secrets:v0.1.0`.
+You can use `allisson/secrets:latest` for fast iteration.
+
 ## ⚡ Quickstart Copy Block
 
 Use this minimal flow when you just want to get a working instance quickly:
 
 ```bash
-docker pull allisson/secrets:latest
+docker pull allisson/secrets:v0.1.0
 docker network create secrets-net || true
 
 docker run -d --name secrets-postgres --network secrets-net \
@@ -18,19 +21,19 @@ docker run -d --name secrets-postgres --network secrets-net \
   -e POSTGRES_DB=mydb \
   postgres:16-alpine
 
-docker run --rm allisson/secrets:latest create-master-key --id default
+docker run --rm allisson/secrets:v0.1.0 create-master-key --id default
 # copy generated MASTER_KEYS and ACTIVE_MASTER_KEY_ID into .env
 
-docker run --rm --network secrets-net --env-file .env allisson/secrets:latest migrate
-docker run --rm --network secrets-net --env-file .env allisson/secrets:latest create-kek --algorithm aes-gcm
+docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.1.0 migrate
+docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.1.0 create-kek --algorithm aes-gcm
 docker run --rm --name secrets-api --network secrets-net --env-file .env -p 8080:8080 \
-  allisson/secrets:latest server
+  allisson/secrets:v0.1.0 server
 ```
 
 ## 1) Pull the image
 
 ```bash
-docker pull allisson/secrets:latest
+docker pull allisson/secrets:v0.1.0
 ```
 
 ## 2) Start PostgreSQL
@@ -48,7 +51,7 @@ docker run -d --name secrets-postgres --network secrets-net \
 ## 3) Generate a master key
 
 ```bash
-docker run --rm allisson/secrets:latest create-master-key --id default
+docker run --rm allisson/secrets:v0.1.0 create-master-key --id default
 ```
 
 Copy the generated values into a local `.env` file.
@@ -77,15 +80,15 @@ EOF
 ## 5) Run migrations and bootstrap KEK
 
 ```bash
-docker run --rm --network secrets-net --env-file .env allisson/secrets:latest migrate
-docker run --rm --network secrets-net --env-file .env allisson/secrets:latest create-kek --algorithm aes-gcm
+docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.1.0 migrate
+docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.1.0 create-kek --algorithm aes-gcm
 ```
 
 ## 6) Start the API server
 
 ```bash
 docker run --rm --name secrets-api --network secrets-net --env-file .env -p 8080:8080 \
-  allisson/secrets:latest server
+  allisson/secrets:v0.1.0 server
 ```
 
 ## 7) Verify
@@ -100,7 +103,21 @@ Expected:
 {"status":"healthy"}
 ```
 
-## 8) First token + first secret
+## 8) Create first client credentials
+
+Use the CLI command to create your first API client and policy set:
+
+```bash
+docker run --rm --network secrets-net --env-file .env allisson/secrets:v0.1.0 create-client \
+  --name bootstrap-admin \
+  --active \
+  --policies '[{"path":"*","capabilities":["read","write","delete","encrypt","decrypt","rotate"]}]' \
+  --format json
+```
+
+Save the returned `client_id` and one-time `secret` securely. The secret is shown only once.
+
+## 9) First token + first secret
 
 ```bash
 curl -X POST http://localhost:8080/v1/token \
@@ -129,3 +146,4 @@ For a full end-to-end check, run `docs/getting-started/smoke-test.sh` (usage in
 - [Smoke test](smoke-test.md)
 - [Troubleshooting](troubleshooting.md)
 - [Environment variables](../configuration/environment-variables.md)
+- [CLI commands reference](../cli/commands.md)
diff --git a/docs/getting-started/local-development.md b/docs/getting-started/local-development.md
@@ -58,7 +58,29 @@ DB_CONNECTION_STRING=postgres://user:password@localhost:5432/mydb?sslmode=disabl
 ./bin/app server
 ```
 
-## 7) Smoke test
+## 7) Create first client credentials
+
+In another terminal, create your first API client and policy set:
+
+```bash
+./bin/app create-client \
+  --name bootstrap-admin \
+  --active \
+  --policies '[{"path":"*","capabilities":["read","write","delete","encrypt","decrypt","rotate"]}]' \
+  --format json
+```
+
+Save the returned `client_id` and one-time `secret` securely.
+
+## 8) Issue token
+
+```bash
+curl -X POST http://localhost:8080/v1/token \
+  -H "Content-Type: application/json" \
+  -d '{"client_id":"<client-id>","client_secret":"<client-secret>"}'
+```
+
+## 9) Smoke test
 
 ```bash
 curl http://localhost:8080/health
@@ -70,3 +92,4 @@ curl http://localhost:8080/health
 - [Smoke test](smoke-test.md)
 - [Troubleshooting](troubleshooting.md)
 - [Testing guide](../development/testing.md)
+- [CLI commands reference](../cli/commands.md)
diff --git a/docs/releases/v0.1.0.md b/docs/releases/v0.1.0.md
