@thoughtflow/core 0.2.1 → 0.3.1

package/README.md

@@ -1,326 +1,386 @@
 # thoughtflow
 
-**TypeScript framework for building autonomous AI agents** — with full, inspectable control over every layer of the agent loop.
+**TypeScript framework for building autonomous AI agents** — streaming, tool-calling, plugins, skills, workspace automation, and advanced orchestration.
 
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![npm](https://img.shields.io/npm/v/@thoughtflow/core)](https://www.npmjs.com/package/@thoughtflow/core)
 
 ```ts
-import { Conversation, OpenAiAdapter } from "@thoughtflow/core";
+import { Conversation, OpenAiAdapter } from "thoughtflow";
 
 const agent = new Conversation({
   llmAdapter: new OpenAiAdapter({ apiKey: process.env.OPENAI_API_KEY }),
   model: "gpt-4o",
-  systemPrompt: "You are a helpful coding agent.",
+  systemPrompt: "You are a helpful agent with tools.",
 });
 
-const { output } = await agent.sendPrompt("List files in the project root");
+const { output } = await agent.sendPrompt("What files are in the project?");
 console.log(output);
 ```
 
 ---
 
-## Why thoughtflow?
+## Features
 
-LLM frameworks tend toward opacity — black-box agents, hidden prompts, implicit tool routing,
-and opaque orchestration. When something goes wrong, you don't know why.
+- **Conversation loop** — multi-turn agent with streaming, tool-calling, and interrupt support
+- **Adapter system** — OpenAI, Anthropic, Ollama, vLLM, and mock adapters via `AdapterFactory`
+- **120+ built-in tools** — file read/write, search, git, browser, docker, code analysis, refactoring, testing, planning, memory, and more
+- **Context window management** — sliding-window and truncation strategies to stay within model limits
+- **Subagent orchestration** — spawn child agents with isolated context, tools, and state
+- **Plugins** — workspace, docker, browser, codebase intelligence
+- **Skills** — loadable `.md` instructions that inject context and constraints
+- **Storage abstraction** — in-memory, JSON file, LanceDB vector store, Ollama/Transformers embeddings
+- **Event bus** — RxJS-based streaming events for real-time UI or logging
+- **Task flow engine** — multi-stage pipelines with git commit/push, docker, and phase gates
+- **MCP support** — Model Context Protocol server with smart compressed tool list, `tool_search` for on-demand schema discovery, multi-provider routing, and vision browser
 
-**thoughtflow exists to give you back control.**
+## Quickstart
 
-Every component is explicit, inspectable, and independently testable:
-
-- **Observability over opacity.** Tool calls are events you subscribe to. Iteration counts,
-  token usage, stall detection — all exposed. Nothing is hidden behind a magic decorator.
-- **Verification over trust.** The framework doesn't assume an LLM's output is correct.
-  Subagents report what they *did*, not what they *said*. You decide when to trust.
-- **Explicit composition.** Agents are assembled from visible parts: adapter, model, tool list,
-  system prompt, skills, temperature, iteration limits, callbacks. Every knob is on the surface.
-- **Autonomy with bounds.** Agents can be autonomous — but bounded by explicit tool sets,
-  skill definitions, iteration caps, stall detection, and human-in-the-loop interrupts.
-
-> thoughtflow emerged from building production agent systems where "it mostly works"
-> wasn't enough. When an agent misbehaves in production, you need to know *why* —
-> not dig through three layers of abstraction to find the actual prompt that was sent.
-
----
-
-## Installation
+### Installation
 
 ```bash
-npm install @thoughtflow/core
+npm install thoughtflow
 # or
-bun add @thoughtflow/core
+bun add thoughtflow
 ```
 
-Requires **Node.js ≥ 18** or **Bun ≥ 1.2**.
-
-> Designed for self-hosted LLMs — tested with **Qwen 3.6** and **Ornith 1.0-35B** inference on vLLM, Ollama, and OpenAI-compatible endpoints. The adapter pattern makes it trivial to point at any local or cloud provider.
-
-### Sub-packages
-
-Additional functionality is available in separate packages for specific use cases:
-
-| Package | What it adds | Dependencies |
-|---------|-------------|--------------|
-| `@thoughtflow/codebase` | Code analysis, quality metrics, neural tools, contexts | ast-grep, better-sqlite3 |
-| `@thoughtflow/browser` | Playwright-based browser automation | playwright |
-| `@thoughtflow/vector` | Vector stores (LanceDB) + local embeddings (Hugging Face) | lancedb, transformers |
-| `@thoughtflow/decoder` | TypeScript structural decoder (ts-morph) | ts-morph |
-
-```bash
-npm install @thoughtflow/codebase   # code analysis tools
-npm install @thoughtflow/browser    # browser automation
-npm install @thoughtflow/vector     # vector search & embeddings
-npm install @thoughtflow/decoder    # TypeScript AST decoder
-```
-
-Each sub-package imports the core types from `@thoughtflow/core` and adds its own tools, libs, and adapters.
-
----
-
-## Core concepts
-
-### Orchestration patterns
-
-Thoughtflow provides six distinct patterns for composing LLM agents:
-
-| Pattern | Description | When to use |
-|---------|-------------|-------------|
-| **Single loop** | One `Conversation` with tools, stall detection, streaming | Simple Q&A, code generation, single tasks |
-| **Pipeline** | Sequential agents that pass artifacts between them | Code review, document processing, staged workflows |
-| **Subagent fan-out** | Parent delegates sub-tasks to child agents, collects verified results | Parallel research, multi-file analysis, independent tasks |
-| **Saga** | Pipeline with compensating rollbacks on failure | Automated refactoring, deployments, irreversible operations |
-| **Role orchestrator** | Role-based pipeline with journal tracking and artifact passing | Code review with analyst → planner → implementer → reviewer roles |
-| **Dynamic decomposition** | Agent breaks a task into sub-problems with dependency tracking | Complex multi-step problems, cross-cutting changes |
-
-### Verification principle
-
-The most important design rule: **don't trust the LLM's self-reported output.**
+### Basic usage
 
 ```ts
-// Subagent reports what it DID, not what it SAID
-const result = await subagent.runTask("count files in src/");
-// Return actual (verified) data to parent — not the LLM's self-reported version
-return { fileCount: result.toolOutputs.fileCount };
-```
-
-Every demo in this repo verifies subagent outputs against ground truth —
-tool execution results, not LLM summaries.
+import { Conversation, OpenAiAdapter, AdapterFactory } from "thoughtflow";
 
----
+// Option A: direct adapter
+const agent = new Conversation({
+  llmAdapter: new OpenAiAdapter({ apiKey: "sk-..." }),
+  model: "gpt-4o",
+});
 
-## Quick Reference
+// Option B: factory with provider
+const adapter = AdapterFactory.create({
+  provider: "openai",
+  baseUrl: "https://api.openai.com/v1",
+  apiKey: "sk-...",
+});
 
-### 1. Basic agent with tools
+// Multi-turn conversation
+await agent.sendPrompt("List the files in src/");
+const history = agent.getHistory(); // full message history
 
-```ts
-import { Conversation, OpenAiAdapter, ReadFileTool, GrepTool } from "@thoughtflow/core";
+// With tools
+import { ReadFileTool, GrepTool } from "thoughtflow";
 
 const agent = new Conversation({
-  llmAdapter: new OpenAiAdapter({ apiKey: process.env.OPENAI_API_KEY }),
+  llmAdapter: adapter,
   model: "gpt-4o",
-  systemPrompt: "You are a coding assistant. Use tools to explore and modify code.",
   tools: [
     new ReadFileTool("/path/to/project"),
     new GrepTool("/path/to/project"),
   ],
 });
-
-const { output } = await agent.sendPrompt("Find all TODO comments in src/");
 ```
 
-### 2. Multi-turn conversation
+### Streaming events
 
 ```ts
-await agent.sendPrompt("What files are in src/tools/?");
-await agent.sendPrompt("How is the ReadFileTool implemented?");
-const history = agent.getHistory(); // full message history
-```
+import { filter } from "rxjs";
 
-### 3. Streaming events
-
-Thoughtflow emits RxJS events for real-time UI and logging:
-
-```ts
 agent.events.pipe(
-  filter((e) => e.type === "stream_chunk"),
+  filter((e) => e.type === "stream:chunk"),
 ).subscribe((chunk) => {
-  process.stdout.write(chunk.contentDelta ?? "");
+  process.stdout.write(chunk.delta.content ?? "");
 });
 ```
 
-Available event types: `stream_chunk`, `status_changed`, `message_pushed`, `tool_event`, `interrupt`, `interrupt_resolved`, `error`.
-
-### 4. Using different providers
+### Subagent delegation
 
 ```ts
-import { LlmAdapterFactory } from "@thoughtflow/core";
+import { SubagentConversationTool } from "thoughtflow";
 
-// Ollama (local)
-const ollama = LlmAdapterFactory.create({
-  provider: "ollama",
-  baseUrl: "http://localhost:11434",
+const agent = new Conversation({
+  llmAdapter: adapter,
+  model: "gpt-4o",
+  tools: [new SubagentConversationTool()],
 });
 
-// Anthropic
-const anthropic = LlmAdapterFactory.create({
-  provider: "anthropic",
-  apiKey: process.env.ANTHROPIC_API_KEY,
-});
+await agent.sendPrompt(
+  "Research the best Node.js testing frameworks, then summarize."
+);
+```
 
-// OpenAI-compatible (vLLM, OpenRouter, etc.)
-const vllm = LlmAdapterFactory.create({
-  provider: "openai",
-  baseUrl: "https://api.openai.com/v1",
-  apiKey: process.env.OPENAI_API_KEY,
-});
+## Architecture
+
+```
+thoughtflow/
+├── packages/mcp-server/  # @thoughtflow/mcp-server — thin npm wrapper
+├── src/
+│   ├── adapters/llm/     # LLM provider adapters (OpenAI, Anthropic, Ollama, mock)
+│   ├── bin/              # CLI entry point (mcp-server)
+│   ├── contracts/        # TypeScript interfaces and types
+│   ├── contexts/         # Context document management & routing
+│   ├── libs/
+│   │   ├── mcp/          # MCP protocol: JSON-RPC, server, tool registry
+│   │   └── ...           # Core libraries (runner, history, subagents, task flow)
+│   ├── plugins/          # Workspace, Docker, Browser, Codebase Intelligence
+│   ├── skills/           # Skill loader + built-in .md skill definitions
+│   ├── storage/          # Persistence adapters (memory, JSON, vector stores)
+│   ├── tools/
+│   │   ├── mcp/          #   tool_search — on-demand tool discovery
+│   │   ├── workspace/    #   file, git, browser, docker, terminal, vision browser
+│   │   ├── codebase/     #   search, graph, impact, knowledge, crossref
+│   │   ├── planning/     #   breakdown, deps, estimate, risks, progress
+│   │   ├── quality/      #   complexity, coupling, coverage, duplication
+│   │   ├── refactor/     #   rename, extract, split, move, imports
+│   │   ├── testing/      #   gen-unit, gen-integration, fuzz, snapshot, fix
+│   │   ├── docs/         #   gen-readme, gen-api, gen-adr, check-links
+│   │   ├── neural/       #   review, debug, explain, optimize, security
+│   │   ├── memory/       #   save, recall, context, patterns, lessons
+│   │   ├── database/     #   migration, diagram, index-suggest
+│   │   └── devops/       #   ci-diagnose, deploy-check, docker-optimize
+│   └── quick/            # Preset configs for common setups
+└── tests/                # 56 unit tests (MCP protocol, JSON-RPC, tool registry)
 ```
 
-| Provider | Adapter | Default baseUrl |
+## LLM Providers
+
+| Provider | Adapter | baseUrl example |
 |----------|---------|-----------------|
 | OpenAI-compatible | `OpenAiAdapter` | `https://api.openai.com/v1` |
 | Anthropic | `AnthropicAdapter` | — |
 | Ollama | `OllamaAdapter` | `http://localhost:11434` |
 | Mock | `MockAdapter` | — (testing) |
 
-### 5. Subagent delegation
+```ts
+const adapter = AdapterFactory.create({
+  provider: "ollama",
+  baseUrl: "http://localhost:11434",
+});
+// Adapter appends /v1/chat internally
+```
 
-Spawn child agents with isolated context, tools, and state:
+## MCP Server — Autonomous Agent via Model Context Protocol
 
-```ts
-import { SubagentConversationTool } from "@thoughtflow/core";
+**Run thoughtflow as an MCP server that any MCP-compatible client can drive.** Claude Desktop, Cursor, OpenCode, Continue, Zed — any client that speaks JSON-RPC over stdio becomes a fully autonomous coding agent with 100+ battle-tested tools.
 
-const agent = new Conversation({
-  llmAdapter: adapter,
-  model: "gpt-4o",
-  tools: [new SubagentConversationTool()],
-});
+### Why thoughtflow MCP?
 
-await agent.sendPrompt(
-  "Research best testing frameworks, then summarize."
-);
+| Problem | thoughtflow solution |
+|---|---|
+| **Context window pollution** — 100+ tools with full JSON schemas consume 50K+ tokens upfront | **Smart compressed mode** — tools list shows names + one-liners only. LLM calls `tool_search("analyze codebase")` to pull full schemas on demand. Default: saves ~80% tokens. |
+| **Static tool list** — LLM can't discover the right tool among dozens of similar names | **tool_search** — describe what you want to do in natural language. Returns matching tools with full parameter schemas. Domain-aware: `"testing tools"`, `"workspace tools"`. |
+| **One model for everything** — vision doesn't work on your text model | **Per-provider routing** — route `visionBrowser` to GPT-4V, planning tools to Claude, code tools to your local Qwen. Mix and match. |
+| **Setup complexity** — config files, env vars, provider wiring | **Single config file** — `thoughtflow.config.json`. Providers, tool filtering, model routing, workspace paths — all in one place. |
+
+### Quickstart — one command
+
+```bash
+npx @thoughtflow/mcp-server
 ```
 
-### 6. Skills — reusable instructions
+That's it. The server auto-detects `thoughtflow.config.json` in the current directory. No config file? Starts with sensible defaults (Ollama on localhost).
+
+**Custom config:**
+```bash
+npx @thoughtflow/mcp-server --config ./my-config.json
+# or
+THOUGHTFLOW_CONFIG=/path/to/config.json npx @thoughtflow/mcp-server
+```
 
-Skills are `.md` files that inject context and constraints into the agent:
+**Minimal `thoughtflow.config.json`:**
+```json
+{
+  "workspace": { "allowedPaths": ["."] },
+  "providers": {
+    "default": {
+      "type": "ollama",
+      "baseUrl": "http://localhost:11434",
+      "model": "qwen3"
+    }
+  }
+}
+```
 
-```ts
-import { SkillLoader } from "@thoughtflow/core";
+Wire into your MCP client:
+
+**Claude Desktop** (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "thoughtflow": {
+      "command": "npx",
+      "args": ["-y", "@thoughtflow/mcp-server", "--config", "/Users/you/project/thoughtflow.config.json"]
+    }
+  }
+}
+```
 
-const loader = new SkillLoader();
-await loader.load("path/to/my-skill.md");
-agent.skills = loader.skills;
+**Cursor** (`.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "thoughtflow": {
+      "command": "npx",
+      "args": ["-y", "@thoughtflow/mcp-server", "--config", "/absolute/path/to/thoughtflow.config.json"]
+    }
+  }
+}
 ```
 
-Skills can define behavior, coding conventions, security rules, or domain knowledge.
+**Zed** (`settings.json`):
+```json
+{
+  "context_servers": {
+    "thoughtflow": {
+      "command": {
+        "path": "npx",
+        "args": ["-y", "@thoughtflow/mcp-server", "--config", "/absolute/path/to/thoughtflow.config.json"]
+      }
+    }
+  }
+}
+```
 
-### 7. Context window management
+Your LLM now has filesystem access, git, search, code analysis, refactoring, testing — 100+ tools, zero setup beyond the config file. No API keys, no path wrangling, no dependency hell.
+
+### The tool_search advantage
+
+In compressed mode (default), the LLM receives this instead of 50K tokens of JSON schemas:
 
-```ts
-const agent = new Conversation({
-  llmAdapter: adapter,
-  model: "gpt-4o",
-  contextWindow: {
-    maxTokens: 8000,
-    strategy: "sliding-window", // or "truncation"
-  },
-});
 ```
+## Tool Discovery — USE THIS FIRST
 
-### 8. Storage / Persistence
+The tool list is COMPRESSED. Use `tool_search` before calling unfamiliar tools.
 
-Plug in different storage backends for memory, vector search, and embeddings:
+Available domains:
+- workspace: File I/O, terminal, git, search, browser, HTTP
+- codebase: Repository intelligence — index, search, graphs, impact
+- neural: LLM-powered analysis — review, explain, debug, security
+- planning: Problem decomposition, project management, estimation
+...
+```
 
-```ts
-import { InMemoryAdapter, JsonFileAdapter } from "@thoughtflow/core";
-import { LanceDbVectorStore } from "@thoughtflow/core";
+When the LLM needs to read a file:
+```
+LLM: tool_search("read a text file")
+     → readFile: path (string, required), offset (number, optional)...
+LLM: readFile({ path: "src/app.ts" })
+```
 
-const store = new JsonFileAdapter("./data/sessions.json");
+Every interaction costs fewer tokens. The LLM discovers tools exactly when needed — like lazy-loading for function schemas.
+
+### Vision browser — visual page analysis
+
+```json
+{
+  "tools": {
+    "visionBrowser": {
+      "enabled": true,
+      "provider": "custom",
+      "baseUrl": "https://integrate.api.nvidia.com/v1",
+      "apiKey": "***",
+      "model": "nemotron-mini-3-omni"
+    }
+  }
+}
+```
 
-// Recalling past context
-const entries = await store.query({ limit: 5 });
+Now the LLM can visually inspect rendered web pages:
+```
+LLM: visionBrowser({ url: "https://example.com", prompt: "Is the login form centered? What color is the submit button?" })
 ```
 
-### 9. Interrupts / Human-in-the-Loop
+Works with any OpenAI-compatible vision endpoint — GPT-4V, Claude 3, Gemini, Nemotron, local Ollama with vision models.
 
-```ts
-const result = await agent.sendPrompt("Deploy to production", {
-  interruptConfig: {
-    riskLevel: "high",     // auto-interrupt on risky actions
-    keywords: ["deploy", "delete", "rm -rf"],
-  },
-});
+### Advanced configuration
 
-if (result.interrupted) {
-  const decision = await agent.resolveInterrupt(result.interruptId, "approved");
-  const resumed = await agent.resume(decision);
+```json
+{
+  "agent": {
+    "toolListMode": "compressed",
+    "maxIterations": 50
+  },
+  "categories": {
+    "workspace": { "enabled": true },
+    "database": { "enabled": false }
+  },
+  "tools": {
+    "visionBrowser": { "enabled": true, "provider": "custom", "model": "gpt-4o" },
+    "browser": { "enabled": false }
+  },
+  "modelRouting": {
+    "vision": { "provider": "openai", "model": "gpt-4o" },
+    "planning": { "provider": "claude", "model": "claude-sonnet-4" },
+    "default": { "provider": "ollama", "model": "qwen3" }
+  },
+  "providers": {
+    "ollama": { "type": "ollama", "baseUrl": "http://localhost:11434", "model": "qwen3" },
+    "openai": { "type": "openai", "baseUrl": "https://api.openai.com/v1", "apiKey": "***" },
+    "claude": { "type": "anthropic", "baseUrl": "https://api.anthropic.com", "apiKey": "***" }
+  }
 }
 ```
 
----
+| Config key | What it does |
+|---|---|
+| `agent.toolListMode` | `"compressed"` (default, saves tokens) or `"full"` (all schemas upfront) |
+| `categories.*.enabled` | Toggle entire tool categories on/off |
+| `tools.*.enabled` | Toggle individual tools |
+| `modelRouting` | Route specific tools/categories to different LLM providers |
+| `tools.visionBrowser` | Enable visual page analysis with any vision-capable model |
+| `workspace.allowedPaths` | Filesystem sandbox — which directories the LLM can touch |
 
-## Examples
-
-Full working examples in [`demos/`](./demos/):
-
-| Example | Pattern | What it demonstrates |
-|---------|---------|---------------------|
-| `agent-live-demo.ts` | Single loop + pipeline | Basic agent, multi-agent pipeline (architect → coder → reviewer) |
-| `subagent-demo.ts` | Fan-out | Parent delegates verification tasks, re-verifies output |
-| `code-review-saga-demo.ts` | Saga | 4-step analyze → fix → test → commit with compensating rollback |
-| `code-review-role-orchestrator-demo.ts` | Role orchestrator | 6-role pipeline with journal and artifact passing |
-| `solve-complex-demo.ts` | Dynamic decomposition | Task → 12+ subproblems with dependency tree |
-| `autonomous-dev-demo.ts` | Auto loop | End-to-end: plan → code → build → test → fix in a loop |
-| `autonomous-corporation-demo.ts` | Multi-agent swarm | Multiple agents with different roles collaborating |
-| `multi-server-demo.ts` | Distributed | Pooled inference across multiple LLM servers |
-| `thinking-leak-detection.ts` | Quality gate | Detects reasoning content leaking into agent output |
-| `code-review-autonomous-demo.ts` | Auto review | Automated PR review with skill injection |
-| `tool-calling-test.ts` | Tool loop | Walkthrough of the tool-calling loop mechanics |
-| `workspace-demo.ts` | Workspace | File, git, terminal automation |
-| `nestjs-hello-world-demo.ts` | Skills | Skill-based NestJS code generation |
-| `nestjs-todo-demo.ts` | Skills | Skill-based NestJS TODO app generation |
+### Protocol
 
----
+Standard MCP over stdio — JSON-RPC 2.0, newline-delimited:
 
-## Design approach
+```
+→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}
+← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},...}}
 
-- **One package, everything included.** Install thoughtflow, get all adapters, tools, storage, skills, and orchestrators in one go. No hunting for plugin packages.
-- **TypeScript-native.** The API, types, and tool system are designed for the TS ecosystem from the ground up — not ported from another language.
-- **Composable.** Conversation, adapters, tools, skills — each piece works independently or together. Use just the event bus, or the full agent stack.
-- **LLM-agnostic.** Switch between OpenAI, Anthropic, Ollama, or vLLM by changing one line.
-- **Pragmatic tooling.** 120+ built-in tools for real workflows — code analysis, refactoring, planning, testing, devops.
-- **Determinism where possible.** Temperature 0, stall detection, max iterations — the framework helps you keep agents predictable.
+→ {"jsonrpc":"2.0","id":2,"method":"tools/list"}
+← {"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"tool_search",...},{"name":"readFile",...},...]}}
 
----
+→ {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"readFile","arguments":{"path":"src/app.ts"}}}
+← {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"..."}]}}
+```
 
-## Architecture
+### Testing
+
+thoughtflow includes a `MockAdapter` — zero network calls, deterministic responses:
+
+```ts
+import { McpServer, MockAdapter } from "thoughtflow";
+
+const server = new McpServer({
+  thoughtflowConfig: { workspace: { allowedPaths: ["."] } },
+  adapters: new Map([["mock", { adapter: new MockAdapter(), model: "mock", baseUrl: "" }]]),
+  defaultProvider: "mock",
+});
+await server.initialize();
+
+const response = await server.handleRequest({
+  jsonrpc: "2.0", id: 1, method: "tools/list",
+});
+```
+
+### Hermes Agent skill
 
+Install the thoughtflow skill for Hermes — one command:
+
+```bash
+npx @thoughtflow/mcp-server install-skill
 ```
-src/
-├── adapters/llm/         # LLM provider adapters (OpenAI, Anthropic, Ollama, mock)
-├── contracts/            # TypeScript interfaces and types
-├── contexts/             # Context document management & routing
-├── libs/                 # Core libraries (runner, history, subagents, task flow, ...)
-├── plugins/              # Workspace, Docker, Browser, Codebase Intelligence
-├── skills/               # Skill loader + built-in .md skill definitions
-├── storage/              # Persistence adapters (memory, JSON, vector stores)
-├── tools/                # 120+ tools across 12 categories
-│   ├── workspace/        #   file, git, browser, docker, terminal, ...
-│   ├── codebase/         #   search, graph, impact, knowledge, ...
-│   ├── planning/         #   breakdown, deps, estimate, risks, ...
-│   ├── quality/          #   complexity, coupling, coverage, duplication, ...
-│   ├── refactor/         #   rename, extract, split, move, eslint-fix
-│   ├── testing/          #   gen-unit, gen-integration, fuzz, snapshot, fix
-│   ├── docs/             #   gen-readme, gen-api, gen-adr, check-links
-│   ├── neural/           #   review, debug, explain, optimize, security, ...
-│   ├── memory/           #   save, recall, context, patterns, lessons
-│   ├── database/         #   migration, diagram, index-suggest
-│   └── devops/           #   ci-diagnose, deploy-check, docker-optimize, ...
-└── quick/                # Preset configs for common setups
+
+This copies the skill to `~/.hermes/skills/thoughtflow-mcp/`. Custom target:
+
+```bash
+npx @thoughtflow/mcp-server install-skill --target ~/.agents/skills/
 ```
 
----
+The skill auto-activates when `mcp__thoughtflow__*` tools are detected and teaches the LLM:
+- Task-based tool selection ("find X" → grep, "review" → neuralReview, etc.)
+- Mandatory workflows (pre-change impact check, pre-commit quality gate, visual testing flow)
+- Safety rules (no destructive ops without backup + user approval)
+- Planning pattern (solveComplex → TODO list)
 
 ## License
 
@@ -328,5 +388,4 @@ MIT — see [LICENSE](LICENSE).
 
 ---
 
-*Built with TypeScript. Requires Node.js ≥18.*  
-*My first published library — crafted with AI assistance.*
+*Built with TypeScript. Requires Node.js ≥18 or Bun ≥1.2.*

package/dist/adapters/llm/openai.adapter.js

@@ -79,10 +79,10 @@ class OpenAiAdapter {
         this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
         // Prevent /v1/v1 double prefix when config already includes /v1
         this.apiUrl = this.baseUrl.endsWith("/v1") ? this.baseUrl : `${this.baseUrl}/v1`;
-        this.headers = {
-            "Content-Type": "application/json",
-            Authorization: `Bearer ${config.apiKey}`,
-        };
+        this.headers = { "Content-Type": "application/json" };
+        if (config.apiKey) {
+            this.headers["Authorization"] = `Bearer ${config.apiKey}`;
+        }
         if (config.organization) {
             this.headers["OpenAI-Organization"] = config.organization;
         }