preflight-dev 3.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jack Felke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+<div align="center">
+
+# ✈️ preflight
+
+**Preflight checks for your AI coding prompts.**
+
+An 18-tool MCP server for Claude Code that catches ambiguous instructions before they cost you 2-3x in wrong→fix cycles — plus semantic search across your entire session history.
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![MCP](https://img.shields.io/badge/MCP-Compatible-blueviolet)](https://modelcontextprotocol.io/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+</div>
+
+---
+
+## The Problem
+
+We built this after analyzing **9 months of real Claude Code usage** — 512 sessions, 32,000+ events, 3,200+ prompts, 1,642 commits, and 258 sub-agent spawns across a production Next.js/Prisma/Supabase app. The findings were brutal:
+
+- **41% of prompts were under 50 characters** — things like `fix the tests`, `commit this`, `remove them`
+- Each vague prompt triggers a **wrong→fix cycle costing 2-3x tokens**
+- **~33K characters/day** duplicated from repeated context pastes
+- **124 corrections logged** — places where Claude went the wrong direction and had to be steered back
+- **94 context compactions** from unbounded session scope blowing past the context window
+- Estimated **30-40% of tokens wasted** on avoidable back-and-forth
+
+The pattern is always the same: vague prompt → Claude guesses → wrong output → you correct → repeat. That's your money evaporating.
+
+## The Solution
+
+18 tools in 3 categories that run as an MCP server inside Claude Code:
+
+| Category | What it does |
+|----------|-------------|
+| 🎯 **Prompt Discipline** (12 tools) | Catches vague prompts, enforces structure, prevents waste |
+| 🔍 **Timeline Intelligence** (4 tools) | LanceDB vector search across months of session history |
+| ✅ **Verification & Hygiene** (2 tools) | Type-check, test, and audit before declaring done |
+
+## Before / After
+
+```
+❌  "fix the auth bug"
+     → Claude guesses which auth bug, edits wrong file
+     → You correct it, 3 more rounds
+     → 12,000 tokens burned
+
+✅  preflight intercepts → clarify_intent fires
+     → "Which auth bug? I see 3 open issues:
+        1. JWT expiry not refreshing (src/auth/jwt.ts)
+        2. OAuth callback 404 (src/auth/oauth.ts)  
+        3. Session cookie SameSite (src/middleware/session.ts)
+        Pick one and I'll scope the fix."
+     → 4,000 tokens, done right the first time
+```
+
+## Quick Start
+
+**1. Clone & install:**
+```bash
+git clone https://github.com/TerminalGravity/preflight.git
+cd preflight && npm install
+```
+
+**2. Add to your Claude Code config** (`.claude/settings.json` or project `.mcp.json`):
+```json
+{
+  "mcpServers": {
+    "preflight": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/preflight/src/index.ts"],
+      "cwd": "/path/to/preflight",
+      "env": {
+        "CLAUDE_PROJECT_DIR": "/path/to/your/project"
+      }
+    }
+  }
+}
+```
+
+**3. Restart Claude Code.** That's it. The tools activate automatically.
+
+## Tool Reference
+
+### 🎯 Prompt Discipline
+
+| Tool | What it does |
+|------|-------------|
+| `scope_work` | Creates structured execution plans before coding starts |
+| `clarify_intent` | Gathers project context to disambiguate vague prompts |
+| `enrich_agent_task` | Enriches sub-agent tasks with file paths and patterns |
+| `sharpen_followup` | Resolves "fix it" / "do the others" to actual file targets |
+| `token_audit` | Detects waste patterns, grades your session A–F |
+| `sequence_tasks` | Orders tasks by dependency, locality, and risk |
+| `checkpoint` | Save game before compaction — commits + resumption notes |
+| `check_session_health` | Monitors uncommitted files, time since commit, turn count |
+| `log_correction` | Tracks corrections and identifies recurring error patterns |
+| `session_handoff` | Generates handoff briefs for new sessions |
+| `what_changed` | Summarizes diffs since last checkpoint |
+
+### 🔍 Timeline Intelligence
+
+| Tool | What it does |
+|------|-------------|
+| `onboard_project` | Indexes a project's session history into LanceDB vectors |
+| `search_history` | Semantic search across all indexed sessions |
+| `timeline` | Chronological view of events across sessions |
+| `scan_sessions` | Live scanning of active session data |
+
+### ✅ Verification & Hygiene
+
+| Tool | What it does |
+|------|-------------|
+| `verify_completion` | Runs type check + tests + build before declaring done |
+| `audit_workspace` | Finds stale/missing workspace docs vs git activity |
+
+## Timeline Intelligence
+
+This is the feature that makes preflight more than a linter.
+
+When you run `onboard_project` for a specific project, the server finds that project's session history (JSONL files in `~/.claude/projects/<encoded-path>/`) and indexes its events into a local [LanceDB](https://lancedb.github.io/lancedb/) database with vector embeddings. Run it once per project you want to search — each project's data stays tagged so you can query across them or filter to one.
+
+**What that gives you:**
+- 🔎 **Semantic search** — "How did I set up the auth middleware last month?" actually works
+- 📊 **32K+ events** indexed across 9 months of real production sessions
+- 🧭 **Timeline view** — see what happened across sessions chronologically
+- 🔄 **Live scanning** — index new sessions as they happen
+
+No data leaves your machine. Embeddings run locally by default (Xenova/transformers.js) or via OpenAI if configured.
+
+## Architecture
+
+```
+Claude Code ←→ MCP Protocol ←→ preflight server
+                                      │
+                    ┌─────────────────┼─────────────────┐
+                    │                 │                  │
+              Discipline Tools   Timeline Tools    Verification
+              (12 tools)         (4 tools)         (2 tools)
+                                      │
+                                  LanceDB
+                                (local vectors)
+                                      │
+                              ~/.claude/projects/
+                            (session JSONL files)
+```
+
+## Configuration
+
+### Embedding Providers
+
+| Provider | Setup | Speed | Quality |
+|----------|-------|-------|---------|
+| **Local (Xenova)** | Zero config, default | ~50 events/sec | Good |
+| **OpenAI** | Set `OPENAI_API_KEY` env var | ~200 events/sec | Excellent |
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CLAUDE_PROJECT_DIR` | Project root to monitor | Required |
+| `OPENAI_API_KEY` | OpenAI key for embeddings | (uses local Xenova) |
+
+## Contributing
+
+This project is young and there's plenty to do. Check the [issues](https://github.com/TerminalGravity/preflight/issues) — several are tagged `good first issue`.
+
+PRs welcome. No CLA, no bureaucracy. If it makes the tool better, it gets merged.
+
+## License
+
+MIT — do whatever you want with it.

package/bin/cli.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// This is a shim that loads the compiled TypeScript CLI
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Load the compiled CLI
+const cliPath = join(__dirname, '../dist/cli/init.js');
+await import(cliPath);

package/dist/cli/init.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/init.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+// =============================================================================
+// preflight init — Zero-config MCP server setup for Claude Code
+// =============================================================================
+import { createInterface } from "node:readline";
+import { readFile, writeFile, mkdir, copyFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+const rl = createInterface({ input: process.stdin, output: process.stdout });
+function ask(question) {
+    return new Promise((resolve) => rl.question(question, resolve));
+}
+/** Create .preflight/ directory with template files */
+async function createPreflightConfig() {
+    const preflightDir = join(process.cwd(), ".preflight");
+    if (existsSync(preflightDir)) {
+        console.log("⚠️  .preflight/ directory already exists, skipping...\n");
+        return;
+    }
+    try {
+        await mkdir(preflightDir, { recursive: true });
+        // Get the current module's directory to find templates
+        const currentFile = fileURLToPath(import.meta.url);
+        const srcDir = dirname(dirname(currentFile)); // Go up from cli/ to src/
+        const templatesDir = join(srcDir, "templates");
+        // Copy template files
+        await copyFile(join(templatesDir, "config.yml"), join(preflightDir, "config.yml"));
+        await copyFile(join(templatesDir, "triage.yml"), join(preflightDir, "triage.yml"));
+        console.log("✅ Created .preflight/ directory with template config files");
+        console.log("   Edit .preflight/config.yml to configure your project settings");
+        console.log("   Edit .preflight/triage.yml to customize prompt triage rules\n");
+    }
+    catch (error) {
+        console.error(`❌ Failed to create .preflight/ directory: ${error}\n`);
+    }
+}
+async function main() {
+    console.log("\n✈️ preflight — MCP server setup\n");
+    const mcpPath = join(process.cwd(), ".mcp.json");
+    let config;
+    try {
+        const existing = await readFile(mcpPath, "utf-8");
+        config = JSON.parse(existing);
+        if (!config.mcpServers)
+            config.mcpServers = {};
+        console.log("Found existing .mcp.json\n");
+    }
+    catch {
+        config = { mcpServers: {} };
+        console.log("Creating new .mcp.json\n");
+    }
+    console.log("Choose a profile:\n");
+    console.log("  1) minimal  — 4 tools: clarify_intent, check_session_health, session_stats, prompt_score");
+    console.log("  2) standard — 16 tools: all prompt discipline + session_stats + prompt_score");
+    console.log("  3) full     — 20 tools: everything + timeline/vector search (needs LanceDB)\n");
+    const choice = await ask("Profile [1/2/3] (default: 2): ");
+    const profileMap = { "1": "minimal", "2": "standard", "3": "full" };
+    const profile = profileMap[choice.trim()] || "standard";
+    // Ask about creating .preflight/ directory
+    console.log("\nPreflight can use either environment variables or a .preflight/ directory for configuration.");
+    console.log("The .preflight/ directory allows you to configure related projects, custom triage rules, and thresholds.\n");
+    const createConfig = await ask("Create .preflight/ directory with template config? [y/N]: ");
+    if (createConfig.trim().toLowerCase() === "y" || createConfig.trim().toLowerCase() === "yes") {
+        await createPreflightConfig();
+    }
+    const env = {
+        PROMPT_DISCIPLINE_PROFILE: profile,
+    };
+    if (profile === "full") {
+        console.log("\nFull profile uses embeddings for vector search.");
+        const provider = await ask("Embedding provider [local/openai] (default: local): ");
+        if (provider.trim().toLowerCase() === "openai") {
+            const key = await ask("OpenAI API key (or set OPENAI_API_KEY later): ");
+            if (key.trim()) {
+                env.OPENAI_API_KEY = key.trim();
+            }
+            env.EMBEDDING_PROVIDER = "openai";
+        }
+        else {
+            env.EMBEDDING_PROVIDER = "local";
+        }
+    }
+    config.mcpServers["preflight"] = {
+        command: "npx",
+        args: ["-y", "preflight-dev@latest"],
+        env,
+    };
+    // For the actual server entry point, we need to point to index.ts via tsx
+    // But npx will resolve the bin entry which is the init script
+    // So use a different approach: command runs the server
+    config.mcpServers["preflight"] = {
+        command: "npx",
+        args: ["-y", "tsx", "node_modules/preflight/src/index.ts"],
+        env,
+    };
+    await writeFile(mcpPath, JSON.stringify(config, null, 2) + "\n");
+    // Offer to create .preflight/ config directory
+    const preflightDir = join(process.cwd(), ".preflight");
+    if (!existsSync(preflightDir)) {
+        const createConfig = await ask("\nCreate .preflight/ config directory with template files? [y/N]: ");
+        if (createConfig.trim().toLowerCase() === "y") {
+            await mkdir(preflightDir, { recursive: true });
+            const configYml = `# Preflight configuration
+profile: ${profile}
+
+related_projects: []
+# - path: /path/to/related/project
+#   alias: project-name
+
+thresholds:
+  session_stale_minutes: 30
+  max_tool_calls_before_checkpoint: 100
+  correction_pattern_threshold: 3
+
+embeddings:
+  provider: local
+`;
+            const triageYml = `# Triage rules for prompt classification
+rules:
+  always_check:
+    - rewards
+    - permissions
+    - migration
+    - schema
+  skip:
+    - commit
+    - format
+    - lint
+  cross_service_keywords:
+    - auth
+    - notification
+    - event
+    - webhook
+
+strictness: standard
+`;
+            await writeFile(join(preflightDir, "config.yml"), configYml);
+            await writeFile(join(preflightDir, "triage.yml"), triageYml);
+            console.log("✅ Created .preflight/config.yml and .preflight/triage.yml");
+        }
+    }
+    else {
+        console.log("\n.preflight/ directory already exists — skipping.");
+    }
+    console.log(`\n✅ preflight added! (profile: ${profile})`);
+    console.log("Restart Claude Code to connect.\n");
+    rl.close();
+}
+main().catch((err) => {
+    console.error("Error:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=init.js.map

package/dist/cli/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// =============================================================================
+// Preflight-Dev MCP Server — v3.0
+// =============================================================================
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { isToolEnabled, getProfile } from "./profiles.js";
+import { getConfig, hasPreflightConfig } from "./lib/config.js";
+import { existsSync } from "fs";
+// Main entry point
+import { registerPreflightCheck } from "./tools/preflight-check.js";
+// Category 1: Plans
+import { registerScopeWork } from "./tools/scope-work.js";
+// Category 2: Clarification
+import { registerClarifyIntent } from "./tools/clarify-intent.js";
+// Category 3: Delegation
+import { registerEnrichAgentTask } from "./tools/enrich-agent-task.js";
+// Category 4: Follow-up Specificity
+import { registerSharpenFollowup } from "./tools/sharpen-followup.js";
+// Category 5: Token Efficiency
+import { registerTokenAudit } from "./tools/token-audit.js";
+// Category 6: Sequencing
+import { registerSequenceTasks } from "./tools/sequence-tasks.js";
+// Category 7: Compaction Management
+import { registerCheckpoint } from "./tools/checkpoint.js";
+// Category 8: Session Lifecycle
+import { registerSessionHealth } from "./tools/session-health.js";
+// Category 9: Error Recovery
+import { registerLogCorrection } from "./tools/log-correction.js";
+// Category 10: Workspace Hygiene
+import { registerAuditWorkspace } from "./tools/audit-workspace.js";
+// Category 11: Cross-Session Continuity
+import { registerSessionHandoff } from "./tools/session-handoff.js";
+import { registerWhatChanged } from "./tools/what-changed.js";
+// Category 12: Verification
+import { registerVerifyCompletion } from "./tools/verify-completion.js";
+// New lightweight tools
+import { registerSessionStats } from "./tools/session-stats.js";
+import { registerPromptScore } from "./tools/prompt-score.js";
+// Timeline: Project Intelligence
+import { registerOnboardProject } from "./tools/onboard-project.js";
+import { registerSearchHistory } from "./tools/search-history.js";
+import { registerTimeline } from "./tools/timeline-view.js";
+import { registerScanSessions } from "./tools/scan-sessions.js";
+import { registerGenerateScorecard } from "./tools/generate-scorecard.js";
+// Validate related projects from config
+function validateRelatedProjects() {
+    const config = getConfig();
+    const projects = config.related_projects;
+    if (projects.length === 0)
+        return;
+    const invalid = [];
+    for (const project of projects) {
+        if (!existsSync(project.path)) {
+            invalid.push(`${project.alias} (${project.path})`);
+        }
+    }
+    if (invalid.length > 0) {
+        process.stderr.write(`preflight-dev: warning - related projects contain invalid paths: ${invalid.join(", ")}\n`);
+    }
+    else {
+        process.stderr.write(`preflight-dev: related projects: ${projects.length} configured\n`);
+    }
+}
+// Load config and validate related projects on startup
+const config = getConfig();
+validateRelatedProjects();
+const profile = getProfile();
+const server = new McpServer({
+    name: "preflight",
+    version: "3.0.0",
+});
+const toolRegistry = [
+    ["preflight_check", registerPreflightCheck],
+    ["scope_work", registerScopeWork],
+    ["clarify_intent", registerClarifyIntent],
+    ["enrich_agent_task", registerEnrichAgentTask],
+    ["sharpen_followup", registerSharpenFollowup],
+    ["token_audit", registerTokenAudit],
+    ["sequence_tasks", registerSequenceTasks],
+    ["checkpoint", registerCheckpoint],
+    ["check_session_health", registerSessionHealth],
+    ["log_correction", registerLogCorrection],
+    ["audit_workspace", registerAuditWorkspace],
+    ["session_handoff", registerSessionHandoff],
+    ["what_changed", registerWhatChanged],
+    ["verify_completion", registerVerifyCompletion],
+    ["session_stats", registerSessionStats],
+    ["prompt_score", registerPromptScore],
+    ["onboard_project", registerOnboardProject],
+    ["search_history", registerSearchHistory],
+    ["timeline_view", registerTimeline],
+    ["scan_sessions", registerScanSessions],
+    ["generate_scorecard", registerGenerateScorecard],
+];
+let registered = 0;
+for (const [name, register] of toolRegistry) {
+    if (isToolEnabled(name)) {
+        register(server);
+        registered++;
+    }
+}
+const configSource = hasPreflightConfig() ? ".preflight/" : "env vars";
+process.stderr.write(`preflight: profile=${profile}, tools=${registered}, config=${configSource}\n`);
+// Graceful shutdown
+function shutdown() {
+    process.stderr.write("preflight: shutting down\n");
+    process.exit(0);
+}
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+// Connect transport
+try {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write("preflight: server started\n");
+}
+catch (err) {
+    process.stderr.write(`preflight: failed to start — ${err}\n`);
+    process.exit(1);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/lib/config.d.ts

@@ -0,0 +1,34 @@
+export type Profile = "minimal" | "standard" | "full";
+export type EmbeddingProvider = "local" | "openai";
+export type TriageStrictness = "relaxed" | "standard" | "strict";
+export interface RelatedProject {
+    path: string;
+    alias: string;
+}
+export interface PreflightConfig {
+    profile: Profile;
+    related_projects: RelatedProject[];
+    thresholds: {
+        session_stale_minutes: number;
+        max_tool_calls_before_checkpoint: number;
+        correction_pattern_threshold: number;
+    };
+    embeddings: {
+        provider: EmbeddingProvider;
+        openai_api_key?: string;
+    };
+    triage: {
+        rules: {
+            always_check: string[];
+            skip: string[];
+            cross_service_keywords: string[];
+        };
+        strictness: TriageStrictness;
+    };
+}
+/** Get the singleton configuration object */
+export declare function getConfig(): PreflightConfig;
+/** Get related projects as simple path array (backward compatibility) */
+export declare function getRelatedProjects(): string[];
+/** Check if .preflight/ directory exists */
+export declare function hasPreflightConfig(): boolean;

package/dist/lib/config.js

@@ -0,0 +1,118 @@
+// =============================================================================
+// Preflight Configuration System
+// =============================================================================
+// Loads configuration from .preflight/ directory if present,
+// falls back to environment variables.
+// =============================================================================
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { load as yamlLoad } from "js-yaml";
+import { PROJECT_DIR } from "./files.js";
+// Default configuration (env var fallback)
+const DEFAULT_CONFIG = {
+    profile: "standard",
+    related_projects: [],
+    thresholds: {
+        session_stale_minutes: 30,
+        max_tool_calls_before_checkpoint: 100,
+        correction_pattern_threshold: 3,
+    },
+    embeddings: {
+        provider: "local",
+    },
+    triage: {
+        rules: {
+            always_check: ["rewards", "permissions", "migration", "schema"],
+            skip: ["commit", "format", "lint"],
+            cross_service_keywords: ["auth", "notification", "event", "webhook"],
+        },
+        strictness: "standard",
+    },
+};
+let _config = null;
+/** Load config from .preflight/ directory or fall back to env vars */
+function loadConfig() {
+    const preflightDir = join(PROJECT_DIR, ".preflight");
+    const configPath = join(preflightDir, "config.yml");
+    const triagePath = join(preflightDir, "triage.yml");
+    // Start with defaults
+    let config = JSON.parse(JSON.stringify(DEFAULT_CONFIG));
+    // Load .preflight/config.yml if it exists
+    if (existsSync(configPath)) {
+        try {
+            const configYaml = readFileSync(configPath, "utf-8");
+            const configData = yamlLoad(configYaml);
+            if (configData) {
+                // Merge config data with defaults
+                if (configData.profile)
+                    config.profile = configData.profile;
+                if (configData.related_projects)
+                    config.related_projects = configData.related_projects;
+                if (configData.thresholds)
+                    config.thresholds = { ...config.thresholds, ...configData.thresholds };
+                if (configData.embeddings)
+                    config.embeddings = { ...config.embeddings, ...configData.embeddings };
+            }
+        }
+        catch (error) {
+            console.warn(`preflight: warning - failed to parse .preflight/config.yml: ${error}`);
+        }
+    }
+    // Load .preflight/triage.yml if it exists
+    if (existsSync(triagePath)) {
+        try {
+            const triageYaml = readFileSync(triagePath, "utf-8");
+            const triageData = yamlLoad(triageYaml);
+            if (triageData) {
+                if (triageData.rules)
+                    config.triage.rules = { ...config.triage.rules, ...triageData.rules };
+                if (triageData.strictness)
+                    config.triage.strictness = triageData.strictness;
+            }
+        }
+        catch (error) {
+            console.warn(`preflight: warning - failed to parse .preflight/triage.yml: ${error}`);
+        }
+    }
+    // Apply environment variable overrides (env vars are fallback, .preflight/ takes precedence)
+    // Only use env vars if .preflight/ directory doesn't exist
+    if (!existsSync(preflightDir)) {
+        // Profile
+        const envProfile = process.env.PROMPT_DISCIPLINE_PROFILE?.toLowerCase();
+        if (envProfile === "minimal" || envProfile === "standard" || envProfile === "full") {
+            config.profile = envProfile;
+        }
+        // Related projects
+        const envRelated = process.env.PREFLIGHT_RELATED;
+        if (envRelated) {
+            const projects = envRelated.split(",").map(p => p.trim()).filter(Boolean);
+            config.related_projects = projects.map(path => ({ path, alias: path.split("/").pop() || path }));
+        }
+        // Embedding provider
+        const envProvider = process.env.EMBEDDING_PROVIDER?.toLowerCase();
+        if (envProvider === "local" || envProvider === "openai") {
+            config.embeddings.provider = envProvider;
+        }
+        // OpenAI API key
+        if (process.env.OPENAI_API_KEY) {
+            config.embeddings.openai_api_key = process.env.OPENAI_API_KEY;
+        }
+    }
+    return config;
+}
+/** Get the singleton configuration object */
+export function getConfig() {
+    if (_config === null) {
+        _config = loadConfig();
+    }
+    return _config;
+}
+/** Get related projects as simple path array (backward compatibility) */
+export function getRelatedProjects() {
+    return getConfig().related_projects.map(p => p.path);
+}
+/** Check if .preflight/ directory exists */
+export function hasPreflightConfig() {
+    return existsSync(join(PROJECT_DIR, ".preflight"));
+}
+//# sourceMappingURL=config.js.map