Add .preflight/ example configs with annotated YAML

README.md

@@ -406,6 +406,8 @@ This prevents the common failure mode: changing a shared type in one service and
 
 ## Configuration Reference
 
+> **💡 Want a ready-to-use starting point?** Copy the [`examples/.preflight/`](examples/.preflight/) directory to your project root and edit to taste.
+
 ### `.preflight/config.yml`
 
 Drop this in your project root. Every field is optional — defaults are sensible.

examples/.preflight/README.md

@@ -0,0 +1,33 @@
+# Example `.preflight/` Configuration
+
+Copy this directory to your project root to get started:
+
+```bash
+cp -r examples/.preflight /path/to/your/project/
+```
+
+Then edit the files for your project:
+
+1. **`config.yml`** — Set your related projects and thresholds
+2. **`triage.yml`** — Add domain-specific keywords that should trigger checks
+3. **`contracts/*.yml`** — Define shared types and API contracts
+
+All fields are optional. Preflight uses sensible defaults for anything you leave out.
+
+## File Overview
+
+```
+.preflight/
+├── config.yml          # Main config: related projects, thresholds, embeddings
+├── triage.yml          # Triage rules: which prompts get checked and how
+├── contracts/
+│   └── api.yml         # Manual contract definitions (types, interfaces, routes)
+└── README.md           # This file (you can delete it)
+```
+
+## Tips
+
+- **Commit `.preflight/` to your repo** so your whole team gets the same behavior
+- **Start with defaults** and add `always_check` keywords as you discover pain points
+- **Split contracts** into multiple files (`api.yml`, `events.yml`, etc.) for organization
+- **Use `profile: minimal`** if preflight feels too chatty during rapid iteration

examples/.preflight/config.yml

@@ -0,0 +1,44 @@
+# .preflight/config.yml — Drop this in your project root
+#
+# This is the main preflight configuration file. Every field is optional;
+# defaults are sensible for most projects. Commit this to your repo so
+# your whole team gets the same preflight behavior.
+#
+# Docs: https://github.com/TerminalGravity/preflight#configuration-reference
+
+# Profile controls how verbose preflight is:
+#   "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 will search these projects' LanceDB indexes and contract
+# registries when it detects cross-service prompts. This prevents the
+# common failure: changing a shared type in one service and forgetting
+# the consumers.
+related_projects:
+  - path: /Users/you/projects/auth-service
+    alias: auth
+  - path: /Users/you/projects/shared-types
+    alias: shared-types
+  # Add more as needed:
+  # - path: /Users/you/projects/notifications
+  #   alias: notifications
+
+# Behavioral thresholds — tune these to your workflow
+thresholds:
+  # Warn if no session activity for this many minutes
+  session_stale_minutes: 30
+  # Suggest a checkpoint after this many tool calls
+  max_tool_calls_before_checkpoint: 100
+  # Minimum corrections before preflight learns a pattern
+  correction_pattern_threshold: 3
+
+# Embedding configuration for semantic search
+embeddings:
+  # "local" uses Xenova (no API key needed, runs on-device)
+  # "openai" uses OpenAI embeddings (faster, requires key)
+  provider: local
+  # Only needed if provider is "openai":
+  # openai_api_key: sk-...

examples/.preflight/contracts/api.yml

@@ -0,0 +1,61 @@
+# .preflight/contracts/api.yml — Manual contract definitions
+#
+# Define contracts that preflight should know about. These supplement
+# auto-extracted contracts from your codebase. If a manual contract has
+# the same name as an auto-extracted one, the manual definition wins.
+#
+# Use cases:
+#   - Document API contracts that aren't easily extracted from code
+#   - Define expected shapes for external services
+#   - Add contracts for planned-but-not-yet-built features
+#
+# You can split contracts across multiple files in this directory:
+#   contracts/api.yml, contracts/events.yml, contracts/external.yml, etc.
+
+- name: User
+  kind: interface
+  description: Core user model 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: createdAt
+      type: Date
+      required: true
+
+- name: RewardsTier
+  kind: interface
+  description: Reward tier levels and their perks
+  fields:
+    - name: tier
+      type: "'bronze' | 'silver' | 'gold' | 'platinum'"
+      required: true
+    - name: multiplier
+      type: number
+      required: true
+    - name: perks
+      type: string[]
+      required: false
+
+- name: AuthToken
+  kind: interface
+  description: JWT payload structure from auth-service
+  fields:
+    - name: userId
+      type: string
+      required: true
+    - name: tier
+      type: string
+      required: true
+    - name: permissions
+      type: string[]
+      required: true
+    - name: exp
+      type: number
+      required: true

examples/.preflight/triage.yml

@@ -0,0 +1,48 @@
+# .preflight/triage.yml — Controls the triage classification engine
+#
+# Triage decides how preflight routes your prompts:
+#   TRIVIAL       → pass through (no preflight check)
+#   CLEAR         → quick validation, no blocking questions
+#   AMBIGUOUS     → preflight asks clarifying questions before proceeding
+#   MULTI-STEP    → preflight breaks down the task and checks each step
+#   CROSS-SERVICE → preflight searches related projects for contracts/types
+#
+# Customize these keywords for your domain. For example, if your app has
+# a "billing" module that's error-prone, add "billing" to always_check.
+
+rules:
+  # Prompts containing these words → always at least AMBIGUOUS.
+  # Add domain-specific terms that commonly lead to wrong guesses.
+  always_check:
+    - rewards
+    - permissions
+    - migration
+    - schema
+    - billing        # example: add your own risky domains
+    # - payments
+    # - deployment
+
+  # Prompts containing these words → TRIVIAL (pass through immediately).
+  # These are safe, well-understood operations that don't need checking.
+  skip:
+    - commit
+    - format
+    - lint
+    - prettier
+    # - typecheck
+
+  # Prompts containing these words → CROSS-SERVICE.
+  # Triggers a search across related_projects defined in config.yml.
+  cross_service_keywords:
+    - auth
+    - notification
+    - event
+    - webhook
+    # - queue
+    # - pubsub
+
+# How aggressively to classify prompts:
+#   "relaxed"  — more prompts pass as clear (fewer interruptions)
+#   "standard" — balanced (recommended)
+#   "strict"   — more prompts flagged as ambiguous (maximum safety)
+strictness: standard