@legioncodeinc/rflectr 0.1.0

package/library/knowledge/public/guides/gemini-cli.md

@@ -0,0 +1,105 @@
+# Gemini CLI
+
+> Category: Guide | Version: 1.0 | Date: June 2026 | Status: Active · Experimental
+
+Use the **Google Gemini CLI** with any model from your rflectr registry — Anthropic, xAI, Google Gemini, Nvidia, DeepSeek, OpenAI, and more.
+
+> 🧪 **Experimental.** Gemini CLI integration is newer than the Claude and Codex paths; expect rough edges.
+
+| Command | Launches | Config target |
+|---|---|---|
+| `rflectr gemini` | Gemini **terminal** (prompt loop / TUI) | Ephemeral proxy port via environment variables. |
+
+It uses the same registry (`~/.rflectr/providers.json`) and provider picker as Claude Code and Codex — Google's native Gemini endpoints when possible, and a local translation proxy for everything else.
+
+> 📖 Full flags: `rflectr gemini --help`.
+> 🤖 Automating it? See [AI Agents & automation](ai-agents.md) or run `rflectr --ai`.
+
+---
+
+## Prerequisites
+
+1. **rflectr** on your PATH (`npm install -g @legioncodeinc/rflectr`, or built locally).
+2. **At least one provider:** `rflectr providers add` (or `rflectr providers import`).
+3. **Gemini CLI installed:** `npm install -g @google/gemini-cli`.
+
+Registry providers plus OpenCode Zen/Go all route through rflectr's translation layer when they don't natively speak Gemini format.
+
+---
+
+## How it works
+
+The Gemini CLI uses the **Gemini API format** (`POST /v1beta/models/<model>:generateContent`). When you pick a non-Google provider, rflectr spins up a local translation proxy:
+
+```mermaid
+flowchart LR
+    gemini["Gemini CLI"]
+    gemini -->|"Tier 1: Google only"| google["Google directly"]
+    gemini -->|"Tier 2: everyone else"| proxy["rflectr proxy<br/>(127.0.0.1)"]
+    proxy --> sdk["Vercel AI SDK"]
+    sdk --> upstream["Anthropic / xAI / OpenAI / …"]
+```
+
+Your real API keys stay in rflectr (keychain / registry); the proxy holds them in memory for the session.
+
+---
+
+## Quick start
+
+```bash
+rflectr gemini
+```
+
+Pick provider → pick model → the Gemini prompt loop opens, pointed at the translation proxy automatically.
+
+### Flags
+
+| Flag | Purpose |
+|---|---|
+| *(none)* | Interactive launch. |
+| `--trace` | Write debug logs to `~/.rflectr/logs/gemini-proxy-debug.log`. |
+| `--help` | Help text. |
+
+rflectr manages `--provider` and `--model`; pass other Gemini CLI flags directly:
+
+```bash
+rflectr gemini -p "Analyze this"
+rflectr gemini --provider google --model gemini-2.5-flash -p "Review this file" -o stream-json
+```
+
+### Environment isolation
+
+On launch, rflectr builds a clean child environment: it removes conflicting Gemini env vars, points the CLI at the proxy via base-URL discovery, and sets the selected model. When the CLI exits (normal, `Ctrl+C`, or terminal close), your shell is unchanged.
+
+### Favorites catalog mode
+
+With favorites saved via `rflectr models`, `rflectr gemini` shows your starting model + favorites in the mid-session picker natively.
+
+---
+
+## Provider routing
+
+| Provider | Route | Notes |
+|---|---|---|
+| **Google** | Tier 1 direct | Native Gemini endpoints for best performance. |
+| **Anthropic, xAI, OpenAI, Nvidia, DeepSeek, …** | Tier 2 proxy | Converts Gemini-format requests to each native format via the Vercel AI SDK. |
+| **OpenCode Zen / Go** | Tier 2 proxy | Requires an OpenCode API key. |
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Provider missing in picker | `rflectr providers add` |
+| Model errors / disconnected | `rflectr gemini --trace`, then read `~/.rflectr/logs/gemini-proxy-debug.log` |
+| JSON parse error on first stdout lines (agents) | Add `-o stream-json` or `-o json` |
+
+**Known limitation:** the model name in the top-right of the Gemini CLI UI does not refresh after a mid-session `.model` switch. This is a Gemini CLI UI limitation, not a routing problem — the new model is active.
+
+---
+
+## Related guides
+
+- [AI Agents & automation](ai-agents.md) · [Providers](providers.md) · [Troubleshooting](../faqs/troubleshooting.md)
+- [Gemini CLI on npm](https://www.npmjs.com/package/@google/gemini-cli)

package/library/knowledge/public/guides/model-compatibility.md

@@ -0,0 +1,80 @@
+# Model Compatibility
+
+> Category: Guide | Version: 1.0 | Date: June 2026 | Status: Active
+
+Why some models don't appear in the picker, and how rflectr decides what to show. By default rflectr shows every model a provider's live API returns — models are hidden **only when there's a specific reason** (they can't run a coding agent, or a free promo ended).
+
+---
+
+## The two filters
+
+```mermaid
+flowchart TD
+    api["Live provider API model list"] --> bl{"In curated blacklist?"}
+    bl -->|yes| hide["Hidden"]
+    bl -->|no| cap{"In models.dev catalog<br/>and unfit for coding agents?"}
+    cap -->|yes| hide
+    cap -->|no| show["Shown in picker"]
+```
+
+1. **Curated blacklist** — `src/data/model-incompatible.json`. Researched entries, each with a provider, model id, category, reason, and sources.
+2. **models.dev capabilities** — a bundled full snapshot in `src/data/models-dev-cache.json` (~2 MB, all providers). When a model exists in that catalog, rflectr may auto-hide it if it can't support coding agents (no text output, `tool_call: false`, etc.). **Missing catalog data never hides a model.**
+
+**Offline / blocked network:** the bundled snapshot is always used when `~/.rflectr/models-dev-cache.json` is missing or a fetch fails. **On launch:** rflectr refreshes from `https://models.dev/api.json` in the background (non-blocking); the next compatibility check uses the updated file.
+
+---
+
+## Google Gemini (raw API)
+
+Google's `GET /v1/models` returns **many non-chat models** (Imagen, Veo, embeddings, TTS, robotics, …), and models.dev only catalogs a subset. So rflectr also keeps explicit `provider: google` entries in the blacklist for non-coding ids verified on the live API list. After `rflectr providers refresh-models`, if new non-coding ids appear, they should be added to the blacklist rather than matched by name patterns.
+
+---
+
+## "Why don't I see model X?"
+
+| Likely cause | What to do |
+|---|---|
+| It's a non-coding model (image/video/embedding/TTS). | Expected — those are filtered out. |
+| Its free promotion ended (stale id still returned by the API). | Expected — hidden via a `"*"` blacklist entry. |
+| Your model list is stale. | `rflectr providers refresh-models [provider]`. |
+| You think it's hidden by mistake. | Run with `--trace` where supported — hidden models log via `hideReason()`. |
+
+---
+
+## Maintainers
+
+### Add a blacklist entry
+
+Edit `src/data/model-incompatible.json`:
+
+```json
+{
+  "provider": "google",
+  "modelId": "example-bad-model",
+  "category": "managed_agent",
+  "reason": "Plain English explanation",
+  "sources": ["https://…"],
+  "verifiedAt": "2026-06-10"
+}
+```
+
+- Use `"provider": "*"` to hide a model id for **every** provider (stale promos, deprecated ids).
+- Optional `"agents": ["codex", "codex-app"]` limits hiding to specific launch surfaces.
+
+Rebuild after changes: `npm run build`.
+
+### Refresh the bundled snapshot
+
+Before a release (or when models.dev changes materially):
+
+```bash
+npm run refresh:models-dev
+```
+
+This commits an updated `src/data/models-dev-cache.json` for offline installs. The user cache path is `~/.rflectr/models-dev-cache.json`, written automatically on launch when the network allows.
+
+---
+
+## Related guides
+
+- [Providers](providers.md) · [Troubleshooting](../faqs/troubleshooting.md)

package/library/knowledge/public/guides/providers.md

@@ -0,0 +1,90 @@
+# Providers
+
+> Category: Guide | Version: 1.0 | Date: June 2026 | Status: Active
+
+Every provider rflectr can launch, the base URL each uses, and the gotchas worth knowing before you add one. New to rflectr? Start with [What is rflectr?](../overview/what-is-rflectr.md)
+
+---
+
+## How the registry works
+
+`rflectr` stores your providers and cached model lists in a **native provider registry** at `~/.rflectr/providers.json`. API keys are kept in your **OS keychain**, never in that file. Add a provider with:
+
+```bash
+rflectr providers add        # pick a template, paste a key
+rflectr providers import     # one-time import from an existing OpenCode setup
+rflectr providers list       # see what's configured
+```
+
+When you add a provider, rflectr picks the correct endpoint format (`@ai-sdk/openai-compatible` vs a provider-specific SDK) and fetches the available models automatically.
+
+---
+
+## Built-in cloud backends
+
+These are always available with an `OPENCODE_API_KEY` — they don't need to be added to the registry.
+
+| id | Description |
+|---|---|
+| `zen` | OpenCode Zen — free and paid models. |
+| `go` | OpenCode Go — paid models. |
+
+---
+
+## Hosted providers
+
+| Provider | Base URL | Notes |
+|---|---|---|
+| **Anthropic** | `https://api.anthropic.com` | Official Claude API. Recommended for standard Claude access. |
+| **OpenAI** | `https://api.openai.com/v1` | GPT, o-series reasoning models, and Codex. |
+| **Google Gemini** | `https://generativelanguage.googleapis.com/v1beta/openai` | Official Gemini API. |
+| **Groq** | `https://api.groq.com/openai/v1` | Ultra-fast inference for open-weight models (Llama, Mixtral). |
+| **Mistral** | `https://api.mistral.ai/v1` | ⚠️ Free tier has strict rate limits (HTTP 429) — tool-heavy sessions burn quota fast. |
+| **Together AI** | `https://api.together.xyz/v1` | Train, fine-tune, and run open-source models. |
+| **Cerebras** | `https://api.cerebras.ai/v1` | High-speed inference on wafer-scale chips. |
+| **DeepInfra** | `https://api.deepinfra.com/v1/openai` | Serverless inference for open-source models. |
+| **DeepSeek** | `https://api.deepseek.com/v1` | DeepSeek coding and chat models. |
+| **Zhipu AI (GLM)** | `https://open.bigmodel.cn/api/paas/v4` | The GLM model family. |
+| **Alibaba DashScope** | `https://dashscope.aliyuncs.com/compatible-mode/v1` | Qwen and other models. |
+| **xAI** | `https://api.x.ai/v1` | Grok models. Supports OAuth — see [Codex § OAuth](codex.md#oauth). |
+| **Perplexity** | `https://api.perplexity.ai` | Perplexity's online Sonar models. |
+| **Cohere** | `https://api.cohere.com/compatibility/v1` | Command models. |
+| **OpenRouter** | `https://openrouter.ai/api/v1` | Unified proxy to dozens of models. |
+
+---
+
+## Local models (Ollama & LM Studio)
+
+Connect to a locally running inference engine. When you add one, rflectr prompts for your local URL (e.g. `http://127.0.0.1:11434/v1`). You can leave the API key blank — local engines generally don't require auth.
+
+---
+
+## The Moonshot / Kimi confusion
+
+Moonshot AI split its product into **three separate platforms**. They all use the "Kimi" name but have **different billing, different base URLs, and non-interchangeable API keys**. Using the wrong template for your key gives a `401 Invalid Authentication` / `Incorrect API key` error.
+
+| Platform | For | Base URL | Key from |
+|---|---|---|---|
+| **Moonshot (Kimi)** | China domestic, pay-as-you-go | `https://api.moonshot.cn/v1` | `platform.moonshot.cn` |
+| **Moonshot Global (kimi.ai)** | International, pay-as-you-go | `https://api.moonshot.ai/v1` | `platform.kimi.ai` |
+| **Kimi Code** | Monthly coding subscription | `https://api.kimi.com/coding/v1` | `kimi.com/code/console` |
+
+> 💡 The **Global** platform also grants `kimi-k2.7-code` directly through the standard API — no separate coding subscription needed. If your key is from `platform.kimi.ai`, pick **Moonshot Global**.
+
+---
+
+## Advanced / not directly addable
+
+These need credentials beyond a simple API key, so they aren't in the `add` template list:
+
+| Provider | How to use |
+|---|---|
+| **Amazon Bedrock** | Needs AWS credentials. Configure in OpenCode, then `rflectr providers import`. |
+| **Azure OpenAI** | Needs per-model deployment URLs. Configure in OpenCode, then import. |
+| **Google Vertex AI** | Handled via `gcloud` Application Default Credentials through `rflectr server --vertex` — no registry key required. See [API Server § Vertex](api-server.md). |
+
+---
+
+## Related guides
+
+- [What is rflectr?](../overview/what-is-rflectr.md) · [Model compatibility](model-compatibility.md) · [Troubleshooting](../faqs/troubleshooting.md)

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

@@ -0,0 +1,7 @@
+# Overview
+
+Start-here material: what rflectr is and the vocabulary for everything else.
+
+| Doc | Covers |
+|---|---|
+| [what-is-rflectr.md](what-is-rflectr.md) | Elevator pitch, the surfaces you can launch, how it works in three ideas, and a glossary. |

package/library/knowledge/public/overview/what-is-rflectr.md

@@ -0,0 +1,71 @@
+# What is rflectr?
+
+> Category: Overview | Version: 1.0 | Date: June 2026 | Status: Active
+
+**rflectr** — *point your coding agents at any model.* Launch Claude Code, OpenAI Codex, Google Gemini CLI, and the Claude / Codex desktop apps against whatever model you want — OpenCode Zen & Go, or your own provider keys (Groq, Mistral, OpenAI, Gemini, DeepSeek, xAI, Ollama, and more) — without touching the host tool's own settings.
+
+Built by [Legion Code Inc.](https://github.com/legioncodeinc) · `npm install -g @legioncodeinc/rflectr`
+
+---
+
+## The one-paragraph version
+
+Every major AI coding tool talks only to its vendor's API out of the box. rflectr sits in front of them: you pick a provider and model from an interactive wizard, and rflectr launches the tool with an environment (or a translating local proxy) that makes it believe it's talking to its native API. Run Claude Code on a Groq Llama model, Codex on DeepSeek, or Gemini CLI on a local Ollama endpoint — same tools, any backend.
+
+```mermaid
+flowchart LR
+    you["You pick<br/>provider + model"] --> rflectr["rflectr"]
+    rflectr --> cc["Claude Code"]
+    rflectr --> cx["Codex CLI / app"]
+    rflectr --> gm["Gemini CLI"]
+    rflectr --> cd["Claude Desktop"]
+    cc & cx & gm & cd --> any["Any model backend<br/>(Zen/Go, Groq, OpenAI, Gemini, Ollama, …)"]
+```
+
+---
+
+## What you can launch
+
+| Command | Launches | Guide |
+|---|---|---|
+| `rflectr claude` | Claude Code CLI | (interactive — start here) |
+| `rflectr codex` / `codex-app` | OpenAI Codex CLI / desktop app | [Codex](../guides/codex.md) |
+| `rflectr gemini` | Google Gemini CLI | [Gemini CLI](../guides/gemini-cli.md) |
+| `rflectr claude-app` | Claude Desktop (Cowork + Code) | [Claude Desktop](../guides/claude-desktop.md) |
+| `rflectr server` | Local API gateway (Anthropic + OpenAI compatible) | [API Server](../guides/api-server.md) |
+| `rflectr providers` | Manage your provider registry | [Providers](../guides/providers.md) |
+| `rflectr models` | Pick favorites for mid-session `/model` switching | — |
+| `rflectr --ai` | Machine-readable reference for scripts & agents | [AI Agents](../guides/ai-agents.md) |
+
+---
+
+## How it works, in three ideas
+
+1. **A provider registry.** Your providers and their models live in `~/.rflectr/providers.json`; secrets live in your OS keychain, never in the file. Add providers with `rflectr providers add` or import them from OpenCode once. See [Providers](../guides/providers.md).
+
+2. **A single translation layer.** Anything that isn't natively Anthropic is routed through one path — the Vercel AI SDK — so the host tool's wire format is translated to and from your chosen model. There's no per-provider hand-rolled translator. See [Model compatibility](../guides/model-compatibility.md).
+
+3. **No settings-file surgery.** rflectr launches the host with a purpose-built environment and a throwaway local proxy on `127.0.0.1`. The two desktop apps are the exception — their config is patched, backed up, and restored on exit.
+
+---
+
+## Glossary
+
+| Term | Meaning |
+|---|---|
+| **Provider** | A source of models — `groq`, `openai`, `zen`, `go`, a local Ollama, etc. |
+| **Registry** | Your saved providers + cached model lists, at `~/.rflectr/providers.json`. |
+| **Zen / Go** | OpenCode's cloud backends. Always available with an `OPENCODE_API_KEY`. |
+| **Proxy** | The local `127.0.0.1` server rflectr starts to translate wire formats. |
+| **Favorites** | Up to 20 models saved with `rflectr models` for live `/model` switching. |
+| **Boot flags** | `--provider` / `--model` — skip the wizard for scripts and CI. |
+| **Gateway** | The `rflectr server` long-lived endpoint, used by Claude Desktop. |
+
+---
+
+## Where to go next
+
+- **Just want to use it?** Run `rflectr providers add`, then `rflectr claude`.
+- **Set up a specific tool:** [Codex](../guides/codex.md) · [Gemini CLI](../guides/gemini-cli.md) · [Claude Desktop](../guides/claude-desktop.md) · [API Server](../guides/api-server.md)
+- **Automating / scripting:** [AI Agents & automation](../guides/ai-agents.md)
+- **Something's wrong:** [Troubleshooting](../faqs/troubleshooting.md)

package/library/notes/README.md

@@ -0,0 +1,21 @@
+---
+ai_description: |
+  HUMAN-ONLY junk drawer. Agents MUST NOT read from, write to, create
+  files in, or reference files in this folder for any purpose.
+  If you want to capture something persistent, write to
+  library/knowledge/private/<domain>/<slug>.md instead.
+  This invariant is absolute and has no exceptions.
+human_description: |
+  Unstructured scratch space for humans. Agents do not touch this folder.
+  Put anything here: rough notes, links, half-formed ideas, meeting notes.
+  Nothing in notes/ is authoritative or maintained.
+  For persistent reference, move content to knowledge/private/ when it matures.
+---
+
+# Notes
+
+Human-only scratch space. Agents never read or write here.
+
+Put rough notes, links, and half-formed ideas here. Nothing here is authoritative.
+
+When a note matures into reference material, move it to `knowledge/private/<domain>/`.

package/library/requirements/README.md

@@ -0,0 +1,51 @@
+---
+ai_description: |
+  This folder contains all planned product and feature work (PRDs).
+  Sub-folders: backlog/ (queued, not started), in-work/ (actively
+  being implemented), completed/ (shipped), reports/ (routine code scans).
+  Lifecycle = location: move entire PRD folders between states.
+  PRD folder naming: prd-<###>-<kebab-slug>/
+  PRD numbers are repo-local sequential. Take max+1 from all prd-* folders
+  across backlog/, in-work/, and completed/.
+  Never write PRD content outside of a prd-<###>-<slug>/ folder.
+  Do NOT put IRDs here — those go in issues/ (peer of requirements/).
+human_description: |
+  Product and feature work (PRDs) organized by lifecycle stage.
+  - backlog/: planned work not yet started
+  - in-work/: currently being implemented
+  - completed/: shipped work (move entire folder here when done)
+  - reports/: routine code-scan and QA reports not tied to a specific PRD
+  To start a new PRD: create prd-<###>-<slug>/ in backlog/ with an index.md.
+  To move lifecycle: move the entire prd-<###>-<slug>/ folder.
+---
+
+# Requirements
+
+Product and feature work, organized by lifecycle state.
+
+## Sub-folders
+
+| Folder | State | Description |
+|---|---|---|
+| `backlog/` | Queued | PRDs planned but not yet started |
+| `in-work/` | Active | PRDs currently being implemented |
+| `completed/` | Shipped | Entire PRD folder moves here when work ships |
+| `reports/` | Evergreen | Routine code-scan and QA reports not tied to a PRD |
+
+## PRD folder structure
+
+```
+prd-007-user-export/
+  prd-007-user-export-index.md         module overview + feature list
+  prd-007a-user-export-backend.md      sub-feature a
+  prd-007b-user-export-ui.md           sub-feature b
+  qa/
+    prd-007-user-export-qa.md          QA audit (written by quality-guardian)
+```
+
+## Naming
+
+- Folder: `prd-<###>-<kebab-slug>/` (3-digit zero-padded)
+- Index: `prd-<###>-<kebab-slug>-index.md`
+- Sub-PRDs: `prd-<###><letter>-<kebab-slug>-<feature>.md`
+- PRD numbers are **repo-local sequential** — not GitHub issue numbers.

package/library/requirements/backlog/README.md

@@ -0,0 +1,30 @@
+---
+ai_description: |
+  Contains PRD folders planned but not yet started. This is where
+  library-guardian creates new PRD folders on "write a PRD for X".
+  PRD folder naming: prd-<###>-<kebab-slug>/ (3-digit zero-padded).
+  PRD number: take max+1 from all prd-* folders across backlog/,
+  in-work/, and completed/ in this repo.
+  Each PRD folder must contain: prd-<###>-<slug>-index.md (always),
+  prd-<###><letter>-<slug>-<feature>.md (one per sub-feature, optional),
+  qa/ subfolder (empty on creation; quality-guardian writes QA reports here).
+  Move entire folder to in-work/ when implementation begins.
+human_description: |
+  PRDs planned but not yet started. Create new PRDs here.
+  - Naming: prd-007-feature-name/ with prd-007-feature-name-index.md inside
+  - Sub-features: prd-007a-feature-name-backend.md, prd-007b-feature-name-ui.md
+  - QA folder: qa/prd-007-feature-name-qa.md (created by quality-guardian)
+  Move to in-work/ when implementation begins.
+---
+
+# Requirements — Backlog
+
+Planned PRDs not yet in implementation. All new PRD folders are created here.
+
+## Creating a new PRD
+
+1. Find `max_n` across `backlog/prd-*/`, `in-work/prd-*/`, `completed/prd-*/`.
+2. Create `prd-<max_n + 1>-<kebab-slug>/`.
+3. Create `prd-<###>-<slug>-index.md` (module overview + feature list).
+4. Create `qa/` subfolder (empty; `quality-guardian` writes reports here).
+5. Add sub-PRDs `prd-<###>a-<slug>-<feature>.md` etc. as needed.

package/library/requirements/completed/README.md

@@ -0,0 +1,14 @@
+---
+ai_description: |
+  Contains shipped PRD folders. Entire prd-<###>-<slug>/ folders move
+  here from in-work/ when the work ships. Read-only after landing here —
+  do NOT edit or move files out of completed/.
+  The PRD index, sub-PRDs, and qa/ sub-folder all travel together.
+human_description: |
+  Shipped PRD folders. Move entire prd-NNN-slug/ here from in-work/ when
+  the feature ships. Read-only — do not edit completed PRDs.
+---
+
+# Requirements — Completed
+
+Shipped PRD folders. Entire `prd-<###>-<slug>/` folders land here after the work ships and is confirmed in production. Do not edit files here after landing.