@legioncodeinc/rflectr 0.1.0 → 0.1.2

package/library/knowledge/private/ai/translation-layer.md

@@ -1,88 +0,0 @@
-# The Translation Layer
-
-> Category: Ai | Version: 1.0 | Date: June 2026 | Status: Active
-
-The single path that lets a Claude Code / Codex / Gemini host talk to any non-Anthropic model. This doc explains the Vercel AI SDK adapter (`src/sdk-adapter.ts`) and the provider factory (`src/provider-factory.ts`) that feeds it. Read [`../architecture/system-overview.md`](../architecture/system-overview.md) first.
-
-**Related:**
-- [`model-discovery-classification.md`](model-discovery-classification.md)
-- [`../integrations/local-proxy.md`](../integrations/local-proxy.md)
-- [`../integrations/harnesses.md`](../integrations/harnesses.md)
-- Source: `src/sdk-adapter.ts`, `src/provider-factory.ts`, `src/proxy-shared.ts`, `src/codex-responses-adapter.ts`, `src/gemini-proxy.ts`
-
----
-
-## Why there is exactly one translation path
-
-A naive launcher would hand-roll a translator per provider: Anthropic→OpenAI, Anthropic→Gemini, and so on. That is a combinatorial mess and every provider has quirks (message ordering, reasoning signatures, tool-call encoding). `rflectr` instead routes **all** non-Anthropic providers through the Vercel AI SDK (`ai` + `@ai-sdk/*`) — the same packages OpenCode loads. The SDK owns wire format, endpoint selection, and provider quirks, so there is one translation path, not N.
-
-```mermaid
-flowchart TD
-    host["Host wire format (Anthropic / Responses / Gemini)"]
-    host --> trans["translate*Request() — host body → SDK call params"]
-    trans --> factory["createLanguageModel({npm, modelId, apiKey, baseURL})"]
-    factory --> model["Vercel AI SDK LanguageModel"]
-    model --> stream["streamText / generateText"]
-    stream --> back["map SDK fullStream → host SSE/response"]
-    back --> host
-```
-
-The rule that decides whether to translate at all: `isSdkMigratedNpm(npm)` (`src/provider-factory.ts`) is true for **any** npm except `@ai-sdk/anthropic`. Anthropic-format models skip the adapter and are forwarded raw.
-
----
-
-## provider-factory.ts — npm → LanguageModel
-
-`createLanguageModel(spec)` (async) is the factory. `spec` carries `{ npm, modelId, apiKey, baseURL?, providerId?, authType?, oauthAccountId?, vertex? }`. It dynamically `import(npm)`s the SDK package and discovers its `create*` factory. The router has special branches:
-
-| npm | Behaviour |
-|---|---|
-| `@ai-sdk/google-vertex/anthropic` (`VERTEX_ANTHROPIC_NPM`) | Claude on Google Vertex AI via gcloud Application Default Credentials (no apiKey). |
-| `@ai-sdk/openai` | OAuth → ChatGPT Codex backend (`https://chatgpt.com/backend-api/codex`); API key → direct OpenAI. `modelPrefersResponsesApi()` picks `openai.responses(id)` vs `openai.chat(id)`. |
-| `@ai-sdk/xai` | Direct; also consults `modelPrefersResponsesApi()`. |
-| `@ai-sdk/google` | Direct — ignores `baseURL`, uses the native `/v1beta` endpoint. |
-| `@ai-sdk/anthropic` | Direct; strips a trailing `/v1` from `baseURL` if present. |
-| `@ai-sdk/openai-compatible`, `@openrouter/ai-sdk-provider` | Routed via `baseURL`. |
-| anything else | `loadSdkProviderFactory(npm)` finds the `create*()` export dynamically. |
-
-The `@ai-sdk/*` provider packages ship as npm **`dependencies`** and are marked `external` in `tsup.config.ts`, so they resolve from `node_modules` at runtime and keep `dist/cli.js` small.
-
-### The Responses API selector
-
-`modelPrefersResponsesApi(modelId)` returns true for OpenAI/xAI models that require the Responses API rather than Chat Completions: GPT-5.4+, GPT-5.5, `gpt-5-pro` / `gpt-5.2-pro`, `*-codex`, the o-series (`o3`, `o4`, …), and xAI `grok-*-multi-agent`. Newer OpenAI reasoning models only round-trip correctly through Responses, so this selection is load-bearing — not cosmetic.
-
-OpenCode catalog ids may differ from upstream API ids (e.g. `gpt-5.5-fast` → `gpt-5.5`); `upstreamModelId` carries OpenCode's `api.id` for the actual upstream call.
-
-### Reasoning capabilities
-
-`getReasoningCapabilities(npm, modelId, metadata)` returns a `ReasoningCapabilities` describing whether a model exposes controllable effort/thinking, internal-only reasoning, or none — covering Claude 4.6+, Gemini 2.5+/3, Mistral reasoners, xAI reasoners, DeepSeek V4, Kimi, and OpenRouter. The adapter uses this (with `effortProviderOptions` / `thinkingProviderOptions` / `deepMergeProviderOptions`) to translate a host's thinking/effort request into the right provider option block.
-
----
-
-## sdk-adapter.ts — Anthropic ↔ SDK
-
-The adapter handles the Claude-Code-facing direction. Its contract: **one turn per request.** Claude Code owns the tool loop, so the adapter never loops; it translates a single request and streams a single response.
-
-- `translateRequest(body, npm, options?)` builds the SDK call params from an Anthropic request — messages, tools, `tool_choice`, system. Critically, it **folds inline `role:'system'` messages into the system prompt**: Claude Code injects the skills list and system-reminders as system-role messages mid-conversation, and dropping them would break behaviour. `TranslateRequestOptions` carries `defaultEffort` (fallback when the client omits effort, e.g. the Claude Desktop gateway), `reasoningMetadata`, and `openAiOAuth` (ChatGPT Codex OAuth manages its own output limit and requires `instructions`).
-- `streamAnthropicResponse` maps the SDK `fullStream` to Anthropic SSE.
-- `generateAnthropicResponse` handles the non-streaming case.
-
-### The thought_signature round-trip
-
-Reasoning models (especially Gemini) require their `thought_signature` to be echoed back verbatim on the next turn. Anthropic's wire format has no field for it, so `rflectr` smuggles it through the tool-use id:
-
-- **Encode:** `encodeToolUseId(rawId, signature)` (`src/proxy-shared.ts`) produces `{id}::ts::{signature}`.
-- **Decode:** `splitToolUseId(id)` recovers `{ rawId, thoughtSignature }`, which is fed back into `providerOptions.google.thoughtSignature`.
-
-Gemini puts the signature on tool-call parts (captured at `tool-input-start`); the SDK then handles Gemini's strict echo-back. This is the reason the old hand-rolled Gemini-native path was retired. The `::ts::` separator would break only if a signature literally contained `::ts::` — extremely unlikely, and a documented edge.
-
----
-
-## The other two host directions
-
-The same factory + SDK model is reused; only the host-facing translation differs:
-
-- **Codex Responses API** (`src/codex-responses-adapter.ts`): `translateResponsesRequest` / `translateResponsesInput` / `translateResponsesTools` build SDK params from a Responses body; `streamResponsesResponse` / `generateResponsesResponse` emit the Responses SSE/JSON shape.
-- **Gemini REST** (`src/gemini-proxy.ts` + `src/gemini-parts.ts`): `translateGeminiRequest` extracts system instruction, contents, tools, and generation config; `parseGeminiPart` / `collectAnthropicBlocksFromGeminiParts` / `mapGeminiUsage` translate parts and usage.
-
-All three converge on `createLanguageModel` + `streamText`/`generateText`. That convergence is the whole point: add a provider once and every host can use it.

package/library/knowledge/private/architecture/README.md

@@ -1,10 +0,0 @@
-# Architecture
-
-System-level design docs and Architecture Decision Records (ADRs).
-
-| Doc | Covers |
-|---|---|
-| [`system-overview.md`](system-overview.md) | What rflectr is, its surfaces, the shared translation core, env isolation. **Start here.** |
-| [`launch-flow-claude.md`](launch-flow-claude.md) | The `rflectr claude` flow: single-model vs switch-menu launch paths. |
-
-ADRs (when added) live here as `ADR-<n>-<kebab-slug>.md`.

package/library/knowledge/private/architecture/launch-flow-claude.md

@@ -1,93 +0,0 @@
-# Claude Code Launch Flow
-
-> Category: Architecture | Version: 1.0 | Date: June 2026 | Status: Active
-
-How `rflectr claude` goes from a command line to a running Claude Code process pointed at the chosen model. Read [`system-overview.md`](system-overview.md) first. This doc traces `runClaudeCommand` in `src/cli.ts` and its two launch paths.
-
-**Related:**
-- [`system-overview.md`](system-overview.md)
-- [`../integrations/local-proxy.md`](../integrations/local-proxy.md)
-- [`../ai/translation-layer.md`](../ai/translation-layer.md)
-- [`../data/preferences-config.md`](../data/preferences-config.md)
-- Source: `src/cli.ts` (`runClaudeCommand`, `runModelsCommand`, `launchClaudeViaCatalog`), `src/env.ts` (`buildChildEnv`), `src/catalog.ts`
-
----
-
-## The two modes
-
-The launch has two shapes, decided by one line in `runClaudeCommand`:
-
-```ts
-const switchMenuActive = favorites.length > 0 && !launchPlan.skip;
-```
-
-- **Single-model mode** (no favorites saved): one model, one route. Launch and exit.
-- **Switch-menu mode** (`rflectr models` has saved at least one favorite): a multi-route catalog proxy is started and Claude Code's gateway model discovery is enabled, so the in-session `/model` command lists the starting model plus every favorite for live switching.
-
-Favorites are managed by `runModelsCommand` (also in `src/cli.ts`) and persisted to `~/.rflectr/config.json`. The cap is `MAX_MODEL_CATALOG = 20` (`src/constants.ts`).
-
----
-
-## Single-model flow
-
-```mermaid
-flowchart TD
-    start["rflectr claude"] --> bin["findClaudeBinary()"]
-    bin --> firstrun["needsFirstRunSetup? → runFirstRunWizard()"]
-    firstrun --> catalog["fetchProviderCatalog()"]
-    catalog --> pickP["p.select: which provider?"]
-    pickP --> pickM["pickLocalModel(provider)"]
-    pickM --> fmt{"selectedModel.modelFormat"}
-    fmt -->|anthropic| direct["buildChildEnv(model.baseUrl, ...) — no proxy"]
-    fmt -->|openai| proxy["startProxy(...) → buildChildEnv(127.0.0.1:port, ...)"]
-    direct --> launch["launchClaude(env, model, args)"]
-    proxy --> launch
-    launch --> wait["Claude Code runs (stdio inherited)"]
-    wait --> close["proxyHandle.close() on exit"]
-```
-
-The format branch is the heart of it (`src/cli.ts`):
-
-- `modelFormat === 'anthropic'` → **direct passthrough.** `buildChildEnv(selectedModel.baseUrl!, selectedModel.id, launchApiKey, undefined, contextWindow)`. No proxy; Claude Code talks straight to the provider's Anthropic-compatible endpoint. `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` is set so beta headers are stripped on the direct hop.
-- otherwise → **SDK adapter proxy.** `startProxy(completionsUrl, modelId, trace, contextWindow, { npm, baseURL, upstreamModelId, providerId, authType, oauthAccountId, supportedParameters, reasoning, interleavedReasoningField }, apiKey)` returns a `ProxyHandle`; the child env points `ANTHROPIC_BASE_URL` at `http://127.0.0.1:<port>`.
-
-The provider API key is resolved by `resolveLocalProviderApiKey(activeProvider)` (`src/provider-catalog.ts`). If none is found, launch aborts with a message pointing at `rflectr providers`.
-
----
-
-## Switch-menu (catalog) flow
-
-When favorites exist, `runClaudeCommand` delegates to `launchClaudeViaCatalog`:
-
-1. `makeRouteResolver(localProviders, zenModels, goModels, zenGoApiKey)` (`src/catalog.ts`) builds a function that maps a `(providerId, modelId)` pair to a `ProxyRoute`.
-2. `buildCatalogRoutes(startingRoute, favorites, resolveRoute)` builds the route list — **starting model + favorites only**, never the full catalog — and reports `droppedFavorites` (favorites whose provider/model is no longer available, silently skipped).
-3. `startProxyCatalog(catalogRoutes, startingRoute.aliasId, trace)` starts one proxy serving all routes.
-4. `buildChildEnv(..., enableGatewayDiscovery = true)` sets `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` so Claude Code fetches `/v1/models` from the proxy and populates `/model`.
-
-Each route's id is rewritten by `aliasModelId()` (`src/proxy.ts`) so Claude Code sees unique, gateway-safe names (e.g. `anthropic-opencode-go__deepseek-v4-flash`) in the picker. See [`../integrations/local-proxy.md`](../integrations/local-proxy.md).
-
-A `__favorites__` pseudo-provider is unshifted onto the provider picker in switch-menu mode; selecting it loads the Favorites Catalog and uses `resolveFirstAvailableFavorite` as the starting model.
-
----
-
-## The context-window caveat
-
-In switch-menu mode the displayed context window reflects the **launch** model and does **not** update on a live `/model` switch. Claude Code's gateway model discovery only carries `id` + `display_name` (no `context_window`) and fetches `/v1/models` once at startup, so `CLAUDE_CODE_MAX_CONTEXT_TOKENS` — fixed at launch by `buildChildEnv` — is the only lever. Single-model launches show the correct window. This is a documented, by-design limitation.
-
----
-
-## Flags and boot shortcuts
-
-`parseArgs` (`src/cli.ts`) recognises starter flags (`--dry-run`, `--setup`, `--trace`, `--help`, `--version`) and relay launch flags (`--provider`, `--model`). Everything after `--`, and any unrecognised flag, is forwarded verbatim to Claude Code (`claudeArgs`).
-
-- `--provider X --model Y` (or print mode `-p`) skips the wizard entirely via `planLaunchWizard` / `findProviderAndModel` (`src/launch-target.ts`).
-- `--dry-run` runs the whole wizard but prints a preview (`printDryRun`) and writes nothing — it ignores saved env keys, keyring, tier, and preferences, simulating a fresh first run.
-- `--trace` writes a debug log under `~/.rflectr/logs/` and prints errors on exit (`prepareClaudeTraceLog` / `printTraceLog`).
-
-Clean-stdout agent mode (`wantsCleanAgentStdout`, `setAgentStdoutMode`) suppresses the interactive intro/spinners when Claude Code is run in print/pipe mode.
-
----
-
-## What the child process receives
-
-For the exact env contract (`ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL`, `CLAUDE_CODE_MAX_CONTEXT_TOKENS`, the tool-search / system-prompt compat vars, and the removed conflict vars), see [`../security/credential-storage.md`](../security/credential-storage.md#child-process-environment).

package/library/knowledge/private/architecture/system-overview.md

@@ -1,108 +0,0 @@
-# System Overview
-
-> Category: Architecture | Version: 1.0 | Date: June 2026 | Status: Active
-
-Read this first. It explains what `rflectr` is, the surfaces it exposes, and the single translation core that every surface shares. New engineers should read this before diving into any domain doc.
-
-**Related:**
-- [`launch-flow-claude.md`](launch-flow-claude.md)
-- [`../ai/translation-layer.md`](../ai/translation-layer.md)
-- [`../ai/model-discovery-classification.md`](../ai/model-discovery-classification.md)
-- [`../integrations/local-proxy.md`](../integrations/local-proxy.md)
-- [`../integrations/harnesses.md`](../integrations/harnesses.md)
-- [`../data/provider-registry.md`](../data/provider-registry.md)
-- Source: `src/cli.ts`, `src/constants.ts`
-
----
-
-## Why this exists
-
-The major agentic coding tools — Claude Code, OpenAI Codex (CLI and desktop), Google Gemini CLI, and Claude Desktop — each speak only to their vendor's own API by default. `rflectr` is a launcher that re-points each of those tools at a *different* model backend without the tool noticing. You can run Claude Code against a Groq Llama model, Codex against DeepSeek, or Gemini CLI against a local Ollama endpoint — picking the model from an interactive wizard, then handing the host tool an environment that makes it believe it is talking to its native API.
-
-The published npm package and CLI binary are both named `rflectr` (`package.json` is the single source of truth for the version; see [`CLAUDE.md`](../../../../CLAUDE.md) for the release workflow). The repository directory is `rflectr`.
-
-The hard problem `rflectr` solves is **wire-format translation**: Claude Code emits Anthropic `/v1/messages`, Codex emits the OpenAI Responses API, Gemini CLI emits the Gemini REST protocol — but the chosen model may speak any of those formats (or none of them directly). A local HTTP proxy sits between the host tool and the upstream model and translates in both directions. All non-Anthropic translation flows through one path: the **Vercel AI SDK adapter** (see [`../ai/translation-layer.md`](../ai/translation-layer.md)).
-
----
-
-## The surfaces
-
-Every surface is a subcommand of the `rflectr` CLI, dispatched from `parseArgs` / `main` in `src/cli.ts`.
-
-| Command | What it launches | Host wire format | Doc |
-|---|---|---|---|
-| `rflectr claude` | Claude Code CLI | Anthropic `/v1/messages` | [`launch-flow-claude.md`](launch-flow-claude.md) |
-| `rflectr codex` | OpenAI Codex CLI | OpenAI Responses (`/v1/responses`) | [`../integrations/harnesses.md`](../integrations/harnesses.md) |
-| `rflectr codex-app` | Codex desktop app | OpenAI Responses | [`../integrations/harnesses.md`](../integrations/harnesses.md) |
-| `rflectr gemini` | Gemini CLI | Gemini REST (`:generateContent`) | [`../integrations/harnesses.md`](../integrations/harnesses.md) |
-| `rflectr claude-app` | Claude Desktop app | Anthropic (gateway config) | [`../integrations/harnesses.md`](../integrations/harnesses.md) |
-| `rflectr server` | Foreground API gateway | Anthropic + OpenAI compatible | [`../infrastructure/server-gateway.md`](../infrastructure/server-gateway.md) |
-| `rflectr providers` | Provider registry manager | — | [`../data/provider-registry.md`](../data/provider-registry.md) |
-| `rflectr models` / `favorites` | Favorite-model manager | — | [`launch-flow-claude.md`](launch-flow-claude.md) |
-
-```mermaid
-flowchart TD
-    subgraph hosts["Host tools (unmodified)"]
-        cc["Claude Code"]
-        cx["Codex CLI / app"]
-        gm["Gemini CLI"]
-        cd["Claude Desktop"]
-    end
-    subgraph relay["rflectr"]
-        proxy["Local proxy 127.0.0.1:random"]
-        adapter["Vercel AI SDK adapter"]
-        registry["Provider registry ~/.rflectr/providers.json"]
-    end
-    subgraph upstream["Upstream models"]
-        anth["Anthropic-format endpoints"]
-        sdk["Any @ai-sdk provider (OpenAI, Groq, Gemini, xAI, ...)"]
-    end
-    cc -->|ANTHROPIC_BASE_URL| proxy
-    cx -->|OPENAI base_url| proxy
-    gm -->|GOOGLE_GEMINI_BASE_URL| proxy
-    cd -->|gateway config| proxy
-    proxy -->|"anthropic format"| anth
-    proxy -->|"everything else"| adapter
-    adapter --> sdk
-    registry --> proxy
-```
-
----
-
-## The shared core
-
-Three subsystems are reused by every surface:
-
-**1. The provider registry** (`src/registry/`, `src/provider-catalog.ts`). The list of providers and their models lives in `~/.rflectr/providers.json`. It is the single source of truth for what shows up in every wizard. Built-in templates (Groq, Mistral, OpenAI, Ollama, …) are defined in `src/provider-templates.ts`; OpenCode Zen / Go are always available even with no registry. See [`../data/provider-registry.md`](../data/provider-registry.md).
-
-**2. The translation layer** (`src/sdk-adapter.ts`, `src/provider-factory.ts`). `createLanguageModel({ npm, modelId, apiKey, baseURL })` turns whatever npm package OpenCode/the registry assigned the provider into a Vercel AI SDK `LanguageModel`. The adapter then maps the host's wire format to and from that model, one turn per request — the host tool always owns its own tool loop. See [`../ai/translation-layer.md`](../ai/translation-layer.md).
-
-**3. The local proxy** (`src/proxy.ts` and the per-protocol variants `src/codex-proxy.ts`, `src/gemini-proxy.ts`). A throwaway HTTP server on `127.0.0.1:<random port>` that the host tool is pointed at. Anthropic-format models are forwarded raw; everything else goes through the SDK adapter. `aliasModelId()` rewrites non-`claude-*` ids to a gateway-safe form. See [`../integrations/local-proxy.md`](../integrations/local-proxy.md).
-
----
-
-## Environment isolation, not config editing
-
-`rflectr` never edits the host tool's settings file. It launches the child process with a purpose-built environment (`buildChildEnv` in `src/env.ts`) that:
-
-- **Removes** the 17 conflicting Anthropic/Vertex/Bedrock/AWS/Foundry env vars listed in `CONFLICTING_ENV_VARS` (`src/constants.ts`), so stale cloud config can't leak in.
-- **Sets** `ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL`, and `CLAUDE_CODE_MAX_CONTEXT_TOKENS`.
-
-This avoids the backup/restore problem that settings-file rewriters have. The one caveat: Claude Code itself persists the launched model to `~/.claude/settings.json`, so a later bare `claude` may still show a relay alias. See [`../security/credential-storage.md`](../security/credential-storage.md) for the full env contract.
-
-The two desktop apps (`claude-app`, `codex-app`) are the exception — they *do* write config files, because the apps have no env to inherit. Those writes are backed up and restored on exit via lock files. See [`../integrations/harnesses.md`](../integrations/harnesses.md).
-
----
-
-## A critical URL constraint
-
-`BACKENDS.baseUrl` in `src/constants.ts` must **not** include `/v1`. The Anthropic SDK appends `/v1/messages` automatically, so `https://opencode.ai/zen/v1` would produce requests to `/zen/v1/v1/messages` → 404. The same rule applies anywhere an Anthropic-format `baseUrl` is built. This is the single most common configuration footgun in the codebase.
-
----
-
-## Where to go next
-
-- To trace a launch end to end: [`launch-flow-claude.md`](launch-flow-claude.md).
-- To understand how a Groq or DeepSeek model gets spoken to as if it were Anthropic: [`../ai/translation-layer.md`](../ai/translation-layer.md).
-- To understand how the model list is built and classified: [`../ai/model-discovery-classification.md`](../ai/model-discovery-classification.md).
-- To understand credential handling: [`../security/credential-storage.md`](../security/credential-storage.md) and [`../auth/oauth-device-flows.md`](../auth/oauth-device-flows.md).

package/library/knowledge/private/auth/README.md

@@ -1,9 +0,0 @@
-# Auth
-
-Provider sign-in flows (distinct from credential storage, which is under `security/`).
-
-| Doc | Covers |
-|---|---|
-| [`oauth-device-flows.md`](oauth-device-flows.md) | RFC 8628 device flows for OpenAI/ChatGPT, xAI/Grok, GitHub Copilot; token storage and refresh; PKCE. |
-
-For where keys/tokens are stored and the env contract, see [`../security/credential-storage.md`](../security/credential-storage.md).

package/library/knowledge/private/auth/oauth-device-flows.md

@@ -1,95 +0,0 @@
-# OAuth Device Flows
-
-> Category: Auth | Version: 1.0 | Date: June 2026 | Status: Active
-
-How `rflectr` signs into providers that use OAuth instead of an API key — OpenAI (ChatGPT), xAI (Grok), and GitHub Copilot — and how those tokens are stored and refreshed. Read [`../data/provider-registry.md`](../data/provider-registry.md) for how an OAuth provider is registered.
-
-**Related:**
-- [`../security/credential-storage.md`](../security/credential-storage.md)
-- [`../data/provider-registry.md`](../data/provider-registry.md)
-- [`../ai/translation-layer.md`](../ai/translation-layer.md)
-- Source: `src/oauth/` (`types.ts`, `openai.ts`, `xai.ts`, `github.ts`, `refresh.ts`, `pkce.ts`)
-
----
-
-## Why device flow
-
-These hosts run in a terminal with no browser redirect URI to catch. The OAuth 2.0 **Device Authorization Grant** (RFC 8628) fits: `rflectr` asks the provider for a user code, prints a URL for the user to visit, then polls until the user approves. No localhost callback server, no redirect handling.
-
-`supportsNativeOAuth(providerId)` (`src/oauth/types.ts`) gates which providers offer this. The native set is `'xai' | 'xai-oauth' | 'openai' | 'openai-oauth' | 'github-copilot'`. The `rflectr providers auth <id>` command (`--native` vs `--broker`) drives it.
-
-```mermaid
-sequenceDiagram
-    participant U as User
-    participant R as rflectr
-    participant P as Provider auth server
-    R->>P: request device/user code
-    P-->>R: user_code + verification URL + interval
-    R->>U: "visit <url>, enter <user_code>"
-    loop until approved (respect interval / slow_down)
-        R->>P: poll token endpoint
-        P-->>R: authorization_pending | slow_down | tokens
-    end
-    P-->>R: access + refresh tokens
-    R->>R: store StoredOAuthCredential in OS keyring
-```
-
----
-
-## Stored credential shape
-
-`StoredOAuthCredential` (`src/oauth/types.ts`) is `{ type: 'oauth', access, refresh, expires, accountId? }`. It is serialized to JSON and written to the keyring account `oauth:provider:<id>` (see [`../security/credential-storage.md`](../security/credential-storage.md)). Helpers:
-
-- `tokensToStoredCredential(tokens, existingRefresh?, accountId?)` — build it from a token response, preserving the existing refresh token if the provider didn't return a new one.
-- `parseStoredOAuthCredential(raw)` — parse + validate from keyring.
-- `oauthCredentialNeedsRefresh(cred, skewMs?)` — true when `expires <= now + skew` (default 120 s).
-- `accessTokenIsExpiring(token, skewMs?)` — decode the JWT `exp` and check proactively.
-
----
-
-## The three providers
-
-### OpenAI / ChatGPT (`src/oauth/openai.ts`)
-
-- Client id `app_EMoaamEEZ73f0CkXaXp7hrann`, issuer `https://auth.openai.com`.
-- `runOpenAiDeviceCodeFlow(onDeviceCode, opts?)`: POST `/api/accounts/deviceauth/usercode` → poll `/api/accounts/deviceauth/token` → exchange the authorization code (with PKCE `code_verifier`) at `/oauth/token`.
-- `extractOpenAiAccountId(tokens)` decodes the `id_token` / access token JWT for `chatgpt_account_id`. That `accountId` is what `provider-factory.ts` uses to route to the ChatGPT Codex backend (`https://chatgpt.com/backend-api/codex`).
-- `refreshOpenAiAccessToken(refreshToken)` — `grant_type=refresh_token` at `/oauth/token`.
-
-### xAI / Grok (`src/oauth/xai.ts`)
-
-- Client id `b1a00492-073a-47ea-816f-4c329264a828`; device endpoint `https://auth.x.ai/oauth2/device/code`, token `https://auth.x.ai/oauth2/token`.
-- Scope `openid profile email offline_access grok-cli:access api:access`.
-- `requestXaiDeviceCode()` → `pollXaiDeviceCodeToken(device, opts?)` (grant `urn:ietf:params:oauth:grant-type:device_code`), combined as `runXaiDeviceCodeFlow`. Handles `slow_down` by bumping the interval +5 s.
-- `refreshXaiAccessToken(refreshToken)`.
-
-### GitHub Copilot (`src/oauth/github.ts`)
-
-A two-step exchange — this is the quirk to remember:
-
-1. Standard GitHub device flow (client id `Iv1.b507a08c87ecfe98`, the VS Code Copilot extension id; scope `copilot`) yields a long-lived `ghu_` access token.
-2. `exchangeForCopilotToken(ghuToken)` GETs `https://api.github.com/copilot_internal/v2/token` to mint a **short-lived Copilot session token**.
-
-`refreshGithubCopilotToken(ghuToken)` simply re-exchanges the `ghu_` for a fresh session token — so the **stored `refresh` field is the `ghu_` itself**, not a conventional refresh token.
-
-> Caveat: Copilot OAuth *login* works, but Copilot as a *model provider* does not — OpenCode loads `@ai-sdk/github-copilot` from internal `@opencode-ai/core`, not a public npm factory. See [`../data/provider-registry.md`](../data/provider-registry.md).
-
----
-
-## Refresh orchestration
-
-`src/oauth/refresh.ts` is the single dispatch point, called lazily at credential-resolution time (`resolveProviderCredential` in `src/env.ts`):
-
-- `oauthCredentialShouldRefresh(cred, providerId)` — true if `oauthCredentialNeedsRefresh(cred)` (time-based) **or**, for native providers, `accessTokenIsExpiring(cred.access)` (proactive JWT check).
-- `refreshStoredOAuthCredential(providerId, cred)` — routes to `refreshOpenAiAccessToken` / `refreshXaiAccessToken` / `refreshGithubCopilotToken` and returns a new `StoredOAuthCredential` via `tokensToStoredCredential`.
-
-Refresh is deduplicated per keyring account (`refreshOAuthKeyringAccount` in `src/env.ts`) so concurrent launches don't double-refresh, and a refreshed token is written back to the keyring. If refresh fails but the existing access token hasn't yet expired, the stale-but-valid token is used.
-
----
-
-## PKCE & utilities (`src/oauth/pkce.ts`)
-
-- `generatePkce()` → `{ verifier, challenge }` with `challenge = SHA256(verifier)`.
-- `generateOAuthState()` → base64url of 32 random bytes.
-- `generateRandomString(length)` — crypto-random from the unreserved-char set.
-- `positiveSecondsToMs(value, defaultMs)`, `sleepMs(ms)` — polling helpers.

package/library/knowledge/private/data/README.md

@@ -1,8 +0,0 @@
-# Data
-
-On-disk state: the provider registry and user preferences.
-
-| Doc | Covers |
-|---|---|
-| [`provider-registry.md`](provider-registry.md) | `~/.rflectr/providers.json` schema, built-in templates, registry → runtime materialization, the `providers` command. |
-| [`preferences-config.md`](preferences-config.md) | `~/.rflectr/config.json`, app-home resolution (`RFLECTR_HOME`), legacy-path migration, large-catalog UX constants. |

package/library/knowledge/private/data/preferences-config.md

@@ -1,87 +0,0 @@
-# Preferences & Config Store
-
-> Category: Data | Version: 1.0 | Date: June 2026 | Status: Active
-
-Where `rflectr` keeps user preferences, how the app-home directory is resolved, and the legacy-path migration. Read [`provider-registry.md`](provider-registry.md) for the separate providers file.
-
-**Related:**
-- [`provider-registry.md`](provider-registry.md)
-- [`../security/credential-storage.md`](../security/credential-storage.md)
-- Source: `src/paths.ts`, `src/config.ts`, `src/types.ts`
-
----
-
-## The app home
-
-Everything `rflectr` writes lives under one directory, resolved by `getAppHome()` (`src/paths.ts`):
-
-1. `RFLECTR_HOME` (or deprecated `OPENCODE_STARTER_HOME`) if set — overrides everything.
-2. otherwise `~/.rflectr`.
-
-Files within it:
-
-| Path helper | File | Contents |
-|---|---|---|
-| `getConfigPath()` | `~/.rflectr/config.json` | User preferences (this doc) |
-| `getProvidersPath()` | `~/.rflectr/providers.json` | Provider registry ([`provider-registry.md`](provider-registry.md)) |
-| `getLogsPath()` | `~/.rflectr/logs/` | `--trace` debug logs |
-| `getVertexModelsPath()` | `~/.rflectr/vertex-models.json` | Optional Vertex model catalog |
-
-The directory is created with mode `0o700` and files with `0o600`. All writes are skipped when `dryRun === true`.
-
----
-
-## Preferences schema
-
-`UserPreferences` (`src/types.ts`), read/written by `loadPreferences()` / `savePreferences()` (`src/config.ts`):
-
-| Field | Purpose |
-|---|---|
-| `lastBackend` | Last cloud backend (`zen` / `go`) |
-| `lastModel`, `lastProvider` | Last Claude Code selection (pre-selected in the wizard) |
-| `lastCodexProvider`, `lastCodexModel` | Last Codex selection |
-| `lastGeminiProvider`, `lastGeminiModel` | Last Gemini selection |
-| `recentModelsByProvider` | `Record<string, string[]>` — up to 3 recent model ids per provider |
-| `favoriteModels` | `FavoriteModel[]` (`{ providerId, modelId }`), max `MAX_MODEL_CATALOG` (20) |
-| `server` | Saved `server`-command settings |
-
-`savePreferences()` does a shallow merge — pass only the keys you're changing. `recordLaunchSelection(agent, providerId, modelId, prefs)` updates the per-agent `last*` fields and prepends to `recentModelsByProvider` (deduped, capped at 3).
-
-```mermaid
-flowchart TD
-    launch["launch a model"] --> rec["recordLaunchSelection()"]
-    rec --> last["set last{Provider,Model} for the agent"]
-    rec --> recent["prepend to recentModelsByProvider[provider] (max 3, dedup)"]
-    last --> save["savePreferences() — skipped on --dry-run"]
-    recent --> save
-```
-
-`recentModelsByProvider` powers the "recent" hint at the top of `pickLocalModel` (`src/prompts.ts`), with a "Browse all models →" escape hatch.
-
----
-
-## Legacy migration
-
-`rflectr` was previously `opencode-starter`, and its config moved twice. `readConfig()` (`src/config.ts`) migrates on first read, transparently:
-
-```mermaid
-flowchart TD
-    read["readConfig()"] --> homeMig["ensureAppHomeMigrated(): copy ~/.opencode-starter/config.json → ~/.rflectr/config.json"]
-    homeMig --> confMig["ensureConfigMigrated(): copy OS-conf-store legacy config → ~/.rflectr/config.json"]
-    confMig --> load["readJsonFile(getConfigPath()) ?? {}"]
-```
-
-- `getLegacyAppHome()` → `~/.opencode-starter` (the prior dotfile dir). `vertex-models.json` migrates alongside `config.json`.
-- `getLegacyConfPath()` → the even older OS-specific `conf` location (macOS `~/Library/Preferences/opencode-starter-nodejs/`, Windows `%APPDATA%\opencode-starter-nodejs\Config\`, Linux `$XDG_CONFIG_HOME/opencode-starter-nodejs/`). After copying, the legacy file is renamed `…​.migrated` (best-effort).
-- `loadPreferences()` also normalizes the old `lastProvider === 'opencode'` value to `'zen'`.
-
-Migration is one-directional and idempotent: if `~/.rflectr/config.json` already exists, nothing is copied.
-
----
-
-## Large-catalog UX constants
-
-Two constants in `src/prompts.ts` shape the picker once a provider's model list grows:
-
-- `MODEL_SEARCH_THRESHOLD = 25` — lists above this show search or paginated browse instead of a flat list.
-- `MODEL_PAGE_SIZE = 15` — page size for prev/next browsing (`selectModelWithSearch`, `selectLargeCatalog`, `pickModelFromPagedList`).

package/library/knowledge/private/data/provider-registry.md

@@ -1,126 +0,0 @@
-# The Provider Registry
-
-> Category: Data | Version: 1.0 | Date: June 2026 | Status: Active
-
-The on-disk catalog of providers and their models — the single source of truth for every wizard. This doc covers the `~/.rflectr/providers.json` schema, the built-in templates, and how a registry entry becomes a runtime provider. Read [`../architecture/system-overview.md`](../architecture/system-overview.md) first.
-
-**Related:**
-- [`preferences-config.md`](preferences-config.md)
-- [`../ai/model-discovery-classification.md`](../ai/model-discovery-classification.md)
-- [`../security/credential-storage.md`](../security/credential-storage.md)
-- [`../auth/oauth-device-flows.md`](../auth/oauth-device-flows.md)
-- Source: `src/registry/` (`types.ts`, `io.ts`, `load.ts`, `materialize.ts`, `crud.ts`, `add-template.ts`, `import-opencode.ts`), `src/provider-templates.ts`, `src/providers-command.ts`, `src/provider-catalog.ts`, `src/paths.ts`
-
----
-
-## Why a registry
-
-Early versions discovered providers by spawning OpenCode's `opencode serve` and reading `/config/providers` on every launch. That is slow and couples `rflectr` to a running OpenCode. The registry replaces that: providers are imported or added **once**, persisted to `~/.rflectr/providers.json`, and read directly on every launch. OpenCode import is now a one-time operation (`rflectr providers import`), not a per-launch dependency. OpenCode Zen / Go remain always available even with an empty registry.
-
----
-
-## On-disk schema
-
-Path: `getProvidersPath()` → `~/.rflectr/providers.json` (`src/paths.ts`). Types in `src/registry/types.ts`:
-
-```ts
-ProviderRegistry {
-  schemaVersion: number          // currently 1
-  providers: RegistryProvider[]
-  importedAt?: string
-  pricingCacheAt?: string
-}
-
-RegistryProvider {
-  id: string                     // /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/ (PROVIDER_ID_PATTERN)
-  templateId: string             // origin template, e.g. 'groq', 'custom-lm-studio'
-  name: string                   // display name
-  enabled: boolean
-  authRef: string                // 'keyring:provider:groq' | 'keyring:global:opencode' | 'env:OPENCODE_API_KEY'
-  authType?: 'api' | 'oauth' | 'none'
-  subscriptionFilter?: 'free' | 'zen' | 'go'
-  api: { npm?: string; url?: string; id?: string }
-  modelsCache?: { fetchedAt: string; models: CachedModel[] }
-  addedAt: string                // ISO
-  refreshedAt?: string
-}
-
-CachedModel {
-  id: string
-  name: string
-  upstreamModelId: string        // provider's native id for the wire call
-  family?: string; brand?: string
-  contextWindow?: number
-  cost?: { input: number; output: number }
-  modelFormat: 'anthropic' | 'openai'
-  npm?: string                   // per-model override of provider.api.npm
-  apiUrl?: string                // per-model override of provider.api.url
-  sourceBackend?: string
-  supportedParameters?: string[]
-  reasoning?: boolean
-  interleavedReasoningField?: string
-}
-```
-
-**Persistence** (`src/registry/io.ts`): `loadRegistry(path?)` returns an empty registry if the file is missing/unparseable and applies migrations; `saveRegistry()` writes atomically (tmp + rename, backup) with secure permissions (`0o600` file inside a `0o700` dir via `ensureSecureAppHome()`), 2-space JSON + trailing newline. **No secrets live in this file** — `authRef` is only a pointer; the actual key lives in the OS keyring (see [`../security/credential-storage.md`](../security/credential-storage.md)).
-
----
-
-## From registry entry to runtime provider
-
-```mermaid
-flowchart TD
-    file["~/.rflectr/providers.json"] --> load["loadRegistry()"]
-    load --> lp["loadRegistryProviders() (async)"]
-    lp --> cred["resolveProviderCredential(id, authRef) — env → keyring → OAuth refresh"]
-    cred --> mat["materializeRegistry(registry, credResolver)"]
-    mat --> filter["skip disabled / no-models / no-credential; shouldHideModel() per agent"]
-    filter --> runtime["LocalProvider[] (the wizard list)"]
-```
-
-- `loadRegistryProviders(diag?, opts?)` (`src/registry/load.ts`) reads enabled entries and resolves each credential.
-- `materializeRegistry(registry, credResolver, opts?)` (`src/registry/materialize.ts`) converts `CachedModel` → `LocalProviderModel`, drops providers with no credential or no cached models, and applies per-agent model hiding (`shouldHideModel()`) — e.g. Zen/Go favorites hidden from Codex.
-- `providersForPicker()` / `resolveLocalProviderApiKey()` / `formatRegistryAuthLabel()` (`src/provider-catalog.ts`) adapt the materialized providers for the interactive pickers and resolve the launch key.
-
----
-
-## Built-in templates
-
-`src/provider-templates.ts` defines `ProviderTemplate`s — the menu of providers a user can add without hand-entering a base URL. Each carries `id`, `name`, `authType`, `npm` (the SDK package), `defaultBaseUrl?`, `signupUrl?`, `urlPrompt?` (for local servers), `modelSource` (`api-list | static-seed | manual-only | zen-go-api`), and `supported` / `addable` / `unsupportedReason` flags.
-
-| Group | Templates |
-|---|---|
-| API-key, addable | groq, mistral, togetherai, cerebras, deepinfra, deepseek, zhipu, moonshot(-global), kimi-code, xai, perplexity, cohere, openai, google, alibaba, openrouter, venice, anthropic |
-| Local servers | ollama, lmstudio (`urlPrompt`, `apiKeyOptional`) |
-| OAuth | github-copilot, xai |
-| Reference only (not addable) | bedrock (AWS creds), azure (deployment URLs), vertex (gcloud ADC) — carry `unsupportedReason` |
-| Cloud stubs | `zen`, `go` (`addable: false`); `opencode-cloud` routes to them. Models fetched live. |
-
-Query helpers: `listSupportedTemplates()`, `listAddableTemplates(configuredIds)`, `getTemplateById(id)`, `filterTemplates(templates, query)`.
-
-OpenCode is the source of truth for *which* models a provider exposes — `rflectr` does not maintain a per-package allowlist beyond these templates.
-
----
-
-## The `providers` command
-
-`src/providers-command.ts` (`parseProvidersArgs` → `runProvidersCommand`):
-
-| Command | Function | Purpose |
-|---|---|---|
-| `rflectr providers` | `runProvidersHub()` | Interactive hub |
-| `… add` | `runProvidersAdd()` | Add from template or custom endpoint → `addProviderFromTemplate` |
-| `… import` | `runProvidersImport()` | One-time import from OpenCode → `importFromOpencode` |
-| `… list` | `runProvidersList()` | Tabular view |
-| `… remove <id>` | `runProvidersRemove(id)` | Remove entry + keyring cleanup → `removeProviderFromRegistry` |
-| `… refresh-models [id]` | `runProvidersRefreshModels(id?)` | Re-fetch the model cache |
-| `… auth <id> [--native\|--broker]` | `runProvidersAuth(id, method?)` | OAuth sign-in (see [`../auth/oauth-device-flows.md`](../auth/oauth-device-flows.md)) |
-
-CRUD lives in `src/registry/crud.ts` (`removeProviderFromRegistry`, `toggleProviderEnabled`), template-add in `src/registry/add-template.ts`, and OpenCode import in `src/registry/import-opencode.ts` (handles duplicate-provider migration).
-
----
-
-## Unsupported-by-design providers
-
-- `@ai-sdk/github-copilot` won't work as a *model* provider — OpenCode loads it from internal `@opencode-ai/core`, not a public npm factory we can ship. (OAuth login still works; it's the model factory that's unavailable.)
-- Bedrock / Azure / Vertex may need env-based auth beyond a simple forwarded `apiKey`; they're reference-only templates. Vertex *is* supported through the dedicated `server --vertex` path (gcloud ADC) — see [`../infrastructure/server-gateway.md`](../infrastructure/server-gateway.md).

package/library/knowledge/private/infrastructure/README.md

@@ -1,7 +0,0 @@
-# Infrastructure
-
-Long-lived services and runtime gateways.
-
-| Doc | Covers |
-|---|---|
-| [`server-gateway.md`](server-gateway.md) | `rflectr server` — the Anthropic/OpenAI-compatible gateway on port 17645, the model catalog + discovery-id masking, and Vertex AI mode (`--vertex`). |