# BYOK vs managed brain -- when to recommend which

Fetch when the user asks: "que conviene?", "BYOK?", "managed?",
"why am I being told to setup keys?", "cap exhausted", "credit
ran out".

## The two paths

| Mode | Where the LLM call lives | Who pays |
|---|---|---|
| **BYOK** (bring-your-own-key) | Directly from `yf chat` to the provider (Anthropic / Google / OpenAI) using the user's API key from CredentialVault | The user, on their own provider account |
| **Managed brain** | `yf chat` -> Cloudflare Workers route -> provider, with a per-user cost-meter in KV | Yujin operator, billed back via subscription |

## When BYOK wins

- User already has a provider account + budget.
- Privacy: the prompt never leaves the user's machine -> Anthropic
  directly. No third party in the middle.
- Heavy / sustained use: BYOK has no per-month cap.
- Custom models the managed runtime doesn't proxy (e.g. specific
  Bedrock variants).

## When managed wins

- First-day onboarding: no provider account yet, but wants to try.
- Cost predictability: hard cap, can't accidentally rack up bills.
- Multi-device: no need to re-pair keys per laptop.
- Voice + reading flows on mobile: managed already wires
  pizarron / lessons / projects without a key per device.

## What to do when cap exhausted

If the user is on managed and hits the monthly cap, the brain
should:

1. Acknowledge the cap with the actual number if known.
2. Offer two paths, in this order:
   a. Configure BYOK -> `yf keys setup`. Costs pass directly to the
      user's provider account; no cap.
   b. Wait for the reset (first of next month). Read-only on
      managed in the meantime.
3. NEVER silently retry the same call.
4. NEVER suggest fishing for a different provider unless the
   user explicitly asks.

## What to do when no keys configured

- Brain MUST refuse anything that needs an LLM call.
- Recommend `yf keys setup` for the simplest path.
- Be clear about what each key unlocks (`anthropic_api_key` ->
  Sonnet/Haiku/Opus; `openai_api_key` -> GPT-4o; `google_ai_key`
  -> Gemini).
- Don't ask the user to paste keys in chat. The Vault setup
  prompts the user for the secret directly.

## Slot canonical names

Vault canonical:
- `anthropic_api_key`
- `openai_api_key`
- `google_ai_key`
- `deepseek_api_key`
- `xai_api_key`
- `mistral_api_key`
- `cohere_api_key`

SDK-convention aliases the brain matrix runner accepts:
`CLAUDE_API_KEY` -> `ANTHROPIC_API_KEY`,
`GEMINI_API_KEY` -> `GOOGLE_AI_KEY`. The user's `.env` may use
either set.

## Edge cases

- Mixed mode: user has BYOK + managed both. cost_router picks the
  cheaper or the available one per turn; the brain should not
  assume one specific provider.
- Override: `yf brain set <tier>` pins the next chat to a
  specific tier regardless of the router.
- Local fallback: there is no offline brain. If the network is
  down and there's no cached response, the chat is broken --
  surface that to the user instead of fabricating an answer.
