feat: add export_timeline tool for markdown session reports

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,16 @@ 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.
+
 ---
 
 ## How It Works
@@ -734,6 +744,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/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

examples/README.md

@@ -12,6 +12,22 @@ The `.preflight/` directory contains example configuration files you can copy in
     └── api.yml             # Manual contract definitions for cross-service types
 ```
 
+## `CLAUDE.md` Integration
+
+The `CLAUDE.md` file tells Claude Code how to behave in your project. Adding preflight rules here makes Claude automatically use preflight tools without you having to ask.
+
+```bash
+# Copy the example into your project:
+cp /path/to/preflight/examples/CLAUDE.md my-project/CLAUDE.md
+
+# Or append to your existing CLAUDE.md:
+cat /path/to/preflight/examples/CLAUDE.md >> my-project/CLAUDE.md
+```
+
+This is the **recommended way** to integrate preflight — once it's in your `CLAUDE.md`, every session automatically runs `preflight_check` on your prompts.
+
+---
+
 ### Quick setup
 
 ```bash

src/cli/init.ts

@@ -9,6 +9,46 @@ import { join, dirname } from "node:path";
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
+// Handle --help and --version before launching interactive wizard
+const args = process.argv.slice(2);
+
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(`
+✈️  preflight-dev — MCP server for Claude Code prompt discipline
+
+Usage:
+  preflight-dev              Interactive setup wizard (creates .mcp.json)
+  preflight-dev --help       Show this help message
+  preflight-dev --version    Show version
+
+The wizard will:
+  1. Ask you to choose a profile (minimal / standard / full)
+  2. Optionally create a .preflight/ config directory
+  3. Write an .mcp.json so Claude Code auto-connects to preflight
+
+After setup, restart Claude Code and preflight tools will appear.
+
+Profiles:
+  minimal   4 tools — clarify_intent, check_session_health, session_stats, prompt_score
+  standard  16 tools — all prompt discipline + session_stats + prompt_score
+  full      20 tools — everything + timeline/vector search (needs LanceDB)
+
+More info: https://github.com/TerminalGravity/preflight
+`);
+  process.exit(0);
+}
+
+if (args.includes("--version") || args.includes("-v")) {
+  const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "../../package.json");
+  try {
+    const pkg = JSON.parse(await readFile(pkgPath, "utf-8"));
+    console.log(`preflight-dev v${pkg.version}`);
+  } catch {
+    console.log("preflight-dev (version unknown)");
+  }
+  process.exit(0);
+}
+
 const rl = createInterface({ input: process.stdin, output: process.stdout });
 
 function ask(question: string): Promise<string> {

src/index.ts

@@ -49,6 +49,7 @@
 import { registerGenerateScorecard } from "./tools/generate-scorecard.js";
 import { registerSearchContracts } from "./tools/search-contracts.js";
 import { registerEstimateCost } from "./tools/estimate-cost.js";
+import { registerExportTimeline } from "./tools/export-timeline.js";
 
 // Validate related projects from config
 function validateRelatedProjects(): void {
@@ -73,7 +74,7 @@
 }
 
 // Load config and validate related projects on startup
 const config = getConfig();
 validateRelatedProjects();
 
 const profile = getProfile();
@@ -110,6 +111,7 @@
   ["generate_scorecard", registerGenerateScorecard],
   ["estimate_cost", registerEstimateCost],
   ["search_contracts", registerSearchContracts],
+  ["export_timeline", registerExportTimeline],
 ];
 
 let registered = 0;