test: add unit tests for scorePrompt and pattern matching

README.md

@@ -12,7 +12,7 @@ A 24-tool MCP server for Claude Code that catches ambiguous instructions before
 [![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/)
 
-[Quick Start](#quick-start) · [How It Works](#how-it-works) · [Tool Reference](#tool-reference) · [Configuration](#configuration) · [Scoring](#the-12-category-scorecard)
+[Quick Start](#quick-start) · [How It Works](#how-it-works) · [Tool Reference](#tool-reference) · [Usage Examples](examples/USAGE_EXAMPLES.md) · [Configuration](#configuration) · [Scoring](#the-12-category-scorecard)
 
 </div>
 
@@ -76,21 +76,36 @@ The pattern is always the same: vague prompt → Claude guesses → wrong output
 
 ## Quick Start
 
-### Option A: Claude Code CLI (fastest)
+### Option A: npx (zero install — fastest)
+
+One command, nothing to clone or install:
 
 ```bash
-claude mcp add preflight -- npx tsx /path/to/preflight/src/index.ts
+claude mcp add preflight -- npx -y preflight-dev
 ```
 
-With environment variables:
+With your project directory (recommended — enables contracts, file search, and context-aware triage):
 
 ```bash
 claude mcp add preflight \
   -e CLAUDE_PROJECT_DIR=/path/to/your/project \
-  -- npx tsx /path/to/preflight/src/index.ts
+  -- npx -y preflight-dev
+```
+
+Restart Claude Code. All 24 tools activate automatically.
+
+### Option B: npm global install
+
+Install once, available everywhere:
+
+```bash
+npm install -g preflight-dev
+claude mcp add preflight -- preflight-dev
 ```
 
-### Option B: Clone & configure manually
+### Option C: Clone & configure manually
+
+Best for contributors or if you want to modify preflight itself:
 
 ```bash
 git clone https://github.com/TerminalGravity/preflight.git
@@ -104,9 +119,9 @@ Add to your project's `.mcp.json`:
   "mcpServers": {
     "preflight": {
       "command": "npx",
-      "args": ["tsx", "/path/to/preflight/src/index.ts"],
+      "args": ["tsx", "/absolute/path/to/preflight/src/index.ts"],
       "env": {
-        "CLAUDE_PROJECT_DIR": "/path/to/your/project"
+        "CLAUDE_PROJECT_DIR": "/absolute/path/to/your/project"
       }
     }
   }
@@ -115,12 +130,7 @@ Add to your project's `.mcp.json`:
 
 Restart Claude Code. The tools activate automatically.
 
-### Option C: npm (global)
-
-```bash
-npm install -g preflight-dev
-claude mcp add preflight -- preflight-dev
-```
+> **Note:** Paths in `.mcp.json` must be absolute — relative paths won't resolve correctly.
 
 ---
 
@@ -406,6 +416,12 @@ This prevents the common failure mode: changing a shared type in one service and
 
 ## Configuration Reference
 
+> **Want a ready-to-use starting point?** Copy the example configs:
+> ```bash
+> cp -r examples/.preflight /path/to/your/project/
+> ```
+> See [`examples/.preflight/README.md`](examples/.preflight/README.md) for details.
+
 ### `.preflight/config.yml`
 
 Drop this in your project root. Every field is optional — defaults are sensible.
@@ -600,6 +616,78 @@ src/
     └── ...                  # One file per tool
 ```
 
+## Troubleshooting
+
+### Tools don't show up in Claude Code
+
+**Symptom:** You added the MCP config but Claude doesn't see any preflight tools.
+
+1. Make sure you restarted Claude Code after editing `.mcp.json`
+2. Check the path in your config is absolute, not relative — `npx tsx /Users/you/preflight/src/index.ts`
+3. Run the server directly to check for startup errors:
+   ```bash
+   npx tsx /path/to/preflight/src/index.ts
+   ```
+   If it crashes on startup, the error will tell you what's missing.
+
+### LanceDB / timeline search not working
+
+**Symptom:** `search_timeline` returns empty results or errors about the database.
+
+- LanceDB stores data in `~/.preflight/projects/<project>/timeline.lance/`
+- You need to **ingest sessions first** — run `preflight_onboard_project` with your project dir, or use the CLI: `preflight-dev init`
+- If you get native module errors, make sure your Node version matches your OS architecture (especially on Apple Silicon — don't use x64 Node via Rosetta)
+- To reset a corrupt database, delete the `.lance` directory and re-ingest:
+  ```bash
+  rm -rf ~/.preflight/projects/YOUR_PROJECT/timeline.lance
+  ```
+
+### `CLAUDE_PROJECT_DIR` not set
+
+**Symptom:** Tools that need project context (contracts, file search) return nothing useful.
+
+Set it in your `.mcp.json` env block:
+```json
+"env": {
+  "CLAUDE_PROJECT_DIR": "/absolute/path/to/your/project"
+}
+```
+Or export it before running Claude Code:
+```bash
+export CLAUDE_PROJECT_DIR=/path/to/your/project
+claude
+```
+
+### `preflight_check` says everything is "TRIVIAL"
+
+This is by design for short, unambiguous commands like `git status` or `ls`. The triage engine only flags prompts that are genuinely ambiguous. If you want stricter checking, add keywords to `always_check` in `.preflight/triage.yml`:
+
+```yaml
+always_check:
+  - refactor
+  - update
+  - change
+```
+
+### npm global install: `preflight-dev: command not found`
+
+After `npm install -g preflight-dev`, your shell may not see the new binary. Try:
+```bash
+# Check where npm puts global bins
+npm bin -g
+# Make sure that directory is in your PATH
+export PATH="$(npm bin -g):$PATH"
+```
+
+### High memory usage during session ingestion
+
+Large JSONL session files (100MB+) can spike memory. Set `NODE_OPTIONS` to increase the heap:
+```bash
+NODE_OPTIONS="--max-old-space-size=4096" npx tsx src/index.ts
+```
+
+---
+
 ## License
 
 MIT — do whatever you want with it.

examples/.preflight/README.md

@@ -0,0 +1,25 @@
+# `.preflight/` Example Config
+
+Copy this directory into your project root to configure preflight:
+
+```bash
+cp -r examples/.preflight /path/to/your/project/
+```
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `config.yml` | Main config — profile, related projects, thresholds, embeddings |
+| `triage.yml` | Triage rules — which keywords trigger which classification level |
+| `contracts/*.yml` | Manual contract definitions — supplement auto-extraction |
+
+## Quick Setup
+
+1. Copy the directory: `cp -r examples/.preflight ./`
+2. Edit `config.yml` — set your `related_projects` paths
+3. Edit `triage.yml` — add your domain-specific keywords to `always_check`
+4. Optionally add contracts in `contracts/` for planned or external APIs
+5. Commit `.preflight/` to your repo so your team shares the same config
+
+All fields are optional. Defaults work well out of the box — only customize what you need.

examples/.preflight/config.yml

@@ -0,0 +1,29 @@
+# .preflight/config.yml — drop this in your project root
+# All fields are optional. Defaults are sensible.
+# See: https://github.com/TerminalGravity/preflight#configuration-reference
+
+# Profile controls overall verbosity
+# "minimal" — only flag ambiguous+, skip clarification detail
+# "standard" — default behavior
+# "full" — maximum detail on every non-trivial prompt
+profile: standard
+
+# Related projects for cross-service awareness
+# Preflight will search these projects' indexes when your prompt
+# touches shared contracts (types, routes, schemas).
+related_projects:
+  # - path: /absolute/path/to/auth-service
+  #   alias: auth-service
+  # - path: /absolute/path/to/shared-types
+  #   alias: shared-types
+
+# Behavioral thresholds
+thresholds:
+  session_stale_minutes: 30           # warn if no activity for this long
+  max_tool_calls_before_checkpoint: 100  # suggest checkpoint after N tool calls
+  correction_pattern_threshold: 3     # min corrections before forming a pattern
+
+# Embedding configuration
+embeddings:
+  provider: local          # "local" (Xenova, zero config) or "openai"
+  # openai_api_key: sk-... # only needed if provider is "openai"

examples/.preflight/contracts/api.yml

@@ -0,0 +1,47 @@
+# .preflight/contracts/api.yml — manual contract definitions
+# These supplement auto-extracted contracts from your codebase.
+# Manual definitions win on name conflicts with auto-extracted ones.
+#
+# Use this when:
+# - You have contracts that aren't in code yet (planned APIs)
+# - Auto-extraction misses something important
+# - You want to document cross-service agreements explicitly
+
+- name: User
+  kind: interface
+  description: Core user object shared across services
+  fields:
+    - name: id
+      type: string
+      required: true
+    - name: email
+      type: string
+      required: true
+    - name: role
+      type: "'admin' | 'member' | 'viewer'"
+      required: true
+    - name: createdAt
+      type: Date
+      required: true
+
+- name: "POST /api/users"
+  kind: route
+  description: Create a new user account
+  fields:
+    - name: body
+      type: "{ email: string, role: string }"
+      required: true
+    - name: response
+      type: "{ user: User, token: string }"
+      required: true
+
+- name: "GET /api/users/:id"
+  kind: route
+  description: Fetch user by ID
+  fields:
+    - name: params
+      type: "{ id: string }"
+      required: true
+    - name: response
+      type: User
+      required: true

examples/.preflight/triage.yml

@@ -0,0 +1,38 @@
+# .preflight/triage.yml — controls the triage classification engine
+# Customize which prompts get flagged, skipped, or escalated.
+
+rules:
+  # Prompts containing these words → always at least AMBIGUOUS
+  # Add domain terms that are too vague without context
+  always_check:
+    - rewards
+    - permissions
+    - migration
+    - schema
+    # - billing        # uncomment for your domain
+    # - onboarding
+
+  # Prompts containing these words → TRIVIAL (pass through immediately)
+  # Common low-risk commands that don't need analysis
+  skip:
+    - commit
+    - format
+    - lint
+    - "git status"
+    - "git log"
+
+  # Prompts containing these words → CROSS-SERVICE
+  # Triggers search across related_projects defined in config.yml
+  cross_service_keywords:
+    - auth
+    - notification
+    - event
+    - webhook
+    # - payment
+    # - analytics
+
+# How aggressively to classify
+# "relaxed"  — more prompts pass as clear (faster, less interruption)
+# "standard" — balanced (recommended)
+# "strict"   — more prompts flagged as ambiguous (thorough, more interruptions)
+strictness: standard