### Install @diagrampilot/mcp

Source: https://github.com/stienswout/diagrampilot/blob/main/packages/mcp/README.md

Install the Model Context Protocol adapter as a dev dependency.

```bash
npm install --save-dev @diagrampilot/mcp
```

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

### Install and Build DiagramPilot CLI

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/quickstart.md

Install project dependencies and build the local CLI. This is a prerequisite for running DiagramPilot commands locally.

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

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

### Install Nightly Build of DiagramPilot

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/installation.md

Use `--save-exact` with `npm install` to pin the `nightly` version of DiagramPilot for testing specific pre-release builds.

```bash
npm install --save-dev --save-exact diagrampilot@nightly
```

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

### Initialize DiagramPilot Configuration

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/quickstart.md

Start a minimal DiagramPilot configuration file using this command. This is the first step in setting up repository workflow configurations.

```bash
diagrampilot init --config
```

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

### Example MCP Client Configuration

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/installation.md

Configure the MCP client to connect to a DiagramPilot MCP server. This JSON defines the server endpoint.

```json
{
  "mcpServers": {
    "diagrampilot": {
      "command": "diagrampilot-mcp"
    }
  }
}
```

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

### Install DiagramPilot Nightly Build

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/agent-workflow.md

Install a specific nightly build of DiagramPilot to test current versions not yet on the normal `latest` path. Use `--save-exact` to pin the nightly version for consistent local and CI runs.

```bash
npm install --save-dev --save-exact diagrampilot@nightly
```

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

### Global Local Installation of DiagramPilot

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/installation.md

Install DiagramPilot globally using npm to make it available as a local shell tool across multiple repositories.

```bash
npm install --global diagrampilot
```

```bash
diagrampilot check
```

```bash
diagrampilot inspect
```

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

### DiagramPilot Source File Example

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/spec.md

This is an example of a DiagramPilot source file in YAML format, defining the diagram's title, direction, nodes, groups, and edges.

```yaml
version: 1
title: Checkout Export Sample
direction: right
nodes:
  - id: web_app
    label: Web App
    kind: frontend
    icon: lucide:globe
    metadata:
      source: src/web/checkout-page.tsx
  - id: api_gateway
    label: API Gateway
    kind: service
    icon: lucide:server
groups:
  - id: backend
    label: Backend
    contains:
      - api_gateway
edges:
  - id: web_app_to_api_gateway
    from: web_app
    to: api_gateway
    label: HTTPS
```

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

### DiagramPilot File Structure

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/quickstart.md

Example file structure for a DiagramPilot project. Use a '.dp.yaml' file for editable source and a corresponding '.svg' file for the rendered output.

```text
docs/architecture.dp.yaml
docs/architecture.svg
```

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

### DiagramPilot CLI Workflow Examples

Source: https://github.com/stienswout/diagrampilot/blob/main/README.md

Demonstrates common DiagramPilot CLI commands for managing diagram source files and generating artifacts. Includes commands for checking, inspecting, creating, validating, linting, formatting, rendering, importing, and exporting diagrams.

```bash
cd demo-projects/checkout
diagrampilot check
diagrampilot inspect
diagrampilot icons search database
diagrampilot create docs/new-architecture.dp.yaml --template architecture
diagrampilot create docs/system-context.dp.yaml --template system-context
diagrampilot create docs/service-map.dp.yaml --template service-map
diagrampilot validate docs/architecture.dp.yaml
diagrampilot lint docs/architecture.dp.yaml
diagrampilot format docs/architecture.dp.yaml
diagrampilot render docs/architecture.dp.yaml --out docs/architecture.svg
diagrampilot render docs/architecture.dp.yaml --view runtime --out docs/architecture-runtime.svg
diagrampilot render docs/architecture.dp.yaml --format png --out docs/architecture.png
diagrampilot import docs/legacy.mmd --format mermaid --out docs/imported.dp.yaml
diagrampilot import docs/legacy.d2 --format d2 --out docs/imported-d2.dp.yaml
diagrampilot import docs/legacy.dot --format dot --out docs/imported-dot.dp.yaml
diagrampilot export docs/architecture.dp.yaml --format mermaid
diagrampilot export docs/architecture.dp.yaml --view runtime --format mermaid --out docs/architecture-runtime.mmd
diagrampilot export docs/architecture.dp.yaml --format d2 --out docs/architecture.d2
diagrampilot export docs/architecture.dp.yaml --format dot --out docs/architecture.dot
```

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

### Minimal Package Dependency Diagram

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/examples.md

A minimal DiagramPilot YAML example showcasing inline styling for nodes and edges, defining package dependencies with icons and labels.

```yaml
version: 1
title: Minimal Package Dependency
direction: right
nodes:
  - id: cli
    label: packages/cli
    kind: package
    icon: lucide:terminal
  - id: core
    label: packages/core
    kind: package
    icon: lucide:box
edges:
  - id: cli_to_core
    from: cli
    to: core
    label: validates source
    kind: imports
```

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

### Minimal DiagramSpec Example

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/spec.md

A basic DiagramSpec file demonstrating the essential structure for a diagram, including version, title, nodes, and edges.

```yaml
version: 1
title: Checkout Architecture
nodes:
  - id: web_app
    label: Web App
  - id: api_gateway
    label: API Gateway
edges:
  - id: web_app_to_api_gateway
    from: web_app
    to: api_gateway
    label: HTTPS
```

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

### Good Prompt Pattern for DiagramPilot

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/prompting.md

Example of a well-structured prompt for creating a DiagramPilot diagram. It specifies the source file location, components, rendering, ID strategy, and edge labeling.

```text
Create a DiagramPilot source file at docs/architecture.dp.yaml for the auth,
API, worker, queue, and database components. Render docs/architecture.svg.
Use stable IDs and include labels on edges that describe protocols or data flow.
```

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

### DiagramSpec Node Example

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/spec.md

A detailed example of a node within a DiagramSpec file, showcasing required fields like id and label, and optional fields such as kind, description, icon, and metadata.

```yaml
nodes:
  - id: api_gateway
    label: API Gateway
    kind: service
    description: Routes public API traffic.
    icon: lucide:server
    metadata:
      source: src/gateway
      external_url: https://example.com/api-gateway-notes
```

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

### Add DiagramPilot as a Dev Dependency with pnpm, yarn, or bun

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/installation.md

Install DiagramPilot as a development dependency using pnpm, yarn, or bun for repeatable repository workflows.

```bash
pnpm add -D diagrampilot
```

```bash
yarn add -D diagrampilot
```

```bash
bun add -D diagrampilot
```

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

### Search for Icons

Source: https://github.com/stienswout/diagrampilot/blob/main/README.md

Searches for icons based on a keyword. For example, searching for 'database' will list relevant icons.

```bash
diagrampilot icons search database
```

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

### Example JSON Repair Plan

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/error-repair.md

This JSON output details a planned repair, specifying the file, whether changes occurred, the repair kind, path, message, and the before/after values.

```json
{
  "file": "docs/icons.dp.yaml",
  "ok": true,
  "changed": true,
  "repairs": [
    {
      "kind": "replace-icon",
      "path": "nodes[0].icon",
      "message": "Replace invalid icon with configured fallback lucide:database.",
      "before": "lucide:databse",
      "after": "lucide:database"
    }
  ],
  "validation": {
    "ok": true,
    "errors": []
  }
}
```

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

### Bad Error Message Example

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/error-repair.md

An example of a vague and unhelpful error message that lacks specific details for repair.

```text
Invalid diagram.
```

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

### Run Diagrampilot Watch Loop

Source: https://github.com/stienswout/diagrampilot/blob/main/README.md

Starts a local authoring loop for a specified scope. It monitors configuration and source files for changes, performs workflow checks, and generates output when the state is valid. Use this for continuous local development.

```bash
diagrampilot watch [path]
```

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

### Add DiagramPilot as a Dev Dependency with npm

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/installation.md

Install DiagramPilot as a development dependency in a repository using npm to ensure consistent versions across scripts and CI.

```bash
npm install --save-dev diagrampilot
```

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

### Example Icon Usage in YAML

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/icons.md

Common valid references for packaged Lucide icons in DiagramPilot configuration. Validation rejects unsupported namespaces and unknown packaged Lucide names.

```yaml
icon: lucide:database
icon: lucide:server
icon: lucide:globe
icon: lucide:shopping-cart
icon: lucide:credit-card
icon: lucide:package-check
icon: lucide:git-pull-request
icon: lucide:workflow
icon: lucide:boxes
icon: lucide:file-code
```

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

### Define Layout Hints in DiagramPilot

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/spec.md

Example of defining layout hints for 'primary_flow' and 'same_layer' kinds. Layout hints express soft, renderer-neutral intent for visual arrangement.

```yaml
layout:
  hints:
    - id: checkout_flow
      kind: primary_flow
      nodes:
        - web_app
        - api_gateway
        - orders_service
    - id: runtime_peers
      kind: same_layer
      nodes:
        - orders_service
        - payments_service
```

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

### DiagramPilot Source Ignore Configuration

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/quickstart.md

Example of a minimal DiagramPilot configuration file. The `sources.ignore` section uses gitignore-style paths to exclude files from source discovery.

```yaml
version: 1
sources:
  ignore:
    - generated/**
    - vendor/diagrams/**
```

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

### Example Broken DiagramPilot Source File

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/error-repair.md

This YAML snippet demonstrates a common error where an edge references an unknown node ID.

```yaml
version: 1
title: Checkout Repair Example
direction: right
nodes:
  - id: web_app
    label: Web App
  - id: api_gateway
    label: API Gateway
edges:
  - id: web_app_to_api_gateway
    from: storefront
    to: api_gateway
    label: HTTPS
```

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

### Example Broken Source with Fallback Icon

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/error-repair.md

This YAML shows a node with an invalid `icon` value, intended for repair using a configured fallback icon.

```yaml
version: 1
title: Icon Repair Example
nodes:
  - id: database
    label: Database
    icon: lucide:databse
```

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

### DiagramPilot CLI Commands for Focused Rendering

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/spec.md

Examples of using focused render filters like --group, --around with --depth, and --hide-edge-labels to create smaller SVG artifacts without modifying the source.

```bash
diagrampilot render docs/architecture.dp.yaml --group checkout_runtime --out docs/architecture-checkout-runtime.svg
```

```bash
diagrampilot render docs/architecture.dp.yaml --around orders_service --depth 1 --out docs/architecture-orders-service.svg
```

```bash
diagrampilot render docs/architecture.dp.yaml --hide-edge-labels --out docs/architecture-overview.svg
```

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

### DiagramPilot Artifact Mapping Configuration

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/quickstart.md

Example of a DiagramPilot configuration file defining artifact mappings. This section specifies how DiagramPilot source files map to various output formats like SVG, Mermaid, D2, PNG, and Markdown.

```yaml
version: 1
artifacts:
  - source: docs/architecture.dp.yaml
    outputs:
      - format: svg
        path: docs/architecture.svg
        profile: presentation
      - format: mermaid
        path: docs/architecture.mmd
        profile: compact
      - format: d2
        path: docs/architecture-overview.d2
        profile: overview
      - format: png
        path: docs/architecture.png
      - format: markdown
        path: docs/architecture.embed.md
  - sourceGlob: docs/diagrams/*.dp.yaml
    outputs:
      - format: d2
        path: artifacts/{sourceDir}/{stem}.{format}
```

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

### Define a View in DiagramPilot

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/spec.md

Example of defining a 'runtime' view with specific node and edge kinds. Views are named projections from a source file used for smaller review artifacts.

```yaml
views:
  - id: runtime
    label: Runtime
    groups:
      - backend
    nodeKinds:
      - service
    edgeKinds:
      - request
      - data_flow
```

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

### Text Validation Output Example

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/error-repair.md

This text output shows a validation error, including the file, path, problem, bad value, expected values, and a suggestion for repair.

```text
DiagramSpec validation error in docs/checkout.dp.yaml: edges[0].from references unknown node "storefront".
  Path: edges[0].from
  Problem: edges[0].from references unknown node "storefront".
  Bad value: "storefront"
  Expected: One of: web_app, api_gateway.
  Suggestion: Add a node with id "storefront" or change edges[0].from to an existing node ID.
```

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

### GitHub Actions Workflow for DiagramPilot

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/integrations.md

This YAML workflow automates DiagramPilot tasks within a GitHub Actions pipeline. It checks out code, sets up Node.js, installs dependencies, and runs DiagramPilot commands for validation, linting, rendering, and checking.

```yaml
name: DiagramPilot

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  diagrams:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npx diagrampilot validate docs/architecture.dp.yaml
      - run: npx diagrampilot lint docs/architecture.dp.yaml
      - run: npx diagrampilot render docs/architecture.dp.yaml --out docs/architecture.svg
      - run: npx diagrampilot check
```

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

### Validate DiagramPilot Source (Text Output)

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/error-repair.md

Run `diagrampilot validate` without the `--json` flag to get human-readable text output detailing validation errors.

```bash
diagrampilot validate docs/checkout.dp.yaml
```

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

### Initialize DiagramPilot Project

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/index.md

Initializes a new DiagramPilot project. Use `--docs` for managed local agent docs and `--config` for a `diagrampilot.config.yaml` file.

```bash
diagrampilot init
diagrampilot init --docs
diagrampilot init --config
```

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

### Uninstall Global DiagramPilot Install

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/installation.md

Remove a globally installed DiagramPilot npm package.

```bash
npm uninstall --global diagrampilot
```

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

### Create DiagramPilot Source Files

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/index.md

Generates starter `*.dp.yaml` source files from maintained templates like architecture, flow, system-context, or service-map.

```bash
diagrampilot create docs/architecture.dp.yaml --template architecture
diagrampilot create docs/system-context.dp.yaml --template system-context
diagrampilot create docs/service-map.dp.yaml --template service-map
```

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

### Launch diagrampilot-mcp

Source: https://github.com/stienswout/diagrampilot/blob/main/packages/mcp/README.md

Launch the package-level executable for the Model Context Protocol server.

```bash
diagrampilot-mcp
```

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

### Render and Check Diagram Pilot Commands

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/agent-workflow.md

Use forward-slash paths for Diagram Pilot commands like 'render' and 'check' on all platforms to ensure consistent provenance.

```bash
diagrampilot render docs/architecture.dp.yaml --out docs/architecture.svg
diagrampilot check docs
```

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

### Create DiagramPilot Templates

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/examples.md

Commands to create new DiagramPilot source files using predefined templates. Each command generates a *.dp.yaml file and suggests subsequent validation and rendering commands.

```bash
diagrampilot create docs/architecture.dp.yaml --template architecture
diagrampilot create docs/login-flow.dp.yaml --template flow
diagrampilot create docs/packages.dp.yaml --template package-map
diagrampilot create docs/system-context.dp.yaml --template system-context
diagrampilot create docs/service-map.dp.yaml --template service-map
```

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

### Good Error Message Example

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/error-repair.md

A high-quality error message that provides context, the problematic element, and specific repair suggestions.

```text
edges[0].from references unknown node "client". Add a node with id "client" or change the edge to reference one of: web_app, api_gateway.
```

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

### List Available Icons

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/icons.md

Use the local CLI to list all supported packaged Lucide icon references. This command prints one `lucide:<name>` reference per line in stable order.

```bash
diagrampilot icons list
```

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

### Invalid Node IDs in DiagramSpec

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/spec.md

Examples of IDs that do not conform to the DiagramSpec ID pattern, including those with hyphens, uppercase letters, or leading numbers.

```text
node1
boxA
new-api-gateway!!!
API Gateway
1_api_gateway
api__gateway
```

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

### Valid Node IDs in DiagramSpec

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/spec.md

Examples of valid node, edge, and group IDs that adhere to the lowercase snake case pattern required by DiagramSpec.

```text
api_gateway
orders_service
orders_db
web_app_to_api_gateway
```

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

### Validate DiagramPilot Source File

Source: https://github.com/stienswout/diagrampilot/blob/main/README.md

Validates the correctness of a DiagramPilot source file. Use --json to get validation results in JSON format.

```bash
diagrampilot validate docs/architecture.dp.yaml
```

```bash
diagrampilot validate docs/architecture.dp.yaml --json
```

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

### Run Demo Workflow Commands

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/quickstart.md

Execute these commands from the demo project directory to run the workflow. These commands are used for checking, inspecting, and linting DiagramPilot source files.

```bash
cd demo-projects/checkout
diagrampilot check
diagrampilot inspect
diagrampilot lint docs/architecture.dp.yaml
```

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

### Manage Icons

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/index.md

Lists available icons or searches the icon database.

```bash
diagrampilot icons list
diagrampilot icons search database
```

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

### List Packaged Icons

Source: https://github.com/stienswout/diagrampilot/blob/main/README.md

Prints all packaged `lucide:*` icon references in a stable, sorted order. This command is useful for discovering available icons.

```bash
icons list
```

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

### Run Local DiagramPilot CLI

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/quickstart.md

Execute the local DiagramPilot CLI if it's not linked on your system's PATH. Navigate to the demo project directory before running this command.

```bash
node ../../packages/cli/dist/index.js
```

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

### DiagramPilot CLI Commands

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/examples.md

Demonstrates common DiagramPilot CLI commands for validating, rendering, and exporting diagrams from a YAML file. Also shows how to check a directory of diagrams.

```bash
diagrampilot validate examples/system-context/system-context.dp.yaml
diagrampilot render examples/system-context/system-context.dp.yaml --out examples/system-context/system-context.svg
diagrampilot export examples/system-context/system-context.dp.yaml --format mermaid
diagrampilot check examples/system-context
```

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

### Validate Broken Architecture Diagram

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/examples.md

Validates a intentionally broken DiagramPilot YAML file to practice repair. This example highlights an edge referencing a non-existent node.

```bash
diagrampilot validate docs/broken-architecture.dp.yaml
```

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

### List Available Icons

Source: https://github.com/stienswout/diagrampilot/blob/main/README.md

Lists all available icons that can be used in diagrams.

```bash
diagrampilot icons list
```

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

### Inspect DiagramPilot Project Inventory

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/quickstart.md

Emits a concise, read-only inventory of the DiagramPilot project for humans. Use --json to emit stable inventory for agents.

```bash
diagrampilot inspect
diagrampilot inspect demo-projects/checkout --json
```

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

### Render Node Neighborhood

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/quickstart.md

Renders a diagram centered around a specific node (Stable ID) with a defined depth for its neighborhood. Useful for starting reviews from a specific component.

```bash
diagrampilot render docs/architecture.dp.yaml --around orders_service --depth 1 --out docs/architecture-orders-service.svg
```

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

### Create and Update DiagramPilot Diagrams

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/agent-workflow.md

Use these commands to create new DiagramPilot source files from templates, format existing ones, and validate their structure. Ensure the source file exists before using format, validate, or fix.

```bash
diagrampilot create docs/architecture.dp.yaml --template architecture
diagrampilot create docs/system-context.dp.yaml --template system-context
diagrampilot create docs/service-map.dp.yaml --template service-map
diagrampilot format docs/architecture.dp.yaml
diagrampilot validate docs/architecture.dp.yaml
diagrampilot fix docs/architecture.dp.yaml --json
diagrampilot lint docs/architecture.dp.yaml
diagrampilot inspect docs --json
diagrampilot render docs/architecture.dp.yaml --out docs/architecture.svg
diagrampilot check
```

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

### Import Diagram Files

Source: https://github.com/stienswout/diagrampilot/blob/main/README.md

Imports diagrams from various formats (Mermaid, D2, DOT) into DiagramPilot source files. Specify the input path, format, and output path.

```bash
diagrampilot import docs/legacy.mmd --format mermaid --out docs/imported.dp.yaml
```

```bash
diagrampilot import docs/legacy.d2 --format d2 --out docs/imported-d2.dp.yaml
```

```bash
diagrampilot import docs/legacy.dot --format dot --out docs/imported-dot.dp.yaml
```

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

### Run DiagramPilot Generator and Check

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/integrations.md

Execute the DiagramPilot repository-wide generator followed by a check. This is useful for repositories with configured outputs.

```bash
diagrampilot generate
diagrampilot check
```

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

### One-Off Use with Alternative Package Managers

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/installation.md

Execute DiagramPilot commands using `dlx` or `bunx` for one-off usage with pnpm, yarn, or bun.

```bash
pnpm dlx diagrampilot check
```

```bash
yarn dlx diagrampilot check
```

```bash
bunx diagrampilot check
```

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

### Validate DiagramPilot Source with JSON Output

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/error-repair.md

Use the `--json` flag with `diagrampilot validate` to get structured, agent-readable output for validation errors. This is useful for automated error processing.

```bash
diagrampilot validate docs/architecture.dp.yaml --json
```

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

### Render Overview CLI

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/quickstart.md

Renders a one-off overview artifact without edge labels. This is useful for generating quick visualizations without modifying the source file.

```bash
diagrampilot render <path> --hide-edge-labels --out <artifact.svg>
```

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

### JSON Validation Output Example

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/error-repair.md

This JSON output provides structured details about a validation error, including the file, status, error path, message, bad value, expected format, and a repair suggestion.

```json
{
  "file": "docs/checkout.dp.yaml",
  "ok": false,
  "errors": [
    {
      "path": "edges[0].from",
      "message": "edges[0].from references unknown node \"storefront\".",
      "badValue": "storefront",
      "expected": "One of: web_app, api_gateway.",
      "suggestion": "Add a node with id \"storefront\" or change edges[0].from to an existing node ID."
    }
  ]
}
```

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

### Inspect and Check DiagramPilot for Read-only Agent Review

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/integrations.md

Use this inspect and check recipe for read-only agent reviews of DiagramPilot files. It helps identify issues without making changes.

```bash
diagrampilot inspect docs --json
diagrampilot lint docs/architecture.dp.yaml --json
diagrampilot check docs --json
```

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

### Inventory Prompt for DiagramPilot

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/prompting.md

Prompt to inspect DiagramPilot files and summarize repository contents without editing. It requests a JSON output for detailed analysis.

```text
Run diagrampilot inspect --json for this repository and summarize the
DiagramPilot Source Files, Stable IDs, topology, and missing or stale artifact
expectations. Do not edit or generate files.
```

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

### Render DiagramPilot File to PNG

Source: https://github.com/stienswout/diagrampilot/blob/main/README.md

Renders a DiagramPilot source file to a PNG image. Specify the output path and format.

```bash
diagrampilot render docs/architecture.dp.yaml --format png --out docs/architecture.png
```

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

### Search for Icons

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/icons.md

Use the local CLI to search for packaged Lucide icon names by substring. This command does not use the network and prints matching `lucide:<name>` references.

```bash
diagrampilot icons search database
```

```bash
diagrampilot icons search server
```

```bash
diagrampilot icons search data
```

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

### Configure npm Scripts for DiagramPilot

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/installation.md

Add a script to the consuming repository's `package.json` to easily run DiagramPilot commands like `diagrampilot check`.

```json
{
  "scripts": {
    "diagrams:check": "diagrampilot check"
  }
}
```

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

### Lint DiagramPilot Source File

Source: https://github.com/stienswout/diagrampilot/blob/main/README.md

Validates a single DiagramPilot source file and reports readability warnings without modifying files. Use --json to see planning mode output.

```bash
diagrampilot lint docs/architecture.dp.yaml
```

```bash
diagrampilot lint docs/architecture.dp.yaml --json
```

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

### Monorepo Overview Export and Check

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/examples.md

Commands for validating, rendering, and exporting a monorepo overview DiagramPilot source file. Demonstrates export to Mermaid, D2, and DOT formats, along with a codebase check.

```bash
diagrampilot validate examples/monorepo-overview/monorepo-overview.dp.yaml
diagrampilot render examples/monorepo-overview/monorepo-overview.dp.yaml --out examples/monorepo-overview/monorepo-overview.svg
diagrampilot export examples/monorepo-overview/monorepo-overview.dp.yaml --format mermaid
diagrampilot export examples/monorepo-overview/monorepo-overview.dp.yaml --format d2 --out examples/monorepo-overview/monorepo-overview.d2
diagrampilot export examples/monorepo-overview/monorepo-overview.dp.yaml --format dot --out examples/monorepo-overview/monorepo-overview.dot
diagrampilot check examples/monorepo-overview
```

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

### Uninstall DiagramPilot with Package Managers

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/installation.md

Verified package-manager equivalents for uninstalling DiagramPilot.

```bash
pnpm remove diagrampilot
```

```bash
yarn remove diagrampilot
```

```bash
bun remove diagrampilot
```

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

### Search Packaged Icons

Source: https://github.com/stienswout/diagrampilot/blob/main/README.md

Searches for Lucide icon names locally based on a query. It prints matching `lucide:*` references, one per line. Use this to find specific icons by name.

```bash
icons search <query>
```

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

### Import Diagram from Text

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/spec.md

Use the `diagrampilot import` command to convert diagrams from Mermaid, D2, or DOT formats into DiagramPilot's YAML format. Options include specifying the input format, output file, and whether to overwrite existing files or output JSON.

```bash
diagrampilot import docs/legacy.mmd --format mermaid --out docs/imported.dp.yaml
```

```bash
diagrampilot import docs/legacy.mmd --format mermaid --out docs/imported.dp.yaml --json
```

```bash
diagrampilot import docs/legacy.mmd --format mermaid --out docs/imported.dp.yaml --force
```

```bash
diagrampilot import docs/legacy.d2 --format d2 --out docs/imported-d2.dp.yaml
```

```bash
diagrampilot import docs/legacy.dot --format dot --out docs/imported-dot.dp.yaml
```

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

### Import and Export Diagrams

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/index.md

Converts legacy diagram formats (Mermaid, D2, DOT) into DiagramPilot YAML sources. Exports DiagramPilot sources to Mermaid, D2, or DOT formats, with options for specific views and output files.

```bash
diagrampilot import docs/legacy.mmd --format mermaid --out docs/imported.dp.yaml
diagrampilot import docs/legacy.d2 --format d2 --out docs/imported-d2.dp.yaml
diagrampilot import docs/legacy.dot --format dot --out docs/imported-dot.dp.yaml
diagrampilot export docs/architecture.dp.yaml --format mermaid
diagrampilot export docs/architecture.dp.yaml --view runtime --format mermaid --out docs/architecture-runtime.mmd
diagrampilot export docs/architecture.dp.yaml --format d2 --out docs/architecture.d2
diagrampilot export docs/architecture.dp.yaml --format dot --out docs/architecture.dot
```

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

### Recommended Agent Instruction for DiagramPilot

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/prompting.md

Use this general instruction for creating or updating DiagramPilot diagrams. It emphasizes using structured source files, repository checks, stable IDs, validation, and rendering SVG artifacts.

```text
Create or update a DiagramPilot diagram in this repository.
Use a structured .dp.yaml source file, run the read-only repo check and inspect
inventory first, preserve stable IDs, validate the spec, and render an SVG
artifact with an explicit --out path. Render PNG with `--format png` only when
a raster artifact is needed. Do not hand-edit generated artifacts.
```

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

### Format DiagramPilot Source File

Source: https://github.com/stienswout/diagrampilot/blob/main/README.md

Applies canonical formatting to a DiagramPilot source file.

```bash
diagrampilot format docs/architecture.dp.yaml
```

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

### Import DOT Diagram

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/quickstart.md

Imports a DOT graph into a DiagramPilot YAML file. The --out flag specifies the output file path.

```bash
diagrampilot import docs/legacy.dot --format dot --out docs/imported-dot.dp.yaml
```

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

### Inspect DiagramPilot Files

Source: https://github.com/stienswout/diagrampilot/blob/main/README.md

Reports metadata about DiagramPilot source files, including title, direction, object counts, and artifact expectations. Use --json for agent-specific output, including diagnostics.

```bash
diagrampilot inspect
```

```bash
diagrampilot inspect docs --json
```

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

### Export Diagram to File CLI

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/quickstart.md

Writes an exported text format (Mermaid, D2, or DOT) to a specified file. Use this to save the exported diagram content to disk.

```bash
diagrampilot export <path> --format mermaid|d2|dot --out <path>
```

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

### One-Off Use of DiagramPilot Commands

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/installation.md

Run DiagramPilot commands directly using `npx` for quick checks, demos, or repair loops without adding it as a repository dependency.

```bash
npx diagrampilot check
```

```bash
npx diagrampilot create docs/architecture.dp.yaml --template architecture
```

```bash
npx diagrampilot create docs/system-context.dp.yaml --template system-context
```

```bash
npx diagrampilot create docs/service-map.dp.yaml --template service-map
```

```bash
npx diagrampilot inspect
```

```bash
npx diagrampilot validate docs/architecture.dp.yaml
```

```bash
npx diagrampilot format docs/architecture.dp.yaml
```

```bash
npx diagrampilot render docs/architecture.dp.yaml --out docs/architecture.svg
```

```bash
npx diagrampilot render docs/architecture.dp.yaml --format png --out docs/architecture.png
```

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

### Architecture Prompt for DiagramPilot

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/prompting.md

Prompt to create a new architecture diagram file. Specifies the output path for the source and the SVG, and details requirements for IDs, grouping, and edge labels.

```text
Create docs/architecture.dp.yaml showing the main runtime components in this
project. Use stable lowercase snake case IDs, group related services, include
labeled edges for major data flows, validate the spec, and render
docs/architecture.svg.
```

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

### Check and Inspect DiagramPilot Project

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/index.md

Performs read-only repository reviews and CI checks. `inspect` provides source inventory, topology, and artifact expectations.

```bash
diagrampilot check
diagrampilot inspect
diagrampilot check docs --json
diagrampilot inspect docs --json
```

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

### DiagramPilot CLI Commands for Inspection and Rendering

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/spec.md

Commands to inspect DiagramPilot files, render views to SVG, and export to Mermaid format. These operations do not mutate the source file.

```bash
diagrampilot inspect docs --json
```

```bash
diagrampilot render docs/architecture.dp.yaml --view runtime --out docs/architecture-runtime.svg
```

```bash
diagrampilot export docs/architecture.dp.yaml --view runtime --format mermaid --out docs/architecture-runtime.mmd
```

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

### Coding-Agent Workflow for DiagramPilot Tasks

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/integrations.md

A step-by-step workflow for a coding agent to update DiagramPilot source files. It emphasizes inspection, validation, formatting, linting, rendering, and checking, while avoiding manual edits of generated artifacts.

```text
Update docs/architecture.dp.yaml to include the new checkout worker.

Use this workflow:
1. Run diagrampilot inspect docs --json and identify the existing Stable IDs.
2. Edit only docs/architecture.dp.yaml.
3. Run diagrampilot format docs/architecture.dp.yaml.
4. Run diagrampilot validate docs/architecture.dp.yaml --json.
5. Run diagrampilot lint docs/architecture.dp.yaml --json.
6. Run diagrampilot render docs/architecture.dp.yaml --out docs/architecture.svg.
7. Run diagrampilot check docs --json.

Do not hand-edit generated SVG, PNG, Mermaid, D2, DOT, or Markdown outputs.
```

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

### Import Mermaid Diagram

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/quickstart.md

Imports a Mermaid flowchart into a DiagramPilot YAML file. The --out flag specifies the output file path.

```bash
diagrampilot import docs/legacy.mmd --format mermaid --out docs/imported.dp.yaml
```

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

### Compare DiagramPilot Source Files

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/agent-workflow.md

Use `diff` to compare two DiagramPilot source files, reporting changes in nodes, edges, and groups. JSON output is for agents and CI, while SVG output generates a diff diagram.

```bash
diagrampilot diff main.dp.yaml branch.dp.yaml --json
diagrampilot diff main.dp.yaml branch.dp.yaml --out review/architecture-diff.svg
diagrampilot inspect docs --json
diagrampilot check
```

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

### Run Canonical Workflow Commands

Source: https://github.com/stienswout/diagrampilot/blob/main/llms.txt

Execute the main DiagramPilot commands for inspecting, creating, formatting, validating, fixing, linting, searching icons, rendering, and importing/exporting diagrams. These commands can be run from the repository root or a scoped project directory.

```bash
diagrampilot inspect
diagrampilot create docs/architecture.dp.yaml --template architecture
diagrampilot create docs/system-context.dp.yaml --template system-context
diagrampilot create docs/service-map.dp.yaml --template service-map
diagrampilot format docs/architecture.dp.yaml
diagrampilot validate docs/architecture.dp.yaml
diagrampilot fix docs/architecture.dp.yaml --json
diagrampilot lint docs/architecture.dp.yaml
diagrampilot icons search database
diagrampilot inspect docs --json
diagrampilot render docs/architecture.dp.yaml --out docs/architecture.svg
diagrampilot render docs/architecture.dp.yaml --view runtime --out docs/architecture-runtime.svg
diagrampilot render docs/architecture.dp.yaml --format png --out docs/architecture.png
diagrampilot import docs/legacy.mmd --format mermaid --out docs/imported.dp.yaml
diagrampilot import docs/legacy.d2 --format d2 --out docs/imported-d2.dp.yaml
diagrampilot import docs/legacy.dot --format dot --out docs/imported-dot.dp.yaml
diagrampilot export docs/architecture.dp.yaml --format mermaid
diagrampilot export docs/architecture.dp.yaml --view runtime --format mermaid --out docs/architecture-runtime.mmd
diagrampilot export docs/architecture.dp.yaml --format d2 --out docs/architecture.d2
diagrampilot export docs/architecture.dp.yaml --format dot --out docs/architecture.dot
diagrampilot check
```

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

### Validate and Render Codebase Architecture

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/examples.md

Commands to validate a DiagramPilot source file for codebase architecture and render it to an SVG file. Also includes commands for exporting to Mermaid format and checking the codebase.

```bash
diagrampilot validate examples/codebase-architecture/codebase-architecture.dp.yaml
diagrampilot render examples/codebase-architecture/codebase-architecture.dp.yaml --out examples/codebase-architecture/codebase-architecture.svg
diagrampilot export examples/codebase-architecture/codebase-architecture.dp.yaml --format mermaid
diagrampilot check examples/codebase-architecture
```

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

### Render DiagramPilot Diagrams

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/index.md

Renders diagrams to SVG or PNG. Supports different views, grouping, node neighborhoods, hiding edge labels, and specific output formats.

```bash
diagrampilot render docs/architecture.dp.yaml --out docs/architecture.svg
diagrampilot render docs/architecture.dp.yaml --view runtime --out docs/architecture-runtime.svg
diagrampilot render docs/architecture.dp.yaml --group checkout_runtime --out docs/architecture-checkout-runtime.svg
diagrampilot render docs/architecture.dp.yaml --around orders_service --depth 1 --out docs/architecture-orders-service.svg
diagrampilot render docs/architecture.dp.yaml --hide-edge-labels --out docs/architecture-overview.svg
diagrampilot render docs/architecture.dp.yaml --format png --out docs/architecture.png
```

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

### Generate DiagramPilot Artifacts

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/index.md

Generates artifacts based on the DiagramPilot configuration and sources.

```bash
diagrampilot generate
```

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

### Pull Request Architecture Review Workflow

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/examples.md

Commands to validate, render, export to Mermaid, and check a DiagramPilot source file for pull request architecture review. Useful for reviewing changes in source files, artifacts, and workflow checks.

```bash
diagrampilot validate examples/pull-request-architecture-review/pull-request-architecture-review.dp.yaml
diagrampilot render examples/pull-request-architecture-review/pull-request-architecture-review.dp.yaml --out examples/pull-request-architecture-review/pull-request-architecture-review.svg
diagrampilot export examples/pull-request-architecture-review/pull-request-architecture-review.dp.yaml --format mermaid
diagrampilot check examples/pull-request-architecture-review
```

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

### YAML Repair for Unknown Icon

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/error-repair.md

Shows the correct YAML format for the 'icon' property, including the proper prefix for Lucide icons.

```yaml
icon: lucide:database
```

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

### Export Diagram to Stdout CLI

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/quickstart.md

Prints an exported text format (Mermaid, D2, or DOT) to standard output. Use this for piping the output to other tools or for quick inspection.

```bash
diagrampilot export <path> --format mermaid|d2|dot
```

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

### Export Prompt for DiagramPilot

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/prompting.md

Prompt to export a DiagramPilot diagram to DOT format and display the output. It explicitly states not to write an exported file unless requested.

```text
Export docs/architecture.dp.yaml to DOT and show me the output. Do not write an
exported file unless I ask for one.
```

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

### Validate and Render Dependency Map

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/examples.md

Commands to validate a DiagramPilot source file for a dependency map and render it to an SVG file. Includes options for exporting to Mermaid and checking the package dependencies.

```bash
diagrampilot validate examples/dependency-map/dependency-map.dp.yaml
diagrampilot render examples/dependency-map/dependency-map.dp.yaml --out examples/dependency-map/dependency-map.svg
diagrampilot export examples/dependency-map/dependency-map.dp.yaml --format mermaid
diagrampilot check examples/dependency-map
```

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

### Render DiagramPilot Source to SVG

Source: https://github.com/stienswout/diagrampilot/blob/main/docs-public/agents/quickstart.md

Render a DiagramPilot source file into an SVG artifact. Use the `--out` flag to specify the output file path for the generated SVG.

```bash
diagrampilot render docs/architecture.dp.yaml --out docs/architecture.svg
```

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

### Export DiagramPilot File

Source: https://github.com/stienswout/diagrampilot/blob/main/README.md

Exports a DiagramPilot source file to other formats like Mermaid, D2, or DOT. Supports specifying view modes and output paths.

```bash
diagrampilot export docs/architecture.dp.yaml --format mermaid
```

```bash
diagrampilot export docs/architecture.dp.yaml --view runtime --format mermaid --out docs/architecture-runtime.mmd
```

```bash
diagrampilot export docs/architecture.dp.yaml --format d2 --out docs/architecture.d2
```

```bash
diagrampilot export docs/architecture.dp.yaml --format dot --out docs/architecture.dot
```