diff --git a/README.md b/README.md
index f60fefa..8a71843 100644
--- a/README.md
+++ b/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>
 
@@ -406,6 +406,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 +606,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.
diff --git a/examples/.preflight/README.md b/examples/.preflight/README.md
new file mode 100644
index 0000000..b8aaf8c
--- /dev/null
+++ b/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.
diff --git a/examples/.preflight/config.yml b/examples/.preflight/config.yml
new file mode 100644
index 0000000..0ad12e8
--- /dev/null
+++ b/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"
diff --git a/examples/.preflight/contracts/api.yml b/examples/.preflight/contracts/api.yml
new file mode 100644
index 0000000..754c5da
--- /dev/null
+++ b/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
diff --git a/examples/.preflight/triage.yml b/examples/.preflight/triage.yml
new file mode 100644
index 0000000..22b05d3
--- /dev/null
+++ b/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
diff --git a/examples/USAGE_EXAMPLES.md b/examples/USAGE_EXAMPLES.md
new file mode 100644
index 0000000..55a2100
--- /dev/null
+++ b/examples/USAGE_EXAMPLES.md
@@ -0,0 +1,205 @@
+# Usage Examples
+
+Real-world examples of preflight tools in action inside Claude Code.
+
+---
+
+## 1. Catching a Vague Prompt with `preflight_check`
+
+You type this into Claude Code:
+
+```
+fix the login bug
+```
+
+Preflight intercepts and returns:
+
+```
+⚠️ Ambiguity detected — routing to clarify_intent
+
+I found 3 potential login issues:
+  1. JWT token not refreshing on expiry (src/auth/jwt.ts:42)
+  2. OAuth callback returning 404 after redirect (src/auth/oauth.ts:118)
+  3. "Remember me" checkbox not persisting session (src/components/LoginForm.tsx:23)
+
+Which one? Or describe the symptoms and I'll narrow it down.
+```
+
+Instead of Claude guessing and editing the wrong file, you get a targeted question. One round-trip instead of three.
+
+---
+
+## 2. Scoping Work Before Coding with `scope_work`
+
+```
+> scope_work "Add rate limiting to the /api/upload endpoint"
+
+📋 Execution Plan
+─────────────────
+Goal: Add rate limiting to POST /api/upload
+
+Files to touch:
+  - src/api/routes/upload.ts (add middleware)
+  - src/middleware/rateLimit.ts (create)
+  - src/config/limits.ts (add upload limits)
+  - tests/api/upload.test.ts (add rate limit tests)
+
+Dependencies:
+  - Check if express-rate-limit is already installed
+  - Review existing middleware chain in src/api/index.ts
+
+Risks:
+  - Existing upload tests may break if rate limit hits in CI
+  - Need to decide: per-IP or per-user limiting?
+
+Estimated scope: ~120 lines across 4 files
+```
+
+---
+
+## 3. Enriching a Sub-Agent Task with `enrich_agent_task`
+
+You want to spawn a sub-agent for a refactor:
+
+```
+> enrich_agent_task "refactor the database queries to use the new ORM"
+
+📦 Enriched Task Brief
+──────────────────────
+Original: "refactor the database queries to use the new ORM"
+
+Context added:
+  - ORM: Drizzle (see drizzle.config.ts, src/db/schema.ts)
+  - 14 files with raw SQL queries (grep results attached)
+  - Existing patterns: src/db/queries/users.ts uses query builder already
+  - Related contracts: UserRecord, PostRecord types in src/types/db.ts
+  - Test coverage: 8/14 query files have corresponding tests
+
+Suggested task for sub-agent:
+  "Refactor raw SQL queries in src/db/queries/ to use Drizzle ORM.
+   Follow the pattern in src/db/queries/users.ts. Schema is in
+   src/db/schema.ts. Run `npm test -- --grep db` after each file.
+   14 files total — see list below."
+```
+
+The sub-agent gets everything it needs instead of fumbling through the codebase.
+
+---
+
+## 4. Resolving Vague Follow-ups with `sharpen_followup`
+
+After Claude fixes a bug, you say:
+
+```
+> do the same for the others
+```
+
+Without preflight, Claude guesses what "the others" means. With it:
+
+```
+> sharpen_followup "do the same for the others"
+
+🔍 Resolved "the others" from conversation context:
+
+You just fixed a missing null check in src/api/users.ts:34.
+Similar pattern found in 4 other files:
+  1. src/api/posts.ts:28 — same nullable field access
+  2. src/api/comments.ts:41 — same pattern
+  3. src/api/teams.ts:55 — same pattern
+  4. src/api/billing.ts:19 — slightly different (optional chain exists but incomplete)
+
+Shall I apply the fix to all 4?
+```
+
+---
+
+## 5. Checking Session Health with `check_session_health`
+
+```
+> check_session_health
+
+🏥 Session Health
+─────────────────
+⏱  Session duration: 47 min
+📝 Uncommitted files: 8 (⚠️ commit soon)
+🔄 Last commit: 38 min ago (⚠️ overdue)
+💬 Turn count: 23
+📊 Context usage: ~62% (healthy)
+🎯 Focus score: B (2 directory switches)
+
+Recommendation: Commit your current changes before continuing.
+Run `checkpoint` to save state.
+```
+
+---
+
+## 6. Searching Past Sessions with `search_history`
+
+```
+> search_history "how did we handle the Stripe webhook retry logic"
+
+🔍 Found 3 relevant results across 2 sessions:
+
+Session 2024-12-15 (confidence: 0.92)
+  "Implemented exponential backoff for Stripe webhook retries
+   in src/webhooks/stripe.ts. Uses 3 retries with 1s/4s/16s delays.
+   Idempotency key stored in Redis."
+
+Session 2024-11-28 (confidence: 0.78)
+  "Discussed webhook retry strategies. Decided against queue-based
+   approach due to infrastructure complexity. Went with in-process
+   retry with circuit breaker."
+```
+
+Never re-research decisions you already made.
+
+---
+
+## 7. Getting a Scorecard with `generate_scorecard`
+
+```
+> generate_scorecard type=trend period=week
+
+📊 Weekly Trend — Jan 20–26, 2025
+──────────────────────────────────
+Overall: B+ (78/100) ↑ from B (74) last week
+
+Improving:
+  ✅ Clarification: 82 → 89 (+7) — more file refs in prompts
+  ✅ Verification: 65 → 78 (+13) — running tests before done
+
+Declining:
+  ⚠️ Compaction Mgmt: 71 → 58 (-13) — 3 compactions without prior commit
+  ⚠️ Session Lifecycle: 80 → 72 (-8) — longer gaps between commits
+
+Top tip: Run `checkpoint` before long exploratory conversations
+to avoid losing work on compaction.
+```
+
+---
+
+## 8. Quick Prompt Grading with `prompt_score`
+
+```
+> prompt_score "update the thing"
+
+📝 Prompt Score: D (32/100)
+───────────────────────────
+Specificity:    F — no file, function, or component named
+Scope:          F — "the thing" is completely ambiguous
+Actionability:  D — "update" is vague (add? change? remove?)
+Done-condition: F — no way to verify completion
+
+Try: "Update the user avatar upload handler in src/api/users.ts
+to accept WebP format and add a test case"  → A (94/100)
+```
+
+---
+
+## Tips
+
+- **Start every session** with `preflight_check` on your first prompt — it'll route to the right tool automatically
+- **Use `checkpoint`** every 20–30 minutes or before exploring a new direction
+- **Run `search_history`** before implementing something — you may have solved it before
+- **Check `session_stats`** at the end of a session to spot waste patterns
+- **Set up `.preflight/config.yml`** to tune thresholds for your team (see [examples/.preflight/](/.preflight/))
diff --git a/src/tools/prompt-score.ts b/src/tools/prompt-score.ts
index 1cecf01..9e91532 100644
--- a/src/tools/prompt-score.ts
+++ b/src/tools/prompt-score.ts
@@ -40,7 +40,7 @@ interface ScoreResult {
   feedback: string[];
 }
 
-function scorePrompt(text: string): ScoreResult {
+export function scorePrompt(text: string): ScoreResult {
   const feedback: string[] = [];
   let specificity: number;
   let scope: number;
diff --git a/tests/tools/prompt-score.test.ts b/tests/tools/prompt-score.test.ts
new file mode 100644
index 0000000..c381984
--- /dev/null
+++ b/tests/tools/prompt-score.test.ts
@@ -0,0 +1,131 @@
+import { describe, it, expect } from "vitest";
+import { scorePrompt } from "../../src/tools/prompt-score.js";
+
+describe("prompt_score — scorePrompt", () => {
+  describe("specificity scoring", () => {
+    it("gives 25 for file paths", () => {
+      expect(scorePrompt("fix src/tools/prompt-score.ts").specificity).toBe(25);
+    });
+
+    it("gives 25 for backtick identifiers", () => {
+      expect(scorePrompt("rename `getUserById` to `findUser`").specificity).toBe(25);
+    });
+
+    it("gives 15 for generic file/function mentions", () => {
+      expect(scorePrompt("update the test").specificity).toBe(15);
+    });
+
+    it("gives 5 for no specific targets", () => {
+      expect(scorePrompt("make it better").specificity).toBe(5);
+    });
+  });
+
+  describe("scope scoring", () => {
+    it("gives 25 for bounded scope words", () => {
+      expect(scorePrompt("fix only the header").scope).toBe(25);
+    });
+
+    it("gives 25 for long prompts (>100 chars)", () => {
+      expect(scorePrompt("a".repeat(101)).scope).toBe(25);
+    });
+
+    it("gives 10 for broad scope words like all/every", () => {
+      // "all" matches broad BUT "refactor" is an action verb, so scope=10 from the broad branch
+      expect(scorePrompt("refactor all handlers").scope).toBe(10);
+    });
+
+    it("gives 10 for unclear scope", () => {
+      expect(scorePrompt("fix bug").scope).toBe(10);
+    });
+  });
+
+  describe("actionability scoring", () => {
+    it("gives 25 for specific action verbs", () => {
+      const verbs = ["add", "remove", "rename", "refactor", "fix", "create", "delete", "update", "implement", "migrate"];
+      for (const verb of verbs) {
+        expect(scorePrompt(`${verb} something`).actionability).toBe(25);
+      }
+    });
+
+    it("gives 15 for vague verbs", () => {
+      expect(scorePrompt("make it work").actionability).toBe(15);
+      expect(scorePrompt("improve performance").actionability).toBe(15);
+      expect(scorePrompt("clean up the code").actionability).toBe(15);
+    });
+
+    it("gives 5 for no action verbs", () => {
+      expect(scorePrompt("the login page").actionability).toBe(5);
+    });
+  });
+
+  describe("done condition scoring", () => {
+    it("gives 25 for verifiable outcome words", () => {
+      expect(scorePrompt("fix so it should return 200").doneCondition).toBe(25);
+      expect(scorePrompt("fix the error on save").doneCondition).toBe(25);
+    });
+
+    it("gives 20 for questions", () => {
+      expect(scorePrompt("why does this crash?").doneCondition).toBe(20);
+    });
+
+    it("gives 5 for no done condition", () => {
+      expect(scorePrompt("refactor the code").doneCondition).toBe(5);
+    });
+  });
+
+  describe("grading", () => {
+    it("gives A+ for perfect scores (100)", () => {
+      const result = scorePrompt("fix only src/index.ts so it should work");
+      expect(result.total).toBe(100);
+      expect(result.grade).toBe("A+");
+    });
+
+    it("gives F for minimal prompts", () => {
+      const result = scorePrompt("hi");
+      expect(result.total).toBeLessThan(45);
+      expect(result.grade).toBe("F");
+    });
+
+    it("total equals sum of dimensions", () => {
+      const result = scorePrompt("add a test for the login module");
+      expect(result.total).toBe(
+        result.specificity + result.scope + result.actionability + result.doneCondition
+      );
+    });
+
+    it("covers all grade thresholds", () => {
+      // Just verify grade is always a valid value
+      const prompts = ["", "hi", "fix bug", "fix only src/x.ts should pass"];
+      const validGrades = ["A+", "A", "A-", "B+", "B", "B-", "C+", "C", "D", "F"];
+      for (const p of prompts) {
+        expect(validGrades).toContain(scorePrompt(p).grade);
+      }
+    });
+  });
+
+  describe("feedback", () => {
+    it("gives congratulatory feedback for perfect score", () => {
+      const result = scorePrompt("fix only src/index.ts so it should work");
+      expect(result.feedback).toHaveLength(1);
+      expect(result.feedback[0]).toContain("Excellent");
+    });
+
+    it("gives improvement tips for weak prompts", () => {
+      const result = scorePrompt("hi");
+      expect(result.feedback.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("handles empty string", () => {
+      const result = scorePrompt("");
+      expect(result.total).toBeGreaterThanOrEqual(0);
+      expect(result.grade).toBeDefined();
+    });
+
+    it("is case-insensitive for keywords", () => {
+      expect(scorePrompt("FIX the bug").actionability).toBe(25);
+      expect(scorePrompt("the FILE needs work").specificity).toBe(15);
+    });
+  });
+});