@legioncodeinc/rflectr 0.1.0 → 0.1.2

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

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

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

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

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

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

package/library/knowledge/private/security/credential-storage.md

@@ -1,129 +0,0 @@
-# Credential Storage & Environment Isolation
-
-> Category: Security | Version: 1.0 | Date: June 2026 | Status: Active
-
-Where secrets live, how they're resolved at launch, and the exact environment contract handed to each child process. This is the security-critical surface of `rflectr`. Read [`../architecture/system-overview.md`](../architecture/system-overview.md) first.
-
-**Related:**
-- [`../auth/oauth-device-flows.md`](../auth/oauth-device-flows.md)
-- [`../data/provider-registry.md`](../data/provider-registry.md)
-- [`../architecture/launch-flow-claude.md`](../architecture/launch-flow-claude.md)
-- Source: `src/env.ts`, `src/key-setup.ts`, `src/constants.ts`
-
----
-
-## Where secrets live
-
-Secrets are **never** written to `providers.json` or `config.json`. Those files hold only an `authRef` pointer. The actual secret lives in one of three places, resolved in priority order by `resolveProviderCredential(providerId, authRef)` (`src/env.ts`):
-
-1. **Env var** — `RFLECTR_KEY_<PROVIDER_ID_UPPER>` (highest priority), or whatever `env:VAR_NAME` the `authRef` names (e.g. `env:OPENCODE_API_KEY`).
-2. **OS keyring** — via `@napi-rs/keyring`, service `rflectr`. Accounts:
-   - `provider:<id>` — an API key.
-   - `oauth:provider:<id>` — a JSON `StoredOAuthCredential` (see [`../auth/oauth-device-flows.md`](../auth/oauth-device-flows.md)).
-   - `global:opencode` — the shared OpenCode Zen/Go key.
-3. **Legacy keyring entries** — `rflectr` / `opencode-starter` accounts, auto-migrated on first successful read.
-
-`@napi-rs/keyring` is an `optionalDependency` loaded via dynamic `import()`, so a missing native binary degrades gracefully rather than crashing. `classifyKeyringError(err)` turns native failures into human messages ("Secret Service daemon is not running", "keychain access was denied or the keychain is locked", "native keyring module not available", …).
-
-```mermaid
-flowchart TD
-    need["launch needs a key for provider X"] --> env{"RFLECTR_KEY_X or env:VAR set?"}
-    env -->|yes| use["use it"]
-    env -->|no| ref{"authRef kind"}
-    ref -->|keyring:provider:X| kr["read keyring account"]
-    ref -->|keyring:oauth:provider:X| oauth["read + refresh OAuth credential"]
-    ref -->|keyring:global:opencode| zen["readGlobalOpencodeCredential() chain"]
-    kr --> use
-    oauth --> use
-    zen --> use
-```
-
-### The OpenCode Zen/Go fallback chain
-
-`readGlobalOpencodeCredential()` tries, in order: `OPENCODE_API_KEY` env var → keyring `global:opencode` → legacy keyring `rflectr` → oldest legacy service `opencode-starter`. On a successful legacy read, `migrateGlobalOpencodeCredential()` rewrites it to `global:opencode` using a **read → write → verify → delete** protocol (the old entry is only deleted after the new one verifies).
-
----
-
-## Child process environment
-
-`buildChildEnv(baseUrl, model, apiKey, proxyPort?, contextWindow?, enableGatewayDiscovery?)` (`src/env.ts`) builds the env for the launched host. It is the security boundary: the parent shell is never mutated (except `OPENCODE_API_KEY` during interactive key setup).
-
-**Removed** — every var in `CONFLICTING_ENV_VARS` (`src/constants.ts`), so stale cloud config can't leak into the child:
-
-```
-CLAUDE_CODE_USE_VERTEX, ANTHROPIC_VERTEX_PROJECT_ID, ANTHROPIC_VERTEX_BASE_URL,
-CLOUD_ML_REGION, ANTHROPIC_BEDROCK_BASE_URL, ANTHROPIC_AWS_BASE_URL,
-ANTHROPIC_AWS_API_KEY, ANTHROPIC_AWS_WORKSPACE_ID, ANTHROPIC_FOUNDRY_API_KEY,
-ANTHROPIC_FOUNDRY_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY,
-ANTHROPIC_BASE_URL, ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL,
-ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL
-```
-
-**Set:**
-
-| Var | Value |
-|---|---|
-| `ANTHROPIC_BASE_URL` | `http://127.0.0.1:<proxyPort>` when a proxy is used, else `baseUrl` (which must **not** end in `/v1`) |
-| `ANTHROPIC_API_KEY` | the provider key, or the proxy token when proxying |
-| `ANTHROPIC_MODEL` | `claudeCodeClientModelId(stripOneMContextSuffix(model), contextWindow)` |
-| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | `resolveContextWindow(bareModel, contextWindow)` |
-| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | `1` when `enableGatewayDiscovery` (switch-menu mode) |
-| `ENABLE_TOOL_SEARCH` | `true` — defer MCP tools like native Claude Code (`applyClaudeCodeThirdPartyCompat`) |
-| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | `0` — keep the full system prompt on proxy routes |
-
-On the **anthropic direct-passthrough** path, the single-model launch additionally sets `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` to strip beta headers on the direct hop. On proxy routes the betas stay enabled so tool search works through the local proxy.
-
-`detectConflicts()` reports which of these vars were present (shown in `--dry-run` and warnings) so a user can see what was scrubbed.
-
----
-
-## Interactive key setup
-
-`resolveOrCollectApiKey(simulate?, trace?)` (`src/key-setup.ts`) is called for the OpenCode Zen/Go key. On startup it silently calls the credential-store read first — if a key is found, no prompt appears. Otherwise it prompts for paste and offers platform-specific save options. In every case `process.env['OPENCODE_API_KEY']` is set immediately so the key is live for the current session regardless of save choice.
-
-| Platform | Options |
-|---|---|
-| **macOS** | Keychain only · Keychain + `~/.zshrc` autoload · shell profile (plaintext) · session only |
-| **Windows** | Credential Manager · `setx` user env var (plaintext) · session only |
-| **Linux desktop** | Secret Service (GNOME Keyring / KWallet) · shell profile (plaintext) · session only |
-| **Linux headless** | shell profile · session only (with a note explaining why secure storage is unavailable) |
-
-Notes:
-
-- The macOS autoload 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)"`.
-- `setx` is invoked with piped stdio to suppress its "SUCCESS" stdout.
-- Secret Service availability is probed with a test `getPassword()` (`isSecretServiceAvailable()`); if the daemon isn't running the option is hidden.
-- `detectShellProfile()` chooses the right profile file per platform/shell (`~/.zshrc`, `~/.bash_profile`, `~/.bashrc`, `~/.profile`).
-
----
-
-## Trust boundaries
-
-```mermaid
-flowchart TD
-    subgraph trusted["Trusted — rflectr process"]
-        keyring["OS keyring"]
-        registry["providers.json (no secrets)"]
-        env["buildChildEnv()"]
-    end
-    subgraph child["Child host (Claude Code / Codex / Gemini)"]
-        proc["host process"]
-    end
-    subgraph net["Network"]
-        prov["upstream provider"]
-    end
-    keyring -->|resolved at launch| env
-    env -->|"scrubbed env + proxy token"| proc
-    proc -->|"127.0.0.1 only"| localproxy["local proxy"]
-    localproxy -->|"provider key (never to child)"| prov
-```
-
-Key properties:
-
-- The **provider's real key never reaches the child** when proxying — the child gets a random proxy token; the proxy holds the real key and calls upstream.
-- The proxy binds `127.0.0.1` only, on a random port, and validates the token, so other local processes can't use it.
-- Secrets are keyring-backed by default; plaintext options (`setx`, shell profile) are opt-in and clearly labelled.
-
-### Server-mode caveat
-
-The `server` command can bind in network mode and asks for a server password (`isAuthorized`, `sanitizeCredential` in `src/server/auth.ts`). When exposed beyond localhost, that password is the only gate — see [`../infrastructure/server-gateway.md`](../infrastructure/server-gateway.md).

package/library/knowledge/private/standards/documentation-framework.md

@@ -1,154 +0,0 @@
-# Documentation Framework
-
-> Category: Standards | Version: 1.0 | Date: (fill in on init) | Status: Canonical
-
-The single source of truth for how documentation is written in this repository. Every document — feature PRDs, issue PRDs, QA reports, architecture docs, API references, guides — must conform to the standards defined here. If a document type is not covered, add a new section to this file rather than inventing a local convention.
-
----
-
-## 1. Document Types
-
-| Type | Purpose | Location | Primary audience |
-|---|---|---|---|
-| **Issue IRD** | Implementation plan for a specific GitHub issue | `library/requirements/issues/issue-<###>-<title>/ird-issue-<###>-<title>.md` | Implementation engineer |
-| **Feature PRD** | Planned feature spec (forward or retroactive) | `library/requirements/features/feature-<###>-<title>/prd-feature-<###>-<title>.md` (or `prd-feature-<###>-<title>-ck-<clickupId>.md` if from ClickUp) | Implementation engineer |
-| **QA Report (tied)** | Audit of an implementation against its plan | The plan's own `reports/<date>-qa-report.md` subfolder | Team lead, author of the feature |
-| **QA Report (standalone)** | Audit not tied to a single plan | `library/qa/<domain>/<date>-qa-report.md` | Team lead, audit reviewer |
-| **Architecture Doc** | System design, data flows, component relationships | `library/knowledge-base/architecture/` | Senior engineers, architects |
-| **API Reference** | Endpoint-by-endpoint documentation with schemas | `library/knowledge-base/api/` | Frontend devs, API consumers |
-| **How-to Guide** | Runbooks for setup, testing, deploying, adding features | `library/knowledge-base/how-to-guides/` | New engineers, DevOps |
-| **Integration Doc** | Third-party service configuration and error handling | `library/knowledge-base/integrations/` | DevOps, engineers wiring services |
-| **UX/UI Standard** | Visual design language — tokens, components, patterns | `library/knowledge-base/design/` | Designers, frontend devs |
-| **Feature Doc** | Completed feature reference (post-ship) | `library/knowledge-base/features/` | Any engineer joining the project |
-| **Spec** | Feature-level handoff spec for a UI flow | `library/knowledge-base/specs/` | Frontend engineers |
-| **Product Brief** | Product vision, scope, roadmap | `library/knowledge-base/product/` | Team, stakeholders |
-| **Standards Doc** | Rules for writing documentation itself | `library/knowledge-base/standards/` | All contributors |
-| **Release Notes** | What changed in each release | `library/knowledge-base/releases/` | All team members |
-
----
-
-## 2. Universal Document Header
-
-Every markdown file under `library/knowledge-base/` starts with:
-
-```markdown
-# <Document Title>
-
-> Category: <Type> | Version: <X.Y> | Date: <Month YYYY> | Status: <Active | Draft | Archived>
-
-<One-sentence description of what this document covers and who should read it.>
-
-**Related:**
-- [Link to related doc]
-- [Link to source code: `src/path/to/file.ts`]
-```
-
-- **Version** — starts at `1.0`; patch bumps (`1.0` → `1.1`) for additions, minor bumps (`1.x` → `2.0`) for reorganizations.
-- **Date** — current month/year on the last meaningful edit.
-- **Status** values:
-  - `Active` — current, should be kept up to date
-  - `Draft` — work in progress, not authoritative
-  - `Archived` — historical, no longer maintained
-  - `Canonical` — (for standards docs only) highest authority; overrides ad-hoc conventions
-
-Requirements-type docs (issue IRDs, feature PRDs, QA reports) use a different header format documented in their respective guides.
-
----
-
-## 3. Filename Conventions
-
-| Document type | Folder + filename pattern | Example |
-|---|---|---|
-| Issue IRD | `issue-<###>-<title>/ird-issue-<###>-<title>.md` (with sibling `reports/`) | `issue-046-stale-cached-responses/ird-issue-046-stale-cached-responses.md` |
-| Feature PRD | `feature-<###>-<title>/prd-feature-<###>-<title>.md` (with sibling `reports/`) | `feature-007-user-profile-export/prd-feature-007-user-profile-export.md` |
-| Feature PRD (from ClickUp) | `feature-<###>-<title>/prd-feature-<###>-<title>-ck-<clickupId>.md` | `feature-007-user-profile-export/prd-feature-007-user-profile-export-ck-86c8wq2k1.md` |
-| QA report (tied to plan) | `<plan-folder>/reports/<date>-qa-report.md` | `feature-007-user-profile-export/reports/2026-04-26-qa-report.md` |
-| QA report (standalone) | `library/qa/<domain>/<date>-qa-report.md` | `library/qa/auth/2026-04-26-qa-report.md` |
-| Knowledge-base | `<domain>/<kebab-slug>.md` (no numeric prefix) | `architecture/authentication-flow.md` |
-
-**Numbering rules:**
-- `<###>` is **3-digit zero-padded** (`006`, `046`, `093`, `100`). 4+ digit natural width.
-- Issue numbers follow the GitHub issue number.
-- Feature numbers are repo-local sequential; take `max + 1` from existing folders (open + `completed/`).
-- Titles are lowercase kebab-case, ≤60 chars.
-- The optional ClickUp suffix `-ck-<clickupId>` goes on the **main file only**, never on the folder name.
-
----
-
-## 4. Folder Location Rules
-
-| Folder | Meaning |
-|---|---|
-| `library/requirements/features/feature-<###>-<title>/` | Feature work in progress. |
-| `library/requirements/features/completed/feature-<###>-<title>/` | Feature has shipped. Move the entire folder (PRD + `reports/`). |
-| `library/requirements/issues/issue-<###>-<title>/` | Issue work in progress (GitHub issue OPEN). |
-| `library/requirements/issues/completed/issue-<###>-<title>/` | Issue has been resolved (GitHub issue CLOSED). Move the entire folder (IRD + `reports/`). Symmetric to features. |
-| `<plan-folder>/reports/` | QA reports tied to that specific feature/issue. Travel with the folder when it moves. |
-| `library/qa/<domain>/` | Standalone QA reports — broad audits not tied to a single plan. |
-
-Move folders when status changes. Never edit lifecycle state in frontmatter alone.
-
----
-
-## 5. Writing Rules (all doc types)
-
-1. **Ground every claim in code.** Quote source with file path + line range; never paraphrase signatures.
-2. **One topic per document.** Split if a doc exceeds ~500 lines.
-3. **Progressive disclosure.** Open with "why this exists" and "who should read it"; deep details below.
-4. **Link out, don't duplicate.** If another doc covers a subtopic, link to it.
-5. **Diagrams use mermaid.** Prefer `flowchart TD` or `sequenceDiagram`. No explicit colors.
-6. **No time-sensitive language.** Avoid "currently", "recently", "as of". Use explicit dates.
-7. **No personal opinions.** Docs describe decisions and rationale, not preferences.
-
----
-
-## 6. Cross-Linking Conventions
-
-- Use relative paths: `[title](../relative/path.md)`.
-- Link to code with file paths (and line numbers where useful): `` `src/routes/users.ts:42-80` ``.
-- PRDs and IRDs link to their related issues, features, and QA reports in a **Related** section at the end.
-- Knowledge-base docs link to the PRDs that drove them (when applicable) and to source code.
-
----
-
-## 7. Diagram Rules
-
-- Mermaid preferred (renders everywhere GitHub does).
-- Use `flowchart TD` (top-down) for process flows; `sequenceDiagram` for temporal flows; `erDiagram` for data models.
-- Node IDs: no spaces (use `camelCase` or `under_scores`).
-- No explicit colors (breaks dark mode).
-- No `click` events.
-- Quote labels containing parentheses, brackets, or colons.
-
----
-
-## 8. Versioning + Dates
-
-- **Versioning** is per-document, not repo-wide. Bump on meaningful content change.
-- **Dates** use the current month/year (from the system clock), not arbitrary timestamps.
-- Each document optionally ends with a **Changelog** section listing version bumps.
-
----
-
-## 9. Ownership
-
-- Requirements docs (issue IRDs, feature PRDs) are owned by the implementation author. QA reports are owned by `quality-guardian`.
-- Knowledge-base docs are owned by the team collectively — anyone may edit with a PR.
-- Standards docs (this file included) require team consensus before changing.
-
----
-
-## 10. Bootstrap — After `initialize`
-
-When `library-guardian initialize` seeds a repo:
-
-1. Replace the placeholder "(fill in on init)" in the header above with the current month/year.
-2. Replace any project-name placeholders in the seeded README files with your repo's actual name.
-3. Edit any section of this framework that doesn't match your team's conventions — then commit.
-4. Start using the agent: ingest issues, plan features, document architecture.
-
----
-
-## Changelog
-
-- v1.0 — Initial template seeded by `library-guardian`. Customize per repo.

package/library/knowledge/public/README.md

@@ -1,49 +0,0 @@
----
-ai_description: |
-  This folder contains customer-facing / end-user documentation.
-  Approved sub-folders: overview/, guides/, faqs/, and any domain
-  folder explicitly designated public by the team.
-  Do NOT file internal engineering docs, ADRs, pricing strategy, or
-  security-sensitive material here.
-  Write path: library/knowledge/public/<domain>/<kebab-slug>.md.
-  All files here may eventually be surfaced in the public help center
-  (Phase 2). Mark each doc with the standard knowledge-base header:
-  Category / Version / Date / Status.
-human_description: |
-  Customer-facing documentation. Content here may be published externally.
-  - overview/: what this product is, glossary, elevator pitch
-  - guides/: how-to guides written for users, not developers
-  - faqs/: frequently asked questions
-  Only add content here that you are comfortable sharing publicly.
-  Internal notes, pricing strategy, and architecture docs belong in
-  knowledge/private/ instead.
----
-
-# Knowledge — Public
-
-Customer-facing documentation for **rflectr** by [Legion Code Inc.](https://github.com/legioncodeinc) Anything in this folder may eventually be published to the help center.
-
-## Documentation map
-
-**Start here:** [What is rflectr?](overview/what-is-rflectr.md)
-
-| Section | Docs |
-|---|---|
-| [Overview](overview/) | [What is rflectr?](overview/what-is-rflectr.md) |
-| [Guides](guides/) | [Providers](guides/providers.md) · [Claude Desktop](guides/claude-desktop.md) · [Codex](guides/codex.md) · [Gemini CLI](guides/gemini-cli.md) · [API Server](guides/api-server.md) · [AI Agents](guides/ai-agents.md) · [Model Compatibility](guides/model-compatibility.md) |
-| [FAQs](faqs/) | [Troubleshooting](faqs/troubleshooting.md) |
-
-## Approved sub-folders
-
-| Folder | Contents |
-|---|---|
-| `overview/` | What this product is, glossary, elevator pitch, high-level FAQs |
-| `guides/` | Step-by-step user guides (written for customers, not developers) |
-| `faqs/` | Frequently asked questions from customers |
-
-## What does NOT belong here
-
-- Internal architecture docs or ADRs
-- Pricing strategy or competitive analysis
-- Engineering standards
-- Anything you would not want a customer to read

package/library/knowledge/public/faqs/README.md

@@ -1,7 +0,0 @@
-# FAQs
-
-Common questions and fixes.
-
-| Doc | Covers |
-|---|---|
-| [troubleshooting.md](troubleshooting.md) | Launch issues with `rflectr claude` — the "Not logged in" prompt, placeholder keys, cloud-builtin providers, and `--trace`. |