Diagram from existing code

Arguments: $ARGUMENTS

The diagram must describe what the code actually does, not what it ought to do. Every node and edge has to trace back to a file you read.

Hard rule: delegate the scan

Never read the repository tree from the main thread. Dispatch the mermaid-source-scout subagent and work from the structured inventory it returns.

Why this is a rule and not a preference: scanning a repo for diagram material means opening many files and keeping little of each. Doing that inline fills the context with source you will not use, and by drafting time the details you needed have been squeezed out. The scout reads widely, returns a compact inventory with file:line evidence, and its context is discarded.

Read files directly only when the user names one or two specific files.

Workflow

1. Resolve the mode

If the first argument is a mode, use it. Otherwise detect candidates and ask - upstream showed a quick-pick widget here; in a CLI you just ask, which is better because you can explain the trade-off.

If several modes apply, say what each would show and let the user pick. Do not silently pick one.

2. Scope the files, and confirm before scanning

Confirm the file list before the scan when the scope is broad - a whole-repo c4 run on a large monorepo is expensive, and the user may only care about one package. Skip the confirmation when the scope is already obvious (they named the file, or there is exactly one docker-compose.yml).

Never diagram vendored or generated code: node_modules/, vendor/, dist/, build/, .venv/, target/, __pycache__/, and anything matched by .gitignore.

3. Dispatch the scout

Give it the mode, the scoped paths, and the per-mode extraction checklist from the reference file. Require: nodes with kind and label, edges with direction and label, groups, and file:line evidence per claim. Require it to state what it could not find.

4. Draft, validate, render

Hand the inventory into the core /mermaid loop: fetch the syntax doc for the target type, draft, validate_and_render_mermaid_diagram, then present source plus link. All the drafting guidance, pitfalls and output format live there - this skill supplies the content, not a second renderer.

For cloud, call search_mermaid_icons for the specific services found. Do not guess icon IDs; a wrong ID breaks the render or silently degrades to a placeholder. With no lookup available, use the five built-ins (cloud, database, disk, internet, server) and say that you did.

5. Record what the diagram documents

When writing a diagram to a file, add a provenance comment as the first line after the type keyword:

%% mermaid:sources: infra/main.tf, infra/rds.tf

This convention is this plugin's own, not an upstream mechanism - /mermaid:dependency-map and the diagram-drift-auditor subagent read it to tell whether a diagram has gone stale. A %% comment is used rather than YAML frontmatter because an unknown frontmatter key risks the Mermaid parser, while %% is safe by construction.

Upstream's equivalent is an id: frontmatter key plus its closed-source GitHub Sync App. That is a different mechanism and this plugin does not implement it.

Regenerating a drifted diagram

When the ask is "this diagram is out of date":

1. Read the existing diagram and its %% mermaid:sources: line. Without one, infer the documented paths from node labels and say that you inferred them.
2. Dispatch diagram-drift-auditor, or scan the named sources directly if there are only a few.
3. Redraw, preserving every node ID and label that is still accurate. A regenerated diagram whose IDs all changed produces an unreviewable diff even when the picture is identical.
4. Show what changed: added, removed, renamed.

Upstream sends your source to a metered endpoint for this - a staged diff for modified files, full content for newly added ones. Here the source never leaves the machine and there are no credits to spend.

Per-mode references

• references/er-from-schema.md - entities, columns, cardinality
• references/cloud-from-iac.md - Terraform, CloudFormation, CDK, k8s
• references/docker-topology.md - services, networks, volumes, ports
• references/sequence-from-callchain.md - lifelines, ordering
• references/c4-levels.md - context / container / component

Honesty rules

• Never invent an edge to make a diagram look complete. A missing relationship is information.
• Mark inferred edges as inferred. If a service probably calls another because of a config key rather than a real call site, say so in the reply - not silently in a solid arrow.
• Report what was skipped. If the scout hit a file it could not parse, or the scope was truncated, the user needs to know the diagram is partial.
• A diagram of nothing is a valid result. If the detectors find no matching files, say so and offer /mermaid to draw from a description instead.