# DiagramPilot

> DiagramPilot is a local-first, repo-native diagram compiler for AI coding
> agents. It helps agents create, update, check, lint, validate, repair,
> render, and export software architecture diagrams from structured
> `*.dp.yaml` source files inside a repository.

DiagramPilot uses DiagramSpec as its source model. A DiagramPilot Source File is
the editable artifact. Rendered SVG or PNG and exported Mermaid, D2, or DOT
text are Derived Artifacts.

DiagramPilot Source Files are YAML-only. `*.dp.json` is not a DiagramPilot
Source File path. Repo discovery ignores JSON source files, explicit commands
reject non-YAML source paths generically, and DiagramPilot does not provide a
JSON-to-YAML migration command. JSON remains valid for `--json` CLI output, the
DiagramSpec JSON Schema, SVG provenance metadata, package manifests, and other
tooling surfaces.

Public documentation is hosted under `https://diagrampilot.com`. The canonical
LLM entrypoint is `https://diagrampilot.com/llms.txt`.

Package install does not create local agent docs.
Normal `diagrampilot init` does not create local agent docs.
`diagrampilot init --docs` is opt-in for managed repository guidance.
Normal `diagrampilot init` does not create Repo Workflow Configuration.
`diagrampilot init --config` is opt-in for a minimal
`diagrampilot.config.yaml`.

## Do

- Inspect the repository first with `diagrampilot inspect` or
  `diagrampilot inspect --json`.
- Edit DiagramPilot Source Files at `*.dp.yaml`.
- Preserve Stable IDs when labels, descriptions, groups, or edges change.
- Use `diagrampilot format` to keep source YAML canonical.
- Use `diagrampilot validate` for repairable validation diagnostics.
- Use `diagrampilot fix --json` to inspect deterministic source-only repair
  plans before applying `diagrampilot fix`.
- Use `diagrampilot lint` for read-only readability warnings on one valid
  DiagramPilot Source File.
- Use `diagrampilot render`, `diagrampilot export`, or `diagrampilot generate`
  to regenerate Derived Artifacts from source.
- Use `diagrampilot check` as the read-only repo review/CI command before
  committing diagram changes.

## Do Not

- Do not hand-edit generated SVG, PNG, Mermaid, D2, or DOT outputs.
- Do not treat generated Markdown embed files as source.
- Do not create `*.dp.json` source files.
- Do not add hosted workspace dependencies to the local diagram workflow.
- Do not replace DiagramSpec source with raw Mermaid, D2, DOT, SVG, or PNG.

## Canonical Workflow

Run the golden path from the repository root or from 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
```

Optional MCP adapter package:

Use the `@diagrampilot/mcp` package when a local MCP client needs DiagramPilot
schema, docs, examples, validation, check, export, render, and prompt helpers.
The adapter is separate so the core `diagrampilot` CLI stays smaller for
normal authoring and CI workflows.

```bash
diagrampilot-mcp
```

Current Source Creation path:

```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
```

Maintained Source Creation templates are `architecture`, `flow`, `package-map`,
`system-context`, and `service-map`.

Mermaid, D2, and DOT are diagram text formats. DiagramPilot is an agent-safe
compiler and workflow that keeps DiagramSpec source validated, reviewable, and
able to complement those text renderers. Import is a best-effort adoption path
from Mermaid flowcharts, D2 diagrams, and DOT graphs into new `*.dp.yaml`
files; inspect the fidelity report before treating imported output as
canonical.

## Important Links

### Public Documentation

- [Agent workflow](https://diagrampilot.com/docs/agents/agent-workflow.md): Canonical Agent Authoring Loop for DiagramPilot Source Files, Stable IDs, `inspect --json`, SVG rendering, Artifact Freshness checks, nightly testing, and Windows forward-slash paths.
- [Checkout demo quickstart](https://diagrampilot.com/docs/agents/quickstart.md): Canonical beginner workflow for repo checks, source repair, SVG and PNG rendering, exports, and copying the source/render pattern into another repository.
- [Installation and removal](https://diagrampilot.com/docs/agents/installation.md): Canonical package install paths, uninstall commands, and repository cleanup guidance.
- [MCP guide](https://diagrampilot.com/docs/agents/mcp.md): Model Context Protocol server launch and client configuration guidance.
- [DiagramSpec](https://diagrampilot.com/docs/agents/spec.md): Structured source model for diagrams.
- [Icon reference](https://diagrampilot.com/docs/agents/icons.md): Local packaged `lucide:*` icon discovery with `diagrampilot icons list` and `diagrampilot icons search <query>`.
- [Error repair](https://diagrampilot.com/docs/agents/error-repair.md): How agents should interpret and fix validation errors.
- [Examples](https://diagrampilot.com/docs/agents/examples.md): Canonical diagram examples.
- [Prompting guide](https://diagrampilot.com/docs/agents/prompting.md): Recommended instructions for agents using DiagramPilot.
- [Comparisons and adjacent tools](https://diagrampilot.com/docs/agents/comparisons.md): When to use DiagramPilot with or instead of Mermaid, D2, Graphviz/DOT, dependency-cruiser, and React Flow.
- [Integrations and agent recipes](https://diagrampilot.com/docs/agents/integrations.md): GitHub Actions validation and coding-agent inspect, repair, render, and check workflows.

### Public Artifacts

- [DiagramSpec v1 JSON Schema](https://diagrampilot.com/schema/diagramspec-v1.schema.json): DiagramSpec v1 JSON Schema is a generated, committed public helper for machine-readable source shape. It does not replace core validation.
- [DiagramPilot wordmark](https://diagrampilot.com/brand/diagrampilot-logo.svg): Official wordmark for light surfaces where the full DiagramPilot name remains legible.
- [DiagramPilot light wordmark](https://diagrampilot.com/brand/diagrampilot-logo-light.svg): Official light-text wordmark for dark surfaces where the full DiagramPilot name remains legible.
- [DiagramPilot mark](https://diagrampilot.com/brand/diagrampilot-mark.svg): Official mark for favicon and icon-sized placements.
- [MIT Code License](https://github.com/StiensWout/DiagramPilot/blob/main/LICENSE): License for DiagramPilot code and repository materials.
- [GitHub repository](https://github.com/StiensWout/DiagramPilot): Source repository.