Add examples/.preflight/ starter config directory

The README references examples/.preflight/ but it didn't exist.
Adds well-commented starter configs:
- config.yml — profile, related projects, thresholds, embeddings
- triage.yml — triage rules with domain-specific keyword examples
- contracts/api.yml — sample manual contract definitions
- README.md — quick setup guide

Author: TerminalGravity

examples/.preflight/README.md

@@ -0,0 +1,31 @@
+# `.preflight/` Config Directory
+
+Drop this directory into your project root to configure preflight for your team.
+
+## Quick Setup
+
+```bash
+# From the preflight repo:
+cp -r examples/.preflight /path/to/your/project/
+
+# Or from your project:
+cp -r /path/to/preflight/examples/.preflight .
+```
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `config.yml` | Main config — profile, related projects, thresholds, embeddings |
+| `triage.yml` | Triage rules — which prompts to check, skip, or flag as cross-service |
+| `contracts/*.yml` | Manual contract definitions — types, interfaces, routes |
+
+## What to customize first
+
+1. **`config.yml`** — Add your `related_projects` if you work across multiple repos
+2. **`triage.yml`** — Add domain-specific keywords to `always_check` (your project's tricky terms)
+3. **`contracts/`** — Define shared types that preflight should know about
+
+## Commit it
+
+These files are meant to be committed to your repo so the whole team shares the same preflight config. No secrets in here — API keys go in env vars.

examples/.preflight/config.yml

@@ -1,35 +1,49 @@
 # .preflight/config.yml — Drop this in your project root
+# Every field is optional. Defaults are sensible — only override what you need.
 #
-# This is an example config for a typical Next.js + microservices setup.
-# Every field is optional — preflight works with sensible defaults out of the box.
-# Commit this to your repo so the whole team gets the same preflight behavior.
+# Copy this entire .preflight/ directory into your project:
+#   cp -r examples/.preflight /path/to/your/project/
 
-# Profile controls how much detail preflight returns.
-#   "minimal"  — only flags ambiguous+ prompts, skips clarification detail
-#   "standard" — balanced (default)
-#   "full"     — maximum detail on every non-trivial prompt
+# ──────────────────────────────────────────────────────────
+# Profile: controls how verbose preflight's feedback is
+# ──────────────────────────────────────────────────────────
+# "minimal"  — only flags ambiguous+ prompts, skips detail
+# "standard" — balanced (default)
+# "full"     — maximum detail on every non-trivial prompt
 profile: standard
 
-# Related projects for cross-service awareness.
-# Preflight will search these for shared types, routes, and contracts
-# so it can warn you when a change might break a consumer.
-related_projects:
-  - path: /Users/you/code/auth-service
-    alias: auth
-  - path: /Users/you/code/billing-api
-    alias: billing
-  - path: /Users/you/code/shared-types
-    alias: types
+# ──────────────────────────────────────────────────────────
+# Related projects for cross-service awareness
+# ──────────────────────────────────────────────────────────
+# When you reference code that lives in another repo (e.g. a shared auth
+# service), preflight can search that project's types, routes, and schemas
+# to give you relevant context automatically.
+#
+# related_projects:
+#   - path: /Users/you/code/auth-service
+#     alias: auth
+#   - path: /Users/you/code/shared-types
+#     alias: types
 
-# Behavioral thresholds — tune these to your workflow
+# ──────────────────────────────────────────────────────────
+# Behavioral thresholds
+# ──────────────────────────────────────────────────────────
 thresholds:
-  session_stale_minutes: 30                # Warn if no activity for this long
-  max_tool_calls_before_checkpoint: 100    # Suggest a checkpoint after N tool calls
-  correction_pattern_threshold: 3          # Min corrections before flagging a pattern
+  # 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 correction count before preflight detects a pattern
+  # (e.g. "you've corrected JWT handling 3 times — adding a reminder")
+  correction_pattern_threshold: 3
 
-# Embedding provider for semantic search over session history.
-# "local" uses Xenova transformers (no API key needed, runs on CPU).
-# "openai" uses text-embedding-3-small (faster, needs OPENAI_API_KEY).
+# ──────────────────────────────────────────────────────────
+# Embedding configuration (for semantic search over session history)
+# ──────────────────────────────────────────────────────────
+# "local" uses Xenova transformers — no API key needed, runs on-device.
+# "openai" uses OpenAI embeddings — better quality, requires API key.
 embeddings:
   provider: local
-  # openai_api_key: sk-...               # Uncomment if using openai provider
+  # openai_api_key: sk-...  # Uncomment if using openai provider

examples/.preflight/contracts/api.yml

@@ -1,58 +1,58 @@
 # .preflight/contracts/api.yml — Manual contract definitions
 #
-# Define shared types and interfaces that preflight should know about.
 # These supplement auto-extracted contracts from your codebase.
-# Manual definitions win on name conflicts with auto-extracted ones.
+# Use them for:
+#   - API contracts that aren't easily auto-detected
+#   - Shared types across services that need explicit documentation
+#   - Domain models that drive business logic
 #
-# Why manual contracts?
-#   - Document cross-service interfaces that live in docs, not code
-#   - Define contracts for external APIs your services consume
-#   - Pin down types that are implicit (e.g., event payloads)
+# Manual definitions win on name conflicts with auto-extracted ones.
 
 - name: User
   kind: interface
-  description: Core user model shared across all services
+  description: Core user model — referenced across auth, billing, and API layers
   fields:
     - name: id
       type: string
       required: true
     - name: email
       type: string
       required: true
-    - name: tier
-      type: "'free' | 'pro' | 'enterprise'"
+    - name: role
+      type: "'admin' | 'member' | 'viewer'"
       required: true
     - name: createdAt
       type: Date
       required: true
 
-- name: AuthToken
-  kind: interface
-  description: JWT payload structure from auth-service
-  fields:
-    - name: userId
-      type: string
-      required: true
-    - name: permissions
-      type: string[]
-      required: true
-    - name: expiresAt
-      type: number
-      required: true
-
-- name: WebhookPayload
+- name: ApiResponse
   kind: interface
-  description: Standard webhook envelope for inter-service events
+  description: Standard API response wrapper used by all endpoints
   fields:
-    - name: event
-      type: string
-      required: true
-    - name: timestamp
-      type: string
+    - name: success
+      type: boolean
       required: true
     - name: data
-      type: Record<string, unknown>
-      required: true
-    - name: source
-      type: string
-      required: true
+      type: T
+      required: false
+    - name: error
+      type: "{ code: string; message: string }"
+      required: false
+
+# Add your own contracts below. Examples:
+#
+# - name: OrderStatus
+#   kind: enum
+#   description: Order lifecycle states
+#   values: [pending, confirmed, shipped, delivered, cancelled]
+#
+# - name: POST /api/webhooks
+#   kind: route
+#   description: Incoming webhook handler
+#   fields:
+#     - name: event
+#       type: string
+#       required: true
+#     - name: payload
+#       type: Record<string, unknown>
+#       required: true

examples/.preflight/triage.yml

@@ -1,45 +1,50 @@
-# .preflight/triage.yml — Controls how preflight classifies your prompts
+# .preflight/triage.yml — Controls the prompt triage engine
 #
-# The triage engine routes prompts into categories:
+# Triage classifies every prompt into one of four categories:
 #   TRIVIAL       → pass through (commit, format, lint)
 #   CLEAR         → well-specified, no intervention needed
 #   AMBIGUOUS     → needs clarification before proceeding
-#   MULTI-STEP    → complex task, preflight suggests a plan
-#   CROSS-SERVICE → touches multiple projects, pulls in contracts
+#   CROSS-SERVICE → touches multiple projects, needs contract context
 #
-# Customize the keywords below to match your domain.
+# Customize the keywords below to match YOUR project's domain.
 
 rules:
-  # Prompts containing these words are always flagged as AMBIGUOUS.
-  # Add domain-specific terms that tend to produce vague prompts.
+  # ── Always check ──────────────────────────────────────
+  # Prompts containing these words are always flagged as AMBIGUOUS
+  # (at minimum) so preflight asks for clarification.
+  # Add your project's tricky/overloaded terms here.
   always_check:
     - rewards
     - permissions
     - migration
     - schema
-    - pricing          # example: your billing domain
-    - onboarding       # example: multi-step user flows
+    # - billing        # Uncomment for fintech projects
+    # - deployment     # Uncomment if deploys are complex
 
-  # Prompts containing these words skip checks entirely (TRIVIAL).
-  # These are safe, mechanical tasks that don't need guardrails.
+  # ── Skip (trivial) ───────────────────────────────────
+  # Prompts matching these pass through without intervention.
+  # These are low-risk, well-understood commands.
   skip:
     - commit
     - format
     - lint
-    - prettier
-    - "git push"
+    - "git status"
+    - "run tests"
 
-  # Prompts containing these words trigger CROSS-SERVICE classification.
-  # Preflight will search related_projects for relevant types and routes.
+  # ── Cross-service keywords ───────────────────────────
+  # Prompts containing these trigger cross-project search,
+  # pulling in types/routes/schemas from related_projects.
   cross_service_keywords:
     - auth
     - notification
     - event
     - webhook
-    - billing          # matches the related_project alias
+    # - payment       # Uncomment if payments are a separate service
+    # - queue         # Uncomment for message queue integrations
 
-# How aggressively to classify prompts.
-#   "relaxed"  — more prompts pass as clear (experienced users)
+# ── Strictness ────────────────────────────────────────
+# How aggressively to classify prompts:
+#   "relaxed"  — more prompts pass as clear (fewer interruptions)
 #   "standard" — balanced (default)
-#   "strict"   — more prompts flagged as ambiguous (new teams, complex codebases)
+#   "strict"   — more prompts flagged as ambiguous (safer, more verbose)
 strictness: standard