@legioncodeinc/rflectr 0.1.1 → 0.1.2

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

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

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

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

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

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

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

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

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

@@ -1,14 +0,0 @@
----
-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.