cmb211087 · cmb211087 · Jun 22, 2026 · Jun 22, 2026 · Jun 22, 2026 · Jun 22, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main, "feature/**"]
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: skills/azure-diagrams
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Graphviz (system package)
+        run: sudo apt-get update && sudo apt-get install -y graphviz
+
+      - name: Install Python dependencies
+        run: pip install -r requirements.txt
+
+      - name: Verify installation
+        run: python scripts/verify_installation.py
+
+      - name: Validate every diagrams import in the docs
+        run: python scripts/check_imports.py
+
+      - name: Render every runnable example block
+        run: python scripts/render_examples.py
+
+      - name: Verify the ARM IaC parser
+        run: python scripts/iac_to_diagram.py tests/fixtures/sample-arm.json --render
diff --git a/.gitignore b/.gitignore
@@ -3,3 +3,12 @@ __pycache__/
 .DS_Store
 *.log
 .venv/
+venv/
+.claude/
+# Windows / editor noise
+Thumbs.db
+desktop.ini
+nul
+.vscode/
+.idea/
+*.code-workspace
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,65 @@
+# AGENTS.md - Azure Architecture Diagrams
+
+This repository is an **agent skill** for generating professional technical diagrams as
+code. It works with any AI coding tool (Claude Code, GitHub Copilot, Cursor, Windsurf, and
+any tool that reads `AGENTS.md` or Agent Skills). The full instructions live in
+[`skills/azure-diagrams/SKILL.md`](skills/azure-diagrams/SKILL.md); this file is the
+portable summary for tools that do not load `SKILL.md` automatically.
+
+## What it does
+
+Generates Azure architecture diagrams (800+ Azure service icons), plus business-process
+flows, ERDs, timelines/Gantt, UI wireframes, sequence diagrams and network topology, using
+the Python [`diagrams`](https://diagrams.mingrammer.com/) library and Graphviz. It can also
+build diagrams from Bicep, Terraform and ARM templates.
+
+## Prerequisites (cross-platform)
+
+1. **Graphviz** (system package, provides the `dot` engine), then restart the terminal:
+   - Windows: `winget install -e --id Graphviz.Graphviz` (or `choco install graphviz`)
+   - macOS: `brew install graphviz`
+   - Linux: `sudo apt-get install graphviz`
+2. **Python 3.9+** with the library: `pip install "diagrams>=0.25.1"`
+
+See [`SETUP.md`](SETUP.md) for a full, step-by-step setup with troubleshooting.
+
+## How to generate a diagram
+
+Write the image to a `diagrams/` folder in the working directory (portable everywhere); do
+not leave a throwaway `.py` script behind.
+
+**macOS / Linux (and Claude Code, Cursor):**
+```bash
+mkdir -p diagrams
+python3 << 'EOF'
+from diagrams import Diagram
+from diagrams.azure.compute import AKS
+from diagrams.azure.database import CosmosDb
+with Diagram("My Architecture", filename="diagrams/architecture", show=False, outformat="png"):
+    AKS("aks-prod") >> CosmosDb("cosmos-prod")
+EOF
+```
+
+**Windows (PowerShell, e.g. GitHub Copilot):**
+```powershell
+New-Item -ItemType Directory -Force diagrams > $null
+@'
+from diagrams import Diagram
+from diagrams.azure.compute import AKS
+from diagrams.azure.database import CosmosDb
+with Diagram("My Architecture", filename="diagrams/architecture", show=False, outformat="png"):
+    AKS("aks-prod") >> CosmosDb("cosmos-prod")
+'@ | Set-Content _diagram.py; python _diagram.py; Remove-Item _diagram.py
+```
+
+PNG is the default output (portable and shareable). See the reference files under
+`skills/azure-diagrams/references/` for patterns, the full component catalogue, and
+diagram-type guides.
+
+## Conventions for agents
+
+- Prefer PNG output; only use SVG when the user asks and `cairosvg` is installed.
+- Use `python skills/azure-diagrams/scripts/list_azure_nodes.py` to look up real icon
+  class names instead of guessing.
+- Keep node labels short; use `Cluster` for logical grouping; set `labelloc="t"`.
+- Verify the environment with `python skills/azure-diagrams/scripts/verify_installation.py`.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to the azure-diagrams skill. This project follows semantic versioning,
+adapted for a skill (see [Versioning](#versioning)).
+
+## [2.0.0] - 2026-06-22
+
+> Follows the v1.1.0 release line. (The SKILL.md frontmatter had read "3.0" in error; it is corrected to 2.0.0 here.)
+
+### Changed (breaking)
+- Require `diagrams >= 0.25.1` (was effectively 0.24.x). 0.25.x added/renamed Azure modules; pin and reinstall.
+- Default output is now **PNG** (was SVG). SVG is opt-in: Graphviz embeds local icon paths, so shared SVG shows broken icons.
+- `Bastions` now imports from `diagrams.azure.networking` (new module in 0.25.x).
+
+### Added
+- Access to 800+ Azure node classes across 32 modules in 0.25.1 (AI/ML, containers, management-governance, databases v2, intune, newicons).
+- New patterns: Azure AI / RAG, Container Apps, landing-zone governance, accessible colour palette, CIDR hub-spoke, private-endpoint DNS.
+- Mermaid zero-install lane (`references/mermaid-output.md`) and C4 model reference (`references/c4-model.md`).
+- Deterministic ARM-to-diagram parser (`scripts/iac_to_diagram.py`) with a committed fixture.
+- Cross-tool / cross-OS portability: `AGENTS.md`, `SETUP.md`, portable `diagrams/` output, Windows PowerShell execution path.
+- CI (`.github/workflows/ci.yml`) plus verification tools: `check_imports.py`, `render_examples.py`, `list_azure_nodes.py`, and `evals/`.
+- `requirements.txt` and `requirements-extras.txt`.
+
+### Fixed
+- Repaired broken imports across the docs (Bastions, ACR, ExpressrouteDirect, Alerts, SAP).
+- Modernised the Terraform mapping to azurerm 4.x.
+- Hardened `verify_installation.py` (real version floor, dot-on-PATH preflight); removed emoji that crashed Windows consoles.
+- Corrected the icon-count claim ("700+ official Microsoft icons" -> measured 842 node classes).
+- Fixed a Graphviz 14 crash in the overlap-prevention example.
+
+### Removed
+- Client-specific example content, replaced throughout with neutral fictional (Contoso) content.
+
+## [1.1.0] - previous release
+- Security sandboxing, Well-Architected patterns, large-diagram strategies, expanded examples.
+
+## Versioning
+
+Semantic versioning adapted to a skill. A change is **major (breaking)** if it changes the
+minimum `diagrams` version, changes the default output format, changes a canonical import
+module, removes a reference file, or changes the trigger description. New patterns, docs and
+tools are **minor**; corrections are **patch**.
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Carl Brindle
+Copyright (c) 2025-2026 Carl Brindle
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/PUBLISHING.md b/PUBLISHING.md
@@ -0,0 +1,41 @@
+# Publishing & release
+
+Maintainer guide for cutting a release and listing the skill in registries.
+
+## Release steps
+
+1. Ensure CI is green and the local checks pass:
+   ```bash
+   python skills/azure-diagrams/scripts/check_imports.py
+   python skills/azure-diagrams/scripts/render_examples.py
+   python skills/azure-diagrams/scripts/iac_to_diagram.py skills/azure-diagrams/tests/fixtures/sample-arm.json --render
+   ```
+2. Update `CHANGELOG.md` and the `metadata.version` in `skills/azure-diagrams/SKILL.md`.
+3. Tag the release so `gh skill install ...@<tag>` can pin it:
+   ```bash
+   git tag v2.0.0 && git push origin v2.0.0
+   ```
+4. Optionally publish to the skill index: `gh skill publish` (GitHub CLI >= v2.90.0).
+
+## Registry listings
+
+These increase discoverability and feed the install CLIs. Submit the blurb below.
+
+- **awesome-copilot** (`github/awesome-copilot`) - open a PR adding the skill.
+- Skill marketplaces that index public repos (e.g. claudemarketplaces.com, skillsmp.com).
+
+### Submission blurb (ready to use)
+
+> **azure-diagrams** - Generate professional Azure architecture diagrams (800+ service
+> icons), business-process flows, ERDs, timelines, wireframes, sequence and network diagrams
+> as code. Runs inside your coding agent (Claude Code, GitHub Copilot, Cursor, Windsurf) so
+> your architecture never leaves your machine; reads your actual Bicep/Terraform/ARM; outputs
+> version-controllable PNG/SVG. MIT, pinned to a verified library with CI.
+> Install: `gh skill install cmb211087/azure-diagrams-skill azure-diagrams`
+
+## Before posting anything (maintainer checklist)
+
+- These submissions are **drafts** - confirm the wording before opening any PR or posting.
+- Verify the active GitHub account before any push or PR: `gh auth status` should show
+  **cmb211087** on **github.com** (not a work GHE host or another account).
+- Double-check no client-specific or internal content has crept back into the examples.
diff --git a/README.md b/README.md
@@ -1,6 +1,3 @@
-[![Buy me a coffee](https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=&slug=carlbrindle&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff)](https://www.buymeacoffee.com/carlbrindle)
-
-
 # Azure Diagrams Skill
 
 A comprehensive technical diagramming toolkit for **solutions architects**, **presales engineers**, and **developers**. Generate professional diagrams for proposals, documentation, and architecture reviews.
@@ -11,6 +8,26 @@ A comprehensive technical diagramming toolkit for **solutions architects**, **pr
   <em>Professional architecture diagram generated in seconds</em>
 </p>
 
+##  Why this skill
+
+Unlike browser-based or SaaS AI diagram tools, this runs **inside your coding agent**:
+
+- **Your architecture never leaves your machine** - nothing is uploaded to a third-party service.
+- **It reads your actual IaC** - point it at your Bicep/Terraform/ARM and diagram what you really deploy (see [iac-to-diagram](skills/azure-diagrams/references/iac-to-diagram.md)).
+- **Diagrams are code** - version-controlled, diffable in pull requests, regenerated on demand.
+- **Works in any AI tool** - Claude Code, GitHub Copilot, Cursor, Windsurf (see [AGENTS.md](AGENTS.md)).
+- **Free and MIT-licensed**, on a pinned, verified library - every example is rendered in CI.
+
+### How this differs
+
+| | This skill | Browser / SaaS AI diagram tools |
+|---|---|---|
+| Where it runs | Your machine, in your coding agent | Their servers |
+| Your architecture data | Stays local | Uploaded |
+| Source of truth | Your Bicep / Terraform / ARM | Manual prompt |
+| Output | Code-based, version-controlled PNG/SVG | Image / proprietary doc |
+| Cost | Free (MIT) | Often subscription |
+
 ##  What You Can Create
 
 | Diagram Type | Use Case | Example Prompt |
@@ -24,6 +41,15 @@ A comprehensive technical diagramming toolkit for **solutions architects**, **pr
 | **Network Topology** | Hub-spoke, VNets, hybrid cloud | "Create a hub-spoke network with shared services and 3 workloads" |
 | **Well-Architected Patterns** | Reliability, Security, Cost, Performance, Operations | "Create a Zero Trust architecture diagram" |
 
+##  Gallery
+
+Modern Azure patterns, generated from the runnable examples in
+[`references/common-patterns.md`](skills/azure-diagrams/references/common-patterns.md):
+
+| Azure AI / RAG | Container Apps | Landing Zone Governance |
+|:---:|:---:|:---:|
+| ![Azure AI RAG application](examples/ai-rag.png) | ![Container Apps microservices](examples/container-apps.png) | ![Landing zone governance](examples/landing-zone-governance.png) |
+
 ##  Output Formats
 
 | Format | Use Case | Example |
@@ -42,9 +68,10 @@ A comprehensive technical diagramming toolkit for **solutions architects**, **pr
 - **Project Managers** - Build timelines and roadmaps
 - **Business Analysts** - Create process flows and swimlane diagrams
 
-##  700+ Azure Components
+##  800+ Azure Components
 
-Official Microsoft icons for all Azure services:
+Azure service icons spanning 32 modules in the `diagrams` library (0.25.1). Run
+`python skills/azure-diagrams/scripts/list_azure_nodes.py` to list every available class:
 
 | Category | Services |
 |----------|----------|
@@ -59,40 +86,45 @@ Official Microsoft icons for all Azure services:
 | **DevOps** | Azure DevOps, Pipelines, Repos, Boards, Artifacts |
 | **IoT** | IoT Hub, IoT Edge, Digital Twins, Time Series Insights |
 
-##  Quick Start
-
 ##  Installation
 
 ### Prerequisites
 ```bash
-pip install diagrams matplotlib
-apt-get install graphviz  # or: brew install graphviz (macOS) / choco install graphviz (Windows)
+# Graphviz (system package), then restart your terminal:
+winget install -e --id Graphviz.Graphviz   # Windows  (or: choco install graphviz)
+brew install graphviz                       # macOS
+sudo apt-get install graphviz               # Linux
+
+# Python library (venv recommended); matplotlib/cairosvg are optional extras:
+pip install "diagrams>=0.25.1"
 ```
 
-### For Claude Code CLI
+> Full step-by-step setup with per-OS troubleshooting (Windows/macOS/Linux) is in
+> **[SETUP.md](SETUP.md)**. This skill works across AI tools - Claude Code, GitHub Copilot,
+> Cursor, Windsurf, and any Agent Skills / AGENTS.md compatible tool (see [AGENTS.md](AGENTS.md)).
+
+**Recommended: GitHub CLI** (works across Copilot, Claude Code, Cursor and more; needs `gh` >= v2.90.0)
+```bash
+gh skill preview cmb211087/azure-diagrams-skill azure-diagrams   # inspect first
+gh skill install cmb211087/azure-diagrams-skill azure-diagrams   # repo and skill are TWO args
+```
+Pin a version with `@<tag-or-sha>`, or use `--scope user` to install everywhere. `gh skill`
+defaults to the GitHub Copilot agent; pass `--agent claude` (etc.) for other hosts.
 
-**Option 1: Using agr (Recommended)**
+**Claude Code via agr**
 ```bash
 pip install agr
-agr add cmb211087/azure-diagrams-skill/azure-diagrams
+agr add cmb211087/azure-diagrams-skill/azure-diagrams   # agr uses a slash-joined path
 ```
 
-**Option 2: Manual Installation**
+**Manual**
 ```bash
-# Clone and copy to personal skills
 git clone https://github.com/cmb211087/azure-diagrams-skill.git
+# Claude Code (user or project scope):
 cp -r azure-diagrams-skill/skills/azure-diagrams ~/.claude/skills/
-
-# Or copy to a specific project
 cp -r azure-diagrams-skill/skills/azure-diagrams YOUR_PROJECT/.claude/skills/
-```
-
-### For GitHub Copilot
-```bash
-# Copy to your repository
+# GitHub Copilot (repository scope):
 cp -r azure-diagrams-skill/skills/azure-diagrams YOUR_REPO/.github/skills/
-# OR
-cp -r azure-diagrams-skill/skills/azure-diagrams YOUR_REPO/.claude/skills/
 ```
 
 ### For Cursor / Other Agent Skills Tools
@@ -270,3 +302,9 @@ MIT License - free to use, modify, and distribute.
 - [diagrams](https://diagrams.mingrammer.com/) - Diagram as Code library
 - [Graphviz](https://graphviz.org/) - Graph visualization
 - [Agent Skills](https://agentskills.io) - Open standard for AI skills
+
+##  Support
+
+If this skill saves you time, you can support its development:
+
+[![Buy me a coffee](https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=&slug=carlbrindle&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff)](https://www.buymeacoffee.com/carlbrindle)