From 24e8fda300dbfac4e1930a235dc89566a48afde0 Mon Sep 17 00:00:00 2001
From: Jack Felke <jrinnfelke@gmail.com>
Date: Thu, 12 Mar 2026 12:23:27 -0700
Subject: [PATCH] docs: add standalone quickstart guide with step-by-step setup
 and verification

---
 README.md          |   2 +-
 docs/QUICKSTART.md | 110 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 111 insertions(+), 1 deletion(-)
 create mode 100644 docs/QUICKSTART.md

diff --git a/README.md b/README.md
index 6d03f5d..ea9f75c 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) · [Configuration](#configuration) · [Scoring](#the-12-category-scorecard) · [Full Quickstart Guide](docs/QUICKSTART.md)
 
 </div>
 
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
new file mode 100644
index 0000000..03d33d7
--- /dev/null
+++ b/docs/QUICKSTART.md
@@ -0,0 +1,110 @@
+# Quickstart Guide
+
+Get preflight running in Claude Code in under 2 minutes.
+
+## 1. Add the MCP server
+
+```bash
+claude mcp add preflight -- npx -y preflight-dev-serve
+```
+
+That's it. No cloning, no `npm install`. The `npx` shim downloads and runs the server automatically.
+
+### Want project-aware features? (recommended)
+
+Point preflight at your project so it can search session history, extract contracts, and give better triage:
+
+```bash
+claude mcp add preflight \
+  -e CLAUDE_PROJECT_DIR=/path/to/your/project \
+  -- npx -y preflight-dev-serve
+```
+
+## 2. Verify it's working
+
+```bash
+claude mcp list
+```
+
+You should see `preflight` in the output. If not, restart Claude Code and try again.
+
+## 3. Use it
+
+Open Claude Code in your project and try a deliberately vague prompt:
+
+```
+fix the bug
+```
+
+Preflight will intercept this and ask you to clarify — that's the point. You'll see something like:
+
+```
+⚠️ AMBIGUOUS — This prompt is too vague to act on safely.
+
+Missing context:
+• Which bug? (file, function, error message)
+• Expected vs actual behavior
+• Any recent changes that might have caused it?
+```
+
+Now try a well-specified prompt:
+
+```
+Fix the JWT refresh logic in src/auth/jwt.ts — the token isn't being
+refreshed when it expires, causing 401s on the /api/user endpoint.
+The expiry check on line 42 compares against seconds but Date.now()
+returns milliseconds.
+```
+
+Preflight will classify this as **CLEAR** and let it through — no friction for good prompts.
+
+## 4. (Optional) Add project config
+
+Run the init wizard to scaffold a `.preflight/` config directory:
+
+```bash
+npx preflight-dev init
+```
+
+This creates:
+
+```
+.preflight/
+├── config.yml      # Profile, related projects, thresholds
+├── triage.yml      # Prompt classification keywords
+└── contracts/      # (empty — add manual type definitions here)
+```
+
+All config is optional — preflight works with zero config. But tuning `triage.yml` to your domain (adding keywords like your service names, domain terms) makes triage significantly better.
+
+## 5. (Optional) Onboard your project
+
+If you have existing Claude Code session history, run the onboard tool to index it for semantic search:
+
+```
+Use the onboard_project tool on this project
+```
+
+This parses your JSONL session files, extracts types and contracts from your codebase, and builds a LanceDB vector index. First run downloads a ~90MB embedding model (one-time).
+
+After onboarding, you can search across all your past sessions:
+
+```
+Search my session history for "auth token refresh"
+```
+
+## Key tools to know
+
+| Tool | When to use it |
+|------|---------------|
+| `preflight_check` | The main entry point — triages any prompt automatically |
+| `search_history` | Semantic search across past Claude Code sessions |
+| `search_contracts` | Find shared types/interfaces across related projects |
+| `generate_scorecard` | Get a 12-category quality score for a session |
+| `estimate_cost` | See how many tokens you're burning on corrections |
+
+## Next steps
+
+- Read the [full README](../README.md) for the complete tool reference
+- Copy `examples/.preflight/` for a commented starter config
+- Check [Troubleshooting](../README.md#troubleshooting) if anything goes wrong