docs: add .preflight/ example config files

.preflight/README.md

@@ -0,0 +1,25 @@
+# `.preflight/` Configuration
+
+This directory contains example configuration files for preflight. Copy the `.example` files to get started:
+
+```bash
+cp .preflight/config.yml.example .preflight/config.yml
+cp .preflight/triage.yml.example .preflight/triage.yml
+mkdir -p .preflight/contracts
+cp .preflight/contracts/api.yml.example .preflight/contracts/api.yml
+```
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `config.yml` | Main config — verbosity profile, related projects, thresholds, embedding provider |
+| `triage.yml` | Triage rules — keywords that control how prompts are classified |
+| `contracts/*.yml` | Manual API contract definitions that supplement auto-extraction |
+
+## Tips
+
+- **Commit these files** to share settings across your team
+- All fields are optional — defaults are sensible
+- Environment variables (`CLAUDE_PROJECT_DIR`, `OPENAI_API_KEY`, etc.) are fallbacks; config files take precedence
+- Add project-specific keywords to `triage.yml` — e.g., if `billing` is always complex in your codebase, add it to `always_check`

.preflight/config.yml.example

@@ -0,0 +1,33 @@
+# .preflight/config.yml — Drop this in your project root
+# All fields are optional. Defaults are sensible.
+# Copy this file to .preflight/config.yml and customize.
+
+# Profile controls overall verbosity
+# "minimal" — only flag ambiguous+, skip clarification detail
+# "standard" — default behavior (recommended)
+# "full" — maximum detail on every non-trivial prompt
+profile: standard
+
+# Related projects for cross-service awareness
+# Preflight searches these when your prompt touches shared contracts
+related_projects:
+  # - path: /absolute/path/to/auth-service
+  #   alias: auth-service
+  # - path: /absolute/path/to/shared-types
+  #   alias: shared-types
+
+# Behavioral thresholds
+thresholds:
+  # Warn if no activity for this many minutes
+  session_stale_minutes: 30
+  # Suggest checkpoint after N tool calls
+  max_tool_calls_before_checkpoint: 100
+  # Minimum corrections before forming a pattern
+  correction_pattern_threshold: 3
+
+# Embedding configuration
+embeddings:
+  # "local" — Xenova/all-MiniLM-L6-v2, zero config, 100% offline
+  # "openai" — faster + higher quality, requires API key
+  provider: local
+  # openai_api_key: sk-...  # Only needed if provider is "openai"

.preflight/contracts/api.yml.example

@@ -0,0 +1,35 @@
+# .preflight/contracts/api.yml — Manual contract definitions
+# These supplement auto-extracted contracts from your source code.
+# Useful for documenting APIs that aren't easily auto-detected.
+# Copy this file to .preflight/contracts/api.yml and customize.
+
+- name: User
+  kind: interface
+  description: Core user object returned by auth endpoints
+  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: ApiResponse
+  kind: interface
+  description: Standard API response wrapper
+  fields:
+    - name: success
+      type: boolean
+      required: true
+    - name: data
+      type: T
+      required: false
+    - name: error
+      type: string
+      required: false

.preflight/triage.yml.example

@@ -0,0 +1,31 @@
+# .preflight/triage.yml — Controls the triage classification engine
+# Copy this file to .preflight/triage.yml and customize.
+
+rules:
+  # Prompts containing these keywords → always at least AMBIGUOUS
+  # Add domain-specific terms that need clarification in your project
+  always_check:
+    - rewards
+    - permissions
+    - migration
+    - schema
+
+  # Prompts containing these → TRIVIAL (pass through, no checks)
+  skip:
+    - commit
+    - format
+    - lint
+
+  # Prompts containing these → CROSS-SERVICE
+  # Add keywords that indicate cross-project concerns
+  cross_service_keywords:
+    - auth
+    - notification
+    - event
+    - webhook
+
+# How aggressively to classify prompts
+# "relaxed" — more prompts pass as clear (fewer interruptions)
+# "standard" — balanced (recommended)
+# "strict" — more prompts flagged as ambiguous (safest for expensive models)
+strictness: standard

README.md

@@ -562,6 +562,79 @@ flowchart TB
 
 ---
 
+## Troubleshooting
+
+### LanceDB native module errors
+
+```
+Error: Failed to load native module
+```
+
+LanceDB uses native bindings that need to match your platform. Fix:
+
+```bash
+# Remove and reinstall node_modules
+rm -rf node_modules package-lock.json
+npm install
+```
+
+If you're on an uncommon platform (musl Linux, older macOS), check [LanceDB compatibility](https://lancedb.github.io/lancedb/). Node 18+ is required.
+
+### First run is slow / "Downloading model" hangs
+
+The local embedding provider downloads `Xenova/all-MiniLM-L6-v2` (~90MB) on first use. This is a one-time download — subsequent runs are instant. If it stalls:
+
+- Check your internet connection
+- The model caches to `~/.cache/huggingface/` — ensure you have write access
+- Switch to OpenAI embeddings if local doesn't work: set `OPENAI_API_KEY` and configure in `.preflight/config.yml`
+
+### "No session data found" / timeline search returns nothing
+
+Timeline tools need indexed session data. Common causes:
+
+1. **`CLAUDE_PROJECT_DIR` not set** — the server needs this to find your project's session JSONL files. Pass it as an env var when adding the MCP server:
+   ```bash
+   claude mcp add preflight -e CLAUDE_PROJECT_DIR=/path/to/project -- npx tsx /path/to/preflight/src/index.ts
+   ```
+2. **Project not onboarded** — run the `onboard_project` tool first to index existing sessions into LanceDB
+3. **No Claude Code sessions exist yet** — timeline search reads from `~/.claude/projects/` which is populated by Claude Code usage
+
+### `.preflight/` config not loading
+
+The `.preflight/` directory must be in your **project root** (the directory `CLAUDE_PROJECT_DIR` points to). Verify:
+
+```
+your-project/
+├── .preflight/
+│   ├── config.yml      # Triage thresholds, scoring weights
+│   └── triage.yml      # Custom skip/always-check keywords
+├── src/
+└── ...
+```
+
+If you renamed or moved your project, update `CLAUDE_PROJECT_DIR` to match.
+
+### Tools not appearing in Claude Code
+
+After adding the MCP server, restart Claude Code completely (not just reload). Verify the server is registered:
+
+```bash
+claude mcp list
+```
+
+You should see `preflight` in the output. If not, re-add it. Check that `npx tsx` works in your shell — you may need to install tsx globally (`npm i -g tsx`) if npx resolution fails.
+
+### Permission errors on `~/.preflight/`
+
+The server stores per-project data in `~/.preflight/projects/`. If you get `EACCES` errors:
+
+```bash
+mkdir -p ~/.preflight
+chmod 755 ~/.preflight
+```
+
+---
+
 ## 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`.