docs: add example .preflight/ config directory

README.md

@@ -500,6 +500,8 @@ Manual contract definitions that supplement auto-extraction:
 
 Environment variables are **fallbacks** — `.preflight/` config takes precedence when present.
 
+> **💡 Ready-to-use example configs:** Copy [`examples/.preflight/`](examples/.preflight/) into your project root to get started quickly. See [`examples/.preflight/README.md`](examples/.preflight/README.md) for details.
+
 ---
 
 ## Embedding Providers

examples/.preflight/README.md

@@ -0,0 +1,24 @@
+# Example `.preflight/` Config
+
+Copy this directory into your project root to get started:
+
+```bash
+cp -r examples/.preflight /path/to/your/project/
+```
+
+Then edit the files to match your project:
+
+| File | Purpose |
+|------|---------|
+| `config.yml` | Profile, related projects, thresholds, embedding provider |
+| `triage.yml` | Keyword rules and strictness for prompt classification |
+| `contracts/*.yml` | Manual type/interface definitions for cross-service awareness |
+
+All files are optional — preflight works without any config. These let you tune it for your team and codebase.
+
+## Tips
+
+- **Commit `.preflight/` to your repo** so the whole team shares the same rules
+- **Start with `strictness: standard`**, then relax or tighten based on your experience
+- **Add domain terms to `always_check`** that are frequently ambiguous in your codebase (e.g., "billing", "permissions")
+- **Use contracts** for types that live in a separate repo or aren't auto-detected

examples/.preflight/config.yml

@@ -0,0 +1,31 @@
+# .preflight/config.yml
+# Drop this in your project root. Every field is optional.
+# See: https://github.com/TerminalGravity/preflight#configuration-reference
+
+# Profile controls how much detail preflight returns.
+# "minimal"  — only flags ambiguous+, skips clarification detail
+# "standard" — default behavior
+# "full"     — maximum detail on every non-trivial prompt
+profile: standard
+
+# Related projects for cross-service contract awareness.
+# When your prompt mentions a keyword from a related project,
+# triage escalates to cross-service and searches those projects.
+related_projects:
+  - path: /Users/you/projects/auth-service
+    alias: auth
+  - path: /Users/you/projects/shared-types
+    alias: shared
+
+# 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 provider for timeline search
+# "local" uses Xenova (zero config, runs on-device)
+# "openai" uses text-embedding-3-small (faster, needs API key)
+embeddings:
+  provider: local
+  # openai_api_key: sk-...  # only needed if provider is "openai"

examples/.preflight/contracts/api.yml

@@ -0,0 +1,35 @@
+# .preflight/contracts/api.yml
+# Manual contract definitions that supplement auto-extraction.
+# Use these when preflight can't auto-detect your shared types,
+# or when you want to be explicit about cross-service boundaries.
+
+- 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: teamId
+      type: string
+      required: false
+
+- name: ApiResponse
+  kind: interface
+  description: Standard API response wrapper
+  fields:
+    - name: data
+      type: T
+      required: true
+    - name: error
+      type: string
+      required: false
+    - name: meta
+      type: "{ page: number, total: number }"
+      required: false

examples/.preflight/triage.yml

@@ -0,0 +1,36 @@
+# .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 frequently underspecified in your codebase.
+  always_check:
+    - rewards
+    - permissions
+    - migration
+    - schema
+    - billing
+
+  # Prompts containing these words → TRIVIAL (pass through without checks).
+  # Safe, low-risk operations that don't need guardrails.
+  skip:
+    - commit
+    - format
+    - lint
+    - prettier
+
+  # Prompts containing these words → CROSS-SERVICE.
+  # Triggers a search across related_projects defined in config.yml.
+  cross_service_keywords:
+    - auth
+    - notification
+    - event
+    - webhook
+    - queue
+
+# How aggressively to classify prompts.
+# "relaxed"  — more prompts pass as clear (experienced users)
+# "standard" — balanced (recommended)
+# "strict"   — more prompts flagged as ambiguous (teams, onboarding)
+strictness: standard