edsger 0.81.1 → 0.83.0

package/README.md

@@ -36,6 +36,69 @@ The agent detects the project's language(s), loads the matching rubric, inspects
 the code, scores every criterion with evidence, and edsger aggregates the
 weighted total into a 0–100 score and a letter grade.
 
+Every run is archived under `.edsger/benchmark/runs/<timestamp>/` and appended to
+`.edsger/benchmark/history.jsonl`, so the JSON data is committable and the
+dashboard can show history and trends over time.
+
+### `edsger serve` — dashboard (current, history, trends)
+
+Serve an interactive dashboard for the benchmark results in the current repo —
+overall score, category breakdown, per-criterion evidence, run history, and
+trend charts. Reads `.edsger/benchmark/`; writes nothing.
+
+```bash
+edsger serve                     # open the dashboard in your browser
+edsger serve --port 8080         # pick a port
+edsger serve --no-open           # just print the URL
+edsger benchmark --serve         # benchmark, then open the dashboard
+```
+
+### `edsger report --html <path>` — shareable export
+
+Export a **self-contained** HTML file (all data inlined, no server needed) for
+sharing or committing. HTML is only written when you ask for it.
+
+```bash
+edsger report --html report.html         # write a single shareable file
+edsger report --html report.html --open  # …and open it
+```
+
+### `edsger diagram` — generate diagrams from the code
+
+Analyse the repository, decide which professional diagrams actually fit **this**
+project (a library needs different diagrams than a microservice), and generate
+each as renderable **Mermaid**. Writes to `.edsger/diagrams/` (`diagrams.md` +
+`diagrams.json`, with each run archived under `runs/<timestamp>/`).
+
+```bash
+edsger diagram                   # generate diagrams for the current repo
+edsger diagram -C ./service      # …for another directory
+edsger diagram --serve           # generate, then open the diagram dashboard
+edsger diagram --only er-diagram,request-sequence   # just specific diagrams
+edsger diagram --json            # also print JSON to stdout
+```
+
+The agent detects the project's language(s), loads the matching diagram
+**catalog** (from [edsger-assets](https://github.com/stevenzg/edsger-assets),
+fully overridable), profiles the project, and emits diagrams grounded in real
+files: **C4** system-context/container/component/deployment, **module dependency**
+graphs, **class** & **domain models**, **ER** database schemas, **sequence**
+flows, **function flowcharts**, **state machines**, **data-flow**, **CI/CD
+pipelines**, and more — plus language-specific ones (React component trees, JPA
+entity models, goroutine pipelines…).
+
+The `diagrams.md` renders directly on GitHub. For an interactive, browsable view:
+
+```bash
+edsger diagram serve             # serve the diagram dashboard (renders Mermaid)
+edsger diagram report --html diagrams.html   # export a self-contained HTML file
+```
+
+The dashboard renders every diagram as Mermaid with per-diagram **zoom**, a
+**source/copy** toggle, and **SVG / PNG download**; each generated diagram also
+gets a static Mermaid sanity check whose warnings surface in the CLI, in
+`diagrams.md`, and on the card.
+
 ### `edsger pr-review <pr>` (requires `gh`)
 
 Review a pull request against the review standard. Previews by default; pass

package/assets/README.md

@@ -8,6 +8,9 @@ This repository is the canonical source of truth for:
   maintainability, testing, documentation, delivery, and language-specific quality.
 - **PR review standards** (`review/`) — what a reviewer (human or agent) should look
   for when reviewing a pull request, and how findings are prioritised.
+- **Diagram catalogs** (`diagrams/`) — the professional software diagrams (C4
+  architecture, ER, sequence, class, state, data-flow, deployment, and more), when
+  each applies to a project, and how to build it as renderable Mermaid.
 
 The content here encodes widely accepted engineering best practices (OWASP, the
 Twelve-Factor App, Google Engineering Practices, SLSA, Keep a Changelog, Semantic
@@ -18,9 +21,9 @@ These standards can be consumed three ways:
 
 1. **The [`edsger`](https://www.npmjs.com/package/edsger) CLI** — bundles these
    assets and runs them with the Claude Agent SDK.
-2. **As a Claude Code plugin** — `/benchmark`, `/pr-review`, `/pr-resolve` skills
-   that work inside Claude Code with no CLI install (see below).
-3. **Raw YAML** — point any tooling at the files in `benchmark/` and `review/`.
+2. **As a Claude Code plugin** — `/benchmark`, `/pr-review`, `/pr-resolve`, `/diagram`
+   skills that work inside Claude Code with no CLI install (see below).
+3. **Raw YAML** — point any tooling at the files in `benchmark/`, `review/`, and `diagrams/`.
 
 ## Use inside Claude Code (no CLI install)
 
@@ -32,10 +35,10 @@ plugin to get the skills as slash commands:
 /plugin install edsger@edsger-assets
 ```
 
-Then run `/benchmark`, `/pr-review`, or `/pr-resolve`. The skills read the same
-rubric YAML from this repo (`${CLAUDE_PLUGIN_ROOT}/benchmark/...`) and prefer the
-`edsger` CLI when it is installed, falling back to running natively with Claude
-Code's own tools.
+Then run `/benchmark`, `/pr-review`, `/pr-resolve`, or `/diagram`. The skills read
+the same YAML from this repo (`${CLAUDE_PLUGIN_ROOT}/benchmark/...`,
+`${CLAUDE_PLUGIN_ROOT}/diagrams/...`) and prefer the `edsger` CLI when it is
+installed, falling back to running natively with Claude Code's own tools.
 
 ## Layout
 
@@ -44,15 +47,17 @@ edsger-assets/
 ├── .claude-plugin/           # Claude Code plugin + marketplace manifests
 │   ├── plugin.json
 │   └── marketplace.json
-├── skills/                   # Claude Code skills (/benchmark, /pr-review, /pr-resolve)
+├── skills/                   # Claude Code skills (/benchmark, /pr-review, /pr-resolve, /diagram)
 │   ├── benchmark/SKILL.md
 │   ├── pr-review/SKILL.md
-│   └── pr-resolve/SKILL.md
+│   ├── pr-resolve/SKILL.md
+│   └── diagram/SKILL.md
 ├── manifest.yaml              # registry: versions, languages, default chains
 ├── languages.yaml            # language detection heuristics (markers + globs)
 ├── schema/
 │   ├── benchmark.schema.json # JSON Schema for a benchmark rubric
-│   └── review.schema.json    # JSON Schema for a review standard
+│   ├── review.schema.json    # JSON Schema for a review standard
+│   └── diagrams.schema.json  # JSON Schema for a diagram catalog
 ├── benchmark/
 │   ├── base.yaml             # language-agnostic baseline (always applied)
 │   ├── typescript.yaml       # overlays, merged on top of base
@@ -61,14 +66,12 @@ edsger-assets/
 │   ├── csharp.yaml
 │   ├── java.yaml
 │   └── dart.yaml
-└── review/
-    ├── base.yaml
-    ├── typescript.yaml
-    ├── python.yaml
-    ├── go.yaml
-    ├── csharp.yaml
-    ├── java.yaml
-    └── dart.yaml
+├── review/
+│   ├── base.yaml
+│   └── …                     # language overlays
+└── diagrams/
+    ├── base.yaml             # universal diagram catalog (C4, ER, sequence, flow, …)
+    └── …                     # language overlays (react tree, JPA model, goroutines, …)
 ```
 
 ## How standards are resolved

package/assets/diagrams/base.yaml

@@ -0,0 +1,351 @@
+id: base
+name: Universal Diagram Catalog
+version: 0.1.0
+kind: diagrams
+extends: null
+appliesTo: ["*"]
+# A catalog of professional software diagrams. For a given repository the agent
+# inspects the code, decides which diagrams genuinely fit the project's
+# characteristics (using `detect` + `appliesWhen`), then emits Mermaid source for
+# each selected diagram, grounded in real files. Diagrams that do not apply are
+# simply omitted — a library needs different diagrams than a microservice.
+
+groups:
+  # ----------------------------------------------------------------------------
+  - id: architecture
+    name: Architecture & Structure
+    description: >
+      How the system is decomposed into parts and how those parts relate — from
+      the outside-in (C4) down to individual types. The backbone for almost any
+      repository.
+    diagrams:
+      - id: system-context
+        title: System Context
+        type: flowchart
+        appliesWhen: >
+          Almost any project. Shows the software as a single box surrounded by
+          the users (personas) and external systems it talks to (APIs, queues,
+          third-party services, databases it does not own).
+        detect: ["*"]
+        guidance: >
+          C4 Level 1. Read the README, entry points, HTTP/SDK clients, env vars,
+          and config to find who uses the system and which external systems it
+          integrates with. Emit a `flowchart LR` with the system as one central
+          node, actors on the left, external systems on the right, and labelled
+          edges describing each relationship ("uses", "reads from", "publishes
+          to"). Keep it to a single screen — do not expand internals here.
+        references:
+          - "https://c4model.com/#SystemContextDiagram"
+      - id: container-architecture
+        title: Container / Service Architecture
+        type: flowchart
+        appliesWhen: >
+          Projects made of more than one deployable/runnable unit, or a clear
+          app + datastore + worker split (web app, API, SPA frontend, worker,
+          cache, database, message broker). Skip for a single-file script.
+        detect: ["docker-compose*", "Dockerfile", "k8s", "*.tf", "helm", "procfile", "services"]
+        guidance: >
+          C4 Level 2. Identify the runnable containers (frontend, backend, worker,
+          scheduler) and the data stores/brokers they use. Read docker-compose,
+          Kubernetes/Helm manifests, Terraform, Procfile, and the service dirs.
+          Emit a `flowchart TB` grouping related containers in `subgraph`s, with
+          each container labelled by its technology (e.g. "API [Node/Express]")
+          and edges labelled with the protocol ("HTTPS/JSON", "gRPC", "SQL",
+          "AMQP"). Include datastores as cylinder-style nodes.
+        references:
+          - "https://c4model.com/#ContainerDiagram"
+      - id: component-breakdown
+        title: Component Breakdown
+        type: flowchart
+        appliesWhen: >
+          A single application/service with enough internal structure that its
+          major components (controllers, services, repositories, adapters) are
+          worth showing. Best for a backend/service with layered architecture.
+        detect: ["controllers", "services", "repositories", "handlers", "usecases", "domain"]
+        guidance: >
+          C4 Level 3 — zoom into one container. Read the source tree of the main
+          app and identify its cohesive components and the direction of
+          dependencies between them (e.g. HTTP layer → use-cases → repositories →
+          DB). Emit a `flowchart TB` with one node per component and directed
+          edges. Prefer showing the dependency direction faithfully over being
+          exhaustive.
+        references:
+          - "https://c4model.com/#ComponentDiagram"
+      - id: module-dependency
+        title: Module / Package Dependency Graph
+        type: flowchart
+        appliesWhen: >
+          Any non-trivial codebase, especially monorepos and multi-package repos.
+          Shows how top-level modules/packages import one another and surfaces
+          layering violations or cycles.
+        detect:
+          [
+            "packages",
+            "apps",
+            "libs",
+            "src",
+            "internal",
+            "pnpm-workspace.yaml",
+            "lerna.json",
+            "go.mod"
+          ]
+        guidance: >
+          Map the import/dependency edges between the top-level modules or
+          workspace packages (not every file — the coarse structure). Use Grep on
+          import/require/use statements or read the workspace manifest. Emit a
+          `flowchart LR`; if you detect an import cycle, keep the edges honest and
+          note the cycle in the description. Aim for 5–20 nodes.
+      - id: class-structure
+        title: Key Class / Type Structure
+        type: classDiagram
+        appliesWhen: >
+          Object-oriented or strongly-typed codebases where the core abstractions
+          are classes/interfaces/structs with inheritance or composition worth
+          showing (frameworks, SDKs, domain-rich services). Skip for thin
+          script-style code.
+        detect: ["class ", "interface ", "abstract", "struct ", "trait "]
+        guidance: >
+          Pick the 6–15 most important types on the core domain/abstraction and
+          model them with a Mermaid `classDiagram`: key fields and methods,
+          inheritance (`<|--`), composition (`*--`), and association (`-->`).
+          Favour the load-bearing abstractions over data-transfer objects.
+        references:
+          - "https://en.wikipedia.org/wiki/Class_diagram"
+
+  # ----------------------------------------------------------------------------
+  - id: behavioral
+    name: Behaviour & Control Flow
+    description: >
+      How the system behaves over time — the ordered interactions, the control
+      flow of important logic, and the lifecycles of stateful things.
+    diagrams:
+      - id: request-sequence
+        title: Request / Interaction Sequence
+        type: sequenceDiagram
+        appliesWhen: >
+          Any system with a meaningful end-to-end flow across participants — an
+          HTTP request through middleware to the DB, a CLI command, an auth
+          handshake, a webhook round-trip, an agent tool-call loop.
+        detect: ["route", "handler", "controller", "middleware", "endpoint", "api", "rpc"]
+        guidance: >
+          Choose the single most representative flow (e.g. the primary API request
+          or the main command) and trace it through the real participants (Client,
+          API, Service, DB, external API). Emit a `sequenceDiagram` with `->>`
+          calls and `-->>` returns, `activate`/`deactivate` where it clarifies,
+          and `alt`/`opt` for the important branches (error/success). Keep to one
+          coherent scenario rather than every path.
+        references:
+          - "https://en.wikipedia.org/wiki/Sequence_diagram"
+      - id: function-flowchart
+        title: Critical Function Flowchart
+        type: flowchart
+        appliesWhen: >
+          There is a non-trivial algorithm or decision-heavy function at the heart
+          of the project (a scheduler, parser, pricing/scoring engine, state
+          reducer, retry/backoff loop). Skip if the logic is mostly straight-line.
+        detect: ["*"]
+        guidance: >
+          Find the most important branching function and render its control flow
+          as a `flowchart TD`: decisions as `{diamond}` nodes with Yes/No edges,
+          processing as rectangles, and terminal states clearly marked. Stay
+          faithful to the actual branches and loops in the code; reference the
+          function by file and name in the description.
+        references:
+          - "https://en.wikipedia.org/wiki/Flowchart"
+      - id: state-machine
+        title: Lifecycle / State Machine
+        type: stateDiagram-v2
+        appliesWhen: >
+          Something in the domain moves through explicit states — an order,
+          job, session, connection, deployment, request, or a UI/workflow with
+          statuses/enums. Very common in services and workflow engines.
+        detect: ["status", "state", "enum", "PENDING", "ACTIVE", "workflow", "lifecycle"]
+        guidance: >
+          Identify a stateful entity and its transitions from enums/status fields
+          and the code that mutates them. Emit a `stateDiagram-v2` with `[*]`
+          start/end, named states, and labelled transitions (the event/condition
+          that causes each move). Keep every transition traceable to real code.
+        references:
+          - "https://en.wikipedia.org/wiki/UML_state_machine"
+      - id: user-journey
+        title: User Journey
+        type: journey
+        appliesWhen: >
+          Products with a human-facing flow (web/mobile app, CLI UX, onboarding)
+          where the sequence of user steps and their friction is meaningful.
+          Skip for pure infrastructure/libraries.
+        detect: ["frontend", "ui", "pages", "views", "components", "onboarding", "signup"]
+        guidance: >
+          Sketch the primary user's path through the product as a Mermaid
+          `journey` with 1–2 sections and steps scored 1–5 for experience. Ground
+          the steps in real screens/commands/endpoints, not invented ones.
+
+  # ----------------------------------------------------------------------------
+  - id: data
+    name: Data & Persistence
+    description: >
+      The shape of the data the system owns and how it moves — schemas, domain
+      models, and data-flow.
+    diagrams:
+      - id: er-diagram
+        title: Entity–Relationship (Database Schema)
+        type: erDiagram
+        appliesWhen: >
+          The project owns a relational schema or ORM models/migrations. One of
+          the highest-value diagrams whenever a database is present.
+        detect:
+          [
+            "*.sql",
+            "migrations",
+            "schema.prisma",
+            "models",
+            "entity",
+            "@Entity",
+            "CREATE TABLE",
+            "ActiveRecord",
+            "sqlalchemy",
+            "gorm"
+          ]
+        guidance: >
+          Read the schema/migrations/ORM models and reconstruct the entities,
+          their key columns (with types and PK/FK markers), and the relationships
+          with correct cardinality. Emit a Mermaid `erDiagram` using
+          `||--o{`-style crow's-foot notation. Include the important tables; you
+          may omit pure join-table noise if you show the relationship it encodes.
+        references:
+          - "https://en.wikipedia.org/wiki/Entity%E2%80%93relationship_model"
+      - id: data-flow
+        title: Data Flow Diagram
+        type: flowchart
+        appliesWhen: >
+          Data moves through stages/transformations — pipelines, ETL/ELT, event
+          streaming, ingestion→processing→storage, ML training/inference. Skip
+          for simple CRUD apps already covered by the ER diagram.
+        detect:
+          ["pipeline", "etl", "kafka", "queue", "stream", "worker", "producer", "consumer", "dag"]
+        guidance: >
+          Trace data from its sources through each processing step to its sinks.
+          Emit a `flowchart LR` where external entities/sources and data stores
+          are visually distinct from processes; label edges with what data flows.
+          Follow classic DFD intent (processes, data stores, data flows, external
+          entities) using Mermaid shapes.
+        references:
+          - "https://en.wikipedia.org/wiki/Data-flow_diagram"
+      - id: domain-model
+        title: Domain Model
+        type: classDiagram
+        appliesWhen: >
+          Domain-rich applications whose core concepts and relationships are not
+          fully captured by a database schema (DDD-style aggregates, value
+          objects, rich business entities). Complements or replaces the ER diagram
+          for non-relational or logic-heavy domains.
+        detect: ["domain", "aggregate", "entity", "valueobject", "model"]
+        guidance: >
+          Model the ubiquitous-language concepts and their relationships as a
+          `classDiagram`, emphasising aggregates/roots, multiplicities, and the
+          associations that carry business meaning rather than storage details.
+        references:
+          - "https://martinfowler.com/eaaCatalog/domainModel.html"
+
+  # ----------------------------------------------------------------------------
+  - id: deployment
+    name: Deployment & Operations
+    description: >
+      Where the code runs and how it gets there — runtime topology and the
+      delivery pipeline.
+    diagrams:
+      - id: deployment-topology
+        title: Deployment Topology
+        type: flowchart
+        appliesWhen: >
+          Anything with a defined runtime environment: containers, Kubernetes,
+          serverless, VMs, a CDN/edge, managed databases. Skip for a plain
+          library with no deployment story.
+        detect:
+          [
+            "Dockerfile",
+            "docker-compose*",
+            "k8s",
+            "kubernetes",
+            "helm",
+            "*.tf",
+            "serverless.yml",
+            "vercel.json",
+            "fly.toml",
+            ".github/workflows"
+          ]
+        guidance: >
+          Read infra manifests (Docker/K8s/Helm/Terraform/serverless configs) and
+          model the runtime nodes/zones and what is deployed onto each. Emit a
+          `flowchart TB` using `subgraph`s for boundaries (client, edge/CDN,
+          cluster/VPC, managed services) and nodes for the deployed units, with
+          edges for network paths. This is the C4 deployment view.
+        references:
+          - "https://c4model.com/#DeploymentDiagram"
+      - id: cicd-pipeline
+        title: CI/CD Pipeline
+        type: flowchart
+        appliesWhen: >
+          A CI/CD configuration exists (GitHub Actions, GitLab CI, CircleCI,
+          Jenkins, etc.). Shows the stages from commit to release.
+        detect:
+          [
+            ".github/workflows",
+            ".gitlab-ci.yml",
+            "Jenkinsfile",
+            ".circleci",
+            "azure-pipelines.yml",
+            "buildkite"
+          ]
+        guidance: >
+          Read the pipeline definition(s) and render the stages and their
+          dependencies as a `flowchart LR` (trigger → build → test/lint →
+          package → deploy environments), including gates/approvals and parallel
+          jobs where present. Keep stage names faithful to the config.
+
+  # ----------------------------------------------------------------------------
+  - id: process
+    name: Process, Domain & Planning
+    description: >
+      Higher-level maps of the domain, the collaboration workflow, and the plan —
+      useful for onboarding and communication. Include only when the evidence
+      exists; never invent a roadmap.
+    diagrams:
+      - id: domain-mindmap
+        title: Domain / Feature Mind Map
+        type: mindmap
+        appliesWhen: >
+          A useful onboarding overview for most non-trivial repos: the main
+          feature areas / bounded contexts / subsystems and what each contains.
+        detect: ["*"]
+        guidance: >
+          Summarise the repository's major areas as a Mermaid `mindmap` rooted at
+          the project name, branching into subsystems/features and their notable
+          pieces. Derive branches from the real directory structure and README,
+          not aspiration.
+      - id: git-branching
+        title: Branching / Release Model
+        type: gitGraph
+        appliesWhen: >
+          The repository follows a discernible branching or release strategy
+          (trunk-based, GitFlow, release branches, tags) worth documenting.
+          Optional; skip if history is trivial.
+        detect: ["CONTRIBUTING", "release", "CHANGELOG", "tags", ".github"]
+        guidance: >
+          Infer the branching model from CONTRIBUTING docs, branch names, tags,
+          and CHANGELOG, and illustrate it with a Mermaid `gitGraph` (main plus
+          representative feature/release branches, commits, merges, tags). This is
+          illustrative of the model, not a literal replay of history.
+      - id: requirements
+        title: Requirements Traceability
+        type: requirementDiagram
+        appliesWhen: >
+          The repo documents explicit requirements/specs and you can trace them to
+          components that satisfy them (regulated, spec-driven, or RFC-heavy
+          projects). Optional and evidence-gated.
+        detect: ["requirements", "specs", "rfc", "docs/adr", "SPEC"]
+        guidance: >
+          Extract stated requirements and the elements that satisfy them from
+          docs/specs, and render a Mermaid `requirementDiagram` with
+          `requirement`/`element` nodes and `satisfies`/`traces` relationships.
+          Only include requirements actually written down in the repo.

package/assets/diagrams/csharp.yaml

@@ -0,0 +1,48 @@
+id: csharp
+name: C# / .NET Overlay
+version: 0.1.0
+kind: diagrams
+extends: base
+appliesTo: [csharp]
+
+groups:
+  - id: architecture
+    name: Architecture & Structure
+    diagrams:
+      - id: aspnet-layers
+        title: ASP.NET Layered Architecture
+        type: flowchart
+        appliesWhen: >
+          An ASP.NET Core web API/app (Controllers or Minimal APIs) with services
+          and EF Core. Shows the request path through the layers and DI.
+        detect:
+          [
+            "ControllerBase",
+            "[ApiController]",
+            "MapGet",
+            "MapPost",
+            "AddScoped",
+            "IServiceCollection"
+          ]
+        guidance: >
+          Read the controllers/endpoints, registered services, and DbContext to
+          map Endpoints → Services → Repositories/DbContext → Database as a
+          `flowchart TB` with layers in `subgraph`s. Reflect the real
+          dependency-injection wiring where you can see it.
+        references:
+          - "https://learn.microsoft.com/aspnet/core/fundamentals/"
+
+  - id: data
+    name: Data & Persistence
+    diagrams:
+      - id: efcore-model
+        title: EF Core Model
+        type: classDiagram
+        appliesWhen: >
+          Entity Framework Core models / a DbContext are present. Shows the
+          entity classes and their navigation-property relationships.
+        detect: ["DbContext", "DbSet<", "[Key]", "HasMany", "WithOne", "EntityFramework"]
+        guidance: >
+          Model the entity POCOs and their navigation properties as a
+          `classDiagram`, using the DbContext `DbSet`s and fluent/attribute
+          configuration to get the relationships and multiplicities right.

package/assets/diagrams/dart.yaml

@@ -0,0 +1,41 @@
+id: dart
+name: Dart / Flutter Overlay
+version: 0.1.0
+kind: diagrams
+extends: base
+appliesTo: [dart]
+
+groups:
+  - id: architecture
+    name: Architecture & Structure
+    diagrams:
+      - id: flutter-widget-tree
+        title: Flutter Widget Tree
+        type: flowchart
+        appliesWhen: >
+          A Flutter app. Shows the widget composition for the main screens —
+          the Flutter equivalent of a component tree.
+        detect:
+          ["flutter", "StatelessWidget", "StatefulWidget", "MaterialApp", "Scaffold", "*.dart"]
+        guidance: >
+          From `main.dart` and the routed screens, map the important widgets and
+          their build-tree composition as a `flowchart TD`. Focus on the screen
+          scaffolds and reusable widgets; note where state is injected
+          (Provider/InheritedWidget) rather than every layout widget.
+        references:
+          - "https://docs.flutter.dev/ui/widgets-intro"
+
+  - id: behavioral
+    name: Behaviour & Control Flow
+    diagrams:
+      - id: bloc-state
+        title: State Management (BLoC / Cubit)
+        type: stateDiagram-v2
+        appliesWhen: >
+          The app uses BLoC/Cubit (or Riverpod/Provider) state management. Shows
+          the states a feature moves through and the events driving them.
+        detect: ["bloc", "cubit", "riverpod", "provider", "emit(", "StateNotifier"]
+        guidance: >
+          Pick a representative feature's BLoC/Cubit and model its states and the
+          events/transitions between them as a `stateDiagram-v2`, tracing each
+          transition to an `emit`/event handler in the code.

package/assets/diagrams/go.yaml

@@ -0,0 +1,44 @@
+id: go
+name: Go Overlay
+version: 0.1.0
+kind: diagrams
+extends: base
+appliesTo: [go]
+
+groups:
+  - id: behavioral
+    name: Behaviour & Control Flow
+    diagrams:
+      - id: goroutine-concurrency
+        title: Goroutine / Channel Concurrency
+        type: flowchart
+        appliesWhen: >
+          The program uses goroutines and channels for a concurrent pipeline,
+          fan-out/fan-in, or worker pool. One of Go's most illuminating and
+          hardest-to-read-from-source structures.
+        detect: ["go func", "chan ", "make(chan", "sync.WaitGroup", "errgroup", "worker pool"]
+        guidance: >
+          Identify the concurrent structure (producers, worker pool, fan-in
+          collector) and render it as a `flowchart LR` where goroutines are nodes
+          and channels are the edges between them (label edges with the channel's
+          element type). Show closing/cancellation (context) where it matters.
+        references:
+          - "https://go.dev/blog/pipelines"
+
+  - id: architecture
+    name: Architecture & Structure
+    diagrams:
+      - id: go-package-layout
+        title: Package Layout (cmd / internal / pkg)
+        type: flowchart
+        appliesWhen: >
+          A multi-package Go module, especially one using the standard
+          cmd/internal/pkg layout. Shows the import direction between packages.
+        detect: ["cmd/", "internal/", "pkg/", "go.mod"]
+        guidance: >
+          Read go.mod and the package imports to map the top-level packages and
+          their import edges as a `flowchart LR`, keeping the dependency direction
+          faithful (binaries in cmd/ depend inward on internal/pkg, never the
+          reverse). Flag any import cycle you find.
+        references:
+          - "https://go.dev/doc/modules/layout"