---
name: project-diagramming-mermaid
description: Use Mermaid to create or update a project diagram. Outline a codebase, project, or system using Mermaid syntax inside standard Markdown fenced blocks, then render it to PNG/SVG (and keep the Mermaid source) under the project's docs/ directory. Use when the user asks to map, outline, diagram, or visualize a codebase/project/system, or to update an existing project diagram. After producing the Mermaid diagram, prompt the user to also create or update the Archify doc. Per-project only — never global.
version: 1.0.0
---

# project-diagramming-mermaid

Diagram a codebase or project with Mermaid, render to image files, all under the project's `docs/` directory.

## When to use

- User asks to outline/map/visualize a codebase, project, system, or data flow at a high level.
- User asks to update an existing Mermaid project diagram.
- User asks to document the home network, Docker containers, or any infra — but see the Obsidian note below.

## Workflow (overview)

1. **Scope** — clarify target: whole project, a subsystem, or a specific flow. Focus on high-level dependencies and data flows. Avoid complex layout overlaps (prefer `<project>/docs/` artifacts that are readable, not exhaustive).
2. **Author Mermaid source** — write the diagram as a fenced ` ```mermaid ` block in the appropriate Markdown doc. See "Where the source lives" below.
3. **Save source** — write the Mermaid source to `<project>/docs/<topic>.mmd`.
4. **Render** — render to `<project>/docs/diagrams/<topic>.png` (and optionally `.svg`) via `mmdc`.
5. **Prompt Archify** — after the Mermaid diagram is done, ask the user: "Create/update the Archify doc for this too?" (see `project-diagramming-archify` skill). Do this automatically, not just when asked.

## Where the source lives

Artifacts for a project go **under that project's `docs/`** — everything is per-project in this setup:

- **Source (single source of truth):** `<project>/docs/<topic>.mmd`
- **Markdown doc with the fenced block:** the project's main doc(s), e.g. `<project>/docs/README.md`, `<project>/docs/<topic>.md`, `<project>/README.md` — anywhere the user wants the diagram visible (Obsidian renders ` ```mermaid ` natively).
- **Rendered images:** `<project>/docs/diagrams/<topic>.png` (+ `.svg` when requested)

If `<project>/docs/` does not exist, create it. Never write diagram artifacts outside the project directory.

## Writing good Mermaid

High-level, readable diagrams — not layout spaghetti:

- **Flowchart** (`graph TD` / `flowchart LR`) for dependencies and data flows. Use `A --> B` for dependency/data flow, `A -.-> B` for optional, subgraphs for grouping.
- **Sequence** (`sequenceDiagram`) for request/API flows with participants.
- **Class** (rare) for type structure; **ER** (`erDiagram`) for data model; **stateDiagram-v2** for lifecycle.
- Keep node labels short. Add them with `A[Label text]`. Edge labels `A -->|"verb"| B`.
- Avoid deeply nested subgraphs and crossing edges — if it gets busy, split into multiple diagrams per topic.
- Prefer `flowchart LR` for wide dependency chains (reads better on screens), `graph TD` for hierarchies.

Example:

```mermaid
flowchart LR
  U[User] --> W[Web UI] --> API[API Gateway] --> DB[(Postgres)]
  API --> Q[Message Queue] --> W1[Worker] --> DB
```

## Rendering with mmdc (mermaid-cli)

- `mmdc` is provided by **nixpkgs `mermaid-cli`** (`pkgs.mermaid-cli`, v11.16.0) installed in `home.packages` on .27 / .13 / .51. It bundles its own Chromium from the Nix store — deterministic, offline, private. See system-architect skill for machine details.
- Check availability: `which mmdc`. If missing, it's a Nix install (home.nix `home.packages`) — NOT an npm install (Nix store is read-only). Tell the user.

Commands:

```bash
# PNG (default 4x for crispness with --scale; choose scale for size)
mmdc -i <project>/docs/<topic>.mmd -o <project>/docs/diagrams/<topic>.png --scale 2 -b white

# SVG (vector, good for docs)
mmdc -i <project>/docs/<topic>.mmd -o <project>/docs/diagrams/<topic>.svg

# Use a theme/style: -t dark|neutral|forest|base
mmdc -i <project>/docs/<topic>.mmd -o <project>/docs/diagrams/<topic>.png --theme neutral
```

After rendering, verify the file exists and is non-trivial in size (a few KB+). If mmdc fails, read the error — most failures are syntax errors in the diagram; fix and re-run.

## Prompt the user for the Archify follow-up

After a successful Mermaid diagram, always ask (or offer via the flow below):

> "Diagram saved to `<project>/docs/diagrams/<topic>.png`. Create/update the Archify doc too?"

If yes (or user asked originally), invoke the **project-diagramming-archify** skill — Archify accepts Mermaid (flowchart → workflow/architecture, sequence → sequence, stateDiagram → lifecycle) directly, so the handoff is cheap.

## Per-project activation

This skill is activated **per project** with `/config-add skill project-diagramming-mermaid` (never globally — reduces context bloat). If it's not available in the current project, that's expected; assets activate per project via the pi-config extension.

## Related

- `project-diagramming-archify` — interactive HTML architecture maps (the client-facing output).
- `pi-mermaid` extension — renders ` ```mermaid ` blocks as ASCII in the TUI for quick in-chat preview + parser warnings/errors.
- `nixos-workflow` skill — how Pi assets are managed (Gitea `pi-config`, per-machine clones).
- `system-architect` skill — machine/infra reference for .27/.13/.51 etc.

## Obsidian documentation (context, if asked)

These tools (Mermaid, Archify, Vikunja, Outline) are documented as tools in Obsidian:
`300 areas/360 Dev-Ops Network Computers/Dev-Ops Tooling — Mermaid, Archify, Vikunja & Outline.md`, plus `Home Network Map Overview.md` and `Docker Containers.md` link to it. Do not recreate diagram versions of the network/container docs.