test: add 29 unit tests for estimate_cost helpers

README.md

@@ -10,7 +10,7 @@ A 24-tool MCP server for Claude Code that catches ambiguous instructions before
 [![MCP](https://img.shields.io/badge/MCP-Compatible-blueviolet)](https://modelcontextprotocol.io/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![npm](https://img.shields.io/npm/v/preflight-dev)](https://www.npmjs.com/package/preflight-dev)
-[![Node 18+](https://img.shields.io/badge/node-18%2B-brightgreen?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Node 20+](https://img.shields.io/badge/node-20%2B-brightgreen?logo=node.js&logoColor=white)](https://nodejs.org/)
 
 [Quick Start](#quick-start) · [How It Works](#how-it-works) · [Tool Reference](#tool-reference) · [Configuration](#configuration) · [Scoring](#the-12-category-scorecard)
 
@@ -124,6 +124,47 @@ claude mcp add preflight -- preflight-dev-serve
 
 > **Note:** `preflight-dev` runs the interactive setup wizard. `preflight-dev-serve` starts the MCP server — that's what you want in your Claude Code config.
 
+### Make Claude use preflight automatically
+
+Add preflight rules to your project's `CLAUDE.md` so Claude runs `preflight_check` on every prompt without you asking:
+
+```bash
+cp /path/to/preflight/examples/CLAUDE.md your-project/CLAUDE.md
+```
+
+See [`examples/CLAUDE.md`](examples/CLAUDE.md) for a ready-to-use template with recommended rules for when to preflight, session hygiene, and skip-lists.
+
+### Verify it's working
+
+After setup, open Claude Code in your project and try:
+
+```
+> fix the tests
+```
+
+If preflight is connected, you'll see a `preflight_check` tool call fire automatically (or when configured via CLAUDE.md). It should respond with something like:
+
+```
+🛫 Preflight Check
+Triage: ambiguous (confidence: 0.70)
+Reasons: short prompt without file references; contains vague verbs without specific targets
+
+⚠️ Clarification Needed
+- Vague verb without specific file targets
+- Very short prompt — likely missing context
+
+Git State
+Branch: main | Dirty files: 3
+```
+
+If you see this, you're good. If nothing happens:
+
+1. **Check tools are loaded:** Type `/mcp` in Claude Code — you should see `preflight` listed with its tools
+2. **Check the server starts:** Run `npx preflight-dev-serve` in your terminal — it should output JSON (MCP protocol), not errors
+3. **Restart Claude Code:** Tools are loaded at startup, so you need a full restart after adding the MCP server
+
+> **Tip:** Try `prompt_score "update the thing"` to test a specific tool directly. You should get a grade and suggestions.
+
 ---
 
 ## How It Works
@@ -734,6 +775,16 @@ curl http://localhost:11434/api/embed -d '{"model":"all-minilm","input":"test"}'
 
 ---
 
+## Troubleshooting
+
+Having issues? Check **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** for solutions to common problems including:
+- LanceDB setup and platform issues
+- Embedding provider configuration
+- `.preflight/` config parsing errors
+- Profile selection guide
+
+---
+
 ## Contributing
 
 This project is young and there's plenty to do. Check the [issues](https://github.com/TerminalGravity/preflight/issues) — several are tagged `good first issue`.

TROUBLESHOOTING.md

@@ -0,0 +1,165 @@
+# Troubleshooting
+
+Common issues and fixes for preflight.
+
+---
+
+## Installation & Setup
+
+### `npx preflight-dev-serve` fails with module errors
+
+**Symptoms:** `ERR_MODULE_NOT_FOUND` or `Cannot find module` when running via npx.
+
+**Fix:** Preflight requires **Node 20+**. Check your version:
+```bash
+node --version
+```
+If you're on Node 18 or below, upgrade via [nvm](https://github.com/nvm-sh/nvm):
+```bash
+nvm install 20
+nvm use 20
+```
+
+### Tools don't appear in Claude Code after `claude mcp add`
+
+**Fix:** Restart Claude Code completely after adding the MCP server. The tool list is loaded at startup.
+
+If tools still don't appear, verify the server starts without errors:
+```bash
+npx preflight-dev-serve
+```
+You should see MCP protocol output (JSON on stdout). If you see errors, check the sections below.
+
+---
+
+## LanceDB & Timeline Search
+
+### `Error: Failed to open LanceDB` or LanceDB crashes on startup
+
+**Symptoms:** Timeline tools (`search_timeline`, `index_sessions`, etc.) fail. Other tools work fine.
+
+**Cause:** LanceDB uses native binaries that may not be available for your platform, or the database directory has permission issues.
+
+**Fixes:**
+1. Make sure `~/.preflight/projects/` is writable:
+   ```bash
+   mkdir -p ~/.preflight/projects
+   ls -la ~/.preflight/
+   ```
+2. If on an unsupported platform, use the **minimal** or **standard** profile (no LanceDB required):
+   ```bash
+   npx preflight-dev
+   # Choose "minimal" or "standard" when prompted
+   ```
+3. Clear corrupted LanceDB data:
+   ```bash
+   rm -rf ~/.preflight/projects/*/timeline.lance
+   ```
+   Then re-index with `index_sessions`.
+
+### Timeline search returns no results
+
+**Cause:** Sessions haven't been indexed yet. Preflight doesn't auto-index — you need to run `index_sessions` first.
+
+**Fix:** In Claude Code, run:
+```
+index my sessions
+```
+Or use the `index_sessions` tool directly. Indexing reads your `~/.claude/projects/` session files.
+
+---
+
+## Embeddings
+
+### `OpenAI API key required for openai embedding provider`
+
+**Cause:** You selected OpenAI embeddings but didn't set the API key.
+
+**Fixes:**
+
+Option A — Set the environment variable when adding the MCP server:
+```bash
+claude mcp add preflight \
+  -e OPENAI_API_KEY=sk-... \
+  -- npx -y preflight-dev-serve
+```
+
+Option B — Switch to local embeddings (no API key needed). Create or edit `~/.preflight/config.json`:
+```json
+{
+  "embedding_provider": "local",
+  "embedding_model": "Xenova/all-MiniLM-L6-v2"
+}
+```
+
+### Local embeddings are slow on first run
+
+**Expected.** The model (~80MB) downloads on first use and is cached afterward. Subsequent runs are fast.
+
+---
+
+## `.preflight/` Config
+
+### `warning - failed to parse .preflight/config.yml`
+
+**Cause:** YAML syntax error in your project's `.preflight/config.yml`.
+
+**Fix:** Validate your YAML:
+```bash
+npx yaml-lint .preflight/config.yml
+```
+Or check for common issues: wrong indentation, tabs instead of spaces, missing colons.
+
+### Config changes not taking effect
+
+**Cause:** Preflight reads config at MCP server startup, not on every tool call.
+
+**Fix:** Restart Claude Code after editing `.preflight/config.yml` or `.preflight/triage.yml`.
+
+---
+
+## Profiles
+
+### Which profile should I use?
+
+| Profile | Tools | Best for |
+|---------|-------|----------|
+| **minimal** | 4 | Try it out, low overhead |
+| **standard** | 16 | Daily use, no vector search needed |
+| **full** | 20 | Power users who want timeline search |
+
+You can change profiles by re-running the setup wizard:
+```bash
+npx preflight-dev
+```
+
+---
+
+## Platform-Specific
+
+### Apple Silicon (M1/M2/M3/M4): LanceDB build fails
+
+LanceDB ships prebuilt binaries for Apple Silicon. If `npm install` fails on the native module:
+```bash
+# Ensure you're using the ARM64 version of Node
+node -p process.arch   # should print "arm64"
+
+# If it prints "x64", reinstall Node natively (not via Rosetta)
+```
+
+### Linux: Permission denied on `~/.preflight/`
+
+```bash
+chmod -R u+rwX ~/.preflight/
+```
+
+---
+
+## Still stuck?
+
+1. Check [open issues](https://github.com/TerminalGravity/preflight/issues) — someone may have hit the same problem
+2. [Open a new issue](https://github.com/TerminalGravity/preflight/issues/new) with:
+   - Your Node version (`node --version`)
+   - Your OS and architecture (`uname -a`)
+   - The full error message
+   - Which profile you selected

examples/.preflight/config.yml

@@ -1,35 +1,35 @@
-# .preflight/config.yml — Drop this in your project root
-#
-# This is an example config for a typical Next.js + microservices setup.
-# Every field is optional — preflight works with sensible defaults out of the box.
-# Commit this to your repo so the whole team gets the same preflight behavior.
+# .preflight/config.yml
+# Drop this directory in your project root to configure preflight per-project.
+# All fields are optional — defaults are used for anything you omit.
 
-# Profile controls how much detail preflight returns.
-#   "minimal"  — only flags ambiguous+ prompts, skips clarification detail
-#   "standard" — balanced (default)
-#   "full"     — maximum detail on every non-trivial prompt
+# Tool profile: how many tools to expose
+#   minimal  — 4 tools (preflight_check, prompt_score, clarify_intent, scope_work)
+#   standard — 16 tools (adds scorecards, cost estimation, corrections, contracts)
+#   full     — 20 tools (adds LanceDB timeline search — requires Node 20+)
 profile: standard
 
-# Related projects for cross-service awareness.
-# Preflight will search these for shared types, routes, and contracts
-# so it can warn you when a change might break a consumer.
+# Related projects for cross-service contract search.
+# Preflight scans these for shared types, API routes, and schemas.
 related_projects:
-  - path: /Users/you/code/auth-service
-    alias: auth
-  - path: /Users/you/code/billing-api
-    alias: billing
-  - path: /Users/you/code/shared-types
+  - path: ../api-service
+    alias: api
+  - path: ../shared-types
     alias: types
 
-# Behavioral thresholds — tune these to your workflow
+# Tuning knobs
 thresholds:
-  session_stale_minutes: 30                # Warn if no activity for this long
-  max_tool_calls_before_checkpoint: 100    # Suggest a checkpoint after N tool calls
-  correction_pattern_threshold: 3          # Min corrections before flagging a pattern
+  # Minutes before a session is considered "stale" (triggers session_health warnings)
+  session_stale_minutes: 30
 
-# Embedding provider for semantic search over session history.
-# "local" uses Xenova transformers (no API key needed, runs on CPU).
-# "openai" uses text-embedding-3-small (faster, needs OPENAI_API_KEY).
+  # Tool calls before preflight nudges you to checkpoint progress
+  max_tool_calls_before_checkpoint: 100
+
+  # How many times a correction pattern repeats before it becomes a warning
+  correction_pattern_threshold: 3
+
+# Embedding config (only matters for "full" profile with timeline search)
 embeddings:
+  # "local" — runs Xenova/all-MiniLM-L6-v2 in-process, no API key needed
+  # "openai" — uses text-embedding-3-small, requires openai_api_key or OPENAI_API_KEY env var
   provider: local
-  # openai_api_key: sk-...               # Uncomment if using openai provider
+  # openai_api_key: sk-...  # or set OPENAI_API_KEY env var instead

examples/.preflight/triage.yml

@@ -1,45 +1,37 @@
-# .preflight/triage.yml — Controls how preflight classifies your prompts
-#
-# The triage engine routes prompts into categories:
-#   TRIVIAL       → pass through (commit, format, lint)
-#   CLEAR         → well-specified, no intervention needed
-#   AMBIGUOUS     → needs clarification before proceeding
-#   MULTI-STEP    → complex task, preflight suggests a plan
-#   CROSS-SERVICE → touches multiple projects, pulls in contracts
-#
-# Customize the keywords below to match your domain.
+# .preflight/triage.yml
+# Controls how preflight_check triages your prompts.
+# Separate from config.yml so you can tune triage rules independently.
+
+# Strictness level:
+#   relaxed  — only flags clearly ambiguous prompts
+#   standard — balanced (default)
+#   strict   — flags anything that could be more specific
+strictness: standard
 
 rules:
-  # Prompts containing these words are always flagged as AMBIGUOUS.
-  # Add domain-specific terms that tend to produce vague prompts.
+  # Keywords that ALWAYS trigger a full preflight check, even for short prompts.
+  # Use this for high-risk areas of your codebase.
   always_check:
     - rewards
     - permissions
     - migration
     - schema
-    - pricing          # example: your billing domain
-    - onboarding       # example: multi-step user flows
+    - billing
+    - auth
 
-  # Prompts containing these words skip checks entirely (TRIVIAL).
-  # These are safe, mechanical tasks that don't need guardrails.
+  # Keywords that SKIP preflight checks entirely.
+  # Use this for low-risk, routine commands.
   skip:
     - commit
     - format
     - lint
     - prettier
-    - "git push"
 
-  # Prompts containing these words trigger CROSS-SERVICE classification.
-  # Preflight will search related_projects for relevant types and routes.
+  # Keywords that trigger cross-service contract scanning.
+  # When these appear, preflight also checks related_projects for shared types.
   cross_service_keywords:
     - auth
     - notification
     - event
     - webhook
-    - billing          # matches the related_project alias
-
-# How aggressively to classify prompts.
-#   "relaxed"  — more prompts pass as clear (experienced users)
-#   "standard" — balanced (default)
-#   "strict"   — more prompts flagged as ambiguous (new teams, complex codebases)
-strictness: standard
+    - payment

examples/CLAUDE.md

@@ -0,0 +1,30 @@
+# CLAUDE.md — Preflight Integration Example
+#
+# Drop this into your project's CLAUDE.md (or .claude/CLAUDE.md) to make
+# Claude Code automatically use preflight tools during your sessions.
+# Customize the rules below to match your workflow.
+
+## Preflight Rules
+
+Before starting any non-trivial task, run `preflight_check` with my prompt. This catches vague instructions before they waste tokens on wrong→fix cycles.
+
+### When to use preflight tools:
+
+- **Every prompt**: `preflight_check` triages automatically — let it decide what's needed
+- **Before multi-file changes**: Run `scope_work` to get a phased plan
+- **Before sub-agent tasks**: Use `enrich_agent_task` to add context
+- **After making a mistake**: Use `log_correction` so preflight learns the pattern
+- **Before ending a session**: Run `checkpoint` to save state for next time
+- **When I say "fix it" or "do the others"**: Use `sharpen_followup` to resolve what I actually mean
+
+### Session hygiene:
+
+- Run `check_session_health` if we've been going for a while without committing
+- If I ask about something we did before, use `search_history` to find it
+- Before declaring a task done, run `verify_completion` (type check + tests)
+
+### Don't preflight these:
+
+- Simple git commands (commit, push, status)
+- Formatting / linting
+- Reading files I explicitly named