### Install and Run Drift CLI

Source: https://github.com/dadbodgeoff/drift/wiki/Getting-Started

Installs the Drift CLI globally using npm and runs the guided setup wizard for your project. The setup wizard helps initialize Drift, scan for patterns, and optionally build call graphs and set up test topology.

```bash
# Install globally
න්ද install -g driftdetect

# Run the guided setup wizard
cd your-project
drift setup

# See what Drift discovered
drift status

# Quick setup (skip prompts):
drift setup -y
```

--------------------------------

### Initialize Drift Project

Source: https://github.com/dadbodgeoff/drift/wiki/Getting-Started

Initializes a Drift project using either a guided setup wizard or manual commands. Manual setup involves running `drift init`, `drift scan`, and `drift approve --auto`, which creates a `.drift/` directory structure.

```bash
# Option A: Guided Setup (Recommended)
cd your-project
drift setup

# Option B: Manual Setup
cd your-project
drift init
drift scan
drift approve --auto  # Auto-approve high-confidence patterns
```

--------------------------------

### Install Drift CLI Options

Source: https://github.com/dadbodgeoff/drift/wiki/Getting-Started

Provides different methods for installing the Drift CLI tool and MCP server. Options include global installation, project-local installation as dev dependencies, and installation from source for development.

```bash
# Option 1: Global Install (Recommended)
න්ද install -g driftdetect
න්ද install -g driftdetect-mcp

# Verify installation
drift --version

# Option 2: Project-Local Install
න්ද install --save-dev driftdetect driftdetect-mcp

# Run via npx
npx drift --version

# Option 3: From Source (Development)
git clone https://github.com/dadbodgeoff/drift.git
cd drift
pnpm install
pnpm build

# Run locally
න්ද packages/cli/dist/bin/drift.js --version
```

--------------------------------

### Install Drift CLI and Scan Project

Source: https://github.com/dadbodgeoff/drift/wiki/Home

This quick start guide shows how to install the Drift CLI using npm and then initialize and scan a project. After installation, navigate to your project directory, run `drift init` to set up Drift for the project, and `drift scan` to analyze the codebase.

```bash
# Install
npm install -g driftdetect

# Scan your project
cd your-project
drift init
drift scan

# See what Drift found
drift status
```

--------------------------------

### Initialize Drift Memory System Setup Wizard

Source: https://github.com/dadbodgeoff/drift/wiki/Getting-Started

Command to launch the interactive setup wizard for initializing the Cortex memory system. The wizard guides users through optional sections like Core Identity, Tribal Knowledge, Workflows, Agent Spawns, Entities, Skills, and Environments.

```bash
# Run the setup wizard (recommended)
drift memory setup
```

--------------------------------

### Drift CLI Configuration File Example

Source: https://github.com/dadbodgeoff/drift/wiki/Getting-Started

An example of the `.drift/config.json` file used to customize Drift's behavior. It includes settings for project identification, ignored files, learning parameters like auto-approval thresholds, and feature flags for analysis capabilities.

```json
{
  "version": "2.0.0",
  "project": {
    "id": "uuid-here",
    "name": "my-project"
  },
  "ignore": [
    "node_modules/**",
    "dist/**",
    "build/**",
    "**/*.test.ts"
  ],
  "learning": {
    "autoApproveThreshold": 0.95,
    "minOccurrences": 3
  },
  "features": {
    "callGraph": true,
    "boundaries": true,
    "contracts": true,
    "testTopology": true
  }
}
```

--------------------------------

### Best Practices

Source: https://github.com/dadbodgeoff/drift/wiki/MCP-Setup

Recommended practices for using Drift effectively.

```APIDOC
## Best Practices

1. **Scan Regularly**: Run `drift scan` after significant code changes.
2. **Approve Patterns**: Approve patterns for improved recommendations.
3. **Use `drift_context`**: Start most tasks with this tool.
4. **Build Analysis Data**: Execute build commands for comprehensive analysis.
5. **Register All Projects**: Ensure all projects are registered for better monorepo support.
```

--------------------------------

### Setup Wizard Pipeline (`drift setup`)

Source: https://github.com/dadbodgeoff/drift/blob/main/drift v2/docs/v2-research/00-overview/pipelines.md

Guides users through the initial setup of a project with Cortex. It orchestrates a sequence of operations including checking prerequisites, initializing project structure and configuration, scanning for patterns, running core and deep analysis features, setting up the memory system, and finalizing the project baseline.

```text
User runs: drift setup [-y] [--resume]

Phase 1: PREREQUISITES
  Check if .drift/ exists, count existing patterns
  Decide: fresh setup or incremental

Phase 2: INIT
  Create .drift/ with 30+ subdirectories
  Generate config.json with project UUID
  Register in global registry (~/.drift/registry.json)

Phase 3: SCAN + APPROVAL
  Run full scan (Pipeline 1)
  Interactive batch approval of high-confidence patterns (≥85%)
  In -y mode: auto-approve above threshold

Phase 4: CORE FEATURES
  Run: boundaries, contracts, environment, constants
  Each is a modular runner (prompted individually or all-enabled with -y)

Phase 5: DEEP ANALYSIS
  Run: callgraph, test-topology, coupling, DNA, error-handling
  Heavier operations, each prompted individually

Phase 6: DERIVED FEATURES
  Run: constraints, audit
  Depend on data from phases 4-5

Phase 7: MEMORY
  Initialize Cortex memory system
  Create cortex.db with schema

Phase 8: FINALIZE
  Sync all data to SQLite (if using hybrid storage)
  Generate source-of-truth.json with baseline checksums
  Print summary with stats and next steps

Resume: SetupState persisted to disk, --resume picks up from last completed phase.
```

--------------------------------

### Install and Configure MCP Server for AI Agents

Source: https://github.com/dadbodgeoff/drift/wiki/Getting-Started

Instructions for installing the driftdetect-mcp server globally using npm and configuring AI tools to connect to it. The configuration involves adding an 'mcpServers' entry with the 'drift' key pointing to the 'driftdetect-mcp' command.

```bash
# Install MCP server globally
npm install -g driftdetect-mcp
```

```json
{
  "mcpServers": {
    "drift": {
      "command": "driftdetect-mcp"
    }
  }
}
```

--------------------------------

### Docker Deployment

Source: https://github.com/dadbodgeoff/drift/wiki/MCP-Setup

Instructions for deploying Drift as a containerized HTTP service.

```APIDOC
## Docker Deployment

### Description
Deploy Drift as a containerized HTTP service.

### Steps
1. Clone the repository: `git clone https://github.com/dadbodgeoff/drift.git`
2. Navigate to the directory: `cd drift`
3. Start the service with your project mounted:
   ```bash
   PROJECT_PATH=/path/to/your/project docker compose up -d
   ```
4. Check the service health: `curl http://localhost:3000/health`

### MCP Client Configuration
Configure your MCP client to connect via HTTP/SSE:
- **SSE endpoint**: `http://localhost:3000/sse`
- **Message endpoint**: `http://localhost:3000/message`
```

--------------------------------

### Run MCP Server with Command-Line Options

Source: https://github.com/dadbodgeoff/drift/wiki/MCP-Setup

Examples of running the `driftdetect-mcp` command with different options. These include using the active project, specifying a project path, disabling cache, and enabling verbose logging.

```bash
driftdetect-mcp                    # Use active project
driftdetect-mcp /path/to/project   # Analyze specific project
driftdetect-mcp --no-cache         # Disable response caching
driftdetect-mcp --verbose          # Enable verbose logging
```

--------------------------------

### Project Management CLI

Source: https://github.com/dadbodgeoff/drift/wiki/MCP-Setup

Commands for registering, listing, and switching between projects.

```APIDOC
## Project Management CLI

### Description
Commands for managing registered projects within the Drift tool.

### Register Project

- **Method**: CLI Command
- **Endpoint**: `drift projects add <path>`
- **Description**: Registers a new project at the specified path.

### List Registered Projects

- **Method**: CLI Command
- **Endpoint**: `drift projects list`
- **Description**: Lists all currently registered projects.

### Switch Active Project

- **Method**: CLI Command
- **Endpoint**: `drift projects switch <project-name>`
- **Description**: Sets the specified project as the active project for subsequent operations.
```

--------------------------------

### Project Start-up Guide

Source: https://github.com/dadbodgeoff/drift/blob/main/drift v2/docs/v2-research/PHASE-6-AGENT-PROMPT.md

Instructions on how to begin working with the drift project, including reading relevant documentation, understanding system dependencies, and the recommended order for implementing and testing different components.

```Markdown
1. Read `docs/v2-research/DRIFT-V2-IMPLEMENTATION-TASKS.md` — Phase 6 section (tasks P6-RUL-01 through P6-NAPI-02, tests T6-RUL-01 through T6-INT-09)
2. Read the three V2-PREP documents listed above for behavioral details and type contracts:
   - `docs/v2-research/systems/09-QUALITY-GATES-V2-PREP.md`
   - `docs/v2-research/systems/25-AUDIT-SYSTEM-V2-PREP.md`
   - `docs/v2-research/systems/31-VIOLATION-FEEDBACK-LOOP-V2-PREP.md`
3. Read `docs/v2-research/DRIFT-V2-IMPLEMENTATION-ORCHESTRATION.md` §9 for Phase 6 rationale and dependency chain
4. Scan the Cortex pattern references:
   - `crates/cortex/cortex-observability/src/health/` — HealthChecker pattern
   - `crates/cortex/cortex-observability/src/degradation/` — DegradationTracker
5. Start with P6-RUL-01 (enforcement/mod.rs) — the module root that all six systems live under
6. Proceed: Rules Engine (6A) → Quality Gates (6B) → Reporters (6C) → Policy Engine (6D) → Audit System (6E) → Feedback Loop (6F) → Storage & NAPI (6G)
7. After each system: implement tests → verify → move to next
8. Run QG-6 checks. Fix anything that fails. Mark all boxes.
```

--------------------------------

### Setup Tools

Source: https://github.com/dadbodgeoff/drift/blob/main/drift v2/docs/v2-research/07-mcp/tools-by-category.md

Tools for initializing projects with MCP and managing telemetry.

```APIDOC
## Setup Tools API

### Description
Initializes Drift in a project or manages telemetry status.

### Method
POST (assumed, as tools typically take parameters)

### Endpoint
`/tools/setup`

### Parameters
#### Query Parameters
- **tool_name** (string) - Required - The name of the setup tool to use (`drift_setup` or `drift_telemetry`).

#### Request Body
- For `drift_setup`: `project` (string) - Required - The project path or name.
- For `drift_telemetry`: `action` (string, e.g., `status`, `enable`, `disable`).

### Request Example
```json
{
  "tool_name": "drift_setup",
  "project": "/path/to/my/new/project"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of the setup or telemetry action.

#### Response Example
```json
{
  "message": "Drift initialized successfully in /path/to/my/new/project."
}
```
```

--------------------------------

### Drift Project Initialization Steps

Source: https://github.com/dadbodgeoff/drift/blob/main/drift v2/docs/v2-research/PHASE-2-AGENT-PROMPT.md

Provides a step-by-step guide on how to start working with the Drift project. It emphasizes reading specific documentation, scanning the Cortex pattern reference, and following a structured approach for implementing and testing system components.

```markdown
1. Read `docs/v2-research/DRIFT-V2-IMPLEMENTATION-TASKS.md` — Phase 2 section (tasks P2-INT-01 through P2-NAPI-01, tests T2-UAE-01 through T2-INT-11)
2. Read the four V2-PREP documents listed above for behavioral details and type contracts
3. Scan the Cortex pattern reference:
   - `crates/cortex/cortex-causal/src/graph/dag_enforcement.rs` — Tarjan's SCC with petgraph
4. Start with P2-INT-01 (string interning integration) — this touches ParseResult and must happen before the analysis engine consumes it
5. Proceed through Track A (2A → 2B → 2C) and/or Track B (2D → 2E → 2F), then 2G
6. After each system: implement tests → verify → move to next
7. Run QG-2 checks. Fix anything that fails. Mark all boxes.
```

--------------------------------

### Install Drift CLI and MCP Server

Source: https://github.com/dadbodgeoff/drift/wiki/MCP-Setup

Installs the Drift command-line interface for scanning projects and the MCP server for AI integration using npm. This is a prerequisite for connecting AI agents.

```bash
# CLI (for scanning)
npm install -g driftdetect

# MCP server (for AI integration)
npm install -g driftdetect-mcp
```

--------------------------------

### MCP Server Project Parameter Example

Source: https://github.com/dadbodgeoff/drift/wiki/MCP-Setup

An example JSON payload for the MCP server demonstrating how to specify a project for an intent. This shows the 'project' field used to target a specific registered project.

```json
{
  "intent": "add_feature",
  "focus": "authentication",
  "project": "backend"
}
```

--------------------------------

### Get Drift Version

Source: https://github.com/dadbodgeoff/drift/wiki/Troubleshooting

Displays the currently installed version of the Drift CLI. This information is often required when reporting issues.

```bash
drift --version
```

--------------------------------

### Verify Prerequisites

Source: https://github.com/dadbodgeoff/drift/wiki/Getting-Started

Checks if Node.js and npm are installed and meet the minimum version requirements for Drift. Drift requires Node.js 18.0.0+ and npm 9.0.0+.

```bash
# Verify your environment
න්ද --version   # Should show v18.x.x or higher
npm --version    # Should show 9.x.x or higher
```

--------------------------------

### Developer Setup: Verify Prerequisites and Install Dependencies (Bash)

Source: https://github.com/dadbodgeoff/drift/blob/main/drift v2/docs/v2-research/systems/04-INFRASTRUCTURE-V2-PREP.md

This bash script outlines the steps to set up a development environment for the Drift project. It verifies prerequisite versions (Node.js, pnpm, Rust) and installs workspace dependencies using pnpm. It also includes commands to build Rust crates and run an initial scan.

```bash
# Verify prerequisites
node --version    # >= 18.0.0
pnpm --version    # >= 8.0.0
rustc --version   # stable

# Install workspace dependencies
pnpm install

# Build Rust crates
cargo build --workspace

# Run initial scan (dogfooding)
drift scan .

# Verify NAPI bridge
node -e "const n = require('@drift/native'); console.log(n.version())"
```

--------------------------------

### Get Drift Capabilities

Source: https://github.com/dadbodgeoff/drift/wiki/AI-Navigation-Guide

This function retrieves the full navigation guide for Drift's MCP tools programmatically. It returns a JSON object containing information about the agent's decision tree, surgical lookups, common mistakes, layers, and a quick start guide.

```typescript
drift_capabilities({});
```

--------------------------------

### Drift CLI Next Steps and Goals

Source: https://github.com/dadbodgeoff/drift/wiki/Getting-Started

A table outlining common goals when using the Drift CLI, along with the corresponding commands and links to relevant documentation. This includes setting up AI memory, connecting AI agents, analyzing call graphs, setting up CI/CD, and exploring patterns.

```bash
# Set up AI memory
`drift memory setup`

# Connect AI agents
`npm install -g driftdetect-mcp`

# Analyze call graph
`drift callgraph build`

# Set up CI/CD
`drift gate --ci`

# Explore patterns
`drift where --category api`
```

--------------------------------

### Quick Start: Initialize, Add, List, and Search Memories with Drift CLI

Source: https://github.com/dadbodgeoff/drift/wiki/Memory-CLI

This section provides a quick start guide for using the `drift memory` command. It demonstrates how to initialize the memory system, add new memories with importance levels, list stored memories, and perform semantic searches.

```bash
# Initialize memory system
drift memory init

# Add your first memory
drift memory add tribal "Always use bcrypt for passwords" --importance critical

# See what you've stored
drift memory list

# Search memories
drift memory search "password"
```

--------------------------------

### Quick Start Drift CI Integration

Source: https://github.com/dadbodgeoff/drift/wiki/CI-Integration

A three-step process to install Drift, initialize it, and run a quality gate within a CI pipeline. This is a foundational setup for automated drift detection.

```yaml
# 1. Install
npm install -g driftdetect

# 2. Initialize (if not already)
drift init --yes

# 3. Run quality gate
drift gate --ci --fail-on error
```

--------------------------------

### Configure Drift Environment Variables

Source: https://github.com/dadbodgeoff/drift/wiki/MCP-Setup

Examples of setting environment variables for Drift. `DRIFT_PROJECT_PATH` specifies the default path for projects, and `DEBUG` enables debug logging for the Drift CLI.

```bash
# Set project path
export DRIFT_PROJECT_PATH=/path/to/project

# Enable debug logging
export DEBUG=drift:*
```

--------------------------------

### TOML: Example Drift Configuration File

Source: https://github.com/dadbodgeoff/drift/blob/main/drift v2/docs/v2-research/systems/04-INFRASTRUCTURE-V2-PREP.md

An example `drift.toml` file demonstrating how to configure various Drift settings. It includes sections for scan, analysis, quality gates, MCP, backup, and telemetry, with example values for each setting.

```toml
# drift.toml

[scan]
max_file_size = 1_048_576  # 1MB
threads = 0                 # 0 = auto-detect
extra_ignore = ["*.generated.ts", "vendor/"]

[analysis]
min_occurrences = 3
dominance_threshold = 0.60
min_files = 2

[quality_gates]
fail_on = "error"
required_gates = ["pattern_compliance", "security_boundaries"]
min_score = 70

[mcp]
cache_ttl_seconds = 300
max_response_tokens = 8000

[backup]
max_operational = 5
max_daily = 7

[telemetry]
enabled = false

```

--------------------------------

### Upgrade Drift CLI and MCP Server

Source: https://github.com/dadbodgeoff/drift/wiki/Getting-Started

Commands to upgrade the Drift CLI and the driftdetect-mcp server to their latest versions using npm. Includes verification steps to check the installed versions of both tools.

```bash
# Upgrade to latest version
npm install -g driftdetect@latest driftdetect-mcp@latest

# Verify versions
drift --version
driftdetect-mcp --version
```

--------------------------------

### Drift CLI Output Examples (Shell)

Source: https://github.com/dadbodgeoff/drift/blob/main/drift v2/docs/v2-research/systems/19-COUPLING-ANALYSIS-V2-PREP.md

Provides example outputs for the 'drift coupling' CLI command, demonstrating the formatted overview and detailed cycle information when specific flags like '--severity high' are used.

```shell
$ drift coupling
╭─────────────────────────────────────────────╮
│  Module Coupling Analysis                    │
│  Health Score: 72/100                        │
│  Modules: 45  │  Files: 312                  │
├─────────────────────────────────────────────┤
│  Cycles: 3 (1 critical, 1 high, 1 medium)   │
│  Hotspots: 5 (1 critical, 2 high)           │
│  Zone of Pain: 4 modules                     │
│  Zone of Uselessness: 2 modules              │
│  Avg Instability: 0.52                       │
│  Avg Distance: 0.28                          │
╰─────────────────────────────────────────────╯

$ drift coupling cycles --severity high
╭─ Critical Cycle (6 modules) ─────────────────╮
│  src/auth → src/users → src/permissions →     │
│  src/roles → src/policies → src/auth          │
│  Break suggestion: src/permissions → src/roles │
│  Approach: Extract interface                   │
│  Effort: Medium                                │
╰───────────────────────────────────────────────╯
```

--------------------------------

### Deploy Drift with Docker Compose

Source: https://github.com/dadbodgeoff/drift/wiki/MCP-Setup

Instructions for deploying Drift as a containerized HTTP service using Docker Compose. This includes cloning the repository, starting the service with a mounted project path, and checking its health.

```bash
# Clone and start
git clone https://github.com/dadbodgeoff/drift.git
cd drift

# Start with your project mounted
PROJECT_PATH=/path/to/your/project docker compose up -d

# Check health
curl http://localhost:3000/health
```

--------------------------------

### Configure MCP Server via JSON

Source: https://github.com/dadbodgeoff/drift/wiki/MCP-Setup

Configuration for the MCP server within a JSON file. This example shows how to define the 'drift' MCP server, specifying its command and environment variables, including `DRIFT_PROJECT_PATH` and `DEBUG`.

```json
{
  "mcpServers": {
    "drift": {
      "command": "driftdetect-mcp",
      "env": {
        "DRIFT_PROJECT_PATH": "/path/to/project",
        "DEBUG": "drift:mcp"
      }
    }
  }
}
```

--------------------------------

### Drift Development Setup

Source: https://github.com/dadbodgeoff/drift/wiki/Contributing

Steps to set up the development environment for contributing to the Drift core project. This includes cloning the repository, installing dependencies using pnpm, building the project, and running tests.

```bash
# Clone the repo
git clone https://github.com/dadbodgeoff/drift.git
cd drift

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests
pnpm test
```

--------------------------------

### Configure Drift MCP Server with npx (JSON)

Source: https://github.com/dadbodgeoff/drift/wiki/MCP-Setup

An alternative JSON configuration for AI tools that uses 'npx' to run the Drift MCP server without global installation. It allows specifying arguments and pinning a version for stability.

```json
{
  "mcpServers": {
    "drift": {
      "command": "npx",
      "args": ["-y", "driftdetect-mcp@0.9.39"]
    }
  }
}
```

--------------------------------

### Drift Memory Setup Wizard

Source: https://github.com/dadbodgeoff/drift/blob/main/drift v2/docs/v2-research/10-cli/commands.md

An interactive wizard for bootstrapping Cortex memory with project-specific knowledge. It guides users through setting up core identity, tribal knowledge, workflows, agent spawns, entities, skills, and environments. Supports quick setup with defaults via a flag.

```typescript
/**
 * Guided wizard for bootstrapping Cortex memory with project-specific knowledge.
 * Separate from `drift memory init` — this is an interactive onboarding flow that populates memories.
 *
 * Setup Phases:
 * 1. Core Identity
 * 2. Tribal Knowledge
 * 3. Workflows
 * 4. Agent Spawns
 * 5. Entities
 * 6. Skills
 * 7. Environments
 * 8. Save to Memory
 *
 * Flags:
 *   -y, --yes: Quick setup with defaults
 *   -v, --verbose: Verbose output
 *
 * Internals: Uses `getCortex()` helper. Auto-detects project info from package.json, Cargo.toml, go.mod, etc.
 */
// Example usage (conceptual):
// memory-setup --yes
// memory-setup -v

```

--------------------------------

### Get Minimal Code Examples (TypeScript)

Source: https://github.com/dadbodgeoff/drift/wiki/Code-Examples

Retrieves a minimal set of code examples for a specific pattern. Useful for token efficiency when only a few examples are needed. It takes the pattern name, maximum number of examples, and context lines as input.

```typescript
drift_code_examples({
  pattern: "api-rest-controller",
  maxExamples: 1,
  contextLines: 5
})
```

--------------------------------

### Project Discovery Examples (Bash)

Source: https://github.com/dadbodgeoff/drift/wiki/Projects-Management

Shows practical examples of using Drift CLI commands to discover projects based on specific criteria like language or tags.

```bash
# All Python projects
drift projects list --language python

# All critical services
drift projects list --tag critical
```

--------------------------------

### Get Detailed Code Examples (TypeScript)

Source: https://github.com/dadbodgeoff/drift/wiki/Code-Examples

Retrieves more detailed code examples, including more context lines around each pattern match. This is useful for understanding the context and implementation of a pattern. It allows filtering by categories and setting the maximum number of examples.

```typescript
drift_code_examples({
  categories: ["api"],
  maxExamples: 3,
  contextLines: 15
})
```

--------------------------------

### Get Status API Endpoint (Bash)

Source: https://github.com/dadbodgeoff/drift/wiki/Dashboard

Example using curl to fetch the status of the Drift dashboard API. This is a simple GET request to the /api/status endpoint.

```bash
curl http://localhost:3000/api/status
```

--------------------------------

### Initialize Cortex Setup Wizard (Bash)

Source: https://github.com/dadbodgeoff/drift/wiki/Cortex-V2-Overview

Initiates the interactive setup wizard for Cortex. This wizard guides the user through optional sections to configure the project, including core identity, tribal knowledge, workflows, agent spawns, entities, skills, and environments.

```bash
drift memory setup
```

--------------------------------

### Get API REST Controller Examples (TypeScript)

Source: https://github.com/dadbodgeoff/drift/wiki/Code-Examples

Retrieves code examples for the 'api-rest-controller' pattern, demonstrating how RESTful API controllers are structured within the codebase. This is useful for understanding API implementation conventions.

```typescript
@Controller('/api/users')
export class UsersController {
  @Get('/:id')
  async getUser(@Param('id') id: string) {
    const user = await this.userService.findById(id);
    return { data: user, meta: { timestamp: Date.now() } };
  }
}
```