@legioncodeinc/rflectr 0.1.0

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

@@ -0,0 +1,95 @@
+# 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

@@ -0,0 +1,8 @@
+# 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

@@ -0,0 +1,87 @@
+# 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

@@ -0,0 +1,126 @@
+# 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

@@ -0,0 +1,7 @@
+# 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`). |

package/library/knowledge/private/infrastructure/server-gateway.md

@@ -0,0 +1,87 @@
+# The Server Gateway
+
+> Category: Infrastructure | Version: 1.0 | Date: June 2026 | Status: Active
+
+`rflectr server` runs a long-lived HTTP gateway that exposes registry/Zen/Go providers (or Claude on Vertex AI) behind Anthropic- and OpenAI-compatible endpoints. It's the backend for Claude Desktop and any tool that can point at a base URL. Read [`../ai/translation-layer.md`](../ai/translation-layer.md) for the translation it reuses.
+
+**Related:**
+- [`../integrations/harnesses.md`](../integrations/harnesses.md)
+- [`../ai/translation-layer.md`](../ai/translation-layer.md)
+- [`../security/credential-storage.md`](../security/credential-storage.md)
+- Source: `src/server/` (`index.ts`, `router.ts`, `models.ts`, `vendor-mask.ts`, `vertex-config.ts`, `auth.ts`, `catalog-filter.ts`, `provider-select.ts`, `prompts.ts`)
+
+---
+
+## What it is
+
+Where the launch commands are short-lived (start a proxy, run a child, tear down), `server` is a **foreground daemon**. `runServerCommand(options)` (`src/server/index.ts`) runs an interactive wizard (which providers to expose, optional favorites-only catalog, discovery-id masking, local vs network bind) and then `startServer()` (`src/server/router.ts`) listens on port **17645**.
+
+It serves the same translation core as the CLI proxies — `handleAnthropicMessages` and `handleOpenAIChatCompletions` both end at `createLanguageModel` + the SDK adapter for openai-format models, or a raw forward for anthropic-format models, with a per-`(model × npm × baseURL)` `LanguageModel` cache.
+
+```mermaid
+flowchart TD
+    client["Claude Desktop / any tool"] --> ep{"endpoint"}
+    ep -->|"POST /anthropic/v1/messages"| anth["handleAnthropicMessages"]
+    ep -->|"POST /openai/v1/chat/completions"| oai["handleOpenAIChatCompletions"]
+    ep -->|"GET /models, /anthropic/v1/models, /openai/v1/models"| list["catalog (apiKey stripped)"]
+    ep -->|"GET /health"| health["{ ok: true }"]
+    anth --> fmt{"modelFormat"}
+    oai --> fmt
+    fmt -->|anthropic| raw["raw forward {baseUrl}/v1/messages"]
+    fmt -->|openai| sdk["SDK adapter"]
+```
+
+---
+
+## Endpoints
+
+| Method + path | Purpose |
+|---|---|
+| `GET /health` | `{ ok: true }` |
+| `GET /models` | Raw catalog, `apiKey` stripped |
+| `GET /anthropic/v1/models` | Anthropic-format list (optionally masked) |
+| `GET /openai/v1/models` | OpenAI-format list |
+| `POST /anthropic/v1/messages` | Anthropic Messages relay |
+| `POST /openai/v1/chat/completions` | OpenAI Chat Completions relay |
+
+Base URLs for clients:
+
+- Anthropic: `ANTHROPIC_BASE_URL=http://127.0.0.1:17645/anthropic`
+- OpenAI: `OPENAI_BASE_URL=http://127.0.0.1:17645/openai/v1`
+
+---
+
+## Model catalog & gateway aliases
+
+`loadServerModels()` (`src/server/index.ts`) assembles `ServerModelInfo[]` from Zen/Go models plus every materialized local provider, enriching each with reasoning metadata (`enrichServerModelReasoning` adds `defaultEffort`). `createGatewayModelCatalog(models, opts?)` (`src/server/models.ts`) builds a bidirectional lookup keyed by `model.id` and by gateway alias.
+
+Helpers in `src/server/models.ts`:
+
+- `gatewayAliasId(model)` / `exposedGatewayAliasId(model, opts?)` — canonical alias `anthropic-{provider}__{model}` (via `aliasModelId`), masked or not.
+- `gatewayDisplayName(model, opts?)` — "Model Name" or "Model Name (Provider Label)" when masked.
+- `upstreamModelId(model)` — strips the `[1m]` context suffix for the wire call.
+- `formatGatewayAnthropicModels` / `formatOpenAIModels` — endpoint payloads.
+
+Filtering (`src/server/catalog-filter.ts`): `filterServerModelsByProviders`, `filterServerModelsByFavorites`, `summarizeServerProviders` (human summary like "OpenCode Zen (5), Groq (3)").
+
+### Discovery-id masking
+
+For Claude Desktop / Cowork, exposing raw vendor model ids may be undesirable. When the wizard enables masking (`gateway.maskGatewayIds = true`), `maskGatewayModelId(aliasId)` (`src/server/vendor-mask.ts`) reverses the provider-slug and model-suffix segments to hide vendor names; it is **self-inverse** (`unmaskGatewayModelId` is the same operation). The response `model` field is also set to the masked `gatewayDisplayName`. Example: `anthropic-openai__gpt-4o` → a reversed-segment alias.
+
+---
+
+## Vertex AI mode (`--vertex`)
+
+`rflectr server --vertex` exposes **Claude on Google Vertex AI** using local gcloud Application Default Credentials — no OpenCode API key. `src/server/vertex-config.ts`:
+
+- `buildVertexRuntimeConfig(env?)` reads the project (`ANTHROPIC_VERTEX_PROJECT_ID` → `GOOGLE_CLOUD_PROJECT` → `GOOGLE_VERTEX_PROJECT`) and location (`GOOGLE_CLOUD_LOCATION` → `CLOUD_ML_REGION` → `GOOGLE_VERTEX_LOCATION` → `global`).
+- `hasApplicationDefaultCredentials()` checks `GOOGLE_APPLICATION_CREDENTIALS` or `~/.config/gcloud/application_default_credentials.json`.
+- `vertexModelsToServerModels(config)` / `createVertexModelCatalog(models)` build the catalog with short aliases (`sonnet` / `haiku` / `opus`) and `[1m]` context variants. Defaults: `claude-sonnet-4-6`, `claude-opus-4-6`, `claude-haiku-4-5`. An optional catalog override lives at `~/.rflectr/vertex-models.json` (see `assets/vertex-models.example.json`).
+
+The models route through `@ai-sdk/google-vertex/anthropic` (`VERTEX_ANTHROPIC_NPM`) — see [`../ai/translation-layer.md`](../ai/translation-layer.md).
+
+---
+
+## Auth
+
+`isAuthorized(request, serverPassword)` (`src/server/auth.ts`) accepts a `Bearer` token or `x-api-key` header and compares it to the configured server password. A `null` password (local mode) allows all callers. `extractBearerToken` and `sanitizeCredential` (first-line only) harden header parsing. In **network mode** the wizard requires a server password; it is the only gate once the port is reachable beyond localhost, so treat it as a real secret. See [`../security/credential-storage.md`](../security/credential-storage.md#server-mode-caveat).

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

@@ -0,0 +1,8 @@
+# Integrations
+
+The local proxy and the per-host harness wiring.
+
+| Doc | Covers |
+|---|---|
+| [`local-proxy.md`](local-proxy.md) | The throwaway `127.0.0.1` proxy, `ProxyRoute` dispatch, `aliasModelId`, shared translation helpers. |
+| [`harnesses.md`](harnesses.md) | Codex CLI/desktop, Gemini CLI, Claude Desktop — how each host is pointed at a translating proxy; macOS/Windows differences. |

package/library/knowledge/private/integrations/harnesses.md

@@ -0,0 +1,87 @@
+# Host Harnesses: Codex, Gemini, and the Desktop Apps
+
+> Category: Integrations | Version: 1.0 | Date: June 2026 | Status: Active
+
+How `rflectr` wires each non-Claude-Code host to a translating proxy. The Claude Code flow is in [`../architecture/launch-flow-claude.md`](../architecture/launch-flow-claude.md); this doc covers Codex CLI, Codex desktop, Gemini CLI, and Claude Desktop. Read [`local-proxy.md`](local-proxy.md) first.
+
+**Related:**
+- [`local-proxy.md`](local-proxy.md)
+- [`../infrastructure/server-gateway.md`](../infrastructure/server-gateway.md)
+- [`../ai/translation-layer.md`](../ai/translation-layer.md)
+- Source: `src/codex.ts`, `src/codex/`, `src/codex-app.ts`, `src/codex-proxy.ts`, `src/codex-responses-adapter.ts`, `src/gemini.ts`, `src/gemini/`, `src/gemini-proxy.ts`, `src/claude-app.ts`, `src/claude-desktop/`
+
+---
+
+## The pattern, and where each host departs from it
+
+Every host follows the same skeleton: find the binary → resolve provider+model → start a proxy that speaks the host's wire format → launch the child with env (CLIs) or a patched config (apps) pointing at the proxy → restore/cleanup on exit. The differences are in *how the host is pointed at the proxy* and *whether config files must be written and restored*.
+
+```mermaid
+flowchart TD
+    cli["CLI hosts (codex, gemini)"] -->|env var| proxy["translating proxy"]
+    app["Desktop apps (codex-app, claude-app)"] -->|patched config file + backup| proxy
+    proxy --> adapter["Vercel AI SDK adapter"]
+    app -.->|lock file| restore["restore original config on exit"]
+```
+
+---
+
+## Codex CLI — `rflectr codex`
+
+Entry: `runCodexCommand` (`src/codex.ts`). Codex speaks the **OpenAI Responses API**.
+
+- **Binary:** `findCodexBinary()` (`src/codex/launch.ts`).
+- **Proxy:** `startCodexProxy(routes, { requireAuth: true })` (`src/codex-proxy.ts`) serves `POST /v1/responses`, translating through `src/codex-responses-adapter.ts` (`translateResponsesRequest` → SDK params; `streamResponsesResponse` / `generateResponsesResponse` → Responses SSE/JSON).
+- **Profile:** a TOML overlay (`buildCodexProfileToml`, `src/codex/profile.ts`) written to `~/.codex/rflectr-launch.config.toml`. It defines a `model_providers.rflectr-proxy` block whose `base_url = http://127.0.0.1:<port>/v1`, `wire_api = "responses"`, and `env_key = "RFLECTR_CODEX_KEY"`. Codex is launched with `--profile rflectr-launch -m <modelId>`.
+- **Catalog:** `~/.rflectr/codex/models-<providerId>.json` (single) or `models-favorites.json` (favorites mode), via `src/codex/catalog.ts`.
+- **Env:** `RFLECTR_CODEX_KEY=proxy-local` for proxy-tier routes; direct providers get their real key via `codexProviderEnvKey()` (`src/codex/routing.ts`).
+- **Sandbox:** default `danger-full-access` (`CODEX_LAUNCH_SANDBOX`, `src/codex/profile.ts`).
+
+**Favorites catalog mode:** when `prefs.favoriteModels.length > 0`, Codex resolves each favorite via the shared `src/favorites-resolver.ts` (filtering by an `agent: 'codex'` blacklist — Zen/Go favorites are skipped, since Codex has no gateway path for them), builds a `CodexProxyRoute[]`, and starts a single multi-route proxy. Catalog slugs are `${providerId}__${modelId}`.
+
+---
+
+## Codex desktop app — `rflectr codex-app`
+
+Entry: `runCodexAppCommand` (`src/codex-app.ts`). The app can't inherit env, so its config is patched in place and restored on exit.
+
+- **Config patch:** `applyAppConfigPatch` (`src/codex/app-config.ts`) edits `~/.codex/config.toml`, writing `model`, `model_provider = 'openai'`, `openai_base_url`, `model_catalog_json`, and `model_context_window` (`buildCodexAppRootConfig`, `src/codex/app-profile.ts`). Display model defaults to `CODEX_APP_DISPLAY_MODEL = 'gpt-5.5'`.
+- **Backup + lock:** the original `config.toml` is copied to `config.toml.bak`; a lock file `~/.codex/.rflectr.lock.json` records `pid`, `configPath`, `catalogPaths`, `backupPath`, and `proxyPort`. `restoreCodexAppOverlay` (`src/codex/app-session.ts`) restores the backup on exit or recovery.
+- **Catalog:** `app-models-<providerId>.json` / `app-models-favorites.json`.
+- **Proxy:** same `startCodexProxy`, but `requireAuth: false` (the app cannot send the proxy token).
+- **`--restore`** globs `app-models-*.json` to clean up prior sessions.
+
+---
+
+## Gemini CLI — `rflectr gemini`
+
+Entry: `runGeminiCommand` (`src/gemini.ts`). Gemini speaks the **Gemini REST protocol**, and every model is routed through the proxy.
+
+- **Binary:** `findGeminiBinary()` (`src/gemini/launch.ts`).
+- **Proxy:** `startGeminiProxy(routes, debug?)` (`src/gemini-proxy.ts`) serves `GET /v1beta/models`, `GET /v1beta/models/<model>`, and `POST /v1beta/models/<model>:generateContent` / `:streamGenerateContent`. `translateGeminiRequest` extracts the system instruction, contents, tools, and generation config, and strips the Gemini-CLI-injected identity. Parts are parsed by `src/gemini-parts.ts`.
+- **Env:** `buildGeminiChildEnv` (`src/gemini/launch.ts`) sets `GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:<port>` and `GEMINI_API_KEY=<random proxy token>`, and clears conflicting `GOOGLE_GENAI_API_KEY` / `GOOGLE_API_KEY`.
+- **Mid-session switch:** the proxy intercepts a `.model <id>` command to switch routes without restarting.
+
+---
+
+## Claude Desktop — `rflectr claude-app`
+
+Entry: `runClaudeAppCommand` (`src/claude-app.ts`). Claude Desktop has a first-class "inference gateway" config, so instead of a per-protocol proxy it is pointed at the full **`server` gateway** (see [`../infrastructure/server-gateway.md`](../infrastructure/server-gateway.md)).
+
+- **App discovery/launch:** `src/claude-desktop/app-launch.ts` finds `Claude.app` (macOS) or `Claude.exe` (Windows) and `launchOrRestartClaudeApp()`. macOS/Windows only (`claudeAppSupported()`).
+- **Gateway injection:** a config `<uuid>.json` is written into the Claude Desktop **3P config library** — `~/Library/Application Support/Claude-3p/configLibrary/` (macOS) or `%LOCALAPPDATA%\Claude-3p\configLibrary\` (Windows) — with `inferenceProvider: 'gateway'`, `inferenceGatewayBaseUrl: http://127.0.0.1:<port>/anthropic`, `inferenceGatewayApiKey: 'dummy'`, `inferenceGatewayAuthScheme: 'bearer'`, and `coworkEgressAllowedHosts`. A `_meta.json` points `appliedId` at the new uuid (`src/claude-desktop/app-config.ts`).
+- **Backup + lock:** `_meta.json.bak` is created before the patch; a `.rflectr.lock` records `pid`, `uuid`, `proxyPort`. On exit or recovery, `cleanupSession(uuid)` / `recoverSession()` (`src/claude-desktop/app-session.ts`) restore the backup and remove the injected config.
+- **Gateway:** the in-process `startServer()` serves `/anthropic` with `createGatewayModelCatalog()`; favorites filter via `filterServerModelsByFavorites`, or a single selected model.
+
+---
+
+## Platform differences (apps)
+
+| Concern | macOS | Windows |
+|---|---|---|
+| Claude Desktop config root | `~/Library/Application Support/Claude-3p/` | `%LOCALAPPDATA%\Claude-3p\` |
+| App launch | `open` / `open -b <bundle id>` | direct `.exe` exec / registry lookup |
+| "Is it running?" | `osascript` | PowerShell `Get-Process` |
+| CLI binary discovery | `which` + fallbacks | `where` + `.cmd` priority + `%APPDATA%\npm\` |
+
+All proxies bind `127.0.0.1:0` on both platforms (Node `http.createServer`).

package/library/knowledge/private/integrations/local-proxy.md

@@ -0,0 +1,82 @@
+# The Local Proxy
+
+> Category: Integrations | Version: 1.0 | Date: June 2026 | Status: Active
+
+The throwaway HTTP server that sits between a host tool and the upstream model. This doc covers `src/proxy.ts` (the Anthropic-facing proxy) and its routing model; the Codex and Gemini variants are summarized in [`harnesses.md`](harnesses.md). Read [`../ai/translation-layer.md`](../ai/translation-layer.md) for what the proxy delegates to.
+
+**Related:**
+- [`harnesses.md`](harnesses.md)
+- [`../ai/translation-layer.md`](../ai/translation-layer.md)
+- [`../architecture/launch-flow-claude.md`](../architecture/launch-flow-claude.md)
+- Source: `src/proxy.ts`, `src/proxy-shared.ts`, `src/proxy-types.ts`, `src/upstream-forward.ts`
+
+---
+
+## What it is
+
+A local HTTP server on `127.0.0.1:<random ephemeral port>` (bind to port `0`, let the OS choose) that accepts Anthropic-format requests at `/v1/messages` and serves a synthetic `GET /v1/models`. The host tool is pointed at it via `ANTHROPIC_BASE_URL=http://127.0.0.1:<port>`. It is created at launch and torn down (`proxyHandle.close()`) when the host process exits.
+
+Two entry points:
+
+- `startProxy(completionsUrl, modelId, debug, contextWindow?, sdk?, apiKey?)` — single-model wrapper.
+- `startProxyCatalog(routes, startingAliasId, debug)` — multi-route catalog for switch-menu sessions.
+
+`startProxy` is just `startProxyCatalog` with one route. Both return a `ProxyHandle` (`{ port, token, close() }`); the `token` becomes the child's `ANTHROPIC_API_KEY`, so only the launched child can call the proxy.
+
+---
+
+## Per-request dispatch
+
+```mermaid
+flowchart TD
+    req["POST /v1/messages (Anthropic format)"]
+    req --> lookup["resolve ProxyRoute by model id (alias or real)"]
+    lookup --> fmt{"route.modelFormat"}
+    fmt -->|anthropic| fwd["relayAnthropicMessages() → {baseUrl}/v1/messages (raw)"]
+    fmt -->|"openai (else)"| sdkguard{"isSdkMigratedNpm(route.npm)"}
+    sdkguard -->|true| adapter["createLanguageModel + sdk-adapter stream/generate"]
+    fwd --> resp["Anthropic SSE / JSON back to host"]
+    adapter --> resp
+```
+
+Each `ProxyRoute` carries everything needed to serve it: `aliasId`, `realModelId`, `displayName`, `upstreamUrl` / `baseURL`, `apiKey`, `modelFormat`, `contextWindow`, `npm`, `providerId`, `authType`, `oauthAccountId`, `supportedParameters`, `reasoning`, `interleavedReasoningField`.
+
+- `modelFormat === 'anthropic'` → direct passthrough via `relayAnthropicMessages` (`src/upstream-forward.ts`), which builds Anthropic auth headers (`anthropicUpstreamHeaders`) and relays both streaming and non-streaming.
+- otherwise → the SDK adapter (`createLanguageModel` + `streamAnthropicResponse` / `generateAnthropicResponse`).
+
+`src/upstream-forward.ts` is shared by both the proxy and the `server` command's router, so the raw-forward path is identical in both. `UpstreamUnreachableError` distinguishes a network failure from an upstream error response.
+
+---
+
+## aliasModelId — making ids gateway-safe
+
+Claude Code's gateway model discovery rejects model ids that don't look like provider-prefixed gateway ids. `aliasModelId(realId, providerId)` (`src/proxy.ts`) rewrites any non-`claude-*` id to the form `anthropic-{provider}__{id}` (e.g. `anthropic-opencode-go__deepseek-v4-flash`). `claude-*` ids pass through unchanged. This is why, after a switch-menu session, a bare `claude` may show a relay alias in `/model` — Claude Code cached the gateway id (see [`../security/credential-storage.md`](../security/credential-storage.md)).
+
+The synthetic `GET /v1/models` returns one entry per route, each formatted by `formatAnthropicModelEntry` with `context_window` so the host's status bar is accurate (single-model mode only; the gateway-discovery payload carries no window).
+
+---
+
+## Shared translation helpers
+
+`src/proxy-shared.ts` holds the format-agnostic glue reused across the Anthropic, Responses, and Gemini proxies:
+
+- `sseChunk()` — formats one SSE event.
+- `encodeToolUseId()` / `splitToolUseId()` — round-trip a `thought_signature` through a tool-use id as `{id}::ts::{signature}` (see [`../ai/translation-layer.md`](../ai/translation-layer.md#the-thought_signature-round-trip)).
+- `grabRoundTripSignature()` — pull the Google/OpenAI signature off a stream part.
+- `parseToolArguments()` — tolerant JSON parse of tool-call args.
+- `serializeToolResultContent()` — normalize tool-result content blocks.
+- `silenceSdkWarnings()` — suppress noisy SDK debug logging.
+- `FullStreamPart` — the unified stream-chunk type the adapters map onto.
+
+`src/proxy-types.ts` defines the Anthropic and Gemini request/response shapes (`AnthropicMessageRequest`, `AnthropicContentBlock`, `GeminiPart`, `GeminiFunctionCall`, …).
+
+---
+
+## Variants
+
+The Codex and Gemini hosts speak different wire formats, so they have sibling proxies that share `proxy-shared.ts` and `provider-factory.ts` but expose different endpoints:
+
+- `src/codex-proxy.ts` — `startCodexProxy(routes, { requireAuth })`, endpoint `POST /v1/responses`, uses `src/codex-responses-adapter.ts`.
+- `src/gemini-proxy.ts` — `startGeminiProxy(routes, debug?)`, endpoints `GET /v1beta/models` and `POST /v1beta/models/<model>:generateContent` / `:streamGenerateContent`.
+
+See [`harnesses.md`](harnesses.md) for how each host is wired to its proxy.

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

@@ -0,0 +1,9 @@
+# Security
+
+Credential handling, environment isolation, and trust boundaries.
+
+| Doc | Covers |
+|---|---|
+| [`credential-storage.md`](credential-storage.md) | Keyring accounts, credential resolution order, the `buildChildEnv` contract (set/removed vars), per-platform key setup, trust boundaries, server-mode caveat. |
+
+For the OAuth sign-in flows that produce stored tokens, see [`../auth/oauth-device-flows.md`](../auth/oauth-device-flows.md).