From e22719c85a95635768636e837716cf6f6ee6be25 Mon Sep 17 00:00:00 2001 From: Jack Felke Date: Wed, 4 Mar 2026 14:19:45 -0700 Subject: [PATCH 1/2] docs: add troubleshooting section to README Covers common issues: LanceDB native modules, first-run model download, missing session data, .preflight/ config not loading, tools not appearing in Claude Code, and permission errors. --- README.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) diff --git a/README.md b/README.md index f60fefa..25b3263 100644 --- a/README.md +++ b/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`. From a540f0f7ab5da98f0d40282e715a93674712f798 Mon Sep 17 00:00:00 2001 From: Jack Felke Date: Wed, 4 Mar 2026 15:18:33 -0700 Subject: [PATCH 2/2] docs: add .preflight/ example config files for easy onboarding Adds copyable example files for config.yml, triage.yml, and contracts/api.yml so users can quickly set up project-level configuration without reading the full README. --- .preflight/README.md | 25 ++++++++++++++++++++ .preflight/config.yml.example | 33 ++++++++++++++++++++++++++ .preflight/contracts/api.yml.example | 35 ++++++++++++++++++++++++++++ .preflight/triage.yml.example | 31 ++++++++++++++++++++++++ 4 files changed, 124 insertions(+) create mode 100644 .preflight/README.md create mode 100644 .preflight/config.yml.example create mode 100644 .preflight/contracts/api.yml.example create mode 100644 .preflight/triage.yml.example diff --git a/.preflight/README.md b/.preflight/README.md new file mode 100644 index 0000000..d5306d2 --- /dev/null +++ b/.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` diff --git a/.preflight/config.yml.example b/.preflight/config.yml.example new file mode 100644 index 0000000..aed92f3 --- /dev/null +++ b/.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" diff --git a/.preflight/contracts/api.yml.example b/.preflight/contracts/api.yml.example new file mode 100644 index 0000000..920ec43 --- /dev/null +++ b/.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 diff --git a/.preflight/triage.yml.example b/.preflight/triage.yml.example new file mode 100644 index 0000000..96690f4 --- /dev/null +++ b/.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