add .preflight.example/ config templates

.preflight.example/README.md

@@ -0,0 +1,36 @@
+# `.preflight/` Example Config
+
+Copy this directory into your project root as `.preflight/`:
+
+```bash
+cp -r .preflight.example /path/to/your/project/.preflight
+```
+
+Then customize for your project:
+
+1. **`config.yml`** — Set your profile, related projects, and thresholds
+2. **`triage.yml`** — Add domain-specific keywords that control how prompts are classified
+3. **`contracts/*.yml`** — Define key types/interfaces preflight should know about
+
+All files are optional. Preflight uses sensible defaults for anything you don't configure.
+
+## Quick Setup
+
+Most projects only need `config.yml` with related projects:
+
+```yaml
+# .preflight/config.yml
+profile: standard
+related_projects:
+  - path: /path/to/your/api
+    alias: api
+  - path: /path/to/your/shared-types
+    alias: types
+```
+
+## Tips
+
+- **Commit `.preflight/`** to your repo so your whole team benefits
+- **Add to `triage.yml`** when you notice preflight missing domain-specific ambiguity
+- **Add contracts** for types that span multiple services — this is where cross-service checks shine
+- **Start with `standard`** strictness and adjust based on your team's experience level

.preflight.example/config.yml

@@ -0,0 +1,36 @@
+# .preflight/config.yml — copy this directory to .preflight/ in your project root
+#
+# This configures preflight's behavior for your project.
+# Every field is optional — defaults are sensible.
+# Commit this to your repo so your whole team gets the same experience.
+
+# Profile controls overall verbosity
+# "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' session history and contracts
+# when it detects cross-service prompts (e.g. "update the auth flow")
+related_projects:
+  # - path: /absolute/path/to/auth-service
+  #   alias: auth-service
+  # - path: /absolute/path/to/shared-types
+  #   alias: shared-types
+
+# Behavioral thresholds
+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 logged corrections before a pattern is formed
+  correction_pattern_threshold: 3
+
+# Embedding configuration for semantic search
+embeddings:
+  # "local" uses Xenova transformers (no API key needed, runs on CPU)
+  # "openai" uses OpenAI's embedding API (faster, needs key)
+  provider: local
+  # openai_api_key: sk-...  # only needed if provider is "openai"

.preflight.example/contracts/api.yml

@@ -0,0 +1,39 @@
+# .preflight/contracts/api.yml — manual contract definitions
+#
+# Define your project's key types and interfaces here.
+# These supplement auto-extracted contracts from your codebase.
+# Manual definitions win on name conflicts with auto-extracted ones.
+#
+# Why? Auto-extraction may miss domain-specific semantics.
+# Manual contracts let you annotate what matters to your team.
+
+- name: User
+  kind: interface
+  description: Core user object returned by auth endpoints
+  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: ApiResponse
+#   kind: interface
+#   description: Standard API response wrapper
+#   fields:
+#     - name: data
+#       type: T
+#       required: true
+#     - name: error
+#       type: string | null
+#       required: false
+#     - name: meta
+#       type: "{ page: number, total: number }"
+#       required: false

.preflight.example/triage.yml

@@ -0,0 +1,44 @@
+# .preflight/triage.yml — controls the triage classification engine
+#
+# Customize how preflight classifies your prompts.
+# This is where you teach preflight about YOUR project's domain.
+
+rules:
+  # Prompts containing these words are ALWAYS flagged as ambiguous.
+  # Add domain-specific terms that tend to produce vague prompts.
+  # Example: "fix rewards" is too vague — which rewards? what's broken?
+  always_check:
+    - rewards
+    - permissions
+    - migration
+    - schema
+    # Add your own:
+    # - billing
+    # - onboarding
+
+  # Prompts containing these words pass through as TRIVIAL.
+  # These are safe, well-understood commands that don't need checks.
+  skip:
+    - commit
+    - format
+    - lint
+    # Add your own:
+    # - typecheck
+    # - prettier
+
+  # Prompts containing these words trigger CROSS-SERVICE checks.
+  # Preflight will search related projects for relevant contracts.
+  cross_service_keywords:
+    - auth
+    - notification
+    - event
+    - webhook
+    # Add your own:
+    # - payment
+    # - analytics
+
+# How aggressively to classify
+# "relaxed" — more prompts pass as clear (experienced users)
+# "standard" — balanced (recommended)
+# "strict" — more prompts flagged as ambiguous (new team members, complex projects)
+strictness: standard

README.md

@@ -406,6 +406,8 @@ This prevents the common failure mode: changing a shared type in one service and
 
 ## Configuration Reference
 
+> **Quick start:** Copy the [`.preflight.example/`](.preflight.example/) directory into your project as `.preflight/` and customize. All files are optional.
+
 ### `.preflight/config.yml`
 
 Drop this in your project root. Every field is optional — defaults are sensible.