docs(m154): privilege boundaries and the free-trial removal

[indykish]

Companion docs branch for agentsfleet M154_002 (feat/m154-privilege-boundaries). One new changelog <Update>; no existing entry is rewritten.

What the entry covers

Breaking

• GET /v1/tenants/me/billing no longer returns the free_trial object (active, ends_at_ms). Every other field, path, and status code is unchanged.

Security

• vault.secrets and billing.tenant_wallet move off api_runtime onto vault_runtime / billing_runtime / metering_runtime. Membership is WITH INHERIT FALSE, SET TRUE, so privileges stay dormant until a statement names one — an unelevated read is refused by PostgreSQL, not by application code.
• Elevation is transaction-scoped via SET LOCAL ROLE. Registered codes: UZ-INTERNAL-004 (elevation refused), UZ-INTERNAL-005 (elevated connection refused at pool release).
• Account erasure no longer strands memory.memory_entries rows for a fleet created mid-purge.

Billing

• The free trial is removed; the starter grant is the free allowance. Worth knowing for anyone reading the old entry: the trial never ended on its own, because the column that would have ended it was never written outside a test fixture. Every account read as permanently mid-trial, so stage billing had never charged anyone. Metered runs are billed from the first slice now.

Notes

• History is append-only per the changelog rules. The Aug 01, 2026 entry describing the per-account trial boundary stays as the archive of what was true then.
• make lint passes (documentation checks + link checks + OpenAPI drift).
• The word "elevation" is kept deliberately despite the marketing-word screen — it is the domain term, matching UZ-INTERNAL-004 elevation refused and the module that implements it.

🤖 Generated with Claude Code

Greptile Summary

This PR adds the Aug 12, 2026 changelog entry covering removal of the billing free-trial response, transaction-scoped privilege elevation, safer account erasure, and first-slice metering.

• Documents free_trial removal from the tenant billing response.
• Describes dedicated database roles and transaction-scoped elevation.
• Records account-erasure and failed-rate-lookup fixes.
• Introduces two error codes that are not yet present in the error-code reference.

Confidence Score: 4/5

The documentation needs the two newly registered elevation error codes added to the error-code reference before merging.

The changelog tells consumers that UZ-INTERNAL-004 and UZ-INTERNAL-005 are emitted, but the reference intended for programmatic error handling documents neither code.

Files Needing Attention: changelog.mdx and api-reference/error-codes.mdx

Important Files Changed

Filename	Overview
changelog.mdx	Adds a detailed breaking/security/billing release entry, but its two newly registered internal error codes are missing from the dedicated reference.

Prompt To Fix All With AI

### Issue 1
changelog.mdx:22
**Elevation error codes lack reference entries**

When clients or operators encounter `UZ-INTERNAL-004` or `UZ-INTERNAL-005`, the error-code reference intended for programmatic interpretation documents neither code, preventing consumers from identifying and correctly handling these newly registered failures.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "docs(m154): record the privilege boundar..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

Context used:

• Knowledge Base — Onboarding: landing page, quickstart, changelog, and memory

[greptile-apps]

Elevation error codes lack reference entries

When clients or operators encounter UZ-INTERNAL-004 or UZ-INTERNAL-005, the error-code reference intended for programmatic interpretation documents neither code, preventing consumers from identifying and correctly handling these newly registered failures.

Prompt To Fix With AI

This is a comment left during a code review.
Path: changelog.mdx
Line: 22

Comment:
**Elevation error codes lack reference entries**

When clients or operators encounter `UZ-INTERNAL-004` or `UZ-INTERNAL-005`, the error-code reference intended for programmatic interpretation documents neither code, preventing consumers from identifying and correctly handling these newly registered failures.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[indykish]

Closing alongside agentsfleet/agentsfleet#598, which this changelog described.

Half of what it documents ships nowhere. The privilege boundary in M154_002 was found unwired — schema/110:38 creates every role NOLOGIN, api_runtime included, and no production code executes SET ROLE api_runtime, so every grant that milestone moved governs an identity no statement ever runs as. That work is parked whole in docs/v2/done/M154_002_*.md with the missing edge identified and proved, and returns as its own design.

The other half — deleting the free trial — is real and is being re-authored against main as M164_001. It fixes a live revenue defect: the wallet's promotional-window column is nullable with no default and has exactly one writer in the repository (a test fixture), and a null reads as an open window, so the gate ahead of the catalogue lookup priced every metered stage at zero for every tenant.

A replacement changelog lands under M164 once that code is final, rather than sitting open against a branch that is closed.