docs(wave2): apply codex review round

Apply 9 / modify 0 / skip 0:
- security-hardening ACL gains ~idempotency:* (admin fund keys use
  idempotency:fund:v2:*)
- prometheus-reference: release counter counts every outcome
  (RELEASED or DENY); UNKNOWN normalisation scoped to operation
  counters with the evidence artifact_type exception
- no-budget vs insufficient-budget split fixed where wave-2 protocol
  corrections created contradictions: glossary three-way-decision
  entry and two full-stack quickstart spots now say 404 NOT_FOUND for
  budgetless scopes, 409 BUDGET_EXCEEDED for insufficient existing
  budgets
- retry-storms snippet: import os
- api-key-management: "6 defaults" wording fixed; cross-tenant admin
  advice corrected (admin key required; tenant-key wildcards never
  grant AdminKeyAuth access)
- changelog current-feature summary: BLMOVE (BRPOP historical)
- multi-tenant-saas: live denial is 409, DENY is decide/dry-run

Author: amavashev

changelog.md

@@ -201,7 +201,7 @@ New event-driven observability system spanning all three services.
 - `reservation.commit_overage` on commit with actual > estimated
 
 **Events delivery service (`cycles-server-events`, internal app port 7980):**
-- Async webhook delivery via BRPOP from shared Redis dispatch queue
+- Async webhook delivery via BLMOVE claim/ack from the shared Redis dispatch queue (BRPOP before v0.1.25.18)
 - HMAC-SHA256 payload signing (`X-Cycles-Signature: sha256=<hex>`)
 - Exponential backoff retry, auto-disable after consecutive failures
 - Stale delivery protection (>24h deliveries auto-fail on pickup)

glossary.md

@@ -77,7 +77,7 @@ A constraint applied to execution when budget is running low but not yet exhaust
 
 ### Three-Way Decision
 
-The three possible outcomes of a budget evaluation: **ALLOW** (proceed normally), **ALLOW_WITH_CAPS** (proceed with reduced limits), or **DENY** (reject the request). `decision=DENY` appears only on `/decide` responses and `dry_run` reservations; a live (non-dry-run) reservation that lacks budget is rejected with HTTP `409 BUDGET_EXCEEDED` instead of a `DENY` decision. This model enables graceful degradation instead of hard pass/fail. See [Caps and the Three-Way Decision Model](/protocol/caps-and-the-three-way-decision-model-in-cycles).
+The three possible outcomes of a budget evaluation: **ALLOW** (proceed normally), **ALLOW_WITH_CAPS** (proceed with reduced limits), or **DENY** (reject the request). `decision=DENY` appears only on `/decide` responses and `dry_run` reservations; a live (non-dry-run) reservation against an existing but insufficient budget is rejected with HTTP `409 BUDGET_EXCEEDED`; if no derived scope has a budget at all, the server returns `404 NOT_FOUND` (dry-run and `/decide` return `DENY` with `reason_code=BUDGET_NOT_FOUND`). This model enables graceful degradation instead of hard pass/fail. See [Caps and the Three-Way Decision Model](/protocol/caps-and-the-three-way-decision-model-in-cycles).
 
 ### Overage Policy
 

how-to/api-key-management-in-cycles.md

@@ -106,7 +106,7 @@ curl -X POST http://localhost:7979/v1/admin/api-keys \
 
 > **Defaults:** When no permissions are specified at key creation, the key receives 10 default permissions: the 6 runtime permissions (`reservations:create`, `reservations:commit`, `reservations:release`, `reservations:extend`, `reservations:list`, `balances:read`) plus `budgets:read`, `budgets:write`, `policies:read`, `policies:write`. Webhook, event, and admin permissions must be explicitly requested.
 
-A typical runtime key needs only the 6 defaults. Add `budgets:write` and `budgets:read` if tenants manage their own budgets. Add `webhooks:write` and `webhooks:read` for [webhook subscriptions](/how-to/managing-webhooks#tenant-self-service). Add `admin:read`/`admin:write` (or granular equivalents) only if the key is used for cross-tenant admin operations via the admin server (port 7979).
+A typical runtime key needs only the 6 runtime permissions (`reservations:*` and `balances:read`) — remember that an explicit `permissions` array replaces the 10-value default set, so include `budgets:read`/`budgets:write` if the key also manages budgets. Add `webhooks:write` and `webhooks:read` for [webhook subscriptions](/how-to/managing-webhooks#tenant-self-service). Cross-tenant admin operations require the admin server's `X-Admin-API-Key` — no tenant-key permission (including the legacy `admin:read`/`admin:write` wildcards) grants access to those endpoints.
 
 ::: warning Admin permissions on tenant keys (v0.1.25.7)
 `admin:read` and `admin:write` are accepted on tenant keys for backward compatibility, but **SHOULD NOT be assigned to new tenant keys**. Use the specific permissions (`budgets:write`, `policies:read`, etc.) instead. The admin key (`X-Admin-API-Key`) is server-configured and is not provisioned through the API key creation endpoint.

how-to/multi-tenant-saas-with-cycles.md

@@ -42,7 +42,7 @@ Map your pricing tiers to budget allocations:
 | Pro | $50 (5,000,000,000 microcents) | $5 overdraft | 5 |
 | Enterprise | $500 (50,000,000,000 microcents) | $50 overdraft | Unlimited |
 
-When a customer hits their budget limit, Cycles returns `DENY` on the next reservation. Your application decides what happens: show an upgrade prompt, queue the request, or degrade to a cheaper model. See [Degradation Paths](/how-to/how-to-think-about-degradation-paths-in-cycles-deny-downgrade-disable-or-defer) for patterns.
+When a customer hits their budget limit, the next live reservation fails with `409 BUDGET_EXCEEDED` (a `/v1/decide` or dry-run check returns `DENY`). Your application decides what happens: show an upgrade prompt, queue the request, or degrade to a cheaper model. See [Degradation Paths](/how-to/how-to-think-about-degradation-paths-in-cycles-deny-downgrade-disable-or-defer) for patterns.
 
 ## Customer onboarding workflow
 

how-to/prometheus-metrics-reference.md

@@ -12,7 +12,7 @@ Cycles' Micrometer instrumentation uses dotted source names (`cycles.*`) which P
 ::: info Tenant-tag cardinality flag
 Every counter tagged with `tenant` respects a per-service toggle, `cycles.metrics.tenant-tag.enabled` (env `CYCLES_METRICS_TENANT_TAG_ENABLED`) — but the **defaults differ by service**: `cycles-server` (runtime) defaults to `true`, while `cycles-server-events` defaults to `false`. The admin server's `cycles_admin_*` counters carry no `tenant` tag at all, so the flag doesn't apply there. Deployments with many thousands of tenants can flip the runtime flag to `false` to drop the per-tenant series and keep Prometheus cardinality bounded; deployments that want per-tenant webhook drill-downs must explicitly enable it on the events service. Set the flag consistently across the two services so dashboards can share the same tag schema.
 
-Null or blank tag values are normalised to the sentinel `UNKNOWN`. Missing tags would otherwise collapse series — making it look like traffic moved when the upstream data actually just got sparse.
+For the operation counters below, null or blank tag values are normalised to the sentinel `UNKNOWN` (exception: `cycles.evidence.emit_failed` uses lowercase `unknown` for a null `artifact_type` and does not normalise blanks). Missing tags would otherwise collapse series — making it look like traffic moved when the upstream data actually just got sparse.
 :::
 
 ## Scrape targets
@@ -33,7 +33,7 @@ Introduced in v0.1.25.10. All counters live under the `cycles.*` namespace.
 |---|---|---|---|---|
 | `cycles.reservations.reserve` | `cycles_reservations_reserve_total` | Counter | `tenant`, `decision`, `reason`, `overage_policy` | Every `POST /v1/reservations` outcome. |
 | `cycles.reservations.commit` | `cycles_reservations_commit_total` | Counter | `tenant`, `decision`, `reason`, `overage_policy` | Every `POST /v1/reservations/{id}/commit` outcome. |
-| `cycles.reservations.release` | `cycles_reservations_release_total` | Counter | `tenant`, `actor_type`, `decision`, `reason` | Every successful release. `actor_type` distinguishes tenant-driven releases from v0.1.25.8 admin-on-behalf-of releases. |
+| `cycles.reservations.release` | `cycles_reservations_release_total` | Counter | `tenant`, `actor_type`, `decision`, `reason` | Every release outcome (`decision` is `RELEASED` or `DENY`). `actor_type` distinguishes tenant-driven releases from v0.1.25.8 admin-on-behalf-of releases. |
 | `cycles.reservations.extend` | `cycles_reservations_extend_total` | Counter | `tenant`, `decision`, `reason` | Every `POST /v1/reservations/{id}/extend` outcome. |
 | `cycles.reservations.expired` | `cycles_reservations_expired_total` | Counter | `tenant` | Each reservation the expiry sweep actually marks EXPIRED. Skipped reservations (still in grace, already finalised) do not increment. |
 | `cycles.events` | `cycles_events_total` | Counter | `tenant`, `decision`, `reason`, `overage_policy` | Every `POST /v1/events` outcome. |

how-to/security-hardening.md

@@ -88,7 +88,7 @@ Restrict the Cycles service account to the key patterns the services actually us
 
 ```conf
 # redis.conf
-user cycles on >${REDIS_PASSWORD} ~tenant:* ~budget:* ~budgets:* ~reservation:* ~reserve:* ~idem:* ~apikey:* ~apikeys:* ~policy:* ~policies:* ~audit:* ~event:* ~events:* ~delivery:* ~deliveries:* ~dispatch:* ~webhook:* ~webhooks:* ~evidence:* ~config:* ~replay:* +@all
+user cycles on >${REDIS_PASSWORD} ~tenant:* ~budget:* ~budgets:* ~reservation:* ~reserve:* ~idem:* ~idempotency:* ~apikey:* ~apikeys:* ~policy:* ~policies:* ~audit:* ~event:* ~events:* ~delivery:* ~deliveries:* ~dispatch:* ~webhook:* ~webhooks:* ~evidence:* ~config:* ~replay:* +@all
 user default off
 ```
 

incidents/retry-storms-and-idempotency-failures.md

@@ -244,6 +244,7 @@ This limits total retry spend per document to the workflow budget, regardless of
 Before each retry, use `decide` to check if budget is available without creating a reservation. This avoids creating reservations you'll immediately release:
 
 ```python
+import os
 import uuid
 
 from runcycles import (

quickstart/deploying-the-full-cycles-stack.md

@@ -403,7 +403,7 @@ export CYCLES_API_KEY="cyc_live_..."   # paste the key from the response
 
 ## Step 4: Create a budget
 
-Create a budget ledger for the tenant. Without a budget, all reservations will be denied with `BUDGET_EXCEEDED`:
+Create a budget ledger for the tenant. Without a budget at any derived scope, reservations fail with `404 NOT_FOUND` ("Budget not found for provided scope"):
 
 ```bash
 curl -s -X POST http://localhost:7979/v1/admin/budgets \
@@ -683,9 +683,9 @@ requests.post(f"{CYCLES_URL}/v1/reservations/{reservation_id}/commit", json={
 
 ## Troubleshooting
 
-### "BUDGET_EXCEEDED" on first reservation
+### "NOT_FOUND" (no budget) or "BUDGET_EXCEEDED" on first reservation
 
-No budget exists for the scope. Create a budget ledger via the admin API (Step 4). Every scope in the subject hierarchy needs an allocated budget.
+`404 NOT_FOUND` means no budget exists at any derived scope — create a budget ledger via the admin API (Step 4); at least one scope in the subject hierarchy needs an allocated budget. `409 BUDGET_EXCEEDED` means a budget exists but the estimate exceeds what remains.
 
 ### "UNAUTHORIZED" or 401