Add .preflight/ example config directory

.preflight/README.md

@@ -0,0 +1,28 @@
+# `.preflight/` — Project Configuration
+
+This directory contains example configuration files for preflight. Copy it to your project root and customize.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `config.yml` | Main config — profile, related projects, thresholds, embeddings |
+| `triage.yml` | Triage rules — keywords that control prompt classification |
+| `contracts/*.yml` | Manual contract definitions that supplement auto-extraction |
+
+## Quick Setup
+
+```bash
+# Copy the example config to your project
+cp -r /path/to/preflight/.preflight /path/to/your/project/
+
+# Edit to match your setup
+$EDITOR your-project/.preflight/config.yml
+```
+
+## Notes
+
+- All fields are optional — defaults are sensible
+- `.preflight/` config takes precedence over environment variables
+- Commit this directory to share settings across your team
+- See the main [README](../README.md#configuration-reference) for full docs

.preflight/config.yml

@@ -0,0 +1,30 @@
+# .preflight/config.yml — Example configuration
+# Copy this directory to your project root and customize.
+# Every field is optional — defaults are sensible.
+
+# Profile controls overall verbosity:
+#   "minimal"  — only flag ambiguous+, skip clarification detail
+#   "standard" — default behavior
+#   "full"     — maximum detail on every non-trivial prompt
+profile: standard
+
+# Related projects for cross-service contract awareness.
+# When a prompt mentions keywords from a related project,
+# preflight escalates to cross-service triage and pulls
+# relevant types, interfaces, and routes automatically.
+related_projects:
+  # - path: /absolute/path/to/auth-service
+  #   alias: auth-service
+  # - path: /absolute/path/to/shared-types
+  #   alias: shared-types
+
+# 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 configuration
+embeddings:
+  provider: local                          # "local" (Xenova, zero config) or "openai"
+  # openai_api_key: sk-...                 # Only needed if provider is "openai"

.preflight/contracts/example-api.yml

@@ -0,0 +1,39 @@
+# .preflight/contracts/example-api.yml — Example manual contract
+# Define contracts that supplement auto-extraction from code.
+# Manual definitions win on name conflicts with auto-extracted ones.
+#
+# Use this for:
+#   - External API contracts not in your codebase
+#   - Shared types that live in a separate repo
+#   - Business-domain types that aren't in code yet
+
+- name: User
+  kind: interface
+  description: Core user record
+  fields:
+    - name: id
+      type: string
+      required: true
+    - name: email
+      type: string
+      required: true
+    - name: role
+      type: "'admin' | 'member' | 'guest'"
+      required: true
+    - name: createdAt
+      type: Date
+      required: true
+
+- name: ApiResponse
+  kind: interface
+  description: Standard API response envelope
+  fields:
+    - name: success
+      type: boolean
+      required: true
+    - name: data
+      type: T
+      required: false
+    - name: error
+      type: string
+      required: false

.preflight/triage.yml

@@ -0,0 +1,36 @@
+# .preflight/triage.yml — Example triage rules
+# Controls how the triage classifier routes prompts.
+
+rules:
+  # Prompts containing these words → always at least AMBIGUOUS.
+  # Add domain-specific terms that are often under-specified.
+  always_check:
+    - rewards
+    - permissions
+    - migration
+    - schema
+    # - billing          # uncomment for billing-heavy projects
+    # - deploy           # uncomment if deploys need extra scrutiny
+
+  # Prompts containing these words → TRIVIAL (pass through).
+  # Safe, well-understood operations that don't need triage.
+  skip:
+    - commit
+    - format
+    - lint
+    - prettier
+
+  # Prompts containing these words → CROSS-SERVICE.
+  # Triggers contract search across related_projects.
+  cross_service_keywords:
+    - auth
+    - notification
+    - event
+    - webhook
+    # - payments         # uncomment if you have a payments service
+
+# How aggressively to classify:
+#   "relaxed"  — more prompts pass as clear
+#   "standard" — balanced (recommended starting point)
+#   "strict"   — more prompts flagged as ambiguous
+strictness: standard

README.md

@@ -406,6 +406,8 @@ This prevents the common failure mode: changing a shared type in one service and
 
 ## Configuration Reference
 
+> **💡 Starter configs included!** Copy the `.preflight/` directory from this repo into your project root for ready-to-customize example configs with inline comments. See [`.preflight/README.md`](.preflight/README.md).
+
 ### `.preflight/config.yml`
 
 Drop this in your project root. Every field is optional — defaults are sensible.