Command surface¶

Brama's invocable surface is larger than its command tree, because Brama Desktop, the account routes and the agent routes reach the same subscription operations over HTTP that an operator reaches over argv. This page measures both at one named revision, names the capabilities that replace the verbs which accumulated one per incident, and states the order in which the replacement lands.

What was measured, and with what¶

Revision 76b7b987b33f950db9c6540d8a001b184d93b539 of wisent-ai/brama, crate version 0.2.78, measured on darwin-arm64. The binary states its own revision, so the numbers below are bound to a build and not to prose:

git fetch origin && git rev-parse origin/main
BRAMA_SOURCE_REVISION=$(git rev-parse origin/main) BRAMA_BUILD_PLATFORM=darwin-arm64 \
  cargo build --release --bin brama
target/release/brama version
{"product":"brama","version":"0.2.78","source_revision":"76b7b987b33f950db9c6540d8a001b184d93b539","platform":"darwin-arm64","built_at":"not-recorded"}

BRAMA_BIN=target/release/brama node --test tests/docs/cli-commands.probierz.spec.mjs

That last command is the measurement. It walks brama help from the root to every leaf, reads one invocation per HTTP method per registered path out of the router in src/core/server.rs, and reads the site's own rewrite table in vercel-ingress/vercel.json to decide which of those invocations resolve to a published page. It writes nothing. A number on this page that the command does not print does not belong on this page.

The counts¶

39 leaf invocations in 6 groups. 13 of them are command-tree leaves in 2 command groups carrying 42 options between them; the other 26 are HTTP method invocations over 22 registered paths.

Two families have landed. It was 50 invocations in 7 groups at 070275a036f35130918948b66f4be8b7e26fcf50 and 42 in 6 at 15c27474b3a870e1a399697068e2b96f4e72d8dd. The eleven the subscription pool replaced and the four the plan-usage capability replaced are gone from the router, the command tree and this site: two invocations stand where eleven did, brama subscriptions list no longer parses, and one POST /v1/plan-usage stands where four per-audience refreshes did. /v1/account is down to its last invocation, and every route that carried an audience in its own path is now either a capability or one of the three families still to land.

/v1/admin is the largest group and it is the one that grew per incident: every diagnostic and repair reached for during an outage was added beside the last one rather than in place of it. The command tree is small by comparison, and its duplication shows up in options instead — brama onboard carries 6 --adopt-* options, which is the whole brama adopt command spelled a second time at a second entry point.

The families, and what replaces each¶

A family here is one operation spelled more than once because a different audience asked for it. 15 of the 39 invocations still fall into three unlanded families, and two are done. Each capability is named by Brama's own vocabulary, and each reads a declaration rather than taking an operator's word for the current state.

Subscription inventory (11 → 0, landed). It was brama subscriptions list; GET, POST and DELETE /v1/subscriptions/:agent_id; GET and POST /v1/account/subscriptions; DELETE /v1/account/subscriptions/:subscription_id; GET and POST /v1/admin/subscriptions/:agent_id; DELETE /v1/admin/subscriptions/:agent_id/:subscription_id; GET /v1/admin/subscription-pool. Three audiences, one question: which subscriptions exist and who owns them. The pool capability now answers it once from the vault declaration over GET and POST /v1/subscription-pool and brama subscription list, scoping the answer by the caller's proven identity, which is where ownership already lives (entitlement). All eleven were deleted in the same change: their routes, their handlers, their tests, the desktop calls that reached them and their paragraphs on this site. A signed agent, an account holder and this installation's own console get one answer narrowed by who they are.

Credential repair (8). brama subscription refresh; brama subscription login (one verb and one route since the former manual sign-in became its --by hand and the route's "by": "hand"; held, import, sync and /v1/admin/subscription-pool/grant were removed in 0.4.4x); POST /v1/account/subscription-sign-in/:subscription_id; POST /v1/admin/subscription-sign-in/:agent_id/:subscription_id; POST /v1/admin/subscriptions/:agent_id/:subscription_id/probe; POST /v1/admin/subscription-pool/sign-in; POST /v1/admin/subscription-pool/sign-in/:sign_in_id; POST /v1/admin/subscription-pool/refresh. Each of these was added because one incident needed one repair, and each requires the operator to already know which repair applies. The ledger records why a credential is unusable — needs_reauthorization, a recorded quota block, a definitive refusal — so the capability reads that state and performs the repair the state names, instead of offering one verb per guess (capability, runbook).

Route adoption (5). brama adopt; PUT and DELETE /v1/admin/routes; POST /v1/admin/configuration-adoption/preview; POST /v1/admin/configuration-adoption/apply, plus the 6 --adopt-* options on brama onboard. Reviewing and adopting aliases is one operation with one declaration behind it; it currently has three entry points and two implementations of the same review (alias).

Plan-usage reading (4 → 0, landed). It was POST /v1/subscription-usage/:agent_id; POST /v1/account/subscription-usage; POST /v1/admin/subscription-usage/:agent_id; POST /v1/admin/subscription-pool/usage. One sweep, one ledger, four ways to ask for it. The capability answers it once over POST /v1/plan-usage, reading the usage ledger and each provider's own usage report through the sweep's own bounded operation, and narrowing the answer by the identity the caller proved — the same PoolScope the pool resolves, so this gateway has one scoping decision rather than one per family (entitlement). All four were deleted in the same change: their routes, their handlers, the desktop calls that reached them and their paragraphs on this site. Three of them also named an audience in the path while none of them was reachable by a model-scoped bearer, which is the shape every workload identity has, so the one audience that signs for itself could not read its own usage on any of the four.

Provider credential administration (3). GET, PUT and DELETE /v1/admin/credentials. Skarbiec is the authority for credentials and Brama holds capability handles until final use; a credential-administration surface inside the routing gateway is a second authority for something Brama does not own (architecture).

The 24 primitives that stay¶

Nothing replaces these, because none of them is a second way to do something else. Inference and translation: POST /v1/chat/completions, POST /v1/messages, POST /v1/responses, POST /v1/embeddings, POST /v1/moderations. Reading what this gateway can serve: GET /v1/models, GET /v1/aliases, GET /v1/admin/snapshot, GET /stats, brama aliases. The two subscription capabilities, which are capabilities rather than per-audience verbs: GET and POST /v1/subscription-pool, POST /v1/plan-usage, brama subscription list. Liveness and readiness, which answer different questions: GET /health, GET /readyz. Process and operator primitives: brama serve, brama version, brama detect, brama mcp, brama onboard, brama test, brama collect-task-quality, brama help.

Invocations with no prose page¶

Still three, at the revision measured: GET, PUT and DELETE /v1/admin/credentials, which the HTTP API page does not mention at all. They are the family this page says Brama should not own; they will be documented by their removal, not by a new page. It was four at 070275a036f35130918948b66f4be8b7e26fcf50: brama aliases had a page file in the site source with no rewrite pointing at it, so /docs/cli/aliases was linked from the CLI tree and did not resolve. That route is registered. POST /v1/plan-usage was undocumented for exactly as long as it took to write its section in the same change that registered it.

The removal rule¶

A replaced command is deleted in the same change as its replacement. Not deprecated, not left answering with a notice, not kept "until callers move" — deleted, with its route, its option, its example and its documentation paragraph, in the one commit that introduces what replaces it. A superseded command standing beside its replacement is a second source of truth, and a second source of truth is not a documentation problem: it is an operator reading the wrong state during an incident, which is how a refused authorization came to be reported as capacity and cost a day (errors). This is Brama's instance of the fleet rule that a replacement and its predecessor do not coexist.

Migration order¶

1. Subscription inventory (11 invocations). Landed at 15c27474b3a870e1a399697068e2b96f4e72d8dd. First, because every other family names a subscription, so the identity and ownership scoping had to be settled before anything else could be expressed in terms of them.
2. Plan-usage reading (4 invocations). Landed at 76b7b987b33f950db9c6540d8a001b184d93b539. Second, because the usage ledger is what the repair capability reads to decide which repair applies; a capability that reads a declaration cannot land before the declaration is single-sourced.
3. Credential repair (13). Third, and only now, because it is the family that consumes the previous two: it selects a subscription from the pool and a verdict from the ledger. The manual sign-in belongs to it as the repair for an account only a person can log into; it stays a separate verb until the capability can ask the person.
4. Route adoption (5). Fourth. It is independent of the subscription families and can be sequenced anywhere after them; it goes here because collapsing three entry points into one changes brama onboard, and changing a first-use path while the pool is mid-migration puts both risks in one release.
5. Provider credential administration (3). Last, because it is the only family whose replacement is a boundary decision rather than a consolidation: the surface moves to Skarbiec, and removing it needs the consumers named in the service directory to have stopped calling it.

The order is dependency-first and blast-radius-second. Reversing it would mean building the repair capability on inventory that still has three owners, which is the defect this page exists to remove rather than relocate.

The command tree itself is the CLI reference; the routes are the HTTP API.