### Initialize Local Development Environment

Source: https://github.com/justinchuby/flightdeck/blob/main/README.md

Install dependencies and start the development server with hot reloading.

```bash
# Local development
npm install
npm run dev    # Starts server + web with hot reload
```

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

### Build Flightdeck from Source

Source: https://github.com/justinchuby/flightdeck/blob/main/packages/docs/guide/deployment.md

Steps to clone the Flightdeck repository, install dependencies, build shared types, build all packages, and start the production server.

```bash
git clone https://github.com/anthropics/flightdeck.git
cd flightdeck
npm install

cd packages/shared && npx tsc && cd ../..

npm run build

npm start
```

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

### Install and Run Flightdeck CLI

Source: https://github.com/justinchuby/flightdeck/blob/main/packages/docs/guide/deployment.md

Install the Flightdeck CLI globally and start the server with default or custom options. The `--no-browser` flag prevents the automatic opening of a web browser.

```bash
npm install -g @flightdeck-ai/flightdeck

flightdeck

flightdeck --port=4000 --host=0.0.0.0 --no-browser
```

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

### Install and Run Flightdeck

Source: https://github.com/justinchuby/flightdeck/blob/main/README.md

Install project dependencies and start the development server with hot reload. The server runs on port 3001 and the web UI on port 5173 during development.

```bash
npm install
npm run build
npm start
```

```bash
npm run dev
```

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

### COMPLETE_TASK Guidance Example

Source: https://github.com/justinchuby/flightdeck/blob/main/docs/research/prompt-critical-review.md

Examples for `COMPLETE_TASK` should consistently show the `dagTaskId` when marking a task as done, aligning with the emphasis on DAG tracking.

```text
⟦⟦ COMPLETE_TASK {"taskId": "task-id"} ⟧⟧ — mark a task as done
```

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

### Install and Run Flightdeck CLI

Source: https://github.com/justinchuby/flightdeck/blob/main/presentations/slides.md

Install the Flightdeck CLI globally using npm and run it. Alternatively, clone the repository, install dependencies, and run the development server.

```bash
npm install -g @flightdeck-ai/flightdeck
flightdeck
```

```bash
git clone https://github.com/justinchuby/flightdeck.git
cd flightdeck && npm install && npm run dev
```

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

### Install and Run Flightdeck

Source: https://github.com/justinchuby/flightdeck/blob/main/README.md

Installs the CLI globally and launches the application. The dashboard will be accessible at http://localhost:3001.

```bash
npm install -g @flightdeck-ai/flightdeck
flightdeck
```

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

### Install and Run Flightdeck CLI (Node.js 20+)

Source: https://github.com/justinchuby/flightdeck/blob/main/presentations/slides.md

Install the Flightdeck CLI globally using npm and run it. This command requires Node.js version 20 or higher and the GitHub Copilot CLI. Alternatively, clone the repository, install dependencies, and run the development server.

```bash
npm install -g @flightdeck-ai/flightdeck
flightdeck
# Requires: Node.js 20+, GitHub Copilot CLI
```

```bash
git clone https://github.com/justinchuby/flightdeck.git
cd flightdeck && npm install && npm run dev
```

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

### YAML Budget Configuration Example

Source: https://github.com/justinchuby/flightdeck/blob/main/docs/archive/budget-threshold-design.md

An example of how to configure budget settings in YAML format, specifying a spending limit in USD and custom threshold values for warning, critical, and pause events. This configuration is loaded from DB settings.

```yaml
budget:
  limit: 50.00        # USD
  thresholds:
    warning: 0.7
    critical: 0.9
    pause: 1.0
```

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

### Create Group Example

Source: https://github.com/justinchuby/flightdeck/blob/main/packages/docs/guide/chat-groups.md

Example of how to create a new group with specified members using a special comment format.

```JavaScript
<!-- CREATE_GROUP {"name": "config-team", "members": ["abc12345", "def67890"]} -->
```

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

### Pretty Output Example

Source: https://github.com/justinchuby/flightdeck/blob/main/docs/specs/r5-structured-logging.md

Example of how logs appear with pretty output enabled during development, showing timestamps, log levels, module, and contextual information.

```plaintext
14:32:05.123 INFO  [agent] Agent spawned  agentId=abc12345 role=developer sessionId=sess-xyz
14:32:05.456 WARN  [delegation] Delegation failed  agentId=def67890 reason="concurrency limit"
```

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

### Flightdeck Configuration Example

Source: https://github.com/justinchuby/flightdeck/blob/main/docs/research/multi-backend-adapter-architecture.md

Example YAML configuration for Flightdeck, specifying default agent backends and providers, and allowing per-role overrides for backend and model choices.

```yaml
# flightdeck.config.yaml (R15 ConfigStore)
agents:
  defaultBackend: acp          # 'acp' | 'sdk'
  defaultProvider: copilot     # CLI provider for ACP backends
  defaultModel: claude-sonnet-4-20250514  # For SDK backends
  
  # Per-role overrides
  roles:
    architect:
      backend: sdk
      model: claude-opus-4-20250514    # Architects get Opus
    developer:
      backend: acp
      provider: copilot              # Developers use Copilot CLI
    qa-tester:
      backend: acp
      provider: gemini               # QA uses Gemini
```

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

### Winget Installation Command

Source: https://github.com/justinchuby/flightdeck/blob/main/docs/design/cross-platform-builds.md

Command used by end-users to install the application via winget.

```bash
# Users install with:
winget install FlightdeckAI.Flightdeck
```

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

### Flightdeck Configuration File Example

Source: https://github.com/justinchuby/flightdeck/blob/main/packages/docs/guide/deployment.md

Example of a project-level Flightdeck configuration file (`flightdeck.config.yaml`). This file allows overriding user-level defaults for server settings, providers, models, budget, and heartbeat intervals.

```yaml
server:
  maxConcurrentAgents: 50  # 1-200, default: 50

provider:
  id: copilot  # Active CLI provider

models:
  known:
    - claude-opus-4.6
    - gpt-5.2
    - gemini-3-pro-preview
  defaults:
    developer: [claude-opus-4.6]
    architect: [claude-opus-4.6]
    code-reviewer: [gemini-3-pro-preview]

budget:
  limit: null  # null = unlimited, or dollar amount
  thresholds:
    warning: 0.7
    critical: 0.9
    pause: 1.0

heartbeat:
  idleThresholdMs: 60000
  crewUpdateIntervalMs: 180000
```

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

### Initialize Configuration File

Source: https://github.com/justinchuby/flightdeck/blob/main/packages/docs/guide/quickstart.md

Copy the example configuration file to the project root to begin customization.

```bash
cp flightdeck.config.example.yaml flightdeck.config.yaml
```

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

### Install and Start Flightdeck Bridge via Homebrew

Source: https://github.com/justinchuby/flightdeck/blob/main/docs/design/macos-sandboxing.md

These bash commands are used to install the Flightdeck bridge using a custom Homebrew tap and then start it as a background service.

```bash
brew install flightdeck-ai/flightdeck/flightdeck-bridge
brew services start flightdeck-bridge
```

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

### Start Development Components Separately

Source: https://github.com/justinchuby/flightdeck/blob/main/packages/docs/guide/quickstart.md

Commands to launch the API server, web interface, and documentation site as individual processes.

```bash
npm run dev:server   # Express API + WebSocket at http://localhost:3001
npm run dev:web      # Vite dev server at http://localhost:5173
npm run docs:dev     # VitePress docs site
```

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

### Initialize Development Environment

Source: https://github.com/justinchuby/flightdeck/blob/main/packages/docs/guide/quickstart.md

Commands to clone the repository and start the development server with hot reloading.

```bash
git clone https://github.com/justinchuby/flightdeck.git
cd flightdeck
npm install
npm run dev          # starts server + web UI with hot reload
```

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

### Inline CREATE_AGENT Guidance Example

Source: https://github.com/justinchuby/flightdeck/blob/main/docs/research/prompt-critical-review.md

A proposed concise inline hint for the CREATE_AGENT command to improve prompt signal strength.

```text
⟦⟦ CREATE_AGENT {"role": "developer", "task": "Extract RoPEConfig", "dagTaskId": "rope-config"} ⟧⟧  ← always include dagTaskId
```

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

### Project ID Request Payload

Source: https://github.com/justinchuby/flightdeck/blob/main/docs/research/synthesis/review-wave2.md

Example of the client-supplied payload used to start or resume a project session.

```json
{ projectId: "known-uuid" }
```

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

### Initialize Container in index.ts

Source: https://github.com/justinchuby/flightdeck/blob/main/docs/specs/r1-di-container.md

Example of initializing the service container and starting the application within the refactored index file.

```typescript
const container = await createContainer({ config, repoRoot });
const app = createExpressApp(container);
const port = await listenWithRetry(config.port, config.host);
container.internal.contextRefresher.start();
// ... minimal startup code
```

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

### Model API Response Structure

Source: https://github.com/justinchuby/flightdeck/blob/main/docs/reference/MODEL_RESOLUTION.md

Example JSON response for the GET /models endpoint, providing available models and provider-specific mappings.

```json
{
  "models": ["claude-opus-4.6", "claude-sonnet-4.6", ...],
  "defaults": { ... },
  "modelsByProvider": {
    "copilot": ["claude-opus-4.6", "claude-sonnet-4.6", ..., "gemini-3-pro-preview"],
    "claude": ["claude-opus-4.6", "claude-sonnet-4.6", "claude-haiku-4.5"],
    "gemini": ["gemini-2.5-pro", "gemini-2.5-flash", "gemini-2.5-flash-lite", "gemini-3-pro-preview"],
    "codex": ["gpt-5.4", "gpt-5.3-codex", ...],
    ...
  }
}
```

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

### POST /lead/start

Source: https://github.com/justinchuby/flightdeck/blob/main/packages/docs/reference/api.md

Initialize a lead agent with a specific task and project context.

```APIDOC
## POST /lead/start

### Description
Start lead agent

### Method
POST

### Endpoint
/lead/start

### Parameters
#### Request Body
- **task** (body) - Required
- **name** (body) - Required
- **model** (body) - Required
- **cwd** (body) - Required
- **sessionId:** (body) - Required
- **projectId** (body) - Required
```

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

### Build for Production

Source: https://github.com/justinchuby/flightdeck/blob/main/packages/docs/guide/quickstart.md

Commands to compile the project packages and start the production application.

```bash
npm run build        # builds shared, server, and web packages
npm start            # or: flightdeck
```

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

### Get Context-Aware Command Suggestions

Source: https://github.com/justinchuby/flightdeck/blob/main/packages/docs/reference/nl-api.md

Obtain context-aware suggestions for Natural Language commands based on the current crew state. Useful for proactively guiding users.

```json
[
  {
    "commandId": "nl-review-approvals",
    "reason": "3 pending approvals",
    "priority": "high"
  },
  {
    "commandId": "nl-restart-agent",
    "reason": "Developer approaching context limit",
    "priority": "medium",
    "parameters": { "agentId": "dev-1" }
  }
]
```

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

### AdapterStartOptions

Source: https://github.com/justinchuby/flightdeck/blob/main/docs/research/multi-backend-adapter-architecture.md

Configuration options for starting an agent adapter, specifically tailored for subprocess-based backends.

```APIDOC
## AdapterStartOptions

### Description
Configuration object used when initializing an agent adapter.

### Fields
- **cliCommand** (string) - Required - The CLI command to execute for subprocess-based agents.
- **cliArgs** (string[]) - Optional - Arguments for the CLI command.
- **cwd** (string) - Optional - The current working directory for the process.
```

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

### Get Crew Descendants Utility (TypeScript)

Source: https://github.com/justinchuby/flightdeck/blob/main/packages/docs/reference/hierarchy-audit.md

Collects all agents in a hierarchy starting from a lead agent. This utility works on both server and web environments and requires the full agent list to be in memory.

```typescript
// Shared utility — works on both server (Agent[]) and web (AgentInfo[])
function getCrewDescendants<T extends { id: string; parentId?: string | null }>(
  leadId: string,
  agents: T[],
): T[] {
  const result: T[] = [];
  const queue = [leadId];
  const visited = new Set<string>();

  while (queue.length > 0) {
    const current = queue.shift()!;
    if (visited.has(current)) continue;
    visited.add(current);

    const agent = agents.find(a => a.id === current);
    if (agent) result.push(agent);

    // Find all agents whose parentId is the current agent
    for (const a of agents) {
      if (a.parentId === current && !visited.has(a.id)) {
        queue.push(a.id);
      }
    }
  }

  return result;
}
```

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

### Enable Full HTTP Request Logging

Source: https://github.com/justinchuby/flightdeck/blob/main/packages/docs/guide/deployment.md

To enable logging of all HTTP requests, including successful GET requests, set the `LOG_ALL_HTTP` environment variable to `true` before starting the npm server. This is useful for debugging but not recommended for production due to high log volume.

```bash
LOG_ALL_HTTP=true npm start
```

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

### SOP Configuration Example

Source: https://github.com/justinchuby/flightdeck/blob/main/docs/research/zeroclaw-memory-research.md

TOML configuration for defining standard operating procedures and their execution steps.

```toml
[sop]
name = "deploy"
trigger = "deploy to production"
cooldown = 300  # 5 minutes between runs

[[steps]]
instruction = "Run tests first"
tool = "shell"
args = { command = "cargo test" }
```

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

### Daemon Startup Flow

Source: https://github.com/justinchuby/flightdeck/blob/main/docs/research/claude-adapter-design.md

Outlines the sequence of steps involved in starting the daemon process, including reading active sessions, resuming agents, and establishing communication with the API server.

```text
1. Daemon starts
2. Read agent_sessions table for status='active', get sdk_session_id for each
3. For each: create ClaudeAdapter, call start({ sessionId: sdk_session_id })
4. start() returns flightdeck_session_id immediately — mapping already exists in DB
5. Agents resume with full context from prior conversation
6. API server connects to daemon, AgentManager discovers running agents via flightdeck_session_id
```

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

### Install npm Dependencies

Source: https://github.com/justinchuby/flightdeck/blob/main/docs/design/cross-platform-builds.md

Installs project dependencies using `npm ci` for a clean and reproducible installation.

```yaml
run: npm ci
```

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

### Visualize Startup Sequence

Source: https://github.com/justinchuby/flightdeck/wiki/[Archived]-Two‐Process-Architecture:-Orchestration-Server---Agent-Server

Represents the initialization flow for the development environment, including server forking and orchestration connection.

```text
1. npm run dev
   └─ scripts/dev.mjs
      │
      ├─ Check for existing agent server (PID file)
      │   ├─ Found + alive → skip fork, reuse existing
      │   └─ Not found or dead → fork new agent server
      │
      ├─ Fork agent server (detached: true)
      │   └─ agent-server.ts starts, writes PID file, sends 'ready'
      │
      ├─ Start orchestration server (tsx watch)
      │   └─ index.ts creates container, connects to agent server via ForkTransport
      │       └─ AgentServerClient.connect() → sends 'subscribe' for each known agent
      │
      └─ Start Vite dev server (UI)
```

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

### GET /crews/:crewId

Source: https://github.com/justinchuby/flightdeck/blob/main/packages/docs/reference/api.md

Gets a crew by ID.

```APIDOC
## GET /crews/:crewId

### Description
Gets a crew by ID.

### Method
GET

### Endpoint
/crews/:crewId

### Parameters
#### Path Parameters
- **crewId** (path) - Required
```

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

### GET /lead/:id

Source: https://github.com/justinchuby/flightdeck/blob/main/packages/docs/reference/api.md

Get lead by ID.

```APIDOC
## GET /lead/:id

### Description
Get lead by ID

### Method
GET

### Endpoint
/lead/:id

### Parameters
#### Path Parameters
- **id** (string) - Yes - id
```

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

### AdapterStartOptions Interface

Source: https://github.com/justinchuby/flightdeck/blob/main/docs/research/multi-backend-adapter-architecture.md

The canonical interface for configuring adapter startup, supporting ACP, SDK, and Daemon backends through a flat, optional field structure.

```APIDOC
## AdapterStartOptions

### Description
Configuration options for initializing an adapter. Uses a flat structure to maintain backward compatibility with existing ACP callers while allowing new SDK and Daemon configurations.

### Parameters
#### Request Body
- **cliCommand** (string) - Required - The CLI command to execute.
- **baseArgs** (string[]) - Optional - Provider-specific ACP flags.
- **cliArgs** (string[]) - Optional - User-specified additional arguments.
- **cwd** (string) - Optional - Current working directory.
- **sessionId** (string) - Optional - Session ID for resuming sessions.
- **backend** ('acp' | 'sdk' | 'daemon' | 'mock') - Optional - The backend type. Defaults to 'acp'.
- **model** (string) - Optional - Model identifier for SDK backends.
- **apiKey** (string) - Optional - API key for SDK backends.
- **systemPrompt** (string) - Optional - System prompt for the agent.
- **maxTurns** (number) - Optional - Safety limit for turns.
- **allowedTools** (string[]) - Optional - Tool allowlist.
- **socketPath** (string) - Optional - UDS path for daemon connection.
- **agentId** (string) - Optional - Agent ID for daemon side.
```

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

### GET /shared/:token/state

Source: https://github.com/justinchuby/flightdeck/blob/main/packages/docs/reference/api.md

Get the state of a shared resource.

```APIDOC
## GET /shared/:token/state

### Method
GET

### Endpoint
/shared/:token/state

### Parameters
#### Path Parameters
- **token** (string) - Required

#### Query Parameters
- **at** (string) - Optional
```

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

### Initialize Main Process

Source: https://github.com/justinchuby/flightdeck/blob/main/docs/design/electron-architecture.md

Sets up the Electron main process, including single-instance locking, IPC handlers, and the in-process server lifecycle.

```typescript
// packages/desktop/src/main.ts
import { app, BrowserWindow, ipcMain } from 'electron';
import { startFlightdeckServer } from './server-runner';
import { createMainWindow, restoreWindowState } from './window-manager';
import { buildMenu } from './menu';
import { setupTray } from './tray';
import { setupAutoUpdater } from './updater';
import { registerIpcHandlers } from './ipc/handlers';
import { registerProtocolHandler } from './protocol';

let mainWindow: BrowserWindow | null = null;
let serverHandle: { port: number; stop: () => Promise<void> } | null = null;

// Single instance lock — prevent multiple Flightdeck windows
const gotLock = app.requestSingleInstanceLock();
if (!gotLock) {
  app.quit();
} else {
  app.on('second-instance', (_event, _argv, _workingDir) => {
    if (mainWindow) {
      if (mainWindow.isMinimized()) mainWindow.restore();
      mainWindow.focus();
    }
  });
}

app.whenReady().then(async () => {
  // 1. Register IPC handlers before creating any windows
  registerIpcHandlers();

  // 2. Register flightdeck:// protocol handler
  registerProtocolHandler();

  // 3. Start the Flightdeck server in-process
  serverHandle = await startFlightdeckServer({
    isDesktop: true,
  });

  // 4. Create the main window
  mainWindow = createMainWindow(serverHandle.port);
  restoreWindowState(mainWindow);

  // 5. Build native menu
  buildMenu(mainWindow);

  // 6. System tray (optional, user preference)
  setupTray(mainWindow, serverHandle.port);

  // 7. Auto-updater (direct distribution only, not MAS)
  if (!process.mas) {
    setupAutoUpdater(mainWindow);
  }
});

// macOS: re-create window when dock icon clicked with no windows
app.on('activate', () => {
  if (BrowserWindow.getAllWindows().length === 0 && serverHandle) {
    mainWindow = createMainWindow(serverHandle.port);
  }
});

// Graceful shutdown
app.on('before-quit', async (e) => {
  if (serverHandle) {
    e.preventDefault();
    await serverHandle.stop();
    serverHandle = null;
    app.quit();
  }
});

// Quit when all windows are closed (Windows/Linux)
// macOS: app stays in dock until explicitly quit
app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit();
  }
});
```

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

### GET /shared/:token

Source: https://github.com/justinchuby/flightdeck/blob/main/packages/docs/reference/api.md

Get shared resource by ID.

```APIDOC
## GET /shared/:token

### Description
Get shared by ID.

### Method
GET

### Endpoint
/shared/:token

### Parameters
#### Path Parameters
- **token** (string) - Required - The shared resource token.
```

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

### GET /projects/:id/knowledge/stats

Source: https://github.com/justinchuby/flightdeck/blob/main/packages/docs/reference/api.md

Gets knowledge statistics for a project.

```APIDOC
## GET /projects/:id/knowledge/stats

### Description
Gets knowledge statistics for a project.

### Method
GET

### Endpoint
/projects/:id/knowledge/stats

### Parameters
#### Path Parameters
- **id** (path) - Required
```

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

### Configure Logging via YAML

Source: https://github.com/justinchuby/flightdeck/blob/main/docs/specs/r5-phases-3-4.md

Example configuration structure for future log shipping and output settings.

```yaml
logging:
  level: debug          # Already supported via LOG_LEVEL
  format: json | pretty # Already supported via NODE_ENV
  # Future:
  # output: stdout | file | loki
  # filePath: /var/log/flightdeck.log
```

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

### Start Flightdeck in Development

Source: https://github.com/justinchuby/flightdeck/blob/main/packages/docs/guide/deployment.md

Launches the server with hot-reload and the Vite development server.

```bash
npm run dev
```

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

### GET /crews/:crewId/health

Source: https://github.com/justinchuby/flightdeck/blob/main/packages/docs/reference/api.md

Gets the health status of a crew.

```APIDOC
## GET /crews/:crewId/health

### Description
Gets the health status of a crew.

### Method
GET

### Endpoint
/crews/:crewId/health

### Parameters
#### Path Parameters
- **crewId** (path) - Required
```

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

### Create/Edit Project Files

Source: https://github.com/justinchuby/flightdeck/blob/main/docs/research/per-user-project-knowledge.md

Use these commands to directly create or edit project configuration files like conventions and preferences.

```bash
vim ~/.flightdeck/projects/<id>/skills/conventions.md
vim ~/.flightdeck/projects/<id>/preferences.yaml
```

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

### Install YAML Dependency

Source: https://github.com/justinchuby/flightdeck/blob/main/docs/specs/r15-hot-reload-config.md

Command to install the yaml package for Node.js.

```bash
npm install yaml
```

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

### GET /projects/:id/knowledge/training

Source: https://github.com/justinchuby/flightdeck/blob/main/packages/docs/reference/api.md

Gets knowledge training status for a project.

```APIDOC
## GET /projects/:id/knowledge/training

### Description
Gets knowledge training status for a project.

### Method
GET

### Endpoint
/projects/:id/knowledge/training

### Parameters
#### Path Parameters
- **id** (path) - Required
```

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

### GET /crews/:crewId/agents/:agentId/profile

Source: https://github.com/justinchuby/flightdeck/blob/main/packages/docs/reference/api.md

Gets the profile of an agent within a crew.

```APIDOC
## GET /crews/:crewId/agents/:agentId/profile

### Description
Gets the profile of an agent within a crew.

### Method
GET

### Endpoint
/crews/:crewId/agents/:agentId/profile

### Parameters
#### Path Parameters
- **crewId** (path) - Required
- **agentId** (path) - Required
```

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

### Server Startup Recovery Sequence

Source: https://github.com/justinchuby/flightdeck/blob/main/docs/design/hot-reload-agent-preservation.md

Outlines the order of operations for restoring system state upon server initialization.

```text
Server startup sequence (message recovery):
  1. Load timers             → TimerRegistry.loadPending()          [EXISTING]
  2. Load delegations        → activeDelegations table → Map        [NEW]
  3. Load message queues     → messageQueue WHERE status='queued'   [NEW]
  4. Apply pending actions   → decisions WHERE status='approved_pending_apply' [NEW]
  5. Connect to daemon       → subscribe to each agent
  6. For each agent:
     a. Daemon replays buffered events (event buffering protocol)
     b. Server rebuilds agent in-memory state from SQLite
     c. Server drains messageQueue → agent.pendingMessages[]
     d. Agent idle? → deliver first queued message immediately
```

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

### GET /api/nl/suggestions

Source: https://github.com/justinchuby/flightdeck/blob/main/packages/docs/reference/nl-api.md

Get context-aware command suggestions based on current crew state.

```APIDOC
## GET /api/nl/suggestions

### Description
Get context-aware command suggestions based on current crew state.

### Method
GET

### Endpoint
/api/nl/suggestions

### Parameters
#### Query Parameters
- **context** (string) - Optional - Current page/view context.

### Response
#### Success Response (200)
- **commandId** (string) - The ID of the suggested command.
- **reason** (string) - The reason why this suggestion is relevant.
- **priority** (string) - The priority of the suggestion (e.g., high, medium, low).
- **parameters** (object) - Optional - Parameters pre-filled for the suggested command.

### Response Example
```json
[
  {
    "commandId": "nl-review-approvals",
    "reason": "3 pending approvals",
    "priority": "high"
  },
  {
    "commandId": "nl-restart-agent",
    "reason": "Developer approaching context limit",
    "priority": "medium",
    "parameters": { "agentId": "dev-1" }
  }
]
```
```

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

### Start a Project Lead Agent

Source: https://context7.com/justinchuby/flightdeck/llms.txt

Spawns a new Project Lead agent to orchestrate a coding task. Requires a task description, project name, AI model, and working directory.

```bash
curl -X POST http://localhost:3001/lead/start \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Refactor the auth module to use JWT tokens, add tests, and update the docs",
    "name": "Auth Refactor Project",
    "model": "claude-opus-4.6",
    "cwd": "/path/to/your/project"
  }'
```

```json
{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "role": { "id": "lead", "name": "Project Lead" },
  "status": "running",
  "projectId": "proj-abc123",
  "projectName": "Auth Refactor Project",
  "model": "claude-opus-4.6",
  "inputTokens": 0,
  "outputTokens": 0
}
```

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

### Install Node.js and Cache Dependencies

Source: https://github.com/justinchuby/flightdeck/blob/main/docs/design/cross-platform-builds.md

Sets up the specified Node.js version and caches npm dependencies for faster builds. Ensure `NODE_VERSION` is defined in the environment.

```yaml
uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: npm
```

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

### Send Group Message Example

Source: https://github.com/justinchuby/flightdeck/blob/main/packages/docs/guide/chat-groups.md

Example of sending a message to a group using a special comment format.

```JavaScript
<!-- GROUP_MESSAGE {"group": "config-team", "content": "Important: _configs.py has breaking changes in progress. Coordinate before editing."} -->
```

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

### Welcome Dashboard UI

Source: https://github.com/justinchuby/flightdeck/blob/main/docs/design/project-centric-ui.md

Displays the empty state welcome screen when no projects are configured.

```text
┌──────────────────────────────────────────────────────────┐
│                                                          │
│              Welcome to Flightdeck! 🚀                   │
│                                                          │
│   Let's set up your first AI-powered dev crew.           │
│                                                          │
│   Step 1: Configure a provider                           │
│   [ Connect Claude ] [ Connect Copilot ] [ More... ]     │
│                                                          │
│   Step 2: Create your first project                      │
│   [ Create Project → ]                                   │
│                                                          │
└──────────────────────────────────────────────────────────┘
```