flowseeker 0.1.7 → 0.1.8

package/README.md

@@ -2,7 +2,7 @@
 
 # FlowSeeker
 
-**Find the files that matter for your task — *before* an AI starts reasoning.**
+**Give AI coding agents the right files before they start guessing.**
 
 [![VS Marketplace](https://img.shields.io/visual-studio-marketplace/v/everestt2806.flowseeker?label=VS%20Marketplace&color=1E63F1)](https://marketplace.visualstudio.com/items?itemName=everestt2806.flowseeker)
 [![Open VSX](https://img.shields.io/open-vsx/v/everestt2806/flowseeker?label=Open%20VSX&color=19D7F0)](https://open-vsx.org/extension/everestt2806/flowseeker)
@@ -11,365 +11,432 @@
 
 </div>
 
-FlowSeeker retrieves relevant codebase context **before** an AI starts reasoning. Describe the problem, get a ranked list of relevant files with reasons, and send a compact **Solve Packet** to the AI &mdash; not the entire repo.
+FlowSeeker is a context-prep layer for AI coding workflows. Describe a task, and FlowSeeker scans the codebase, ranks the relevant files, explains why they matter, and returns a compact **Solve Packet** for Claude Code, Codex, VS Code Chat, Cursor, Windsurf, Antigravity, or any MCP-compatible client.
 
----
-
-## Choose Your Path
+It does not try to replace your coding agent. It gives the agent a cleaner starting point: what to read, what may need editing, what is probably noise, what is missing, and which checks are worth running.
 
-> **I want the VS Code extension** &rarr; Install from the Marketplace/Open VSX and use Native VS Code Chat or the FlowSeeker sidebar.
->
-> **I want MCP only** &rarr; Install the npm package and connect `flowseeker-mcp` to Cursor, Antigravity, Windsurf, Claude Desktop, VS Code/Copilot, or another MCP client.
->
-> **I want both** &rarr; Install the extension. It includes the sidebar experience and a bundled FlowSeeker MCP server where the host supports MCP providers.
+```text
+Task: Fix grade export to Excel
+
+FlowSeeker returns:
+- likely edit files
+- read-only context files
+- routes/controllers/services/schema slots
+- missing links if the flow is incomplete
+- verification commands
+- token-savings proof
+- guardrails so the agent does not edit random files
+```
 
 ---
 
-## What FlowSeeker Does
+## Why This Exists
 
-You have a large project. You need to fix a bug, add a feature, or investigate a problem. You ask an AI agent. The AI reads the wrong files, hallucinates, or runs out of context.
+AI coding agents are powerful, but on large repos they often spend the first part of a task doing blind exploration:
 
-FlowSeeker fixes this by doing the retrieval first:
+- reading unrelated files
+- grepping broad keywords
+- mixing stale context from another project
+- filling gaps with guesses
+- burning tokens before reaching the real edit location
 
-- Finds every file that's **likely relevant** &mdash; not just code, but configs, migrations, templates, tests, docs
-- Explains **why** each file was selected &mdash; path match, content match, framework edge, dependency
-- Separates **edit candidates** from **read-only context** and **verification targets**
-- Reports **measured token savings** so you can see how much context the AI avoided loading
-- Reports **context coverage** so token savings are judged alongside whether required flow slots were found
+FlowSeeker handles that retrieval step first. The goal is simple: turn a vague code task into a small, evidence-backed context packet that an AI agent can act on.
 
 ---
 
-## Quick Start
+## Use It Your Way
 
-### If you installed the VS Code extension
+| Workflow | Best entry point |
+|---|---|
+| VS Code user | FlowSeeker sidebar or `@flowseeker /guide` |
+| Claude Code / Codex CLI user | `flowseeker guide`, `flowseeker auto`, `flowseeker files` |
+| MCP-first user | `flowseeker mcp`, `flowseeker-mcp`, or `fs-mcp` |
+| Marketplace/OpenVSX user | Install the extension |
+| Automation/eval user | Headless CLI and reproducible benchmark scripts |
 
-Open VS Code Chat (`Ctrl+Shift+I` or `Cmd+Shift+I`) and type:
+---
+
+## 30-Second Start
+
+### VS Code Chat
 
 ```text
-@flowseeker /guide The payment confirmation email is not being sent after checkout
+@flowseeker /guide The payment confirmation email is not sent after checkout
 ```
 
-FlowSeeker scans your project and returns a ranked results tree. The AI then explains what to look at, why, and what to change.
+FlowSeeker retrieves the relevant context and returns an agent-ready Solve Packet.
 
 ```text
 @flowseeker /auto Add SMS notification when payment fails
 ```
 
-Same scan, but the AI produces a **reviewable plan only**. No files are changed. After you review and approve, structured edits are generated and applied with one click.
+`/auto` starts from the same retrieval step, but asks the AI for a reviewable plan before edits.
 
-### If you installed the MCP server
+### Claude Code / Codex CLI
 
-Run the server and connect your IDE:
+Install from npm, then run FlowSeeker from the target repo:
 
 ```bash
-npx -p flowseeker flowseeker-mcp --workspace /path/to/your/repo
-```
+npm i -g flowseeker
 
-Then configure your IDE to connect to it — see [MCP Server](#mcp-server-cross-ide-integration) below for per-IDE setup.
+cd /path/to/your/repo
+flowseeker guide "Fix checkout webhook retry"
+flowseeker auto "Add CSV export with tests"
+flowseeker files "Find the auth middleware"
+flowseeker retrieve "Debug login session expiry"
+```
 
----
+FlowSeeker works immediately without embeddings. No API key, model, runtime, or setup is required for the default deterministic retrieval path.
 
-## MCP Server (Cross-IDE Native Chat)
+FlowSeeker core does not bundle the local embedding runtime/model in the npm or VSIX package; install `flowseeker-local` only when you want local embeddings.
 
-FlowSeeker ships a standalone **MCP server** for IDEs and AI clients that support the Model Context Protocol: Cursor, Antigravity, Windsurf, Claude Desktop, VS Code/Copilot, and others.
+Optional local embeddings with no API key:
 
-Use this path when you want FlowSeeker inside an IDE's Native Chat without installing the VS Code extension. The IDE's own model reasons over the Solve Packet, so FlowSeeker does not need a separate provider key.
+```bash
+npm i -g flowseeker-local
+flowseeker semantic init --local
+flowseeker semantic check --test
+```
 
-### Install
+If the ready local package is not available in your environment, use explicit project-level setup:
 
 ```bash
-# Run on demand, no global install
-npx -p flowseeker flowseeker-mcp --help
-npx -p flowseeker flowseeker-mcp --version
-
-# Or install globally
-npm i -g flowseeker
-flowseeker-mcp --help
-flowseeker-mcp --check-updates
+flowseeker semantic local setup --yes       # install @huggingface/transformers
+flowseeker semantic local download --yes     # fetch/cache model files
+flowseeker semantic check --test
 ```
 
-FlowSeeker 0.1.7 and newer also check for extension updates once per day and show a non-modal notice when a newer npm package is available. The MCP CLI never checks for updates during normal stdio server startup; use `flowseeker-mcp --check-updates` when you want an explicit check.
+Offline mode (pre-cached model, no network): `flowseeker semantic local download --yes --offline`
 
-### MCP Tools and Prompts
+Hosted embeddings are also supported through provider-neutral OpenAI-compatible config:
 
-| Tool | Purpose |
-|------|---------|
-| `flowseeker_retrieve` | Return a full Solve Packet with ranked evidence, context coverage, and token savings |
-| `flowseeker_guide` | Return an agent guidance prompt with relevant files, edit candidates, and verification steps |
-| `flowseeker_files` | Return a lightweight top-ranked file list |
-
-FlowSeeker also exposes short MCP prompts for clients that surface prompt suggestions:
+```bash
+flowseeker semantic init --openai-compatible
+# set semanticModel / semanticBaseUrl in .flowseeker/config.json
+# put your API key in .env as FLOWSEEKER_EMBEDDING_API_KEY
+flowseeker semantic check --test
+```
 
-| Prompt | Maps to |
-|--------|---------|
-| `retrieve` | `flowseeker_retrieve` |
-| `guide` | `flowseeker_guide` |
-| `files` | `flowseeker_files` |
+**Deterministic/no-embedding mode** works without setup and is the default. No API key, no runtime, no model - just code-structure analysis.
 
-Autocomplete behavior is controlled by the host IDE. Some clients show tools/prompts after selecting the MCP server; others only insert a server mention such as `@mcp:flowseeker:`. In those clients, use natural language or type the tool name directly.
+**Local evidence report:** Verify your local embedding setup produces valid vectors. The command is report-only - no install, no download, no network by default.
 
-### Native Chat Examples
+```bash
+# Structured JSON report (preferred):
+flowseeker semantic local evidence --json
+flowseeker semantic local evidence --report .flowseeker/local-evidence.json
 
-```text
-Use FlowSeeker to find relevant files for: fix payment confirmation email after checkout
+# Setup and download are explicit separate commands:
+flowseeker semantic local setup --yes
+flowseeker semantic local download --yes
 ```
 
-```text
-flowseeker_retrieve task: find where MCP server prompts/list is implemented
+The report includes: workspace, runtime/model status, readiness, provider, model ID, dimensions, vector count, finite check, embed latency, classification, and next action. Classifications: `runtime_missing`, `model_missing`, `model_invalid`, `pass`, `runtime_api_mismatch`, `embedding_shape_invalid`, `unknown_error`.
+
+**Developer/manual opt-in script** (source-repo only, requires env flags):
+```bash
+set FLOWSEEKER_RUN_REAL_LOCAL_RUNTIME_TEST=1
+set FLOWSEEKER_LOCAL_TEST_WORKSPACE=<path>
+node scripts/smoke-local-real-runtime-manual.js
+# Optional: allow install/download via FLOWSEEKER_ALLOW_RUNTIME_INSTALL=1 etc.
 ```
 
-In Antigravity, current builds may insert this prefix without showing a second-level command menu:
+Recommended terminal flow:
 
-```text
-@mcp:flowseeker: Use FlowSeeker to find relevant files for: fix MCP config loading
+```bash
+flowseeker auto "Fix payment retry idempotency" --out .flowseeker/agent-prompt.md
 ```
 
-That is a host UI limitation. FlowSeeker still works as long as the MCP server is connected.
+Then paste the generated prompt into Claude Code, Codex CLI, or your preferred agent.
 
-### IDE Configuration
+Short aliases are also available:
 
-#### Cursor
+```bash
+fs-guide "Fix checkout webhook retry"
+fs-auto "Add CSV export with tests"
+fs-files "Find the auth middleware"
+```
 
-Global config:
+### Claude Code MCP
 
-- macOS: `~/.cursor/mcp.json`
-- Windows: `%USERPROFILE%\.cursor\mcp.json`
+After global install, run the one-command setup from your project:
 
-Project config:
+```bash
+# One-command setup (preview first, then apply):
+flowseeker setup claude --no-exec
+flowseeker setup claude --yes
 
-- `.cursor/mcp.json` in your project root
+# Optional: add ready local embeddings (no API key needed)
+npm i -g flowseeker-local
 
-```json
-{
-  "mcpServers": {
-    "flowseeker": {
-      "command": "npx",
-      "args": ["-p", "flowseeker", "flowseeker-mcp", "--workspace", "."]
-    }
-  }
-}
+# Verify everything:
+flowseeker doctor --mcp
+flowseeker semantic check --test
 ```
 
-#### Antigravity
+Also available: `flowseeker setup codex`, `flowseeker setup cursor`, `flowseeker setup vscode`. Then ask Claude Code to use FlowSeeker for the task. The MCP server exposes `flowseeker_guide`, `flowseeker_auto`, `flowseeker_retrieve`, and `flowseeker_files`.
 
-Config file:
+### MCP Server
 
-- macOS: `~/.gemini/antigravity/mcp_config.json`
-- Windows: `%USERPROFILE%\.gemini\antigravity\mcp_config.json`
-
-```json
-{
-  "mcpServers": {
-    "flowseeker": {
-      "command": "npx",
-      "args": ["-p", "flowseeker", "flowseeker-mcp", "--workspace", "."]
-    }
-  }
-}
+```bash
+npx -p flowseeker flowseeker-mcp --workspace /path/to/your/repo
 ```
 
-Testing a local build before npm publish:
+Short alias after install:
 
-```json
-{
-  "mcpServers": {
-    "flowseeker": {
-      "command": "node",
-      "args": [
-        "D:\\Developing\\FlowSeeker\\dist\\cli\\mcpServer.js",
-        "--workspace",
-        "D:\\Developing\\FlowSeeker"
-      ]
-    }
-  }
-}
+```bash
+flowseeker mcp --workspace /path/to/your/repo
+fs-mcp --workspace /path/to/your/repo
 ```
 
-#### Windsurf
+For Cursor, Antigravity, Windsurf, Claude Desktop, and VS Code/Copilot config snippets, see [docs/mcp-onboarding.md](docs/mcp-onboarding.md).
 
-Config file:
+---
 
-- macOS: `~/.codeium/windsurf/mcp_config.json`
-- Windows: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
+## What A Solve Packet Contains
 
-```json
-{
-  "mcpServers": {
-    "flowseeker": {
-      "command": "npx",
-      "args": ["-p", "flowseeker", "flowseeker-mcp", "--workspace", "."]
-    }
-  }
-}
-```
+FlowSeeker separates context by role so the agent can act without treating every file as an edit target.
 
-#### VS Code / GitHub Copilot
+| Section | Purpose |
+|---|---|
+| **Primary edit candidates** | Files most likely to need changes |
+| **Read-only context** | Files that explain behavior but should not be edited by default |
+| **Candidate Flow** | Route/controller/service/schema/test style flow slots |
+| **Missing Links** | Required context that was not found, with search hints |
+| **Noise Risk** | Files that matched keywords but may be irrelevant |
+| **Verification** | Focused checks and test targets |
+| **Token proof** | Solve Packet size compared with scanned/indexed workspace text |
 
-VS Code uses `.vscode/mcp.json` and root key `servers`:
+This is the core idea: the agent starts with a map, not a pile of files.
 
-```json
-{
-  "servers": {
-    "flowseeker": {
-      "command": "npx",
-      "args": ["-p", "flowseeker", "flowseeker-mcp", "--workspace", "."]
-    }
-  }
-}
-```
+---
 
-#### Claude Desktop
+## Features
 
-Add to `claude_desktop_config.json`:
+- **Task-aware retrieval**: understands the task shape, extracts keywords, and checks required context slots.
+- **Evidence-ranked files**: every selected file includes score, role, slot, confidence, and reasons.
+- **Solve Packet 3.0**: compact markdown packet designed for AI coding agents.
+- **CLI-first workflow**: `fs-guide`, `fs-auto`, `fs-files`, `fs-retrieve`, and `fs-mcp`.
+- **One-command install path**: `npm i -g flowseeker`, then `flowseeker guide`, `flowseeker auto`, or `flowseeker mcp`.
+- **MCP support**: exposes retrieval tools and prompts through a standalone stdio server.
+- **VS Code integration**: sidebar, result tree, Native Chat participant, and bundled MCP provider where supported.
+- **Structured extraction**: structured-regex parser for 13 languages.
+- **Semantic retrieval setup**: optional local or hosted embeddings configured via `.flowseeker/config.json`, verified with `flowseeker semantic check --test`.
+- **Cache safety**: atomic cache writes, corrupt-cache recovery, and delete cleanup checks.
+- **Honest fallbacks**: if context is incomplete, FlowSeeker reports missing links instead of pretending it knows.
+
+---
+
+## MCP Tools
+
+FlowSeeker exposes these MCP tools:
+
+| Tool | Use |
+|---|---|
+| `flowseeker_retrieve` | Return the full Solve Packet |
+| `flowseeker_guide` | Return an agent guidance prompt |
+| `flowseeker_auto` | Return a reviewable implementation-plan prompt |
+| `flowseeker_files` | Return top ranked files only |
+
+Example MCP config:
 
 ```json
 {
   "mcpServers": {
     "flowseeker": {
       "command": "npx",
-      "args": ["-p", "flowseeker", "flowseeker-mcp", "--workspace", "/path/to/repo"]
+      "args": ["-p", "flowseeker", "flowseeker-mcp", "--workspace", "."]
     }
   }
 }
 ```
 
-### How It Works
-
-1. Your IDE sends a tool call to the FlowSeeker MCP server.
-2. FlowSeeker runs the headless pipeline: scan workspace, rank evidence, build Solve Packet.
-3. The compact result returns to your IDE's model.
-4. The model answers in your native chat with focused context instead of reading the whole repository.
+VS Code/Copilot `.vscode/mcp.json` uses `servers` instead of `mcpServers`.
 
 ---
 
-## Token Measurement
+## Evidence-Backed Capabilities
 
-FlowSeeker measures token reduction from the actual text it prepares, then evaluates retrieval quality and context coverage separately. That keeps the claim grounded: fewer tokens only matter if the expected files and required flow slots still appear.
+FlowSeeker avoids inflated claims. The public claims below are tied to reproducible local checks.
 
-FlowSeeker uses three measurement levels:
+| Capability | Evidence |
+|---|---|
+| Cold scan under 2s (153 files) / 5s (149 files) for benchmarked workspaces | Generated by `scripts/smoke-phase06-warm-query-performance.js` |
+| Warm reuse with zero churn on unchanged workspace | Phase 06 warm query report |
+| Solve Packet 3.0 with 5 role sections | Phase 07 packet gate report |
+| Candidate Flow with numbered execution steps | Packet gate report and Solve Packet output |
+| Actionable Missing Links with slot-specific search hints | Packet gate report and Solve Packet output |
+| Runnable verification commands with separate metadata | Packet gate report |
+| Structured-regex parser for 13 languages | `src/index/structuredExtractor.ts` |
+| Delete safety and corrupt-cache recovery | Phase 06 smoke scripts |
+| VS Code extension, MCP stdio, and headless CLI | `src/extension.ts`, `src/mcp/mcpTools.ts`, `src/cli/*` |
+| 9 smoke tests passing on clean compile | `npm.cmd run test:smoke` |
 
-| Level | When used | What it means |
-|-------|-----------|---------------|
-| `local_bpe` / `cl100k_base` | Default headless, sidebar, and report path | Workspace text and Solve Packet text are counted with the same BPE tokenizer |
-| VS Code model `countTokens()` | Native VS Code Chat when the selected model exposes token counting | The exact prompt sent to the selected chat model is counted by that model provider |
-| `heuristic` / `chars_per_4` | Fallback only if local tokenization fails | Conservative compatibility fallback, marked as heuristic |
+### Reproduce The Proof
 
-The baseline is not a guess from file count. FlowSeeker tokenizes eligible workspace text during indexing, stores per-file token counts, and compares that against the final Solve Packet text sent to the AI workflow.
+```bash
+npm.cmd run compile --silent
+npm.cmd run test:manifest
+npm.cmd run test:smoke
 
-FlowSeeker shows these metrics directly after each retrieval:
+node scripts/analyze-phase08-public-proof.js --out-md .flowseeker/reports/phase08-8a-public-proof.md --out-json .flowseeker/reports/phase08-8a-public-proof.json
+node scripts/smoke-phase06-warm-query-performance.js --out-md .flowseeker/reports/phase06-6g-warm-query-performance.md --out-json .flowseeker/reports/phase06-6g-warm-query-performance.json
+```
 
-| Metric | Meaning |
-|--------|---------|
-| Solve Packet tokens | Tokens in the FlowSeeker packet prepared for the AI |
-| Workspace tokens | Tokens in eligible workspace text files, counted during indexing |
-| Reduction | Context reduction from workspace text to Solve Packet |
-| Context coverage | Required slots found for the task shape, such as entry, handler, data, validation, permissions, side effects, or tests |
+Generated reports are written under `.flowseeker/reports/`.
 
 ---
 
-## How to Use (VS Code Extension)
+## Supported Languages
 
-### Chat Commands
+Structured-regex extraction currently supports:
 
-| Command | What it does |
-|---------|--------------|
-| `@flowseeker /guide <task>` | Retrieve context, get explanation and guidance |
-| `@flowseeker /auto <task>` | Retrieve context, get a reviewable plan before any edits |
-| `@flowseeker /apply <planId>` | After approving a plan, generate structured edits |
+TypeScript, JavaScript, Python, PHP, Dart, Java, Go, Ruby, C#, Swift, Kotlin, Rust, and Scala.
 
-### Agent Workflow
+Tree-sitter support is available for TypeScript/JavaScript but is not part of the default public benchmark claim.
 
-FlowSeeker intentionally separates retrieval, planning, editing, and verification:
+---
 
-1. Retrieve a Solve Packet from the workspace.
-2. Ask the AI for a reviewable plan in the user's language.
-3. Disable approval if the AI only asks for more context instead of returning a real plan.
-4. After approval, ask for structured JSON edits only.
-5. Show a diff before applying edits, unless auto-apply is explicitly enabled.
-6. Run focused verification commands when requested or allowed by your approval policy.
+## Optional Semantic Retrieval
 
-If the AI says the packet is incomplete, FlowSeeker reads a small bounded set of candidate files and retries the plan or edit request.
+FlowSeeker works without embeddings by default. Semantic retrieval only runs when you explicitly enable it.
 
-### Command Palette
+Default mode needs no setup:
 
-| Command | Action |
-|---------|--------|
-| `FlowSeeker: Find Relevant Context` | Run retrieval from the command palette |
-| `FlowSeeker: Copy Context Pack` | Copy evidence as markdown for external AI tools |
-| `FlowSeeker: Check Host Compatibility` | Inspect Native Chat, Language Model, and MCP support in the current editor |
+```bash
+flowseeker guide "Find the checkout retry logic"
+```
 
-### If You Don't Have Native Chat
+Optional local embeddings with no API key:
 
-VS Code-compatible editors vary in how much of the VS Code Chat and Language Model APIs they expose. If `@flowseeker` is unavailable, use the **FlowSeeker sidebar** when the extension host supports it, or use the **MCP server** above to integrate FlowSeeker with your IDE's native chat.
+```bash
+npm i -g flowseeker-local
+flowseeker semantic init --local
+flowseeker semantic check --test
+```
 
----
+Optional hosted embeddings:
 
-## Configuration
+```bash
+flowseeker semantic init --openai-compatible
+# Edit .flowseeker/config.json:
+#   semanticModel = the embedding model exposed by your provider
+#   semanticBaseUrl = provider endpoint if needed
+# Add the key to .env:
+#   FLOWSEEKER_EMBEDDING_API_KEY=your_key_here
+flowseeker semantic check --test
+```
 
-Add `.flowseeker/config.json` to your project root:
+Non-secret settings (provider, model, base URL, cache, limits) are written to `.flowseeker/config.json`. Only `FLOWSEEKER_EMBEDDING_API_KEY` goes into `.env`.
 
-```json
-{
-  "project": {
-    "include": ["src", "app", "lib", "tests"],
-    "exclude": ["node_modules", "vendor", "dist", "build"]
-  },
-  "synonyms": {
-    "mail": ["email", "smtp", "notification"],
-    "payment": ["billing", "invoice", "checkout", "transaction"]
-  }
-}
+Expected result:
+
+```text
+Result: active
+Provider test: passed
+```
+
+**Generic OpenAI-compatible path:**
+
+```bash
+flowseeker semantic init --openai-compatible
+# edit .flowseeker/config.json to set semanticModel before --test
+# set semanticBaseUrl if your provider needs a custom endpoint
+# fill FLOWSEEKER_EMBEDDING_API_KEY in .env
+flowseeker semantic check --test
 ```
 
-`include` / `exclude` control which folders are indexed; `synonyms` expand task keywords during retrieval.
+Config keys in `.flowseeker/config.json`:
+- `semanticProvider` (e.g. `openaiCompatible`)
+- `semanticBaseUrl` (provider endpoint)
+- `semanticModel` (embedding model name from your provider)
+- `semanticApiKeyEnv` (env var name for the key)
+
+If token usage does not change on your provider dashboard, check `flowseeker semantic check` first. Most cases mean semantic is still disabled, the key is missing from the target repo's `.env`, or cached embeddings are being reused.
+
+**Embedding modes**: FlowSeeker works without embeddings by default.
+
+- **Deterministic (default)**: No setup, no API key, no runtime, no model. Code-structure analysis only.
+- **Local (no API key)**: Install the optional `flowseeker-local` package, run `flowseeker semantic init --local`, then `flowseeker semantic check --test`. If needed, use project-level `semantic local setup/download`.
+- **Hosted**: Bring your own embedding endpoint, model, and API key. Use `flowseeker semantic init --openai-compatible`, set the model/base URL, put the key in `.env`, then run `flowseeker semantic check --test`.
+
+Use `flowseeker semantic check` or `flowseeker doctor` to confirm your status.
+
+**Hosted provider note**: `--openai-compatible` initializes a provider-neutral config. Before `--test`, set `semanticModel` to the embedding model exposed by your provider. Set `semanticBaseUrl` if your provider needs a custom endpoint. The API key goes in `.env`. The model must match the provider and base URL.
 
 ---
 
 ## Install
 
-### VS Code Extension
+### VS Code / OpenVSX
 
-Search **FlowSeeker** in VS Code Extensions (`Ctrl+Shift+X`), or:
+Search **FlowSeeker** in VS Code Extensions, or run:
 
-```
+```text
 ext install everestt2806.flowseeker
 ```
 
-FlowSeeker is also available on Open VSX for editors such as VSCodium and Eclipse Theia:
-
-```
-open-vsx.org/extension/everestt2806/flowseeker
-```
+Also available on Open VSX for VSCodium and Eclipse Theia-compatible hosts.
 
-### MCP Server (npm)
+### npm / MCP / CLI
 
 ```bash
-# Run on demand (no install needed)
 npx -p flowseeker flowseeker-mcp --help
-
-# Or install globally
 npm i -g flowseeker
+flowseeker --help
+fs-guide --help
+flowseeker mcp --help
+flowseeker semantic check
 ```
 
 ---
 
-## Requirements
+## Current Limits
+
+These are intentionally explicit so users know what is proven today:
 
-- **For the VS Code extension:** VS Code 1.90 or later, plus a VS Code language model, a configured AI provider, or an external AI chat tool.
-- **For the MCP server:** Node.js 18 or later and any MCP-compliant client (Cursor, Antigravity, Windsurf, Claude Desktop, VS Code/Copilot, etc.).
+- No sub-second cold-scan guarantee.
+- AI/LLM-based reranking exists experimentally but is disabled by default.
+- Semantic/embedding retrieval is configurable but disabled by default.
+- Tree-sitter parser support exists, but public proof uses structured-regex extraction.
+- Graph expansion is not a production default.
+- Monorepo, git-history, and LSP integrations are not public guarantees yet.
 
 ---
 
-## Supported Languages & Frameworks
+## Roadmap
 
-| Level | What | Coverage |
-|-------|------|----------|
-| **Universal** | Path/content/chunk search | Every text file |
-| **Structured** | Symbol, call, string, comment extraction | TypeScript, JavaScript, Python, PHP, Java, Go, C#, Ruby, Rust, Kotlin |
-| **Framework-aware** | Route -> controller -> service -> model -> test edges | Laravel, NestJS, Express |
+- Real-repo demo screenshots and short videos.
+- More public benchmark fixtures across larger repo shapes.
+- Cleaner first-run onboarding for MCP hosts.
+- Bundled extension packaging to reduce VSIX size and startup overhead.
+- Optional semantic retrieval profiles with provider-specific setup checks.
+
+---
 
 ---
 
+## Rollback / Disable Semantic Retrieval
+
+FlowSeeker works without embeddings. To return to deterministic/no-embedding mode:
+
+```bash
+# Disable semantic retrieval
+flowseeker semantic check --workspace .  # confirm current status
+# Edit .flowseeker/config.json: set "semanticEnabled": false
+# Or remove the "index" block's semantic keys entirely
+flowseeker benchmark  # verify: deterministic_no_embedding = first_class
+flowseeker semantic check  # should show Result: disabled
+```
+
+Safe to remove from `.flowseeker/config.json`:
+- `semanticEnabled`, `semanticProvider`, `semanticBaseUrl`, `semanticModel`, `semanticApiKeyEnv`, `semanticCache`, `semanticMaxFilesPerRun`, `semanticTimeoutMs`, `semanticLocalModelPath`, `semanticLocalModelId`, `semanticDimensions`, `semanticRuntime`
+
+Safe to remove from `.env`:
+- `FLOWSEEKER_EMBEDDING_API_KEY`
+
+No models are bundled or auto-downloaded. Removing the config keys above returns FlowSeeker to its default deterministic retrieval mode. Use `flowseeker benchmark` anytime to confirm what is active.
+
 ## License
 
 MIT