@legioncodeinc/rflectr 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@legioncodeinc/rflectr",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "publishConfig": {
     "access": "public"
   },
@@ -24,6 +24,9 @@
     "vertex"
   ],
   "type": "module",
+  "files": [
+    "dist"
+  ],
   "bin": {
     "rflectr": "dist/cli.js"
   },

package/.markdown-link-check.json

@@ -1,7 +0,0 @@
-{
-  "ignorePatterns": [
-    {
-      "pattern": "^https://www\\.npmjs\\.com/package/"
-    }
-  ]
-}

package/AGENTS.md

@@ -1,169 +0,0 @@
-# AGENTS.md
-
-This file provides guidance to Codex (Codex.ai/code) when working with code in this repository. Note that the codebase supports Claude Code, OpenAI Codex, and Google Gemini CLI.
-
-## Commands
-
-```bash
-npm run build       # compile TypeScript → dist/cli.js (via tsup, ESM, shebang injected)
-npm test            # run all tests with vitest
-npm run typecheck   # type-check without emitting (tsc --noEmit)
-npm run dev         # watch mode build
-
-# Run a single test file
-npx vitest run tests/env.test.ts
-npx vitest run tests/models.test.ts
-
-# Test the CLI locally (already npm-linked)
-rflectr --help
-rflectr models          # manage favorite models for mid-session switching
-rflectr Codex --dry-run   # simulate full first-run without writing anything
-rflectr Codex --setup    # re-ask subscription tier
-rflectr Codex --trace    # write debug log to /tmp/rflectr-debug.log and print errors on exit
-rflectr server           # foreground OpenCode/registry API gateway
-rflectr server --vertex  # foreground Vertex AI gateway (gcloud ADC)
-rflectr codex            # Codex CLI with registry providers (see library/knowledge/public/guides/codex.md)
-rflectr codex-app        # Codex desktop app (macOS/Windows; see library/knowledge/public/guides/codex.md)
-rflectr gemini           # Gemini CLI with registry providers (see library/knowledge/public/guides/gemini-cli.md)
-
-# Rebuild after code changes before testing manually
-npm run build && rflectr --version
-```
-
-## Architecture
-
-**Entry point:** `src/cli.ts` orchestrates the full flow. Every other module is a focused unit with no side effects at import time.
-
-**Data flow (`rflectr Codex`):**
-```
-cli.ts
-  → findClaudeBinary()         [launch.ts — locate Codex binary]
-  → fetchLocalProviders()      [providers.ts — ephemeral opencode serve, GET /config/providers, normalize]
-  → p.select "Which provider?" [shown when local providers are available]
-
-  ── OpenCode cloud path (default) ──
-  → resolveOrCollectApiKey()   [reads env, OS credential store (all platforms), or prompts user]
-  → askSubscriptionTier()      [prompts.ts — one-time question, saved to conf store]
-  → getModels()                [models.ts — API fetch + cache enrichment + format classification]
-  → runWizard()                [prompts.ts — backend/model selector, filters unsupported]
-
-  ── Local provider path ──
-  → pickLocalModel()           [prompts.ts — filter/select model from local provider]
-
-  ── Shared launch (no favorites) ──
-  → startProxy()               [proxy.ts — single-model wrapper around startProxyCatalog]
-  → buildChildEnv(baseUrl, …)  [env.ts — removes 17 conflicting vars, sets OpenCode vars]
-  → launchClaude()             [launch.ts — spawn with stdio:inherit]
-  → proxyHandle.close()        [stops proxy after Codex exits]
-
-  ── Switch-menu launch (favorites.length > 0) ──
-  → buildCatalogRoutes()       [catalog.ts — starting model + favorites, max 20]
-  → startProxyCatalog()        [proxy.ts — multi-route proxy, alias IDs per model]
-  → buildChildEnv(…, gatewayDiscovery=true)  [sets CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1]
-  → launchClaudeViaCatalog()   [cli.ts — shared launch + trace cleanup]
-```
-
-**`rflectr models`:** Interactive favorites manager (`src/favorites.ts`). Reads/writes `favoriteModels` in config. Saves once on Done. Stale favorites (unavailable models) are silently skipped when building the catalog.
-
-**Catalog routing** (`src/catalog.ts`): `localModelToRoute`, `zenGoModelToRoute`, `makeRouteResolver`, `buildCatalogRoutes`. Routes built only for starting model + favorites — not the full model list. Alias IDs via `aliasModelId()` in proxy so Codex sees unique model names in `/model`.
-
-**Critical URL constraint:** `BACKENDS.baseUrl` in `constants.ts` must NOT include `/v1`. The Anthropic SDK appends `/v1/messages` automatically. Setting it to `https://opencode.ai/zen/v1` would cause requests to hit `/zen/v1/v1/messages` → 404.
-
-**Model discovery two-source merge:**
-- Primary: `GET {backendUrl}/v1/models` (no auth needed, returns available IDs)
-- Enrichment: `~/.cache/opencode/models.json` (written by OpenCode CLI) — provides `name`, `family`, `cost`, `provider.npm`
-- `isAnthropicNative`: true when `modelFormat === 'anthropic'`
-- `modelFormat`: classified from `provider.npm` in cache, or by ID-prefix heuristic:
-  - `@ai-sdk/anthropic` or `Codex-*` → `'anthropic'` (direct passthrough)
-  - `@ai-sdk/openai` or `gpt-*` → `'unsupported'` in the **cloud OpenCode wizard** (OpenCode Zen/Go proxy layer; not direct OpenAI). Use the **local OpenAI provider** instead for GPT models.
-  - `@ai-sdk/google` or `gemini-*` → `'unsupported'` (needs model-specific endpoints)
-  - Everything else → `'openai'` (routed through the SDK adapter via the local proxy)
-- `sourceBackend`: set from the backend that was queried — critical for `go` tier which shows Zen free models + Go paid models in one list, so the correct `ANTHROPIC_BASE_URL` can be set per selected model
-
-**Translation layer — the Vercel AI SDK adapter** (`src/sdk-adapter.ts` + `src/provider-factory.ts`): All non-Anthropic providers route through the Vercel AI SDK (`ai` + `@ai-sdk/*`, the same packages OpenCode loads), which owns wire format, endpoint selection, and provider quirks. This is the **single** translation path — there is no hand-rolled per-provider translation.
-
-- **`provider-factory.ts`** — `createLanguageModel({ npm, modelId, apiKey, baseURL })` (async) maps whatever `api.npm` OpenCode assigns to an SDK `LanguageModel` via dynamic `import(npm)` + `create*` factory discovery. Special branches for OpenAI/xAI Responses API selection and openai-compatible/openrouter base URLs. `isSdkMigratedNpm(npm)` is true for any npm except `@ai-sdk/anthropic`. `modelPrefersResponsesApi(modelId)` selects `provider.responses(id)` over `provider.chat(id)` for OpenAI/xAI models that require the Responses API (GPT-5.4+, GPT-5.5, `*-codex`, o-series, xAI `*-multi-agent`). OpenCode's bundled SDK provider packages ship as npm `dependencies` (externalized in tsup, loaded on demand).
-- **`sdk-adapter.ts`** — Anthropic `/v1/messages` ↔ SDK, one turn per request (Codex owns the tool loop). `translateRequest(body, npm)` builds the SDK call params (messages, tools, tool_choice, system) and folds inline `role:'system'` messages — Codex injects the skills list / system-reminders this way — into the system prompt so they aren't dropped. `streamAnthropicResponse` maps the SDK `fullStream` to Anthropic SSE; `generateAnthropicResponse` handles non-streaming. `thought_signature` round-trips: encoded into the Anthropic `tool_use.id` as `{id}::ts::{signature}` and decoded back into `providerOptions.google.thoughtSignature` (Gemini puts the signature on the tool-call parts, captured at `tool-input-start`). The SDK handles Gemini's strict `thought_signature` echo-back correctly — the reason a hand-rolled Gemini-native path used to be required.
-
-**Local proxy** (`src/proxy.ts`): a local HTTP server on `127.0.0.1:<random-port>` that accepts Anthropic-format requests at `/v1/messages` and dispatches per route (`startProxyCatalog`/`startProxy`): `modelFormat === 'anthropic'` → direct passthrough to the provider's Anthropic endpoint; otherwise → `isSdkMigratedNpm(route.npm)` → the SDK adapter. Each `ProxyRoute` carries `npm` + `baseURL`. `GET /v1/models` returns a synthetic catalog including `context_window` per model (via `formatAnthropicModelEntry` / `resolveContextWindow`) so Codex's status bar shows accurate remaining context. `aliasModelId()` rewrites non-`Codex-*` ids to `anthropic-{provider}__{id}` so gateway model discovery accepts them.
-
-**Subscription tiers** control which models are shown and whether a backend selector appears:
-- `free` / `zen`: always Zen backend, no backend selector
-- `go`: Go backend, but also fetches Zen for free models — combined list, backend inferred from `sourceBackend` of selected model
-- `both`: shows backend selector
-
-**Env isolation:** `buildChildEnv()` copies `process.env`, deletes all 17 vars in `CONFLICTING_ENV_VARS`, then sets `ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL`. `launchClaude()` also passes `--model`. Isolation applies to the child process only — the parent shell is not mutated (except `OPENCODE_API_KEY` during key setup). Codex may persist the model to `~/.Codex/settings.json` independently; that is outside rflectr's control.
-
-**Preferences** (at `~/.rflectr/config.json`, migrated from legacy `conf` path on first read): `lastBackend`, `lastModel`, `lastProvider`, `recentModelsByProvider`, `favoriteModels`, `subscriptionTier`, and a 1-hour model list cache. Override path with `RFLECTR_HOME`. All writes are skipped when `dryRun === true`.
-
-**API key storage** uses `@napi-rs/keyring` (installed as `optionalDependencies`) for cross-platform credential store access. The module is loaded via dynamic `import()` so a missing native binary degrades gracefully. `tsup.config.ts` marks `@napi-rs/keyring` and all `@ai-sdk/*` provider packages as `external` so they resolve from `node_modules` at runtime (keeps `dist/cli.js` small).
-
-On startup, `resolveOrCollectApiKey()` silently calls `readFromCredentialStore()` — if a key is found the prompt is skipped entirely.
-
-Save options per platform:
-- **macOS** (4 options): Keychain only | Keychain + `~/.zshrc` auto-load | shell profile (plaintext) | session only
-  - The `~/.zshrc` auto-load line uses the `security` CLI directly (so the shell can source it): `export OPENCODE_API_KEY="$(security find-generic-password -s rflectr -a rflectr -w 2>/dev/null)"`
-- **Windows** (3 options): Windows Credential Manager | `setx` user env var (plaintext) | session only
-  - `setx` is called with `stdio: ['pipe','pipe','pipe']` to suppress its "SUCCESS" stdout
-- **Linux desktop** (3 options): Secret Service (GNOME Keyring / KWallet) | shell profile (plaintext) | session only
-  - Secret Service availability is probed via a test `getPassword()` call — returns false if the daemon isn't running
-- **Linux headless** (2 options): shell profile | session only — shown with a `p.log.info` note explaining why secure storage is unavailable
-
-In all cases `process.env['OPENCODE_API_KEY']` is set immediately so the key is active for the current session regardless of save choice.
-
-**Local provider discovery** (`src/providers.ts`): `fetchLocalProviders()` spawns `opencode serve --port 0`, waits for the listening URL in stdout/stderr (10s timeout, spinner shown in CLI), fetches `GET /config/providers`, then kills the process. `normalizeProviders()` (called internally) skips OAuth providers (empty key), and classifies each model via `resolveEndpoint(npm, apiUrl)`: `@ai-sdk/anthropic` → passthrough; `@ai-sdk/openai-compatible` without `api.url` → skip; any other non-empty `api.npm` → SDK adapter (`format: 'openai'`). OpenCode is the source of truth for which providers/models appear — rflectr does not maintain a per-package allowlist. Each model captures `api.npm`, `api.url` (`apiBaseUrl`), and `api.id` (`upstreamModelId` for SDK/upstream calls; catalog `id` stays for Codex's picker). Cost display in Codex is inaccurate for non-Anthropic models (Codex applies its own pricing table); documented limitation.
-
-**Local provider routing:** Two paths depending on `model.modelFormat`:
-- `'anthropic'`: `buildChildEnv(model.baseUrl, model.id, provider.apiKey)` — no proxy, Codex talks directly to the provider's Anthropic-compatible endpoint. The `baseUrl` must NOT include `/v1` (the Anthropic SDK appends it).
-- `'openai'`: `startProxy(model.completionsUrl ?? '', model.id, trace, contextWindow, { npm, baseURL, upstreamModelId })` — SDK adapter proxy on a random local port; `buildChildEnv('http://127.0.0.1', model.id, provider.apiKey, proxyPort)`. The route's `npm` selects the SDK provider via dynamic import; `baseURL` (`api.url`) is used for openai-compatible / openrouter providers. `completionsUrl` is optional for SDK-first-party packages (SDK owns endpoints).
-
-**Providers that need a non-empty API key:** `normalizeProviders` skips any provider with an empty `key` field (to filter OAuth-only providers like OpenAI/xAI configured via browser login). Local providers that don't validate keys (e.g. Ollama) must still have a non-empty placeholder key set in OpenCode (e.g. `"ollama"`).
-
-**Server command local providers** (`src/server/index.ts`): `loadServerModels()` fetches the provider catalog via `fetchProviderCatalog({ agent: 'server' })` and converts all registry providers to `ServerModelInfo[]` via `localProvidersToServerModels`. The router (`src/server/router.ts`) `handleAnthropicMessages`: anthropic-format → forward raw to `{baseUrl}/v1/messages`; openai-format → `isSdkMigratedNpm(npm)` guard → `createLanguageModel` + `streamAnthropicResponse`/`generateAnthropicResponse` (same SDK adapter as the CLI proxy). `GET /models` strips `apiKey` from output. Spinner shows `"N models (M from registry providers)"`.
-
-**Stale free models:** `STALE_FREE_MODELS` in `constants.ts` contains models whose free promotion ended but the API still returns them. Currently only `qwen3.6-plus-free`. These are filtered out in `mergeModels()`.
-
-**Recent models per provider** (`src/prompts.ts`, `src/cli.ts`, `src/types.ts`, `src/config.ts`): `UserPreferences.recentModelsByProvider: Record<string, string[]>` stores up to 3 recently used model IDs per provider. `pickLocalModel()` shows them at the top of the picker with a `'recent'` hint, plus a "Browse all models →" option. On launch, `cli.ts` prepends the selected model id and saves back (deduped, max 3). Skipped on `--dry-run`.
-
-**Large catalog UX** (`src/prompts.ts`): `MODEL_SEARCH_THRESHOLD = 25` — lists above this show search or paginated browse. `MODEL_PAGE_SIZE = 15` — prev/next pagination. `selectModelWithSearch`, `selectLargeCatalog`, `pickModelFromPagedList`.
-
-**Shared upstream forwarding** (`src/upstream-forward.ts`): `relayAnthropicMessages`, `postJsonUpstream`, anthropic header helpers — used by `proxy.ts` and `server/router.ts`.
-
-**Provider catalog helpers** (`src/provider-catalog.ts`): `fetchProviderCatalog`, `resolveLocalProviders`, `providersForPicker`, `localProvidersToServerModels`, `resolveProvidersForDisplay`, `formatRegistryAuthLabel` — registry-first catalog resolution used by CLI, server, and providers command.
-
-**Tests** cover pure functions: `env.ts`, `models.ts`, `sdk-adapter.ts`, `provider-factory.ts`, `proxy.ts` (`aliasModelId`), `providers.ts`, `catalog.ts`, `favorites.ts`, `prompts.ts`, `upstream-forward.ts`, `config.ts`, `tool-search.ts`, `cli.ts` (help text), server modules. Interactive launch flow and real-provider behavior verified manually.
-
-## Key constraints
-
-- `settings.json` is never touched by rflectr. Launch config is env-var-only, passed to the child process (plus `--model`). This avoids the backup/restore problem that `ollama launch Codex` has. **Caveat:** Codex itself persists the launched model to `~/.Codex/settings.json`, so bare `Codex` later may still show an rflectr alias (e.g. `anthropic-opencode-go__deepseek-v4-flash`). Gateway discovery caches at `~/.Codex/cache/gateway-models.json`. Reset with `Codex --model sonnet` or by editing/removing those files.
-- `--dry-run` ignores all saved state (env key, Keychain, tier, preferences) and skips all writes. Used to simulate a fresh first-run experience.
-- When adding a new backend, update `BACKENDS` in `constants.ts`, the `BackendConfig` id union in `types.ts`, and the subscription tier logic in `prompts.ts` and `cli.ts`.
-- `buildChildEnv(baseUrl: string, model, apiKey, proxyPort?)` — takes a plain string URL, not a `BackendConfig`. When `proxyPort` is set, `ANTHROPIC_BASE_URL` is always `http://127.0.0.1:{proxyPort}` regardless of `baseUrl`.
-- `startProxy(completionsUrl, modelId, debug, contextWindow?, sdk?)` — single-model wrapper around `startProxyCatalog`; `sdk` carries `{ npm, baseURL }` to select the SDK provider.
-- `startProxyCatalog(routes, startingAliasId, debug)` — multi-route catalog proxy for switch-menu sessions.
-- `MAX_MODEL_CATALOG = 20` in `constants.ts` — favorites cap and max routes in catalog.
-
-**Codex favorites catalog:** When `prefs.favoriteModels.length > 0`, `rflectr codex` and `rflectr codex-app` enter favorites mode on launch:
-- Shared resolver (`src/favorites-resolver.ts`) resolves each favorite to a `{providerId, providerName, model, apiKey}` entry, filtering by `agent: 'codex'` blacklist.
-- Codex CLI builds a `CodexProxyRoute[]` from resolved entries and starts a single multi-route proxy (`startCodexProxy(routes, { requireAuth: true })`).
-- The proxy port is exposed to the child via `OPENAI_API_KEY=proxy-local`.
-- Catalog slugs are `${providerId}__${modelId}` (CLI) or `codexAppModelSlug(modelId)` (App).
-- `--restore` globs `models-*.json` (CLI) and `app-models-*.json` (App); the new files are `models-favorites.json` and `app-models-favorites.json`.
-- Zen/Go favorites are skipped in Codex (use Claude or Desktop gateway).
-
-## Release status (v0.3.0)
-
-Current version is **v0.3.0** — official launch release with the native provider registry, complete Claude/Codex app help, unified OpenCode Zen / Go setup, duplicate-provider migration, stable post-import refreshes, agent boot flags (`--provider` / `--model`), `rflectr --ai`, favorites catalogs, reasoning capability metadata, and new native Chinese provider templates (DeepSeek, Zhipu, Moonshot) with improved models endpoint routing.
-
-**Known limitations (by design):**
-- Cost display in Codex is always inaccurate for non-Anthropic models.
-- OAuth-authenticated providers (no stored key) are silently skipped.
-- `@ai-sdk/github-copilot` won't work — OpenCode loads it from internal `@opencode-ai/core`, not a public npm factory we can ship.
-- Bedrock/Azure/Vertex may need env-based auth beyond a simple `apiKey` forwarded from OpenCode.
-- Providers with custom auth mechanisms (e.g. Azure OpenAI with deployment URLs) are not fully supported.
-- The `::ts::` separator in tool_use ids encodes `thought_signature`; would break if a signature ever literally contained `::ts::`. Extremely unlikely.
-- In switch-menu (gateway-discovery) mode the displayed context window reflects the **launch** model and does NOT update on live `/model` switch. Codex'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) is the only lever. Single-model launches show the correct window.
-
-**Provider quirks (documented from testing):**
-- **Mistral free tier:** strict API rate limits (HTTP 429, code `1300`). Tool-heavy Codex sessions burn quota quickly (parallel title-generation requests, Skill injection, multi-turn tool loops). The SDK handles Mistral message ordering; throttling is unaffected.
-- **OpenAI direct (`@ai-sdk/openai` local provider):** newer models (GPT-5.4+, GPT-5.5, `*-codex`, o-series) require the Responses API — `provider-factory.modelPrefersResponsesApi()` selects `openai.responses(id)` for them, `openai.chat(id)` otherwise. OpenCode catalog IDs may differ from upstream API IDs — `upstreamModelId` uses OpenCode's `api.id` (e.g. `gpt-5.5-fast` → `gpt-5.5`). GPT-5.5 reasoning round-trips via encrypted content in `thinking.signature`. Cloud OpenCode Zen/Go GPT models remain hidden in the wizard (`unsupported`); use the local OpenAI provider for GPT access.

package/assets/vertex-models.example.json

@@ -1,14 +0,0 @@
-[
-  {
-    "id": "claude-sonnet-4-6",
-    "display_name": "Claude Sonnet 4.6"
-  },
-  {
-    "id": "claude-opus-4-6",
-    "display_name": "Claude Opus 4.6"
-  },
-  {
-    "id": "claude-haiku-4-5",
-    "display_name": "Claude Haiku 4.5"
-  }
-]

package/library/README.md

@@ -1,39 +0,0 @@
----
-ai_description: |
-  This is the root of the repository's documentation library (schema v2).
-  You own everything under library/ except notes/, which is human-only.
-  Sub-trees: knowledge/ (public and private docs), requirements/ (product
-  work: PRDs), issues/ (reactive bug/incident work: IRDs), notes/ (junk
-  drawer, read-only to agents).
-  Schema reference: legion-shared/standards/library-schema-v2.md.
-  Standardize script: pnpm standardize-library --repository <name>.
-human_description: |
-  Root of this repository's documentation library.
-  - knowledge/: reference documentation split by audience (public vs private)
-  - requirements/: planned product work (PRDs) with backlog/in-work/completed lifecycle
-  - issues/: reactive bug and incident work (IRDs) with same lifecycle
-  - notes/: unstructured scratch space — only humans write here
-  Run `pnpm standardize-library --repository <name>` to scaffold any missing structure.
----
-
-# Library
-
-Documentation root for this repository. Schema version: **v2**.
-
-See [`legion-shared/standards/library-schema-v2.md`](../../legion-shared/standards/library-schema-v2.md) for the full specification.
-
-## Top-level layout
-
-| Folder | What goes here |
-|---|---|
-| `knowledge/public/` | End-user / customer-facing docs: overviews, guides, FAQs |
-| `knowledge/private/` | Internal engineering and business docs: ADRs, standards, domain knowledge |
-| `requirements/` | Product and feature work: PRDs in backlog/in-work/completed |
-| `issues/` | Reactive bug and incident work: IRDs in backlog/in-work/completed |
-| `notes/` | Human-only scratch space |
-
-## What does NOT belong here
-
-- Brand assets → `legion-shared/brands/`
-- Wiki entity pages → `legion-wiki/<repo>/wiki/` (derived, never edit)
-- Library mirrors → `legion-wiki/<repo>/library/` (derived, never edit)

package/library/issues/README.md

@@ -1,46 +0,0 @@
----
-ai_description: |
-  This folder contains all reactive bug and incident work (IRDs).
-  It is a PEER of requirements/, not nested under it.
-  Sub-folders: backlog/, in-work/, completed/ — same lifecycle as requirements/.
-  IRD folder naming: ird-<###>-<kebab-slug>/
-  IRD numbers match the GitHub issue number for this repo.
-  Never invent IRD numbers — a GitHub issue must exist first.
-  IRDs are single-scope: one issue per IRD, no sub-IRDs.
-  Do NOT put PRDs here — those go in requirements/.
-human_description: |
-  Reactive bug and incident work (IRDs), organized by lifecycle stage.
-  - backlog/: tracked issues with a fix plan, not yet started
-  - in-work/: issues currently being fixed
-  - completed/: resolved issues (move entire folder)
-  IRD numbers match GitHub issue numbers. Create an IRD only after the
-  GitHub issue exists.
----
-
-# Issues
-
-Reactive bug and incident work (IRDs), organized by lifecycle state.
-
-## Sub-folders
-
-| Folder | State | Description |
-|---|---|---|
-| `backlog/` | Tracked | IRDs with a fix plan, not yet in progress |
-| `in-work/` | Active | Issues currently being resolved |
-| `completed/` | Resolved | Entire IRD folder moves here when the issue closes |
-
-## IRD folder structure
-
-```
-ird-042-stale-cache/
-  ird-042-stale-cache-index.md     single-scope fix plan
-  qa/
-    ird-042-stale-cache-qa.md      QA audit (written by quality-guardian)
-```
-
-## Naming rules
-
-- Folder: `ird-<###>-<kebab-slug>/`
-- Index: `ird-<###>-<kebab-slug>-index.md`
-- IRD number = GitHub issue number (never invented)
-- No sub-IRDs (scope one issue per IRD)

package/library/issues/backlog/README.md

@@ -1,26 +0,0 @@
----
-ai_description: |
-  Contains IRD folders for tracked issues not yet in active fix work.
-  Create a new IRD here only AFTER the GitHub issue exists for this repo.
-  IRD folder: ird-<###>-<slug>/ where ### = GitHub issue number.
-  Must contain: ird-<###>-<slug>-index.md (the fix plan) and qa/ folder.
-  IRDs are single-scope: do not add sub-IRDs.
-human_description: |
-  IRDs planned but not yet in active fix work. Create IRDs here.
-  - Naming: ird-042-stale-cache/ with ird-042-stale-cache-index.md inside
-  - IRD number must match the GitHub issue number
-  - Create only after the GitHub issue exists
-  Move to in-work/ when fix work begins.
----
-
-# Issues — Backlog
-
-Tracked issues with a fix plan, not yet in active resolution.
-
-## Creating a new IRD
-
-1. Confirm the GitHub issue number (e.g., #42).
-2. Create `ird-042-<kebab-slug>/`.
-3. Create `ird-042-<slug>-index.md` — the single-scope fix plan.
-4. Create `qa/` subfolder (empty; `quality-guardian` writes here).
-5. No sub-IRDs — keep scope to one issue.

package/library/issues/completed/README.md

@@ -1,13 +0,0 @@
----
-ai_description: |
-  Resolved IRD folders. Entire ird-<###>-<slug>/ folders move here from
-  in-work/ when the corresponding GitHub issue is closed and verified.
-  Read-only after landing — do NOT edit or re-open IRDs here.
-human_description: |
-  Resolved issue folders. Move entire ird-NNN-slug/ here from in-work/
-  when the GitHub issue is closed and the fix is confirmed. Read-only.
----
-
-# Issues — Completed
-
-Resolved IRD folders. Entire `ird-<###>-<slug>/` folders land here when the GitHub issue closes and the fix is confirmed. Do not edit files here after landing.

package/library/issues/in-work/README.md

@@ -1,13 +0,0 @@
----
-ai_description: |
-  IRD folders actively being resolved. Mirror of requirements/in-work/
-  but for issues. Move entire ird-<###>-<slug>/ folder from backlog/
-  here when fix work begins, then to completed/ when the issue closes.
-human_description: |
-  IRDs currently being fixed. Move folder from backlog/ here when work
-  starts, and to completed/ when the GitHub issue is closed.
----
-
-# Issues — In Work
-
-IRDs currently being resolved. Move from `backlog/` → here when fix work starts, then `completed/` when the GitHub issue closes.

package/library/knowledge/README.md

@@ -1,34 +0,0 @@
----
-ai_description: |
-  This folder contains all reference documentation for this repository,
-  split by intended audience: public/ for end-users, private/ for internal
-  team and AI agents. When filing a new doc, default to private/. Promote
-  to public/ only when the content is intentionally customer-facing.
-  Allowed writes: knowledge/public/<domain>/<slug>.md and
-  knowledge/private/<domain>/<slug>.md. ADRs always go in
-  knowledge/private/architecture/ADR-<n>-<slug>.md.
-  Never write to knowledge/ itself (write to the sub-folders).
-human_description: |
-  Reference documentation split by audience.
-  - public/: docs that will eventually be surfaced to customers or published
-  - private/: internal engineering, architecture, business, and strategy docs
-  When adding a new doc, pick the right subdomain folder inside public/ or
-  private/. If the domain doesn't exist yet, create it.
----
-
-# Knowledge
-
-Reference documentation for this repository, organized by audience.
-
-## Sub-folders
-
-| Folder | Audience | Typical content |
-|---|---|---|
-| `public/` | End-users, customers, external | Overviews, user guides, FAQs |
-| `private/` | Internal team + AI agents | ADRs, standards, architecture, domain engineering docs |
-
-## Decision rule: public vs private
-
-> "Would I publish this on a help center or product docs site?"
-
-Yes → `public/`. No → `private/`. When in doubt, `private/`.

package/library/knowledge/private/README.md

@@ -1,40 +0,0 @@
----
-ai_description: |
-  This folder contains internal engineering and business documentation.
-  ADRs MUST live in architecture/ADR-<n>-<kebab-slug>.md.
-  Engineering standards MUST live in standards/documentation-framework.md.
-  Other domain folders (<domain>/) are repo-specific and may be created as
-  needed (ai/, auth/, data/, frontend/, infrastructure/, integrations/,
-  marketing/, operations/, personas/, reporting/, roadmap/, scanners/,
-  security/, strategy/, etc.).
-  Do NOT file customer-facing content here (that goes in knowledge/public/).
-  Write path: library/knowledge/private/<domain>/<kebab-slug>.md.
-human_description: |
-  Internal engineering and business documentation.
-  - architecture/: Architecture Decision Records (ADRs)
-  - standards/: Documentation framework and coding standards
-  - <domain>/: Any repo-specific knowledge domain (ai/, auth/, data/, etc.)
-  Default landing zone for any doc that does not need to be customer-facing.
-  When creating a new domain folder, add a README.md explaining what belongs.
----
-
-# Knowledge — Private
-
-Internal documentation for engineers, product, and AI agents.
-
-## Required sub-folders (always present)
-
-| Folder | Contents |
-|---|---|
-| `architecture/` | ADRs: `ADR-<n>-<kebab-slug>.md`. Locked decisions with context, alternatives, consequences. |
-| `standards/` | `documentation-framework.md` and any repo-specific writing rules. |
-
-## Optional domain folders
-
-Create any of these as needed: `ai/`, `auth/`, `data/`, `frontend/`, `infrastructure/`, `integrations/`, `marketing/`, `operations/`, `personas/`, `reporting/`, `roadmap/`, `scanners/`, `security/`, `strategy/`, `reference/`, `<product>-ux-ui/`.
-
-## What does NOT belong here
-
-- Customer-facing content (put in `knowledge/public/`)
-- PRDs or IRDs (put in `requirements/` or `issues/`)
-- Brand assets (put in `legion-shared/brands/`)

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

@@ -1,8 +0,0 @@
-# AI
-
-The model-routing brain: wire-format translation and model discovery/classification.
-
-| Doc | Covers |
-|---|---|
-| [`translation-layer.md`](translation-layer.md) | The Vercel AI SDK adapter + provider factory — the single translation path; Responses-API selection; thought_signature round-trip. |
-| [`model-discovery-classification.md`](model-discovery-classification.md) | `classifyModelFormat`, the two-source merge, context-window resolution, cost-display limitation. |

package/library/knowledge/private/ai/model-discovery-classification.md

@@ -1,81 +0,0 @@
-# Model Discovery & Classification
-
-> Category: Ai | Version: 1.0 | Date: June 2026 | Status: Active
-
-How `rflectr` builds the model list a user picks from, and how it decides whether each model is forwarded raw or translated. Read [`translation-layer.md`](translation-layer.md) for what happens *after* a model is classified.
-
-**Related:**
-- [`translation-layer.md`](translation-layer.md)
-- [`../data/provider-registry.md`](../data/provider-registry.md)
-- Source: `src/constants.ts` (`classifyModelFormat`), `src/models.ts`, `src/context-window.ts`, `src/context-model-id.ts`, `src/registry/materialize.ts`
-
----
-
-## The format decision
-
-Every model carries a `modelFormat` that drives the launch branch (`'anthropic'` = direct passthrough, anything else = SDK adapter proxy). It is computed by `classifyModelFormat(modelId, providerNpm)` in `src/constants.ts`:
-
-```ts
-if (providerNpm === '@ai-sdk/anthropic') return 'anthropic';
-if (providerNpm === '@ai-sdk/openai')    return 'unsupported';
-if (providerNpm === '@ai-sdk/google')    return 'unsupported';
-// Fallback: ID-prefix heuristics when no cache npm is known
-if (id.startsWith('claude-'))  return 'anthropic';
-if (id.startsWith('gpt-'))     return 'unsupported';
-if (id.startsWith('gemini-'))  return 'unsupported';
-return 'openai';
-```
-
-The four values mean:
-
-| `modelFormat` | Meaning |
-|---|---|
-| `anthropic` | Direct passthrough to the provider's Anthropic endpoint. `isAnthropicNative` is true. |
-| `openai` | Routed through the SDK adapter via the local proxy. The catch-all for everything that isn't natively Anthropic. |
-| `unsupported` | Hidden in the **cloud OpenCode wizard** only. GPT/Gemini through OpenCode Zen/Go's proxy layer needs model-specific endpoints that the cloud path can't provide. |
-
-> **Important nuance:** `unsupported` is a *cloud-wizard* restriction, not a global one. To use GPT or Gemini models, configure the **local OpenAI / Google provider** (which carries the real `@ai-sdk/openai` / `@ai-sdk/google` npm) — those route through the SDK adapter normally. The `unsupported` classification only blocks the OpenCode Zen/Go proxy layer where direct OpenAI/Google access isn't available.
-
----
-
-## The two-source merge
-
-The cloud (OpenCode Zen/Go) model list is built from two sources merged together:
-
-```mermaid
-flowchart TD
-    api["GET {backendUrl}/v1/models — available ids (no auth)"]
-    cache["~/.cache/opencode/models.json — name, family, cost, provider.npm"]
-    api --> merge["mergeModels()"]
-    cache --> merge
-    merge --> enrich["enriched ModelInfo with modelFormat, sourceBackend, contextWindow"]
-```
-
-- **Primary:** `GET {backendUrl}/v1/models` returns the available model ids (no auth required).
-- **Enrichment:** `~/.cache/opencode/models.json` (written by the OpenCode CLI, path in `OPENCODE_CACHE_PATH`) supplies `name`, `family`, `cost`, and `provider.npm`. It is optional enrichment, never a runtime dependency.
-
-`sourceBackend` is set from the backend that was queried. This matters for the `go` subscription tier, which shows Zen free models *and* Go paid models in one combined list — `sourceBackend` lets the launcher set the correct `ANTHROPIC_BASE_URL` per selected model.
-
-### Stale free models
-
-`STALE_FREE_MODELS` in `src/constants.ts` lists models whose free promotion ended but the API still returns. They are filtered out in `mergeModels()`. (Historically this held `qwen3.6-plus-free`; treat the constant as the source of truth.)
-
----
-
-## Registry models
-
-Registry providers (`~/.rflectr/providers.json`) carry their own `CachedModel[]`, each already stamped with `modelFormat`, `npm`, `upstreamModelId`, `contextWindow`, `cost`, `supportedParameters`, and `reasoning`. `materializeRegistry` (`src/registry/materialize.ts`) converts those into runtime `LocalProviderModel`s and applies per-agent hiding via `shouldHideModel()` — e.g. Zen/Go favorites are hidden from Codex, which has no gateway path for them. See [`../data/provider-registry.md`](../data/provider-registry.md).
-
----
-
-## Context window resolution
-
-The status bar in Claude Code shows remaining context, which depends on a correct window. `resolveContextWindow(modelId, contextWindow?)` (`src/context-window.ts`) picks the window; `buildChildEnv` writes it to `CLAUDE_CODE_MAX_CONTEXT_TOKENS`. The proxy's synthetic `GET /v1/models` includes `context_window` per model (`formatAnthropicModelEntry`) so the host can render it.
-
-A model id may carry a `[1m]` suffix to denote a 1-million-token context variant; `stripOneMContextSuffix` / `claudeCodeClientModelId` (`src/context-model-id.ts`) separate the wire id from the display id and the context hint. In switch-menu mode the window is fixed at launch and does not change on live `/model` switch (see [`../architecture/launch-flow-claude.md`](../architecture/launch-flow-claude.md#the-context-window-caveat)).
-
----
-
-## Cost display is inaccurate for non-Anthropic models
-
-Claude Code applies its own internal pricing table to whatever model id it sees, so the cost it shows for a Groq/DeepSeek/Gemini model is wrong. This is a documented, unfixable-from-here limitation — the host owns its pricing display.