@legioncodeinc/rflectr 0.1.0 → 0.1.1

package/library/requirements/completed/prd-007-oauth-device-flows/prd-007-oauth-device-flows-index.md

@@ -0,0 +1,208 @@
+# PRD-007: OAuth Device & PKCE Flows *(Retroactive)*
+
+> **Status:** Shipped
+> **Priority:** —
+> **Effort:** —
+> **Written:** June 2026
+> **Retroactive:** Yes — written after implementation (rflectr v0.2.7).
+> **Source:** `src/oauth/*`, `src/registry/refresh-credentials.ts`
+
+---
+
+## Overview
+
+Some model providers a developer might want to point Claude Code / Codex / Gemini at do not hand out a simple API key. ChatGPT (Plus/Pro), xAI SuperGrok, and GitHub Copilot authenticate the *user account* through OAuth, not a long-lived `sk-...` secret. Because rflectr runs in a terminal with no browser redirect URI to catch a callback, it uses the OAuth 2.0 **Device Authorization Grant** (RFC 8628): rflectr asks the provider for a user code, prints a verification URL, and polls the token endpoint until the user approves in their browser.
+
+This PRD documents the device-code login flows, the PKCE utilities that back them, the stored-credential shape, the lazy token-refresh path, and the static OAuth-derived model lists that stand in for the `/v1/models` endpoints those OAuth tokens cannot reach. It is the auth-acquisition counterpart to PRD-006 (credential storage), which owns where the resulting token lives.
+
+Knowledge doc: [`oauth-device-flows.md`](../../../knowledge/private/auth/oauth-device-flows.md).
+
+---
+
+## What Was Built
+
+- A shared PKCE/utility module (`src/oauth/pkce.ts`) — crypto-random verifier + SHA-256 challenge, OAuth `state` generation, and polling helpers (`positiveSecondsToMs`, `sleepMs`).
+- A stored-credential contract (`src/oauth/types.ts`) — `StoredOAuthCredential`, builders/parsers, time-based and proactive-JWT expiry checks, and the `supportsNativeOAuth()` gate over the native provider set `xai | xai-oauth | openai | openai-oauth | github-copilot`.
+- Three per-provider device-code flows:
+  - **OpenAI / ChatGPT** (`src/oauth/openai.ts`) — usercode → poll → authorization-code exchange with PKCE `code_verifier`, plus `chatgpt_account_id` extraction.
+  - **xAI / Grok** (`src/oauth/xai.ts`) — standard RFC 8628 device grant with `slow_down` handling.
+  - **GitHub Copilot** (`src/oauth/github.ts`) — GitHub device flow → `ghu_` token → second exchange for a short-lived Copilot session token.
+- A single refresh dispatcher (`src/oauth/refresh.ts`) — `oauthCredentialShouldRefresh()` and `refreshStoredOAuthCredential()` routing to the right per-provider refresh.
+- Integration into credential resolution (`src/env.ts`) — OAuth tokens are read from the keyring account `oauth:provider:<id>`, refreshed lazily and deduplicated per account, and written back; a stale-but-valid token is reused if refresh fails.
+- Static OAuth model lists (`src/data/openai-oauth-models.ts`, `src/data/xai-oauth-models.ts`) — because the OAuth tokens are rejected by the providers' `/v1/models` endpoints.
+- Placeholder/env-fallback key resolution for the refresh-models path (`src/registry/refresh-credentials.ts`).
+
+---
+
+## Goals
+
+- Let a user sign into ChatGPT, SuperGrok, or GitHub Copilot from a terminal with no localhost callback server.
+- Acquire and persist OAuth tokens in a shape that PRD-006 credential storage can read transparently (an access token comes back from `oauth:provider:<id>` just like an API key would).
+- Keep short-lived access tokens fresh automatically, without re-prompting the user, by refreshing just-in-time at credential-resolution time.
+- Provide a usable model list for OAuth providers even though their tokens cannot call the standard model-discovery endpoint.
+- Make refresh robust to transient failures (reuse a still-valid token rather than hard-failing a launch).
+
+## Non-Goals
+
+- A localhost redirect-URI / authorization-code-in-browser flow — device code is the only path (`src/oauth/openai.ts:51`, `xai.ts:115`, `github.ts:149`).
+- Making GitHub Copilot usable as a *model provider*. Copilot OAuth *login* is implemented, but Copilot-as-backend is out of scope (OpenCode loads `@ai-sdk/github-copilot` from internal `@opencode-ai/core`, not a public npm factory).
+- Live model discovery for OAuth providers — replaced by static seed lists (`src/data/openai-oauth-models.ts:7`, `xai-oauth-models.ts:6`).
+- Owning the keyring/OS-credential-store mechanics (that is PRD-006).
+
+---
+
+## Features
+
+| Feature | Provider(s) | Module | Notes |
+| --- | --- | --- | --- |
+| Device-code login (RFC 8628) | OpenAI, xAI, GitHub Copilot | `openai.ts`, `xai.ts`, `github.ts` | user code + verification URL printed, then poll |
+| PKCE verifier/challenge | OpenAI (authorization-code exchange) | `pkce.ts:22` | `challenge = base64url(SHA-256(verifier))` |
+| OAuth `state` generation | shared utility | `pkce.ts:28` | base64url of 32 random bytes |
+| `slow_down` / `authorization_pending` poll handling | OpenAI, xAI, GitHub | all three flows | interval bumped +5 s on `slow_down` (xAI/GitHub) |
+| Account-id extraction | OpenAI | `openai.ts:20` | `chatgpt_account_id` from JWT → routes to ChatGPT Codex backend |
+| Two-step token exchange | GitHub Copilot | `github.ts:57` | `ghu_` → short-lived Copilot session token |
+| Token refresh | OpenAI, xAI, GitHub | `refresh.ts:21` | `grant_type=refresh_token` (OpenAI/xAI), re-exchange `ghu_` (GitHub) |
+| Proactive JWT-expiry refresh | native providers | `types.ts:53` | decode `exp`, refresh before expiry |
+| Static OAuth model list | OpenAI, xAI | `openai-oauth-models.ts`, `xai-oauth-models.ts` | substitutes for `/v1/models` |
+| Refresh-time placeholder/env-fallback key | OpenCode-imported providers | `refresh-credentials.ts:56` | env fallback for `openai`/`anthropic` |
+
+---
+
+## Architecture & Implementation
+
+### Why device flow
+
+These hosts run in a terminal with no browser redirect URI to catch a callback. The Device Authorization Grant fits: request a user code, print a URL, poll until approval. `supportsNativeOAuth(providerId)` (`src/oauth/types.ts:71`) gates which providers offer this; the native set is defined in `NATIVE_OAUTH_PROVIDER_IDS` (`src/oauth/types.ts:68`). The `rflectr providers auth <id>` command drives it (`runProvidersAuth`, `src/providers-command.ts:221`).
+
+### Device-code flow steps (generic)
+
+```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 at keyring account oauth:provider:<id>
+```
+
+The shared `runXxxDeviceCodeFlow(onDeviceCode, opts?)` signature (`openai.ts:51`, `xai.ts:115`, `github.ts:149`) calls back with `{ url, userCode }` so the CLI can print the prompt, then polls. `opts.sleep` / `opts.now` are injectable for tests. Each poller computes a `deadline` from the device response `expires_in` (defaulting to 5 min for OpenAI/xAI, 15 min for GitHub) and a per-iteration `intervalMs` from the response `interval`, capping each sleep at the remaining time (`xai.ts:64`, `github.ts:101`, `openai.ts:77`).
+
+### Per-provider differences
+
+| Aspect | OpenAI / ChatGPT | xAI / Grok | GitHub Copilot |
+| --- | --- | --- | --- |
+| Client id | `app_EMoamEEZ73f0CkXaXp7hrann` (`openai.ts:9`) | `b1a00492-073a-47ea-816f-4c329264a828` (`xai.ts:9`) | `Iv1.b507a08c87ecfe98` — VS Code Copilot extension id (`github.ts:13`) |
+| Device endpoint | `…/api/accounts/deviceauth/usercode` (`openai.ts:58`) | `https://auth.x.ai/oauth2/device/code` (`xai.ts:11`) | `https://github.com/login/device/code` (`github.ts:14`) |
+| Poll endpoint | `…/api/accounts/deviceauth/token` (`openai.ts:82`) | `https://auth.x.ai/oauth2/token` (`xai.ts:10`) | `https://github.com/login/oauth/access_token` (`github.ts:15`) |
+| Grant on poll | proprietary device-auth, then `authorization_code` exchange at `/oauth/token` with PKCE `code_verifier` (`openai.ts:96`) | `urn:ietf:params:oauth:grant-type:device_code` (`xai.ts:12`) | `urn:ietf:params:oauth:grant-type:device_code` (`github.ts:114`) |
+| Scope | (none on device request; `client_id` only) | `openid profile email offline_access grok-cli:access api:access` (`xai.ts:13`) | `copilot` (`github.ts:17`) |
+| PKCE used | Yes — `code_verifier` returned by device-auth, sent on exchange (`openai.ts:104`) | No (standard device grant) | No (standard device grant) |
+| Pending signal | HTTP 403/404 from token poll (`openai.ts:114`) | `error: authorization_pending` JSON (`xai.ts:84`) | `error: authorization_pending` JSON (`github.ts:132`) |
+| `slow_down` handling | (margin only; no interval bump) | interval += 5 s (`xai.ts:88`) | interval += 5 s (`github.ts:136`) |
+| Second exchange | none | none | `ghu_` → Copilot session token at `…/copilot_internal/v2/token` (`github.ts:57`) |
+| Stored `refresh` field | provider refresh token | provider refresh token | the long-lived `ghu_` token itself (`github.ts:91`) |
+| Account id | `chatgpt_account_id` from JWT (`openai.ts:20`) | — | — |
+
+The GitHub two-step is the quirk to remember: the standard device flow yields a long-lived `ghu_` access token, then `exchangeForCopilotToken(ghuToken)` GETs `…/copilot_internal/v2/token` to mint a **short-lived** Copilot session token (`github.ts:57`). Because the session token is what's used at inference time, the **stored `refresh` field is the `ghu_` itself** (`github.ts:91`); `refreshGithubCopilotToken()` just re-exchanges it (`github.ts:87`).
+
+### PKCE & utilities (`src/oauth/pkce.ts`)
+
+- `generatePkce()` → `{ verifier, challenge }` with `challenge = base64url(SHA-256(verifier))` and a 64-char verifier from the unreserved-char set (`pkce.ts:22`).
+- `generateOAuthState()` → base64url of 32 random bytes (`pkce.ts:28`).
+- `generateRandomString(length)` — crypto-random from `A-Za-z0-9-._~` (`pkce.ts:10`).
+- `positiveSecondsToMs(value, defaultMs)`, `sleepMs(ms)` — polling helpers (`pkce.ts:34`, `pkce.ts:39`).
+
+### Stored credential shape (`src/oauth/types.ts`)
+
+`StoredOAuthCredential` aliases OpenCode's `OpencodeOAuthCredential` (`types.ts:7`) — `{ type: 'oauth', access, refresh, expires, accountId? }`. It is serialized to JSON and written to the keyring account `oauth:provider:<id>` (`oauthProviderKeyringAccount`, `src/env.ts:100`). Helpers:
+
+- `tokensToStoredCredential(tokens, existingRefresh?, accountId?)` — builds it from a token response, preserving the existing refresh token when the provider didn't return a new one, and defaulting `expires` to now + 1 h when `expires_in` is absent (`types.ts:16`).
+- `parseStoredOAuthCredential(raw)` — parse + validate from the keyring (`types.ts:30`).
+- `oauthCredentialNeedsRefresh(cred, skewMs?)` — true when `expires <= now + skew` (default 120 s, `types.ts:48`).
+- `accessTokenIsExpiring(token, skewMs?)` — best-effort decode of the JWT `exp` claim; opaque tokens return `false` (no proactive refresh) (`types.ts:53`).
+
+### Refresh orchestration (`src/oauth/refresh.ts` + `src/env.ts`)
+
+`oauthCredentialShouldRefresh(cred, providerId)` is true when `oauthCredentialNeedsRefresh(cred)` (time-based) **or**, for native providers, `accessTokenIsExpiring(cred.access)` (proactive JWT check) (`refresh.ts:11`). `refreshStoredOAuthCredential(providerId, cred)` dispatches to `refreshOpenAiAccessToken` / `refreshXaiAccessToken` / `refreshGithubCopilotToken` and rebuilds a `StoredOAuthCredential` via `tokensToStoredCredential`, throwing if no refresh token is present (`refresh.ts:21`).
+
+Refresh runs lazily at credential-resolution time. `readProviderSecret()` (`src/env.ts:324`) detects a JSON OAuth blob at an `oauth:provider:*` account and routes to `refreshOAuthKeyringAccount()` (`src/env.ts:290`), which:
+
+- Deduplicates per keyring account via an in-flight `Map` (`src/env.ts:296`, `oauthRefreshInflight` at `src/env.ts:109`) so concurrent launches don't double-refresh.
+- Writes the refreshed credential back to the keyring (`src/env.ts:307`).
+- **On refresh failure**, reuses the existing access token if it hasn't yet expired (`src/env.ts:311`), otherwise rethrows.
+
+The decoded *access token* (not the JSON blob) is what `resolveProviderCredential()` ultimately returns to callers (`decodeProviderSecret`, `src/env.ts:274`), so OAuth providers look identical to API-key providers downstream.
+
+### OAuth-derived model lists (PRD-003 cross-reference)
+
+OAuth tokens cannot call the providers' `/v1/models`:
+
+- **OpenAI** — the ChatGPT OAuth backend (`chatgpt.com/backend-api/codex`) has no `GET /v1/models`, and `auth.openai.com` access tokens are rejected by `api.openai.com/v1/models` (`openai-oauth-models.ts:7`). `buildOpenAiOAuthModels()` returns a static seed list of GPT/o-series models with `npm '@ai-sdk/openai'` (`openai-oauth-models.ts:56`). `CHATGPT_CODEX_UNSUPPORTED_MODELS` filters out models the Codex backend explicitly rejects (currently `gpt-5.5-fast`) (`openai-oauth-models.ts:34`).
+- **xAI** — the SuperGrok OAuth JWT is rejected by `api.x.ai/v1/models` with 401, so `buildXaiOAuthModels()` is a fallback seed list with `npm '@ai-sdk/xai'` (`xai-oauth-models.ts:6`, `xai-oauth-models.ts:40`).
+
+Both lists are consumed by the registry refresh path (`src/registry/refresh-models.ts:186`, `:226`).
+
+### Refresh-time key resolution (`src/registry/refresh-credentials.ts`)
+
+OpenCode imports often carry placeholder keys (`anything`, `ollama`, `none`, …) because OAuth/env supplies the real credential at runtime. `isPlaceholderProviderKey()` / `isLikelyPlaceholderKey()` detect those (`refresh-credentials.ts:25`, `:30`), and `resolveRefreshCredential()` falls back to an env var (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`) when the stored key looks like a placeholder (`refresh-credentials.ts:56`).
+
+---
+
+## Acceptance Criteria
+
+- [x] Device-code login is implemented for OpenAI, xAI, and GitHub Copilot with a `{ url, userCode }` callback for the CLI prompt (`openai.ts:51`, `xai.ts:115`, `github.ts:149`).
+- [x] PKCE verifier/challenge generation exists and the OpenAI flow exchanges the authorization code with a `code_verifier` (`pkce.ts:22`, `openai.ts:104`).
+- [x] Pollers honor the device `interval`, handle `authorization_pending` and `slow_down` (interval +5 s where applicable), and time out at the device `expires_in` deadline (`xai.ts:70`, `github.ts:107`, `openai.ts:81`).
+- [x] The GitHub two-step exchange mints a short-lived Copilot session token and stores the `ghu_` token as the refresh field (`github.ts:57`, `github.ts:91`).
+- [x] OpenAI account id (`chatgpt_account_id`) is extracted from the JWT for backend routing (`openai.ts:20`).
+- [x] `StoredOAuthCredential` is built/parsed/validated and persisted to keyring account `oauth:provider:<id>` (`types.ts:16`, `types.ts:30`, `env.ts:100`).
+- [x] Refresh is dispatched per provider and is both time-based and proactively JWT-based for native providers (`refresh.ts:11`, `refresh.ts:21`, `types.ts:53`).
+- [x] Refresh is deduplicated per keyring account, written back, and falls back to a stale-but-valid token on failure (`env.ts:290`, `env.ts:307`, `env.ts:311`).
+- [x] Static OAuth model lists exist for OpenAI and xAI, with Codex-unsupported models filtered (`openai-oauth-models.ts:56`, `xai-oauth-models.ts:40`, `openai-oauth-models.ts:34`).
+- [x] Placeholder-key detection with env fallback is implemented for the refresh-models path (`refresh-credentials.ts:25`, `refresh-credentials.ts:56`).
+- [x] Flows are unit-tested with injectable `sleep`/`now` (`tests/oauth.test.ts`, `tests/oauth-openai.test.ts`, `tests/oauth-github.test.ts`).
+
+---
+
+## Files
+
+| File | Role |
+| --- | --- |
+| `src/oauth/pkce.ts` | PKCE verifier/challenge, OAuth `state`, polling helpers |
+| `src/oauth/types.ts` | `StoredOAuthCredential`, builders/parsers, expiry checks, `supportsNativeOAuth` |
+| `src/oauth/openai.ts` | OpenAI ChatGPT device-code flow + PKCE exchange + account-id + refresh |
+| `src/oauth/xai.ts` | xAI SuperGrok device-code flow + refresh |
+| `src/oauth/github.ts` | GitHub Copilot device flow + two-step Copilot-token exchange + refresh |
+| `src/oauth/refresh.ts` | Single refresh dispatcher (`oauthCredentialShouldRefresh`, `refreshStoredOAuthCredential`) |
+| `src/registry/refresh-credentials.ts` | Placeholder-key detection + env-fallback for refresh-models |
+| `src/data/openai-oauth-models.ts` | Static ChatGPT-OAuth model seed list + Codex-unsupported filter |
+| `src/data/xai-oauth-models.ts` | Static SuperGrok-OAuth model fallback seed list |
+| `src/env.ts` (integration) | OAuth read/refresh/write-back at `oauth:provider:<id>`, dedup, stale-token fallback |
+| `src/providers-command.ts` (integration) | `rflectr providers auth <id>` entry point |
+
+---
+
+## Risks & Known Limitations
+
+- **OAuth providers with no stored key are silently skipped in some local-provider paths.** `normalizeProviders` skips providers whose `key` field is empty, which is exactly how OAuth-only providers (configured via browser login, no `sk-...`) appear. This is documented as by-design in the project notes; rflectr's own native OAuth path (`oauth:provider:<id>`) is the supported way to use these accounts.
+- **GitHub Copilot works as a login but not as a model provider** — OpenCode loads `@ai-sdk/github-copilot` from internal `@opencode-ai/core`, not a public npm factory rflectr can ship.
+- **No live model discovery for OAuth providers** — model lists are static seeds (`src/data/*-oauth-models.ts`) and must be hand-updated as providers change offerings. Codex-rejected models are filtered by a hard-coded set (`CHATGPT_CODEX_UNSUPPORTED_MODELS`).
+- **Proactive refresh only works for JWT access tokens** — `accessTokenIsExpiring()` returns `false` for opaque tokens, so those rely solely on the time-based `expires` field (`types.ts:53`).
+- **`::ts::`-style or other separator collisions** are not a concern here, but the `ghu_`-as-refresh design means a revoked GitHub OAuth grant surfaces only at the next Copilot-token exchange.
+- **Best-effort error reuse** — if refresh fails and the access token is already expired, the launch fails hard (`env.ts:312`); there is no interactive re-auth prompt at launch time.
+
+---
+
+## Related
+
+- [`oauth-device-flows.md`](../../../knowledge/private/auth/oauth-device-flows.md) — knowledge doc this PRD is grounded in.
+- [PRD-006 — Credential Storage & API Key Management](../prd-006-credential-storage/prd-006-credential-storage-index.md) — owns the OS keyring / credential store where OAuth tokens live.
+- [PRD-002 — Provider Registry](../prd-002-provider-registry/prd-002-provider-registry-index.md) — how an OAuth provider is registered and resolved (`authRef` = `keyring:oauth:provider:<id>`).
+- [PRD-003 — Model Discovery & Classification](../prd-003-model-discovery-classification/prd-003-model-discovery-classification-index.md) — consumes the static OAuth model seed lists.

package/library/requirements/completed/prd-008-preferences-tiers-favorites/prd-008-preferences-tiers-favorites-index.md

@@ -0,0 +1,249 @@
+# PRD-008: Preferences, Subscription Tiers & Favorites *(Retroactive)*
+
+> **Status:** Shipped
+> **Priority:** —
+> **Effort:** —
+> **Written:** June 2026
+> **Retroactive:** Yes — written after implementation (rflectr v0.2.7).
+> **Source:** `src/config.ts`, `src/favorites.ts`, `src/favorites-resolver.ts`, `src/prompts.ts`
+
+---
+
+## Overview
+
+`rflectr` keeps a small, durable layer of user state so the CLI feels personal across sessions: the last backend/model/provider you launched, recently used models per provider, a curated list of favorite models for the mid-session `/model` switch menu, and per-command `server` settings. All of it lives in a single JSON file under a per-user app-home directory, resolved with an override hook and migrated transparently from two earlier locations.
+
+On top of that state sit three interaction systems:
+
+1. **Preferences store** — read/write helpers around `~/.rflectr/config.json`, with legacy-path migration and a `--dry-run` write-skip contract.
+2. **Subscription / Zen tier filtering** — a `RegistrySubscriptionFilter` (`free` / `zen` / `go`) carried on the OpenCode Zen registry stub that scopes which cloud models surface; seeded as `free` during first-run.
+3. **Favorites** — a manager command (`rflectr models`) plus a resolver shared with the Codex catalog, capped at `MAX_MODEL_CATALOG` (20), and a large-catalog UX (search + pagination) that keeps long model lists navigable.
+
+This PRD documents what was built, grounded in the shipped code.
+
+---
+
+## What Was Built
+
+- A single app-home directory (`~/.rflectr`, override via `RFLECTR_HOME`) holding `config.json` and sibling files, created `0o700` / files `0o600` (`src/paths.ts:28`, `src/config.ts:63`).
+- `loadPreferences()` / `savePreferences()` with a shallow per-key merge so callers pass only what changed (`src/config.ts:67`, `src/config.ts:85`).
+- `recordLaunchSelection(agent, providerId, modelId, prefs)` — updates the per-agent `last*` fields and prepends to `recentModelsByProvider` (deduped, capped at 3) (`src/config.ts:101`).
+- Two-stage legacy migration: dotfile dir (`~/.opencode-starter`) then OS `conf` store, both one-directional and idempotent (`src/config.ts:17`, `src/config.ts:34`).
+- `lastProvider === 'opencode'` normalized to `'zen'` on read (`src/config.ts:70`).
+- Pure favorites algebra: `isFavorite`, `addFavorite` (duplicate / cap results), `removeFavorite` (`src/favorites.ts`).
+- The `rflectr models` favorites manager: list / add (global search or browse-by-provider, multi-select) / remove, single save on Done (`src/cli.ts:534`).
+- A surface-agnostic favorites resolver shared by Claude and Codex (`src/favorites-resolver.ts`).
+- Recent-models hint at the top of the local-model picker, with a "Browse all models →" escape hatch (`src/prompts.ts:305`).
+- Large-catalog UX: search at `MODEL_SEARCH_THRESHOLD = 25`, pagination at `MODEL_PAGE_SIZE = 15` (`src/prompts.ts:22`).
+- Inline, never-dead-end first-run wizard that ends in launch or explicit cancel (`src/first-run.ts:36`).
+
+---
+
+## Goals
+
+- Persist enough state that repeat launches pre-select the user's prior choice rather than starting cold.
+- Make a curated multi-model `/model` switch menu possible without re-picking every session.
+- Keep one canonical config location, surviving the project's two historical renames without user action.
+- Honor `--dry-run` as a true no-write simulation of a fresh first run.
+- Keep long provider model lists usable (search / paginate) instead of dumping 100+ entries into one prompt.
+
+## Non-Goals
+
+- Touching `~/.claude/settings.json` — launch config is env-var-only (see [PRD-001](../prd-001-cli-core-launch-orchestration/prd-001-cli-core-launch-orchestration-index.md)).
+- Storing secrets in `config.json` — API keys live in the OS credential store ([PRD-006](../prd-006-credential-storage/) — folder pending). The server password is migrated *out* of `config.json` into the keyring on first read (`src/config.ts:131`).
+- Cloud-syncing preferences across machines (the file is per-user, per-host).
+
+---
+
+## Features
+
+| # | Feature | Entry point | Notes |
+|---|---------|-------------|-------|
+| F1 | App-home resolution + override | `getAppHome()` (`src/paths.ts:28`) | `RFLECTR_HOME` (or deprecated `OPENCODE_STARTER_HOME`) wins, else `~/.rflectr` |
+| F2 | Preferences load/save (shallow merge) | `loadPreferences` / `savePreferences` (`src/config.ts:67`) | Pass only changed keys |
+| F3 | Record launch selection | `recordLaunchSelection` (`src/config.ts:101`) | Per-agent `last*` + recent list (max 3, dedup) |
+| F4 | Legacy migration (2 stages) | `ensureConfigMigrated` (`src/config.ts:34`) | Dotfile dir → OS conf store; idempotent |
+| F5 | Subscription/Zen tier filter | `RegistrySubscriptionFilter` (`src/registry/types.ts:7`) | `free` / `zen` / `go` on the Zen stub |
+| F6 | Favorites algebra | `addFavorite` / `removeFavorite` (`src/favorites.ts`) | Cap at `MAX_MODEL_CATALOG` (20) |
+| F7 | Favorites manager command | `runModelsCommand` (`src/cli.ts:534`) | `rflectr models`; saves once on Done |
+| F8 | Favorites resolver (shared) | `resolveFavorite` / `buildFavoritesList` (`src/favorites-resolver.ts:52`) | Stale favorites dropped silently |
+| F9 | Recent-models picker | `pickLocalModel` (`src/prompts.ts:305`) | Recent shown first + "Browse all" |
+| F10 | Large-catalog search/pagination | `selectModelWithSearch` / `selectLargeCatalog` (`src/prompts.ts:246`) | Thresholds 25 / 15 |
+| F11 | First-run wizard | `runFirstRunWizard` (`src/first-run.ts:36`) | Zen quick-start / import / providers |
+
+---
+
+## Architecture & Implementation
+
+### Config store schema
+
+`config.json` is parsed into `UserPreferences` (`src/types.ts:72`). Unknown keys are tolerated; everything is optional.
+
+| Field | Type | Purpose | Cite |
+|-------|------|---------|------|
+| `lastBackend` | `'zen' \| 'go'` | Last cloud backend launched | `src/types.ts:73` |
+| `lastModel` | `string` | Last Claude Code model (pre-selects wizard) | `src/types.ts:74` |
+| `lastProvider` | `string` | Last Claude Code provider (`'opencode'`→`'zen'` on read) | `src/config.ts:70` |
+| `lastCodexProvider` / `lastCodexModel` | `string` | Last Codex selection | `src/types.ts:76` |
+| `lastGeminiProvider` / `lastGeminiModel` | `string` | Last Gemini selection | `src/types.ts:78` |
+| `recentModelsByProvider` | `Record<string,string[]>` | Up to 3 recent model ids per provider | `src/types.ts:80` |
+| `favoriteModels` | `FavoriteModel[]` | `{ providerId, modelId }`, max 20 | `src/types.ts:81` |
+| `server` | object | `savedPassword`, `exposedProviders`, `maskGatewayIds`, `favoritesOnly` | `src/types.ts:82` |
+
+**Write path.** `writeConfig()` creates the parent dir `0o700` and writes the file `0o600` with a trailing newline (`src/config.ts:61`). `savePreferences()` is a key-by-key conditional merge — every field is copied through only when `!== undefined`, so partial updates never clobber siblings (`src/config.ts:85`).
+
+> **Note on `subscriptionTier`.** Earlier drafts of the design (and `CLAUDE.md`) describe a `subscriptionTier` (`free`/`zen`/`go`/`both`) preference field. In the shipped v0.2.7 code that field is **not** part of `UserPreferences`, `loadPreferences()`, or `savePreferences()`. The tier concept survives instead as `RegistrySubscriptionFilter` on the registry's Zen provider stub (see *Tier behavior* below). This PRD documents the code as shipped.
+
+### App home & override
+
+`getAppHome(env)` returns `resolveAppHomeOverride(env)` when `RFLECTR_HOME`/`OPENCODE_STARTER_HOME` is set (trimmed, non-empty), else `~/.rflectr` (`src/paths.ts:23`, `src/paths.ts:28`). Sibling path helpers (`getConfigPath`, `getProvidersPath`, `getLogsPath`, `getVertexModelsPath`) all derive from it (`src/paths.ts:38`).
+
+### Legacy migration
+
+`readConfig()` runs `ensureConfigMigrated()` before every read (`src/config.ts:56`). Both stages bail the instant `~/.rflectr/config.json` already exists, making migration idempotent:
+
+1. `ensureAppHomeMigrated()` copies `~/.opencode-starter/config.json` (and `vertex-models.json` alongside) into the new home (`src/config.ts:17`).
+2. `ensureConfigMigrated()` then copies the even-older OS `conf` file (`getLegacyConfPath`, platform-specific — `src/paths.ts:54`) and best-effort renames the source to `…​.migrated` (`src/config.ts:49`).
+
+### Tier behavior
+
+The Zen registry stub carries an optional `subscriptionFilter: RegistrySubscriptionFilter` (`src/registry/types.ts:7`, `src/registry/builtins.ts:7`). First-run seeds it as `'free'` via `zenRegistryStub('free')` (`src/first-run.ts:31`). The filter scopes which OpenCode cloud models surface; combined Zen+Go lists track the originating backend per model so the correct base URL is set per selection (see [PRD-003](../prd-003-model-discovery-classification/) for model-discovery merge and `sourceBackend`).
+
+| Filter | Behavior |
+|--------|----------|
+| `free` | Zen free models only — seeded default on first-run (`src/first-run.ts:31`) |
+| `zen` | Zen backend models |
+| `go` | OpenCode Go (paid) backend models |
+
+`lastBackend` (`'zen' \| 'go'`) records the most recently launched cloud backend independently of the filter (`src/types.ts:73`). The two cloud backends are defined in `BACKENDS` (`src/constants.ts:9`); their `baseUrl` must **not** include `/v1` (the Anthropic SDK appends `/v1/messages`).
+
+### Favorites flow
+
+Pure algebra (`src/favorites.ts`):
+
+- `isFavorite(list, fav)` — `providerId` + `modelId` equality.
+- `addFavorite(list, fav, max=MAX_MODEL_CATALOG)` returns `{ ok:false, reason:'duplicate' }`, `{ ok:false, reason:'cap' }`, or `{ ok:true, list }` (`src/favorites.ts:14`).
+- `removeFavorite(list, fav)` — filtered copy (`src/favorites.ts:24`).
+
+Manager (`runModelsCommand`, `src/cli.ts:534`): fetches the provider catalog, builds a `providerId:modelId → label` lookup, then loops a menu where each favorite row removes-on-select, `+ Add a model →` offers global cross-provider search (`pickGlobalFavoriteModel`, `src/favorites-picker.ts:85`) or browse-by-provider multi-select, and `Done` exits. State is held in memory and written **once** on exit via `savePreferences({ favoriteModels })` only when `favoritesDirty` (`src/cli.ts:728`). The cap is enforced both in the UI (`atCap` disables Add, `src/cli.ts:579`) and in `addFavorite`.
+
+**Resolution shared with Codex.** `resolveFavorite(fav, ctx)` (`src/favorites-resolver.ts:52`) is route-shape-agnostic — each surface (Claude / Codex / Server) builds its own `ResolveContext`. Zen/Go favorites resolve against `zenModels`/`goModels` + `zenGoApiKey` and carry `sourceBackend`; registry favorites resolve via `ctx.findLocalModel` and are dropped when `ctx.agent` blacklists them via `shouldHideModel` (`src/favorites-resolver.ts:73`). `buildFavoritesList(starting, favorites, ctx, max=20)` dedups (starting model + favorites), caps at `max`, and returns `{ resolved, droppedFavorites }` — **stale / unavailable favorites are silently skipped** (`src/favorites-resolver.ts:87`). Resolved favorites become catalog routes (see [PRD-005](../prd-005-local-proxy-catalog-routing/)); the Codex catalog consumes the same resolver (see [PRD-009](../prd-009-codex-integration/prd-009-codex-integration-index.md)).
+
+### Recent models per provider
+
+On launch, `recordLaunchSelection()` prepends the chosen model id to `recentModelsByProvider[providerId]`, dedupes, and slices to `MAX_RECENT_MODELS = 3` (`src/config.ts:99`, `src/config.ts:107`). `pickLocalModel()` reads them back, showing up to 3 with a `'recent'` hint plus a "Browse all models →" option; when there are none it goes straight to the full browse (`src/prompts.ts:311`).
+
+### Large-catalog UX
+
+`selectModelWithSearch()` shows a flat list when `models.length <= MODEL_SEARCH_THRESHOLD` (25), otherwise delegates to `selectLargeCatalog()` which offers search vs paginated browse at `MODEL_PAGE_SIZE` (15) per page (`src/prompts.ts:246`, `src/prompts.ts:155`). `pickModelFromPagedList()` provides prev/next paging and computes the initial page from a target model id (`src/prompts.ts:87`). Search tokenizes the query on whitespace + punctuation with AND logic across id/name/brand (`src/prompts.ts:52`).
+
+### First-run
+
+`needsFirstRunSetup()` returns true only when the registry is empty **and** no Zen/Go key is stored (`src/first-run.ts:21`). `runFirstRunWizard()` offers Zen quick-start (collect key → seed `zenRegistryStub('free')`), import-from-OpenCode, or set-up-your-own-provider — and every branch terminates in `continue` (launch) or explicit `cancel`, never a dead end (`src/first-run.ts:36`).
+
+### `--dry-run`
+
+All preference writes are gated on the caller passing `dryRun`. In dry-run, favorites load as `[]` (`src/cli.ts:761`) and the launch path skips `recordLaunchSelection`, so a fresh first-run is fully simulated without mutating `config.json`.
+
+---
+
+## Data Shapes
+
+```ts
+// src/types.ts:67
+export interface FavoriteModel {
+  providerId: string;
+  modelId: string;
+}
+
+// src/types.ts:72
+export interface UserPreferences {
+  lastBackend?: 'zen' | 'go';
+  lastModel?: string;
+  lastProvider?: string;
+  lastCodexProvider?: string;
+  lastCodexModel?: string;
+  lastGeminiProvider?: string;
+  lastGeminiModel?: string;
+  recentModelsByProvider?: Record<string, string[]>;
+  favoriteModels?: FavoriteModel[];
+  server?: {
+    savedPassword?: string;
+    exposedProviders?: string[];
+    maskGatewayIds?: boolean;
+    favoritesOnly?: boolean;
+  };
+}
+
+// src/registry/types.ts:7
+export type RegistrySubscriptionFilter = 'free' | 'zen' | 'go';
+
+// src/favorites-resolver.ts:8
+export interface ResolvedFavorite {
+  providerId: string;
+  providerName: string;
+  model: LocalProviderModel | ServerModelInfo;
+  apiKey: string;
+  sourceBackend?: 'zen' | 'go';
+}
+```
+
+---
+
+## Acceptance Criteria
+
+- [x] App home resolves from `RFLECTR_HOME` (or deprecated `OPENCODE_STARTER_HOME`), else `~/.rflectr` (`src/paths.ts:23`).
+- [x] Config dir created `0o700`, file written `0o600` with trailing newline (`src/config.ts:61`).
+- [x] `savePreferences()` shallow-merges, copying only defined keys (`src/config.ts:85`).
+- [x] `recordLaunchSelection()` sets per-agent `last*` and prepends to `recentModelsByProvider`, deduped and capped at 3 (`src/config.ts:101`).
+- [x] Legacy migration runs both stages, is idempotent, and renames the old conf file best-effort (`src/config.ts:34`).
+- [x] `lastProvider === 'opencode'` is normalized to `'zen'` on read (`src/config.ts:70`).
+- [x] Zen registry stub carries a `subscriptionFilter`, seeded `'free'` at first-run (`src/first-run.ts:31`, `src/registry/builtins.ts:7`).
+- [x] `addFavorite` rejects duplicates and enforces the `MAX_MODEL_CATALOG` (20) cap (`src/favorites.ts:14`).
+- [x] `rflectr models` saves favorites once on Done, only when dirty (`src/cli.ts:728`).
+- [x] Favorites resolver drops stale/unavailable favorites silently and is shared across Claude/Codex/Server (`src/favorites-resolver.ts:87`).
+- [x] `buildFavoritesList` dedups starting model + favorites and caps at `max` (`src/favorites-resolver.ts:103`).
+- [x] `pickLocalModel` surfaces up to 3 recent models with a "Browse all" escape hatch (`src/prompts.ts:311`).
+- [x] Lists above `MODEL_SEARCH_THRESHOLD` (25) switch to search/paginated browse at `MODEL_PAGE_SIZE` (15) (`src/prompts.ts:257`).
+- [x] First-run wizard never dead-ends; every path returns `continue` or `cancel` (`src/first-run.ts:36`).
+- [x] `--dry-run` loads favorites as `[]` and skips all preference writes (`src/cli.ts:761`).
+
+---
+
+## Files
+
+| File | Role |
+|------|------|
+| `src/config.ts` | Read/write preferences, legacy migration, server-password keyring move, recent-models recording |
+| `src/paths.ts` | App-home resolution, override hook, sibling path helpers, legacy conf path |
+| `src/types.ts` | `UserPreferences`, `FavoriteModel` shapes |
+| `src/favorites.ts` | Pure favorites algebra (`isFavorite`/`addFavorite`/`removeFavorite`) |
+| `src/favorites-picker.ts` | Global cross-provider favorite search (`pickGlobalFavoriteModel`) |
+| `src/favorites-resolver.ts` | Surface-agnostic favorite → route resolution, shared with Codex |
+| `src/prompts.ts` | `pickLocalModel`, recent-models, large-catalog search/pagination |
+| `src/first-run.ts` | Inline never-dead-end first-run wizard |
+| `src/cli.ts` | `runModelsCommand` favorites manager; launch-time recent/favorite wiring |
+| `src/constants.ts` | `BACKENDS`, `MAX_MODEL_CATALOG` |
+| `src/registry/builtins.ts` | Zen/Go registry stubs carrying `subscriptionFilter` |
+| `src/registry/types.ts` | `RegistrySubscriptionFilter` type |
+
+---
+
+## Risks & Known Limitations
+
+- **`subscriptionTier` drift:** the field named in `CLAUDE.md` is not present in shipped code; tier filtering is registry-stub-based (`subscriptionFilter`). Documentation that references a `subscriptionTier` preference key is stale.
+- **Stale favorites are invisible:** unavailable favorites (provider removed, model retired) are silently dropped at resolution time; in the `rflectr models` list they render as `★ <id> — provider gone` (`src/cli.ts:575`) but are not auto-pruned from `config.json`.
+- **No schema versioning:** `config.json` has no version field; forward/backward compat relies on all keys being optional and unknown keys being tolerated.
+- **Per-host only:** preferences are not synced across machines.
+- **Best-effort legacy rename:** if renaming the old conf file to `…​.migrated` fails (permissions), the copy still succeeds but the stale source remains (`src/config.ts:51`).
+- **Context window in switch-menu mode** reflects the launch model, not live `/model` switches — a downstream limitation of the catalog/gateway path (see [PRD-005](../prd-005-local-proxy-catalog-routing/)), not the preferences layer.
+
+---
+
+## Related
+
+- **Knowledge:** [`preferences-config.md`](../../../knowledge/private/data/preferences-config.md)
+- [PRD-001 — CLI Core & Launch Orchestration](../prd-001-cli-core-launch-orchestration/prd-001-cli-core-launch-orchestration-index.md) — launch flow that reads/writes these preferences
+- [PRD-003 — Model Discovery & Classification](../prd-003-model-discovery-classification/) — tier-scoped model lists, `sourceBackend` merge
+- [PRD-005 — Local Proxy & Catalog Routing](../prd-005-local-proxy-catalog-routing/) — catalog routes built from resolved favorites
+- [PRD-009 — Codex Integration](../prd-009-codex-integration/prd-009-codex-integration-index.md) — Codex favorites catalog using the shared resolver