flowseeker 0.1.7 → 0.1.9

package/dist/pipeline/subsystem.js

@@ -217,8 +217,29 @@ function subsystemAlignmentScore(unit, profile) {
     if (matches.length > 0) {
         return 4 + Math.min(10, matches.length * 4);
     }
+    // Penalize files whose subsystem terms are clearly unrelated to the task
+    const hasClearDomainMismatch = unitTerms.length > 0 && taskTerms.length > 0 &&
+        !unitTerms.some((ut) => taskTerms.some((tt) => overlap3(ut, tt)));
+    if (hasClearDomainMismatch) {
+        return -16;
+    }
     return 0;
 }
+function overlap3(a, b) {
+    if (a === b)
+        return true;
+    if (a.length < 3 || b.length < 3)
+        return false;
+    for (let i = 0; i <= a.length - 3; i++) {
+        if (b.includes(a.slice(i, i + 3)))
+            return true;
+    }
+    for (let i = 0; i <= b.length - 3; i++) {
+        if (a.includes(b.slice(i, i + 3)))
+            return true;
+    }
+    return false;
+}
 function primarySubsystemFromUnits(units) {
     const counts = new Map();
     for (const unit of units) {

package/dist/pipeline/taskUnderstanding.js

@@ -106,7 +106,7 @@ const lowSignalInstructionTerms = new Set([
     "function",
     "functionality"
 ]);
-function understandTask(task, config) {
+async function understandTask(task, config, workspaceRoot) {
     const normalizedTask = (0, text_1.normalizeText)(task);
     const rawTokens = (0, text_1.splitIdentifier)(task);
     const literalCodeTerms = detectLiteralCodeTerms(task);
@@ -118,7 +118,7 @@ function understandTask(task, config) {
     const keywords = (0, text_1.uniq)([...literalCodeTerms, ...concepts, ...synonymTerms, ...actionTerms]).filter((term) => term.length > 1);
     const intent = detectIntent(normalizedTask);
     const negativeTerms = detectNegativeTerms(normalizedTask);
-    const blueprint = (0, contextBlueprint_1.buildTaskBlueprint)({ intent: intent.intent, normalizedTask, concepts, actions, keywords, negativeTerms, confidence: intent.confidence });
+    const blueprint = await (0, contextBlueprint_1.buildTaskBlueprint)({ intent: intent.intent, normalizedTask, concepts, actions, keywords, negativeTerms, confidence: intent.confidence, workspaceRoot });
     const retrieval = (0, retrievalPlan_1.createRetrievalPlan)({ rawTask: task, normalizedTask, concepts, actions, keywords, blueprint }, config);
     return {
         rawTask: task,

package/dist/ui/chatViewProvider.js

@@ -1102,7 +1102,7 @@ class ChatViewProvider {
     }
     renderHtml(webview) {
         const nonce = getNonce();
-        const logoUri = webview.asWebviewUri(vscode.Uri.joinPath(this.context.extensionUri, "resources", "flowseeker-logo-vector-v2.svg"));
+        const logoUri = webview.asWebviewUri(vscode.Uri.joinPath(this.context.extensionUri, "resources", "flowseeker-logo.png"));
         const providerOptions = aiProviders_1.AI_PROVIDER_DEFINITIONS.map((provider) => `<option value="${provider.id}">${escapeHtml(provider.label)}</option>`).join("");
         const providerMeta = JSON.stringify(Object.fromEntries(aiProviders_1.AI_PROVIDER_DEFINITIONS.map((provider) => [
             provider.id,

package/docs/demo-screenshot-checklist.md

@@ -0,0 +1,86 @@
+# FlowSeeker Demo And Screenshot Checklist
+
+Use this checklist before refreshing landing-page, Marketplace, OpenVSX, npm,
+or README screenshots. It is intentionally conservative: screenshots should show
+current FlowSeeker output, not future-state features.
+
+## Source Of Truth
+
+- Public proof audit: `.flowseeker/reports/phase08-8a-public-proof.json`
+- Solve Packet proof: `.flowseeker/reports/phase07-7f-final-packet-gates.json`
+- Performance proof: `.flowseeker/reports/phase06-6g-warm-query-performance.json`
+- README: `README.md`
+- MCP onboarding: `docs/mcp-onboarding.md`
+
+## Required Demo Scenes
+
+1. **VS Code retrieval flow**
+   - Show `@flowseeker /guide <task>`.
+   - Show focused context or Solve Packet output.
+   - Do not imply automatic code edits.
+
+2. **Solve Packet 3.0 structure**
+   - Show the role-separated sections:
+     Primary Edit Candidates, Read-Only Context, Tests/Verification,
+     Noise Risk, Missing Links.
+   - Include visible evidence reasons where possible.
+
+3. **MCP setup**
+   - Show one copy-pasteable config from `docs/mcp-onboarding.md`.
+   - Prefer Cursor or VS Code/Copilot because both are common MCP entry points.
+
+4. **Evidence-backed proof**
+   - Show the reproducible command block from README.
+   - Include report paths, not broad marketing claims.
+
+## Assets To Review
+
+Current assets found under `landing/`:
+
+- `landing/hero.png`
+- `landing/dark.png`
+- `landing/bench.png`
+- `landing/compare.png`
+- `landing/mobile.png`
+
+Before public publishing, verify each image still matches current product output.
+If an asset shows older UI, future-state graph expansion, default semantic search,
+or unsupported parser claims, replace or remove it.
+
+## Claims Allowed In Captions
+
+- "Focused codebase context before AI reasoning"
+- "Solve Packet with edit candidates, read-only context, verification targets,
+  noise risk, and missing links"
+- "Structured-regex parser for 13 languages"
+- "MCP stdio support through `flowseeker-mcp`"
+- "Cold scan under 2s medium / under 5s large for the benchmarked workspaces"
+  only when the Phase 06 report path is visible nearby
+
+## Claims To Avoid
+
+- "AI-powered search" as a default behavior
+- "Sub-second cold scan"
+- "Semantic search by default"
+- "Tree-sitter production accuracy"
+- "Graph expansion in production"
+- "Monorepo support"
+- "Git history integration"
+- "LSP integration"
+
+## Verification Commands
+
+```bash
+npm.cmd run compile --silent
+npm.cmd run test:manifest
+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
+```
+
+## Public Publishing Gate
+
+Public screenshots are ready only when:
+
+- screenshots show current FlowSeeker output,
+- every visible claim maps to the public proof audit,
+- no blocked claim appears as a product capability,
+- the README and marketplace copy use the same wording boundaries.

package/docs/marketplace-copy.md

@@ -0,0 +1,92 @@
+# FlowSeeker Marketplace Copy
+
+This file is the evidence-backed copy source for VS Code Marketplace, OpenVSX,
+and npm descriptions. Keep it aligned with `README.md` and the Phase 08 public
+proof report.
+
+## One-Line Description
+
+FlowSeeker prepares focused codebase context for AI coding agents before they
+start reasoning.
+
+## Short Description
+
+FlowSeeker scans your workspace, ranks relevant files with evidence reasons, and
+returns a compact Solve Packet instead of sending the whole repository to an AI
+agent.
+
+## Marketplace Summary
+
+FlowSeeker helps AI coding agents start with the right codebase context. You
+describe a task, and FlowSeeker prepares a focused Solve Packet with edit
+candidates, read-only context, verification targets, noise risk warnings, and
+missing link alerts.
+
+It works as a VS Code extension, an MCP stdio server through `flowseeker-mcp`,
+and a headless CLI path for reproducible evaluation.
+
+## Evidence-Backed Capability Bullets
+
+- Solve Packet 3.0 with role-separated sections for edit candidates, read-only
+  context, tests/verification, noise risk, and missing links.
+- Candidate Flow with numbered execution steps and task-aware purpose labels.
+- Actionable Missing Links with slot-specific search hints.
+- Runnable verification commands with separate evidence, reason, and confidence
+  metadata.
+- Structured-regex parser for 13 languages.
+- Optional MCP stdio setup for Cursor, Antigravity, Windsurf, Claude Desktop,
+  and VS Code/Copilot.
+- 9 smoke tests passing on clean compile.
+- Benchmark proof available under `.flowseeker/reports/`.
+
+## Honest Limitations
+
+- FlowSeeker does not guarantee sub-second cold scan.
+- FlowSeeker does not use AI/LLM-based ranking by default.
+- Semantic search is optional and disabled by default.
+- Tree-sitter parser support is available but disabled by default in public
+  benchmark claims.
+- Graph expansion is disabled in production.
+- Monorepo, git-history, and LSP integration are not public guarantees.
+
+## Reproducible Proof Commands
+
+```bash
+npm.cmd run compile --silent
+npm.cmd run test:manifest
+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
+```
+
+## Copy Notes By Surface
+
+### VS Code Marketplace
+
+Use the one-line description plus the marketplace summary. Mention Native VS
+Code Chat and the FlowSeeker sidebar only as user surfaces. Keep the blocked
+claims out of feature bullets.
+
+### OpenVSX
+
+Use the same copy as VS Code Marketplace. Add that the extension can be used by
+VS Code-compatible editors where the extension host supports the required APIs.
+
+### npm
+
+Lead with MCP:
+
+```text
+npx -p flowseeker flowseeker-mcp --workspace <path-to-repo>
+```
+
+Then link to `docs/mcp-onboarding.md` for client-specific JSON snippets.
+
+## Do Not Use
+
+- "AI-powered code search"
+- "Sub-second search"
+- "Production-ready tree-sitter accuracy"
+- "Semantic search by default"
+- "Understands your whole repo"
+- "Monorepo-ready"
+- "Uses git history"
+- "Uses LSP"

package/docs/mcp-onboarding.md

@@ -0,0 +1,191 @@
+# FlowSeeker MCP Onboarding
+
+FlowSeeker provides a standalone MCP (Model Context Protocol) server. Your IDE or AI client sends a task description; FlowSeeker scans your project, ranks relevant files, and returns a compact **Solve Packet** -- not the entire repository.
+
+## Prerequisites
+
+- Node.js 18 or later
+- FlowSeeker npm package (installed or via `npx`)
+- A workspace path (any directory with source files)
+
+## Quick Start
+
+```bash
+# Run without installing
+npx -p flowseeker flowseeker-mcp --workspace /path/to/your/repo
+
+# Or install globally
+npm i -g flowseeker
+flowseeker mcp --workspace /path/to/your/repo
+flowseeker-mcp --workspace /path/to/your/repo
+
+# Short aliases
+fs-mcp --workspace /path/to/your/repo
+flowseeker guide "Fix checkout webhook retry"
+flowseeker auto "Add CSV export with tests"
+fs-guide "Fix checkout webhook retry"
+fs-auto "Add CSV export with tests"
+fs-files "Find the auth middleware"
+```
+
+`flowseeker mcp`, `flowseeker-mcp`, and `fs-mcp` start the same MCP server. `flowseeker guide`, `flowseeker auto`, `fs-guide`, and `fs-auto` are direct CLI helpers for Claude Code/Codex style terminal workflows.
+
+### Claude Code
+
+From the repository you want Claude Code to work on:
+
+```bash
+npm i -g flowseeker
+claude mcp add flowseeker -- flowseeker mcp --workspace .
+```
+
+Direct prompt workflow without MCP:
+
+```bash
+flowseeker auto "Fix checkout webhook retry" --out .flowseeker/agent-prompt.md
+```
+
+### Optional Semantic Retrieval
+
+FlowSeeker works without embeddings by default. To enable hosted semantic retrieval:
+
+```bash
+# Jina quick preset (recommended)
+flowseeker semantic init --jina
+
+# Generic OpenAI-compatible path
+flowseeker semantic init --openai-compatible
+```
+
+For non-Jina providers, edit `.flowseeker/config.json` after init:
+- `semanticBaseUrl` -- your provider's endpoint
+- `semanticModel` -- the embedding model name (must match your provider)
+- `semanticApiKeyEnv` -- env var holding the key
+
+The API key still belongs in `.env`. Jina is a preset/recommendation, not a requirement.
+
+Verify setup:
+
+```bash
+flowseeker semantic check --test
+```
+
+If `flowseeker semantic check` says `incomplete_config`, configure `semanticModel` (and optionally `semanticBaseUrl`) in `.flowseeker/config.json` before testing.
+
+If `flowseeker semantic check` says `disabled`, MCP scans will not call the embedding provider.
+
+### Verify Installation
+
+```bash
+npx -p flowseeker flowseeker-mcp --help
+npx -p flowseeker flowseeker-mcp --version
+```
+
+### Local Development (after clone + compile)
+
+```bash
+npm.cmd run compile --silent
+node dist/cli/mcpServer.js --workspace /path/to/your/repo
+```
+
+## IDE Configuration
+
+Copy the JSON snippet for your IDE into its MCP configuration file.
+
+### Cursor
+
+Config path: `~/.cursor/mcp.json` (macOS/Linux) or `%USERPROFILE%\.cursor\mcp.json` (Windows). Project-local: `.cursor/mcp.json`.
+
+```json
+{
+  "mcpServers": {
+    "flowseeker": {
+      "command": "npx",
+      "args": ["-p", "flowseeker", "flowseeker-mcp", "--workspace", "<path-to-repo>"]
+    }
+  }
+}
+```
+
+### Antigravity
+
+Config path: `~/.gemini/antigravity/mcp_config.json` (macOS) or `%USERPROFILE%\.gemini\antigravity\mcp_config.json` (Windows).
+
+```json
+{
+  "mcpServers": {
+    "flowseeker": {
+      "command": "npx",
+      "args": ["-p", "flowseeker", "flowseeker-mcp", "--workspace", "<path-to-repo>"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Config path: `~/.codeium/windsurf/mcp_config.json` (macOS) or `%USERPROFILE%\.codeium\windsurf\mcp_config.json` (Windows).
+
+```json
+{
+  "mcpServers": {
+    "flowseeker": {
+      "command": "npx",
+      "args": ["-p", "flowseeker", "flowseeker-mcp", "--workspace", "<path-to-repo>"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Config path: `claude_desktop_config.json` (see Claude Desktop docs for OS-specific path).
+
+```json
+{
+  "mcpServers": {
+    "flowseeker": {
+      "command": "npx",
+      "args": ["-p", "flowseeker", "flowseeker-mcp", "--workspace", "<path-to-repo>"]
+    }
+  }
+}
+```
+
+### VS Code / GitHub Copilot
+
+Config path: `.vscode/mcp.json` in your project root. Uses root key `servers` (not `mcpServers`).
+
+```json
+{
+  "servers": {
+    "flowseeker": {
+      "command": "npx",
+      "args": ["-p", "flowseeker", "flowseeker-mcp", "--workspace", "<path-to-repo>"]
+    }
+  }
+}
+```
+
+## How It Works
+
+1. Your IDE sends `flowseeker_retrieve` with a task description.
+2. FlowSeeker scans the workspace, ranks evidence, and builds a Solve Packet.
+3. The Solve Packet returns to the client: edit candidates, read-only context, verification targets, noise risk, and missing links.
+4. The client model answers in your native chat with focused context instead of searching the whole repository.
+
+## Available Tools
+
+| Tool | Purpose |
+|------|---------|
+| `flowseeker_retrieve` | Full Solve Packet with ranked evidence and focused context |
+| `flowseeker_guide` | Agent guidance: relevant files, edit candidates, verification steps |
+| `flowseeker_auto` | Reviewable implementation-plan prompt |
+| `flowseeker_files` | Lightweight top-ranked file list |
+
+## Caveats
+
+- Config paths vary by OS and client version. Check your IDE's MCP documentation for the exact path.
+- The host client controls autocomplete behavior and tool UI. Some clients show tools/prompts after selecting the server; others insert a server mention like `@mcp:flowseeker:`.
+- FlowSeeker supplies context from your codebase. The client model performs reasoning over that context. FlowSeeker does not generate code, make edits, or run AI models.
+- The structured-regex parser supports 13 languages. Semantic search is optional and disabled by default. See the [README](../README.md) for evidence-backed capabilities and known limitations.