flowseeker 0.1.7

package/README.md

@@ -0,0 +1,375 @@
+<div align="center">
+
+# FlowSeeker
+
+**Find the files that matter for your task &mdash; *before* an AI starts reasoning.**
+
+[![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)
+[![npm](https://img.shields.io/npm/v/flowseeker?color=CB3837)](https://www.npmjs.com/package/flowseeker)
+[![License: MIT](https://img.shields.io/badge/License-MIT-success.svg)](./LICENSE)
+
+</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.
+
+---
+
+## Choose Your Path
+
+> **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.
+
+---
+
+## What FlowSeeker Does
+
+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.
+
+FlowSeeker fixes this by doing the retrieval first:
+
+- 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
+
+---
+
+## Quick Start
+
+### If you installed the VS Code extension
+
+Open VS Code Chat (`Ctrl+Shift+I` or `Cmd+Shift+I`) and type:
+
+```text
+@flowseeker /guide The payment confirmation email is not being 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.
+
+```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.
+
+### If you installed the MCP server
+
+Run the server and connect your IDE:
+
+```bash
+npx -p flowseeker flowseeker-mcp --workspace /path/to/your/repo
+```
+
+Then configure your IDE to connect to it — see [MCP Server](#mcp-server-cross-ide-integration) below for per-IDE setup.
+
+---
+
+## MCP Server (Cross-IDE Native Chat)
+
+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.
+
+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.
+
+### Install
+
+```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 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.
+
+### MCP Tools and Prompts
+
+| 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:
+
+| Prompt | Maps to |
+|--------|---------|
+| `retrieve` | `flowseeker_retrieve` |
+| `guide` | `flowseeker_guide` |
+| `files` | `flowseeker_files` |
+
+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.
+
+### Native Chat Examples
+
+```text
+Use FlowSeeker to find relevant files for: fix payment confirmation email after checkout
+```
+
+```text
+flowseeker_retrieve task: find where MCP server prompts/list is implemented
+```
+
+In Antigravity, current builds may insert this prefix without showing a second-level command menu:
+
+```text
+@mcp:flowseeker: Use FlowSeeker to find relevant files for: fix MCP config loading
+```
+
+That is a host UI limitation. FlowSeeker still works as long as the MCP server is connected.
+
+### IDE Configuration
+
+#### Cursor
+
+Global config:
+
+- macOS: `~/.cursor/mcp.json`
+- Windows: `%USERPROFILE%\.cursor\mcp.json`
+
+Project config:
+
+- `.cursor/mcp.json` in your project root
+
+```json
+{
+  "mcpServers": {
+    "flowseeker": {
+      "command": "npx",
+      "args": ["-p", "flowseeker", "flowseeker-mcp", "--workspace", "."]
+    }
+  }
+}
+```
+
+#### Antigravity
+
+Config file:
+
+- macOS: `~/.gemini/antigravity/mcp_config.json`
+- Windows: `%USERPROFILE%\.gemini\antigravity\mcp_config.json`
+
+```json
+{
+  "mcpServers": {
+    "flowseeker": {
+      "command": "npx",
+      "args": ["-p", "flowseeker", "flowseeker-mcp", "--workspace", "."]
+    }
+  }
+}
+```
+
+Testing a local build before npm publish:
+
+```json
+{
+  "mcpServers": {
+    "flowseeker": {
+      "command": "node",
+      "args": [
+        "D:\\Developing\\FlowSeeker\\dist\\cli\\mcpServer.js",
+        "--workspace",
+        "D:\\Developing\\FlowSeeker"
+      ]
+    }
+  }
+}
+```
+
+#### Windsurf
+
+Config file:
+
+- macOS: `~/.codeium/windsurf/mcp_config.json`
+- Windows: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
+
+```json
+{
+  "mcpServers": {
+    "flowseeker": {
+      "command": "npx",
+      "args": ["-p", "flowseeker", "flowseeker-mcp", "--workspace", "."]
+    }
+  }
+}
+```
+
+#### VS Code / GitHub Copilot
+
+VS Code uses `.vscode/mcp.json` and root key `servers`:
+
+```json
+{
+  "servers": {
+    "flowseeker": {
+      "command": "npx",
+      "args": ["-p", "flowseeker", "flowseeker-mcp", "--workspace", "."]
+    }
+  }
+}
+```
+
+#### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "flowseeker": {
+      "command": "npx",
+      "args": ["-p", "flowseeker", "flowseeker-mcp", "--workspace", "/path/to/repo"]
+    }
+  }
+}
+```
+
+### 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.
+
+---
+
+## Token Measurement
+
+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 uses three measurement levels:
+
+| 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 |
+
+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.
+
+FlowSeeker shows these metrics directly after each retrieval:
+
+| 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 |
+
+---
+
+## How to Use (VS Code Extension)
+
+### Chat Commands
+
+| 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 |
+
+### Agent Workflow
+
+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.
+
+If the AI says the packet is incomplete, FlowSeeker reads a small bounded set of candidate files and retries the plan or edit request.
+
+### Command Palette
+
+| 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 |
+
+### If You Don't Have Native Chat
+
+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.
+
+---
+
+## Configuration
+
+Add `.flowseeker/config.json` to your project root:
+
+```json
+{
+  "project": {
+    "include": ["src", "app", "lib", "tests"],
+    "exclude": ["node_modules", "vendor", "dist", "build"]
+  },
+  "synonyms": {
+    "mail": ["email", "smtp", "notification"],
+    "payment": ["billing", "invoice", "checkout", "transaction"]
+  }
+}
+```
+
+`include` / `exclude` control which folders are indexed; `synonyms` expand task keywords during retrieval.
+
+---
+
+## Install
+
+### VS Code Extension
+
+Search **FlowSeeker** in VS Code Extensions (`Ctrl+Shift+X`), or:
+
+```
+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
+```
+
+### MCP Server (npm)
+
+```bash
+# Run on demand (no install needed)
+npx -p flowseeker flowseeker-mcp --help
+
+# Or install globally
+npm i -g flowseeker
+```
+
+---
+
+## Requirements
+
+- **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.).
+
+---
+
+## Supported Languages & Frameworks
+
+| 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 |
+
+---
+
+## License
+
+MIT