th llm onboard: connect Big Smooth to a Smoo org in one step

[brentrager]

What this is

Big Smooth is something a Smoo AI org adopts, and there was no adoption path. Three
pieces existed and nothing joined them: th auth login (the Smoo session),
th llm keys create <name> (mints a LiteLLM virtual key, prints the value exactly
once), th model login smooai-gateway (writes credentials into
~/.smooth/providers.json). Joining them meant a human copying a live, billable
credential out of their terminal and pasting it into a second command.

th llm onboard (alias of th llm provision) is the whole path:

1. Reuse the Smoo session — sign in if there isn't one.
2. Choose the org. No silent default.
3. Mint big-smooth-<hostname> on that org, through the existing org-admin-gated
   API as the logged-in user.
4. Back up providers.json → providers.json.bak-<stamp> (the naming th reclaim
   already sweeps).
5. Write the key into the smooai-gateway provider and point every routing slot at it.
6. Make one real call through the gateway and report the result.

The key value never touches the terminal. The single exception is a failed write —
at that point the key is live, billable, and unrecoverable, so it is printed loudly with
the name to revoke it by, and the command exits non-zero.

Why the org matters

The key is minted on the onboarding org, so that org's LiteLLM team and budget are
what Big Smooth spends against (team_id == org_id). Per-org billing and isolation fall
out of the existing model — no platform special-case. That is exactly what is broken
today: Big Smooth runs on the master org's __backend__ key, sharing a team with
smoo.ai's public chat agent, and in 2026-08 it spent $377.92 of $396.44 (95.3%) of that
team's budget and took the public agent down with it (that agent's own key had spent
$11.08).

So org selection is a first-class step, not a flag with a default:

• --org-id takes a UUID or a name/slug substring; omitted, you get the same interactive
  picker th org switch uses; with no TTY it is a hard error.
• It reuses resolve_switch_org rather than inventing selection UI.
• Silently taking the active org would bill Big Smooth to whichever customer you last
  looked at — and the first user of this administers ~20 orgs.

--org-id <other-org> is the only thing that changes the blast radius: a second key on
the same org gives attribution (per-key spend in LiteLLM_SpendLogs), not isolation.
That sentence is in --help, the output footer, the changeset, and the CLI guide.

Auth: the existing route, no side path

Every llm-gateway route is requireSupabaseUser + requireOrgAdmin server-side. This
goes through it as the th auth login user — no LiteLLM admin key, no master key, nothing
CLI-specific in what onboarding means, so the product UI can call the same thing. Failures
are reported in product terms: a 403 becomes "connecting Big Smooth to <org> needs ADMIN
on that org — ask an admin to run this, or pick an org you administer"; a missing session
signs in rather than erroring.

Named key, not the org's default key

Big Smooth mints its own named key via the named-keys path. An org can already have a
gateway key for its own reasons, so "the org has a key" is not "Big Smooth is onboarded" —
and the create-key 409 the default path throws is a normal state for such an org, not an
error to route around. A named key also keeps Big Smooth's spend separable in
LiteLLM_SpendLogs. Same team, so same budget: attribution, not isolation.

Idempotency follows from that: re-running recognises already connected to <org> and
offers --rotate (also how a second machine gets a value), never stacking keys. The
pre-check is a GET /keys, so the 409 is never surfaced raw.

Minting is not read-only

The route runs syncOrgLlmLimits before minting ("no cap, no key"), which re-stamps the
org's tier budget onto its team — the exact mechanism behind the outage above (a mint put a
monthly-sized cap on a team carrying months of lifetime spend). The output says this
happened. It does not report the resulting number: no API surface returns the tier,
maxBudget, or budgetDuration — overview returns { key, spendMtd } and the key routes
return neither. Filed rather than guessed.

Deliberately NOT shipped

--max-budget. POST /organizations/{org}/llm-gateway/keys accepts { name } and nothing
else — the route never passes maxBudget/budgetDuration to createVirtualKey, so the flag
would be a switch wired to nothing. Pearl th-a23962 (smooai monorepo) covers both this and
exposing the cap for read. When the cap ships, the window must ship with it: max_budget
with no budget_duration is a LIFETIME cap that never resets.

Tests — 15 assertions, each negative-controlled

Every one was broken, the run watched, and restored:

mutation	test that failed
drop the leading-char strip in sanitize_key_name	sanitized_names_always_satisfy_the_api_rule
key_exists matches the mask instead of the name	key_exists_matches_by_name_only
skip the backup	write_stores_the_key_wires_routing_and_keeps_other_providers
skip the retired-alias migration	″
start from a fresh registry (evict other providers)	″
wire routing even under --credential-only	credential_only_leaves_routing_alone
key_lost_message omits the key value	a_failed_write_errors_and_the_message_carries_the_key
write_gateway_key swallows the save_to_file error	a_failed_save_errors_too
verify_gateway reports success regardless	verification_fails_when_the_gateway_rejects_the_key
verify against a retired smooth-* alias	verify_model_is_concrete
org_label falls back to empty instead of the id	org_label_never_comes_out_empty
admin_hint drops the org name from the 403	a_403_explains_the_admin_requirement_and_names_the_org
admin_hint rewrites every failure as a permissions problem	other_failures_are_left_alone

The swallow-the-save mutation is why there are two write-failure tests: the first forces
failure in back_up and never reaches the save, so it still passed under that mutation.
The read-only-directory case is the one that actually covers it.

Verification is tested against a tiny_http stub returning 401 — a rejected key must not
read as verified.

Gates

cargo fmt --all --check, cargo clippy --workspace --all-targets (exit 0, zero errors;
the repo deliberately does not pass -D warnings — pedantic/nursery are advisory by
design), cargo test -p smooai-smooth-cli → 801 + 3 passed. Changeset included (minor).
CI was green on the first push.

Nothing was minted against prod — the network paths are unexercised by design, for Brent to
dogfood.

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 4296010

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@smooai/smooth	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR