[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7BV68TFWNHFXA4T5XY5ZB08":3,"skill-same:01M7BV68TFWNHFXA4T5XY5ZB08":48},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":27,"commitSha":28,"skillDirectory":29,"forksCount":30,"repositoryHtmlUrl":31,"repositoryHomepageUrl":6,"ownerHtmlUrl":32,"ownerBlogUrl":6,"ownerDescription":33,"updatedAt":34,"install":35,"resources":47},"01M7BV68TFWNHFXA4T5XY5ZB08","mermaid-infra-diagram",null,"Generate a control's 'Demo infrastructure setup (simplified)' diagram with real Microsoft\u002FAzure service icons instead of abstract colored boxes. Primary path: draw.io XML rendered headlessly via the bundled VS Code draw.io extension, using the official Azure Public Service Icons set indexed at media\u002Ficons\u002FAzure_Public_Service_Icons\u002Ficon-index.jsonl. Fallback path: Mermaid architecture-beta with Iconify icon packs, pre-rendered because GitHub does not render Mermaid icon packs live. For controls that deploy Azure resources, follow the KNW-001 reference layout: nested subscription, resource group and resource boundaries, a legend, an outside-scope band and tiered icon sizes. Use when creating or refreshing a control's Demo infrastructure setup (simplified) section, or when a plain flowchart diagram should show recognizable real-world service icons instead of abstract colored boxes.","doruit\u002Fforged-with-foundry","doruit","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F144165645?v=4","01M7BV5HKR7V6XSAZ13DBMXHW5","Douwe van de Ruit","01M7BV5HMDT1WMC9W91K0K08TR",2,"MIT","https:\u002F\u002Fgithub.com\u002Fdoruit\u002Fforged-with-foundry\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fmermaid-infra-diagram\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: mermaid-infra-diagram\ndescription: \"Generate a control's 'Demo infrastructure setup (simplified)' diagram with real Microsoft\u002FAzure service icons instead of abstract colored boxes. Primary path: draw.io XML rendered headlessly via the bundled VS Code draw.io extension, using the official Azure Public Service Icons set indexed at media\u002Ficons\u002FAzure_Public_Service_Icons\u002Ficon-index.jsonl. Fallback path: Mermaid architecture-beta with Iconify icon packs, pre-rendered because GitHub does not render Mermaid icon packs live. For controls that deploy Azure resources, follow the KNW-001 reference layout: nested subscription, resource group and resource boundaries, a legend, an outside-scope band and tiered icon sizes. Use when creating or refreshing a control's Demo infrastructure setup (simplified) section, or when a plain flowchart diagram should show recognizable real-world service icons instead of abstract colored boxes.\"\nlicense: MIT\nuser-invocable: true\nmetadata:\n  authors: \"Douwe van de Ruit\"\n  spec_version: \"2.0\"\n---\n\n# Demo infrastructure setup (simplified) diagram with real icons\n\n## Why this exists, and the one hard constraint to respect\n\nMost controls' \"Demo infrastructure setup (simplified)\" sections in this repository use\na plain Mermaid `flowchart` with `classDef`-based color coding\n(purple\u002Fblue\u002Fgreen\u002Forange) instead of real service icons, because that is\nwhat GitHub's built-in Mermaid renderer supports natively in a live code\nblock. Two controls use this skill's icon-based pipeline\n(`docs\u002Farchitecture.drawio` + `media\u002Farchitecture.png`):\n\n- **`KNW-001_knowledge_freshness_breach` -- the preferred reference.** Its\n  Azure-scope layout (see \"Reference layout\" below) was confirmed by the\n  user on 2026-11-08 as clearly better than the earlier style. Copy its\n  `.drawio` as the starting point for any control that deploys Azure\n  resources.\n- `QLT-001_hallucination_rate_high` -- the earlier free-floating icon\n  chain. It is still a valid example of a causal chain with no deployed\n  resource boundary to show, but don't copy its group or icon-size\n  conventions into a new diagram.\n\nWhichever tool builds the diagram, **GitHub cannot render it live**: it does\nnot call Mermaid's `registerIconPacks()` for `architecture-beta` icons, and\nit has no draw.io renderer at all for `.drawio` XML. Either way the only\noption is to pre-render the diagram locally to a static PNG and commit that\nimage -- the same \"capture once, commit the artifact\" pattern this\nrepository already uses for screenshots (`scripts\u002Fcapture_teams_card.py`).\nThis means an icon-based architecture diagram is **not** a live-editable\ncode block like this repository's other diagrams: every future edit\nrequires re-running the render step and re-committing the image. Say this\ntrade-off out loud to the user before switching a control over, and keep the\ndiagram source file (`.drawio` or `.mmd`) committed alongside the image so it\ncan be re-rendered.\n\n## When to use\n\n- Creating a new control's \"Demo infrastructure setup (simplified)\" section and real\n  Azure\u002FMicrosoft\u002FGitHub\u002FPython service icons would make the building blocks\n  easier to recognize than colored boxes.\n- The user asks to add or refresh real icons on an existing control's\n  architecture diagram.\n- Do **not** use this for \"Logical design\" diagrams (decision flow, not\n  building blocks) -- keep those as plain `flowchart` code blocks per\n  `.github\u002Finstructions\u002Fgovernance-controls.instructions.md`.\n\n## Which tool: draw.io (preferred) or Mermaid (fallback)\n\nUse **draw.io** (`scripts\u002Frender_drawio_diagram.py`) unless the VS Code\n\"Draw.io Integration\" extension (`hediet.vscode-drawio`) is not installed on\nthis machine. It is the better fit for this repository specifically because\n`media\u002Ficons\u002FAzure_Public_Service_Icons\u002F` already holds the official,\nMicrosoft-published Azure Public Service Icons set (714 SVGs across ~29\ncategories) with a prebuilt search index -- draw.io just needs a relative\npath to one of those files, no icon-pack build step, no CORS server, and\nfree-form pixel-precise layout instead of Mermaid's `architecture-beta`\nauto-layout (which produced label\u002Ficon overlap and awkward spacing on\nearlier attempts).\n\nFall back to **Mermaid** (`scripts\u002Frender_architecture_diagram.py`, see\n\"Mermaid fallback\" below) only when the draw.io extension genuinely is not\navailable and installing it is not an option -- it needs its own local\nIconify icon-pack build step and a CORS-enabled local server for any\nofficial custom icon, which is more moving parts for the same result.\n\n## Reference layout: Azure scope boundaries (preferred)\n\nConfirmed on KNW-001 (2026-11-08). The user compared it with that control's\nearlier diagram (free-floating icons, dashed \"NOT DEPLOYED\"\u002F\"pending\"\nboxes and edges, a \"Remaining integrations\" column) and called the new\nversion clearly better. Use this layout whenever a control deploys or\nconfigures Azure resources. Open\n`controls\u002Fdata_and_knowledge\u002FKNW-001_knowledge_freshness_breach\u002Fdocs\u002Farchitecture.drawio`\nand copy its cells rather than restyling from scratch.\n\nWhy it works: a reader can match each box one to one with what they will\nsee in the Azure Portal after deployment (subscription, then resource\ngroup, then resource, then sub-resource). It shows only what the demo\nactually deploys. Every arrow means the same thing (the caller calls the\nservice the arrow points to), and the legend says so.\n\n**Canvas layout, top to bottom:**\n\n1. **Title and subtitle**, top-left. The title is\n   `\u003CID> · \u003Ccontrol name> — demo infrastructure` (`fontSize=19;fontStyle=1;fontColor=#182B39`).\n   The subtitle is italic gray (`fontSize=12;fontStyle=2;fontColor=#555555`),\n   for example \"Synthetic data only. Arrows point from the caller to the\n   service it calls.\"\n2. **Legend box**, top-right (`fillColor=#FFFFFF;strokeColor=#7F7F7F`,\n   `rounded=1;arcSize=4;absoluteArcSize=1`). It has one short sample line\n   per edge kind (for example \"Data access (Entra ID)\" and \"Notification\n   (HTTPS)\") and one sample box per boundary meaning (for example \"Deployed\n   for the demo; removed by cleanup\"). Every edge colour and boundary style\n   in the diagram must appear in the legend, and nothing else should.\n3. **Subscription boundary**: a square-cornered rectangle with\n   `fillColor=#CFE2F7;strokeColor=#9DBFE6`, plus a header tab above its\n   top-left corner. The tab is a `fillColor=#1F4E8C;strokeColor=none`\n   rectangle with a white bold text cell on top reading\n   \"Azure subscription (demo)\".\n4. **Resource group panel** inside it (`fillColor=#FAFAFA;strokeColor=#A6A6A6`,\n   `arcSize=4` absolute). Its header is the Resource Groups icon (28px)\n   followed by one text line: `Resource group \u003Cb>rg-…-demo\u003C\u002Fb> · \u003Cregion> ·\n   every resource tagged \u003Ci>control-id=\u003CID>\u003C\u002Fi>`. This turns the tagging\n   convention from `copilot-instructions.md` into something visible.\n5. **One white panel per resource or capability**\n   (`fillColor=#FFFFFF;strokeColor=#BFBFBF` or `#7F7F7F`, `arcSize=4`\n   absolute). Lay them out on a grid with equal gutters (20px in KNW-001).\n   Each panel header is a 32-40px icon plus a two-line label:\n   `\u003Cb>Resource type\u003C\u002Fb>\u003Cbr>\u003Ci>SKU · region\u003C\u002Fi>`.\n6. **Sub-resources inside a panel**, such as Blob containers, go in an\n   inner tinted panel (`fillColor=#F4F7FB;strokeColor=#BFBFBF`) with a small\n   italic caption (\"Blob containers\"). Use one 30px icon plus a\n   `\u003Cb>name\u003C\u002Fb>\u003Cbr>\u003Ci>purpose\u003C\u002Fi>` label per item. Show sub-resources only\n   when the control reads or writes them separately.\n7. **Function apps: one card per function**, not one icon per app. Use a\n   `120x72` card (`strokeColor=#E8B53A;strokeWidth=1.5;fillColor=#FFFFFF`,\n   `arcSize=6` absolute) with a 28px Functions icon centered at the top and\n   the label `\u003Cb>Function name\u003C\u002Fb>\u003Cbr>\u003Ci>trigger · auth\u003C\u002Fi>` below it. Put\n   the app's own header (icon + `\u003Cb>Function App\u003C\u002Fb>\u003Cbr>\u003Ci>plan · runtime\u003C\u002Fi>`)\n   at the bottom-left of the panel. That way edges leave from the specific\n   function that makes the call.\n8. **Identity and RBAC panel** (only when the control relies on a managed\n   identity): show the managed identity (`\u003Ci>system-assigned · no stored\n   secrets\u003C\u002Fi>`) and one \"RBAC role assignments\" row listing the actual role\n   names. Draw this as a passive panel with no edges. The legend's \"Data\n   access (Entra ID)\" entry already explains how the calls authenticate.\n   This narrows step 1's \"leave auth out of the diagram\" rule rather than\n   contradicting it: no `authenticates via` edges or auth nodes, but a\n   least-privilege access model the README's \"Inspect in Azure\" asks the\n   reader to verify does belong on the diagram.\n9. **Outside-scope band** below the subscription, for anything the\n   control uses but does not own or delete, such as Microsoft Entra ID and\n   external notification sinks (Teams, HTTPS endpoints). Use a\n   `fillColor=#FFF8E1;strokeColor=#F2B705;strokeWidth=3` rectangle with a\n   corner tag at its bottom-right (`fillColor=#F9D86B`, bold right-aligned\n   text \"Outside the control's resource group\"). Write \"(optional)\" in the\n   label of anything that is optional.\n10. **Human actors** (for example the Data Owner) stand outside every\n    boundary, usually on the left. Use the Azure \"Users\" icon with a bold\n    role name under it, and put their action on the edge label (\"signs in,\n    confirms the shown revision\").\n\n**Icon sizes by tier, not one size for everything.** Inside one tier, keep\nevery icon the same size. Between tiers, size icons by role:\n\n| Tier | Size | Examples |\n|---|---|---|\n| Primary service or actor | 48px | Azure AI Search, Foundry agent, model deployment, Entra ID, Teams, a human actor |\n| Resource panel header | 32-40px | Storage account, Foundry project, Function App, managed identity, RBAC |\n| Small header badge or sub-resource | 28-30px | Resource Groups badge, Blob containers, per-function icon in a card |\n\nThis replaces the older \"every icon, badges included, at 64x64\" rule. That\nrule fit a flat chain of four nodes, but in a nested layout the hierarchy\nis what makes it readable. Keep the \"visual weight\" check from\n\"Verify icon sizing\" below: a thin ribbon-style logo can still look smaller\nthan a solid icon in the same tier.\n\n**Edges: two kinds, both solid, directed caller to callee.**\n\n- Near-black data access: `strokeColor=#1A1A1A;strokeWidth=1.5;endArrow=block;endFill=1;endSize=7`.\n- Teal notification: the same style with `strokeColor=#00A3BF`, and a teal\n  label.\n\nUse `edgeStyle=orthogonalEdgeStyle;rounded=0` with pinned\n`exitX\u002FexitY\u002FentryX\u002FentryY` on every edge (see \"Route edges deliberately\").\nWrite labels as short verb phrases from the caller's side (\"reads source\nmetadata, writes evidence\", \"retrieves via project connection\", \"calls\").\nPut a schedule or other qualifier in italics on a second line\n(\"Blob indexer\u003Cbr>\u003Ci>(24-hour schedule)\u003C\u002Fi>\").\n\n**Match the label backdrop to the panel it sits on.** The two-cell label\npattern (see \"Differentiate edges by meaning\") still applies, but the\nbackdrop rectangle's `fillColor` must equal the fill of the panel under it:\n`#FAFAFA` on the resource-group panel, `#FFFFFF` on a white resource panel.\nA white backdrop on the light-gray resource-group fill shows up as a\nvisible white patch.\n\n**Show only what is deployed.** Do not draw planned, pending, or\n\"NOT DEPLOYED\" components with dashed boxes and edges. The earlier KNW-001\ndiagram did this, and it made the picture about project status instead of\nthe control. Status belongs in the README status line and\n`docs\u002FVALIDATION.md`. Until a component exists, leave it out of the\ndiagram, or mark it \"(optional)\" if it really is optional.\n\n**Size and embedding.** KNW-001's canvas is about 1340 x 770 and is\nembedded at `width=\"1100\"` after resizing. The alt text should list every\nboundary and component in reading order, so the image's content is\navailable without seeing it.\n\n## draw.io workflow (preferred)\n\n### One-time setup (author-only, per machine)\n\nInstall the \"Draw.io Integration\" VS Code extension\n(`hediet.vscode-drawio`, marketplace id `hediet.vscode-drawio`) if it is not\nalready present. Nothing else to install: `scripts\u002Frender_drawio_diagram.py`\ndrives the extension's own bundled copy of the diagrams.net web app with\nPlaywright (already a repository dependency via `capture_teams_card.py`),\nserving it over a throwaway local HTTP server (it needs http:\u002F\u002F, not\nfile:\u002F\u002F, for its own internal resource fetches) and reusing the system\nChrome via `--channel chrome` by default.\n\n### Steps\n\n1. **Decide what belongs in the diagram before listing building blocks.**\n   Default to showing the *core mechanism* -- what a first-time reader needs\n   to understand why this control works -- not every plumbing detail of how\n   it happens to be run today. Confirmed the hard way on QLT-001\n   (2026-09-24), across several rounds of feedback: an early version made\n   authentication (`az`\u002F`azd auth login`) and the execution environment\n   (\"Local developer workstation (not an Azure resource)\") into the most\n   visually prominent nodes, each with its own box, badge, and long\n   connecting line -- and the reviewer's reaction was that authentication\n   \"is not really the key thing to show here,\" and that naming the exact\n   current execution environment \"feels cumbersome\" for a detail that could\n   change (it could just as well be an Azure Function tomorrow). The fix\n   that stuck: cut auth and the execution environment out of the diagram\n   entirely and cover them in one prose sentence *above* the image instead\n   (for example \"This control's infrastructure is minimal: `demo.py`, run\n   locally and authenticated via `az`\u002F`azd auth login`, orchestrates every\n   step below against an already-deployed Foundry project\") -- then draw\n   only the causal chain that explains the control's actual mechanism (a\n   hosted agent's output is scored, the score becomes a decision, a\n   breaching decision notifies someone). Treat \"does every node in this\n   diagram help someone understand why this control works, or does it just\n   describe today's deployment convenience\" as the filter, and default to\n   prose for anything that fails it. A hosting detail earns a diagram node\n   only when it is itself the notable fact (for example, a control whose\n   whole point is a specific network boundary or managed identity). For a\n   `DEPLOYABLE_DEMO` or `HYBRID_DEMO` with an \"Inspect in Azure\" section,\n   the deployed resources and their scope *are* the notable fact. Show\n   them with the \"Reference layout\" above, but still leave out deployment\n   tooling (`az`, `azd`, the operator's workstation).\n\n2. **List the real building blocks** that survive that filter: the hosted\n   agent\u002Fservice, the platform capability that provides its signal, the\n   component that turns the signal into a decision, and any external\n   destination (Teams, GitHub Actions).\n\n3. **Differentiate from this control's \"Logical design\" section.** Every\n   control README already has a \"Logical design\" Mermaid flowchart showing\n   the decision *branches* (which threshold produces which outcome).\n   Demo infrastructure setup (simplified) should not redraw the same branches with\n   icons instead of colored boxes -- that is pure duplication with no new\n   information. Show the building blocks and the *data flow* between them\n   instead (what calls what, what artifact produces what), and say so\n   explicitly in the prose above the image so the two sections' distinct\n   jobs are legible to the reader, not just to whoever designed them (for\n   example: \"This is a different view from 'Logical design' above, not a\n   repeat of it: Logical design shows the three decision branches; this\n   diagram shows the building blocks and data flow that produce the score\n   those branches decide on\").\n\n4. **Find a real icon for each node** by searching the index instead of\n   guessing a filename:\n\n   ```zsh\n   grep -i \"foundry agent\" media\u002Ficons\u002FAzure_Public_Service_Icons\u002Ficon-index.jsonl\n   ```\n\n   Each match is one JSON object with a `path` (relative to\n   `media\u002Ficons\u002FAzure_Public_Service_Icons\u002FIcons\u002F`), `category`, `name`, and\n   `slug`. Prefer the most specific official match over a generic one --\n   confirmed the hard way on QLT-001 (2026-09-24): this set has precise\n   icons like \"Foundry Agent Service\" and \"Foundry Project\", which are a\n   real, correct match for a Foundry hosted agent and its containing\n   project, not a stand-in. Re-run `scripts\u002Findex_azure_icons.py` if the\n   icon set folder has been updated and the index looks stale (it is\n   deterministic and diffable, so a re-run's diff shows exactly what\n   changed). For anything that is not an Azure service at all (a local\n   Python script, Microsoft Teams, another non-Azure product), do not force\n   an Azure icon onto it. Check `media\u002Ficons\u002F` (repo root) for an existing\n   real asset first; if none exists but the official brand SVG is already\n   cached locally in `.tooling\u002Fmermaid\u002Fnode_modules\u002F@iconify-json\u002Flogos\u002Ficons.json`\n   (installed for the Mermaid fallback below, but its icons are legitimate\n   official brand SVGs regardless of which renderer uses them), extract it\n   into a standalone file once:\n\n   ```zsh\n   python3 -c \"\n   import json\n   with open('.tooling\u002Fmermaid\u002Fnode_modules\u002F@iconify-json\u002Flogos\u002Ficons.json') as f:\n       d = json.load(f)\n   icon = d['icons']['python']  # or 'microsoft-teams', etc.\n   w, h = icon.get('width', d['width']), icon.get('height', d['height'])\n   open('media\u002Ficons\u002Fpython-language.svg', 'w').write(\n       f'\u003Csvg xmlns=\\\"http:\u002F\u002Fwww.w3.org\u002F2000\u002Fsvg\\\" width=\\\"{w}\\\" height=\\\"{h}\\\" viewBox=\\\"0 0 {w} {h}\\\">{icon[\\\"body\\\"]}\u003C\u002Fsvg>'\n   )\"\n   ```\n\n   (an iconify pack entry is just an inner `\u003Cbody>` fragment, not a\n   standalone file -- it must be wrapped in a real `\u003Csvg>` root before\n   `icon:` placeholder expansion or `build_icon_pack.py` can use it). Only\n   if no real asset exists anywhere should a node fall back to a plain\n   labeled box with no icon.\n\n5. **Write the `.drawio` source** (an `\u003Cmxfile>` containing one `\u003Cdiagram>`\n   with a plain `\u003CmxGraphModel>`) in the control's own directory, for\n   example `docs\u002Farchitecture.drawio`. Reference each icon with an\n   `icon:\u003Crelative-path>` placeholder in a `shape=image` style -- the\n   render script resolves this to a real embedded image, you never write a\n   raw `data:` URI by hand:\n\n   ```xml\n   \u003CmxCell id=\"agent\" value=\"Hosted agent\"\n           style=\"shape=image;image=icon:..\u002F..\u002F..\u002F..\u002Fmedia\u002Ficons\u002FAzure_Public_Service_Icons\u002FIcons\u002Fai + machine learning\u002F038470523-icon-service-Foundry-Agent-Service.svg;verticalLabelPosition=bottom;verticalAlign=top;fontSize=12;labelBackgroundColor=#ffffff;\"\n           vertex=\"1\" parent=\"1\">\n     \u003CmxGeometry x=\"608\" y=\"110\" width=\"64\" height=\"64\" as=\"geometry\" \u002F>\n   \u003C\u002FmxCell>\n   ```\n\n   The path is relative to the `.drawio` file's own directory. Use a plain\n   rounded rectangle with a real icon (`shape=image` as above) for anything\n   with an official match, and only fall back to a plain\n   `style=\"rounded=1;whiteSpace=wrap;html=1;fillColor=#EEF2FF;strokeColor=#6E56CF;fontSize=12;\"`\n   box when nothing fits -- confirmed on QLT-001 (2026-09-24) that swapping\n   plain boxes for real per-node icons (the Microsoft Teams logo for a\n   \"Teams Workflows\" node, the Python logo for each Python script node) made\n   the rendered diagram noticeably more compelling than text-only boxes,\n   even where no Azure-specific icon exists.\n\n   **For a control that deploys Azure resources, use the nested Azure-scope\n   boundaries from \"Reference layout\" above instead of the dashed tinted\n   groups and uniform 64x64 icons described in the rest of this paragraph.**\n   The rest of this paragraph still applies to a flat causal chain with no\n   deployed resource boundary (the QLT-001 shape).\n\n   Draw a dashed rounded rectangle *with a light fill tint*\n   (`fillColor=#F5F3FF` for a Foundry\u002Fgovernance boundary,\n   `fillColor=#EFF6FF` for a platform boundary, matching each group's\n   `strokeColor`) *behind* a group of related nodes (added earlier in the\n   XML so it renders behind, not as a true mxGraph parent\u002Fchild container)\n   to visually group them -- a filled tint reads as more finished than a\n   transparent outline. Badge the group with a real icon representing what\n   the group actually is, as a separate `shape=image` cell layered near the\n   group's top-left corner, with the text label (a separate plain\n   `style=\"text;html=1;...\"` cell, not the group rectangle's own `value`)\n   offset to the right of the badge rather than overlapping it -- confirmed\n   on QLT-001 (2026-09-24) that a \"Microsoft Foundry project\" group with no\n   Foundry badge and a \"Local developer workstation\" group with no device\n   badge both read as incomplete once a reviewer compared them to the\n   fully-iconed nodes inside. **Give every icon in the diagram the same\n   geometry (for example 64x64) -- badges included.** A first pass at this\n   used a smaller size (24-28px) for group badges than for the main nodes;\n   the user immediately flagged it as inconsistent, and separately, some\n   official icons (a thin ribbon mark like \"AI Foundry\") visually read as\n   smaller than a bolder icon (a solid hexagon) even at the *exact same*\n   bounding box, because the artwork itself uses less of its own canvas --\n   render a same-size comparison strip (see the size-check pattern below)\n   before assuming equal geometry means equal visual weight. **Center a\n   group's main icon(s) within the group's width, not flush against its\n   left edge next to the badge column.** A first pass placed the badge and\n   the main icons in the same left-aligned column, leaving a wide unused\n   strip down the right side of every group -- confirmed on QLT-001\n   (2026-09-24) that this reads as unfinished (\"icons hugging the wall\n   instead of standing in the room\"). Compute `icon_x = group_x + (group_\n   width - icon_width) \u002F 2` for the main icons; leave the header badge\n   left-aligned next to its label, since a badge-plus-label header is\n   conventionally left-aligned like a title bar and centering it would look\n   stranger, not better. Use a small, fixed corner radius on group\n   rectangles instead of `rounded=1`'s default (which reads as an oversized\n   pill on a large box): `rounded=1;arcSize=5;absoluteArcSize=1;` fixes the\n   radius at 5px regardless of the rectangle's size, rather than scaling\n   the radius as a percentage of the shorter side. Connect nodes\n   with edges styled per relationship type, not one identical arrow for\n   everything -- see \"Differentiate edges by meaning\" below. Keep node count\n   small and labels short -- this is still a bite-sized diagram, not a full\n   topology map.\n\n### Differentiate edges by meaning\n\nA diagram where every edge is an identical black arrow forces the reader to\ninfer what kind of relationship each one is. Give each distinct kind of\nrelationship its own color, dash pattern, and short label, reusing this\nrepository's palette so the meaning stays consistent across controls:\n\n- Solid black or gray, no label or a short factual label -- plain\n  sequential\u002Fdata flow (one node's output directly becomes the next node's\n  input).\n- Teal (`strokeColor=#00A3BF`) labeled \"notifies\" -- a message sent to a\n  human or a notification channel.\n- Purple (`strokeColor=#A855F7` or `#7E22CE`) labeled \"invokes\" -- a call\n  into a governed\u002Fhosted component.\n\nNote: an earlier version of this guidance recommended a dashed amber edge\nlabeled \"authenticates via\" for auth\u002Fidentity steps. Per \"Decide what\nbelongs in the diagram\" above, authentication is now a prose note above the\nimage, not a node or edge -- if a control's diagram still has an\n\"authenticates via\" edge, that is a sign it should be simplified, not a\npattern to copy into a new diagram.\n\n**Prefer solid over dashed once dashed no longer carries real meaning.**\nDashed strokes are useful for a genuine distinction (for example \"Foundry's\nown internal mechanism\" vs. \"this control's own code calling out\"), but two\nreal problems show up otherwise: (1) a dash's phase can land exactly at a\nlabel's edge and peek a couple of pixels beyond it -- switching the edge to\nsolid avoids this specific symptom, though see the more general\n`labelBackgroundColor` problem below, which affects solid edges too; (2)\nonce a diagram is simplified down to a single causal chain (see above),\nevery edge in it is the same kind of \"this produces that\" relationship, so\na dashed\u002Fsolid split stops encoding any real distinction and is just\ninconsistent for its own sake -- confirmed on QLT-001 (2026-09-24), where\ndashed styling left over from a more complex, multi-actor version of the\ndiagram no longer matched anything once the diagram was cut down to four\nnodes.\n\n**`labelBackgroundColor` on an edge's own `value`, or on a standalone\n`style=\"text;...\"` cell used as a label, does not reliably produce a padded\nbackground -- confirmed on QLT-001 across several attempts (2026-09-25).**\nThe symptom: a connecting line appears to touch or run directly through the\nlabel's text on both sides, as if the white background box were sized\nexactly to the glyphs with zero padding. This is not a dash-phase artifact\n(it persists on solid edges too) and is not fixed by any of the following,\neach tried and confirmed *not* to work: padding the label's own text value\nwith leading\u002Ftrailing spaces (draw.io's own model strips or ignores this\nfor width purposes); giving a standalone label cell an explicit, generous\n`width`\u002F`height` in its `mxGeometry` (a plain `text;` style shape auto-sizes\nto fit its rendered content in draw.io's graph model on load, silently\noverriding whatever geometry the source XML declares); adding\n`whiteSpace=wrap` to that same text cell (does not override the auto-sizing\nbehavior either). **The fix that actually worked:** stop relying on any\ntext shape's own background entirely. Pair every label with two separate\ncells at the identical position and size: a plain rectangle with a real\nfill and no text\n(`style=\"rounded=0;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=none;\"`)\nsized generously wider than the text it will cover, plus a `style=\"text;...\"`\ncell on top with no `labelBackgroundColor` of its own. Rectangles reliably\nhonor their declared `mxGeometry` (proven by every icon and group box in\nthis same diagram), so this is what actually creates real, verifiable\npadding -- confirm it by rendering, then cropping and viewing the label\nregion at full (pre-resize) resolution, not by eyeballing the downscaled\nembed image, since the gap this fix produces is only a few pixels wide.\n\n**Don't duplicate a fact the prose above the diagram already states.**\nIf a detail is already established in the sentence introducing the image\n(for example \"scored by a *batch* evaluation run\"), don't also cram it into\nan edge label -- confirmed on QLT-001 (2026-09-24): adding \"(batch eval\nrun)\" to an edge label that already had a full-sentence-worth of text made\nthe label wide enough to visually collide with the arrowhead at the far end\nof its own routing segment. Add the qualifier to the prose (or shorten the\nsegment\u002Fwiden the gap) rather than to an already-long label.\n\n```xml\n\u003CmxCell id=\"e1\" value=\"\" edge=\"1\" parent=\"1\" source=\"runner\" target=\"teams\"\n        style=\"edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;strokeWidth=2;strokeColor=#00A3BF;exitX=0;exitY=0.5;entryX=0;entryY=0.5;\">\n  \u003CmxGeometry relative=\"1\" as=\"geometry\" \u002F>\n\u003C\u002FmxCell>\n\u003C!-- Label as two separate cells at the same position, not the edge's own\n     value\u002FlabelBackgroundColor -- see above for why. -->\n\u003CmxCell id=\"e1-bg\" parent=\"1\" style=\"rounded=0;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=none;\" value=\"\" vertex=\"1\">\n  \u003CmxGeometry x=\"640\" y=\"121\" width=\"70\" height=\"18\" as=\"geometry\" \u002F>\n\u003C\u002FmxCell>\n\u003CmxCell id=\"e1-label\" parent=\"1\" style=\"text;html=1;align=center;verticalAlign=middle;fontSize=11;fontColor=#00A3BF;\" value=\"notifies\" vertex=\"1\">\n  \u003CmxGeometry x=\"640\" y=\"121\" width=\"70\" height=\"18\" as=\"geometry\" \u002F>\n\u003C\u002FmxCell>\n```\n\n### Route edges deliberately -- floating connections cross and collide\n\nmxGraph's default \"floating\" connection (no `exitX`\u002F`exitY`\u002F`entryX`\u002F`entryY`,\nno waypoints) picks whatever point on each shape's perimeter is closest to\nthe other shape's center. This looks fine for one isolated edge and produces\ntwo real, confirmed failure modes once a diagram has several:\n\n1. **Edges cross each other** when two edges leave the same source toward\n   targets on opposite sides, because each one's floating exit point can end\n   up more central than expected. Fix: pin `exitX`\u002F`exitY` and\n   `entryX`\u002F`entryY` explicitly (fractions 0-1 of the shape's own bounding\n   box) on every edge, and add `edgeStyle=orthogonalEdgeStyle;rounded=0;` so\n   the line bends at right angles instead of drawing a diagonal.\n2. **An edge cuts straight through an unrelated icon or label** when its\n   shortest path happens to pass through a group's badge\u002Flabel header on the\n   way from an interior node to a target outside the group. Fix: give the\n   edge explicit waypoints (`\u003CArray as=\"points\">\u003CmxPoint x=\"..\" y=\"..\"\u002F>...\u003C\u002FArray>`\n   inside the edge's `\u003CmxGeometry>`) that route it outside the group's\n   bounding box first, then up or across to the target, instead of straight\n   through the group's interior. Confirmed on QLT-001 (2026-09-24): two\n   edges from a node inside a group to two nodes above the group both\n   originally cut straight through that group's badge icon; adding one\n   waypoint just outside each side of the group's bounding box before\n   turning toward the target fixed it.\n\nSeparately, **an edge's own auto-placed label can land exactly on top of a\nnearby node's label** if the edge's midpoint happens to coincide with where\nthat node's label sits below it -- confirmed on QLT-001 (2026-09-24), where\na vertical edge's default centered label overlapped the source node's own\nlabel directly above it, rendering as garbled overlapping text. Fix: give\nthe edge no `value` and add a separate manually positioned `style=\"text;...\"`\ncell for its label instead, positioned in whatever free space actually\nexists (increase the gap between the two connected nodes first if none\ndoes), rather than trusting the edge's automatic midpoint placement.\n\n**A chain of nodes at the same height needs its connecting edges routed\nabove or below the icon row, never through the icons' own vertical\ncenter.** `entryY=0.5`\u002F`exitY=0.5` connects at each icon's vertical\nmidpoint, which is *inside* the icon artwork when both nodes sit at the\nsame height -- confirmed on QLT-001 (2026-09-24): a simplified left-to-right\nchain of four same-height icons rendered its connecting lines and labels\ndirectly behind the icon glyphs, invisible against the artwork. Fix: route\nevery edge in the chain along a shared horizontal \"spine\" a fixed distance\nabove the icon row instead -- `exitX=0.5;exitY=0` (icon's top-center) with a\nwaypoint at the same `x` a fixed offset above the icons (for example 20px),\nacross to the target's `x` at that same spine height, then down into\n`entryX=0.5;entryY=0` (target's top-center). Because the segments between\ndifferent node pairs in a simple left-to-right chain don't share an `x`\nrange, every edge can use the *same* spine height without colliding with\nits neighbors -- there's no need to stagger heights unless two edges\nactually cross the same `x` range.\n\n### Verify icon sizing and edge layout before calling it done\n\nTwo verification passes catch what \"does it render at all\" does not:\n\n1. **Size comparison.** Render every candidate icon at the same fixed\n   geometry (for example a row of `shape=image` cells all sized 64x64) in a\n   disposable test diagram before wiring them into the real one, and look\n   at whether they read as visually equal -- not just whether the bounding\n   box matches. A thin ribbon-style logo can look smaller than a solid\n   geometric icon at an identical box size.\n2. **Full-diagram visual review**, specifically checking for: any label\n   touching or overlapping the icon above it, any two edges crossing each\n   other, any edge passing through an icon or a label instead of empty\n   space, and how much unused white space the group boxes contain relative\n   to their actual content (a box sized for content that got trimmed later\n   reads as an unfinished layout). Treat \"the command exited 0 and produced\n   a PNG\" as necessary, not sufficient.\n3. **Scope review**: does any node exist only to describe today's\n   deployment\u002Fexecution convenience rather than to explain why the control\n   works (see \"Decide what belongs in the diagram\" above)? Does the diagram\n   redraw the same decision branches \"Logical design\" already shows instead\n   of showing building blocks and data flow? Both were real, repeated\n   findings on QLT-001, not hypothetical risks -- check for them explicitly\n   rather than assuming a diagram that renders cleanly is also well-scoped.\n   For the Azure-scope layout, also check: does every box nest under the\n   scope it really lives in (subscription, resource group, resource)? Does\n   the outside-scope band hold exactly the things cleanup does not delete?\n   Does the legend list every edge colour and boundary style and nothing\n   else? Is nothing drawn as planned or pending? Does every label backdrop\n   match the fill of the panel under it?\n4. **A group's own boundary stroke can bisect a node's label that sits just\n   inside it.** Confirmed on QLT-001 (2026-09-25): a group box sized to end\n   right at its icon row's bottom, with the icon's text label positioned\n   just below that (a common layout, since labels conventionally sit under\n   their icon), placed the group's dashed bottom edge exactly through the\n   vertical middle of that label's text, rendering as a strikethrough. This\n   is a distinct failure mode from \"label overlaps the icon above it\" in\n   item 2 above -- the label doesn't touch its own icon at all, it collides\n   with the *group container's* edge instead, so a review pass that only\n   checks label-vs-icon overlap misses it. **A first attempted fix --\n   enlarging the group to enclose the label with a 10px+ margin below it --\n   did not reliably resolve this** (confirmed on a second render pass, same\n   control, same day: the boundary still read as touching\u002Funderlining the\n   label even after adding margin). The fix: keep every contained node's\n   label fully *outside* the group -- matching how every other (non-grouped)\n   node's label already sits outside any box in the same diagram -- rather\n   than trying to size the group to enclose the label with margin. Don't\n   stop at \"outside,\" though: a first pass at this shrank the group down to\n   just 4px of clearance below the icon row, which fixed the text collision\n   but then read as visually cramped -- box edge nearly touching the icons\n   -- next to the generous, un-boxed white space around every other node in\n   the same diagram (confirmed on a third render pass, same control, same\n   day, after the user flagged the cramped result as still not right). The\n   padding that actually read as correct: roughly 20px of clear space\n   between the icon row's bottom and the group's bottom edge, achieved by\n   moving *every* node's label (grouped and ungrouped alike) down together\n   by the same offset to open up that room, keeping every label row aligned\n   at the same height across the whole diagram. Verify at full render\n   resolution (crop and inspect the group region directly, not just\n   eyeballing the full downscaled image), not only at the final resized\n   embed dimensions -- and judge padding by comparison against the\n   un-grouped nodes' own white space in the same image, not in isolation.\n5. **Multiple edges converging on the same target's entry side need\n   real visual separation, not just distinct `entryX` values.** Confirmed\n   on QLT-001 (2026-09-25): two edges entering the same icon with\n   `entryX=0.4` and `entryX=0.6` (a 0.2 spread, roughly 13px apart on a\n   64px-wide icon) still read as one merged arrowhead at a glance. Spread\n   convergent entries much further apart -- `entryX=0.2`\u002F`entryX=0.8` (a\n   0.6 spread) reads as two clearly distinct arrows. The same applies in\n   reverse to multiple edges leaving the same source: give each its own\n   `exitX` spread this wide too, not just a technically-different value,\n   so the lines visibly diverge right from their source instead of\n   overlapping for their first stretch.\n\n6. **Render it**:\n\n   ```zsh\n   .venv\u002Fbin\u002Fpython scripts\u002Frender_drawio_diagram.py \\\n       --input controls\u002F\u003Ccategory>\u002F\u003CID>\u002Fdocs\u002Farchitecture.drawio \\\n       --output controls\u002F\u003Ccategory>\u002F\u003CID>\u002Fmedia\u002Farchitecture.png\n   ```\n\n   The export format embeds the source XML in the PNG's own metadata\n   (`xmlpng`), so the committed image is also directly re-openable and\n   re-editable in the VS Code draw.io extension, not just a dead-end\n   raster -- a nice side benefit over the Mermaid pipeline's plain PNG.\n\n7. **Verify the output visually** before committing: open the rendered\n   image and confirm every icon shows a real logo\u002Fglyph, not a broken-image\n   placeholder. A broken image most often means either the `icon:` path is\n   wrong relative to the `.drawio` file's directory, or (if hand-editing\n   the style outside this script's placeholder mechanism) a raw `;` snuck\n   into an embedded `data:` URI -- mxGraph's style parser does a naive\n   `style.split(';')` (confirmed 2026-09-24 by reading\n   `mxgraph\u002Fsrc\u002Fview\u002FmxStylesheet.js` in the bundled extension), so any\n   literal semicolon inside a value silently truncates it. This is exactly\n   why the render script's `icon:` placeholder expands to a **non-base64**,\n   fully percent-encoded `data:image\u002Fsvg+xml,...` URI instead of the more\n   common `data:image\u002Fsvg+xml;base64,...` form: the base64 form's own\n   `;base64,` segment contains the one semicolon that breaks it.\n\n8. **Embed the image in the README**, following this repository's existing\n   `\u003Cimg>`-with-caption convention:\n\n   ```html\n   \u003Cp align=\"center\">\n       \u003Cimg src=\"media\u002Farchitecture.png\" alt=\"\u003Cdescribe what the diagram shows>\" width=\"900\">\n   \u003C\u002Fp>\n   ```\n\n   Do **not** add a \"Source: docs\u002Farchitecture.drawio ... re-render it with\n   `scripts\u002Frender_drawio_diagram.py`\" caption sentence after the image --\n   confirmed on VAL-001 and QLT-001 (2026-09-25) that this is authoring\n   information (how a maintainer regenerates the picture), not something\n   the reader of the control needs, and it was removed from both. The\n   `.drawio` source being committed next to the image (see the next step)\n   is enough for a future editor to find it; a diffable git history and the\n   file's own presence in `docs\u002F` already answer \"where does this come\n   from\" without spending a reader-facing sentence on it.\n\n   The declared `width` must equal the actual rendered image's pixel width\n   (this repository's own tests enforce that) -- resize the PNG first if\n   the raw render is wider than is comfortable to read, and update `width`\n   to match the resized file, not the original.\n\n9. **Keep the `.drawio` source committed** next to the image so a future\n   edit only needs to change the source and re-run step 4.\n\n## Mermaid fallback (when the draw.io extension is unavailable)\n\nThe same pipeline this skill previously used exclusively still works and is\nstill the right choice for a machine without the draw.io extension\ninstalled:\n\n1. One-time setup: `mkdir -p .tooling\u002Fmermaid && cd .tooling\u002Fmermaid && npm init -y && npm install @mermaid-js\u002Fmermaid-cli @iconify-json\u002Flogos && cd -`\n   (`.tooling\u002F` is gitignored; never add these packages to a control's own\n   dependency files).\n2. Write `docs\u002Farchitecture.mmd` using `architecture-beta` syntax\n   (`service name(logos:microsoft-teams)[Teams Workflows]`, `group id(icon)[Label]`,\n   edges as `from:SIDE --> SIDE:to`).\n3. Pick icons from, in order: a user-supplied official asset in\n   `media\u002Ficons\u002F` turned into a local pack with `scripts\u002Fbuild_icon_pack.py`\n   (referenced as `--local-icon-pack fwf#media\u002Ficons\u002Ffwf-icons.json`, served\n   with a CORS header the script already adds -- a locally-built pack\n   fetched without one silently fails and renders a \"?\"); `logos:\u003Cname>`\n   from the installed `@iconify-json\u002Flogos` set; `azure:\u003Cname>` from the\n   community pack fetched by URL via `--iconPacksNamesAndUrls`; no icon at\n   all if nothing fits.\n4. Render: `python3 scripts\u002Frender_architecture_diagram.py --input docs\u002Farchitecture.mmd --output media\u002Farchitecture.png [--local-icon-pack ... ] [--chrome \"\u002FApplications\u002FGoogle Chrome.app\u002FContents\u002FMacOS\u002FGoogle Chrome\"]`.\n5. Verify visually, embed in the README, and keep the `.mmd` committed --\n   same as steps 5-7 of the draw.io workflow above.\n\n### Verify relationships against the actual code, not memory or a prior summary\n\nBefore drawing an edge between two building blocks, confirm what actually\ncalls what by reading the control's own entry point (`demo.py` or\nequivalent), not by reasoning from an earlier design description or a\nmental model carried over from a previous session. Confirmed the hard way\non QLT-001 (2026-09-24): an earlier pass drew `az \u002F azd auth login` as the\nnode that invokes the hosted agent, and drew the agent's output as flowing\ninto a passive downstream \"Eval definition\" scorer. Reading `demo.py`\ndirectly showed both were wrong -- authentication is a one-time prerequisite\nwith no outgoing calls of its own, and `demo.py` itself is the caller that\ndirectly invokes the agent (`azd ai agent invoke`) *and* directly triggers\nand reads the eval run (`azd ai agent eval run`, then\n`openai_client.evals.runs.output_items.list`); the agent's involvement in\nscoring happens through Foundry's own eval-run mechanism, not through a\ncall chain `demo.py` orchestrates end to end. A visually polished diagram\nthat draws the wrong caller is worse than an ugly one that draws the right\none -- treat \"does this match what the code actually does\" as a required\ncheck, equal in weight to the visual checks in the previous section.\n\n### Do not add step numbers, even if asked for \"reading order\"\n\nThe Demo infrastructure setup (simplified) diagram is a component overview, not an\nexecution trace -- `docs\u002Fcontrol-readme-template.md` says so explicitly\n(\"This is a component overview, not a numbered execution trace\"). If a\nreviewer asks for a way to tell reading order from the image, resist adding\n①②③-style sequence numbers to nodes or edges; that reintroduces the exact\ncall-order framing the template rules out, and this control's own several\nCLI subcommands (`run`, `evaluate`, `notify`) are invoked as separate,\nindependently-runnable steps by an operator, not one atomic top-to-bottom\nsequence a numbered diagram would honestly represent. Address the concern\nwith descriptive edge labels (what relationship this is) instead of\nsequence numbers (when it happens).\n\n## What this does not replace\n\n- \"Logical design\" diagrams stay plain `flowchart` code blocks -- decision\n  flow, not building blocks, and no rendering pipeline is needed for them.\n- A control with no interesting real-world services to show (for example, a\n  guided exercise with no deployed components) should keep stating\n  \"Not applicable\" rather than forcing an icon diagram where none is\n  warranted.\n","# Demo infrastructure setup (simplified) diagram with real icons\n\n## Why this exists, and the one hard constraint to respect\n\nMost controls' \"Demo infrastructure setup (simplified)\" sections in this repository use\na plain Mermaid `flowchart` with `classDef`-based color coding\n(purple\u002Fblue\u002Fgreen\u002Forange) instead of real service icons, because that is\nwhat GitHub's built-in Mermaid renderer supports natively in a live code\nblock. Two controls use this skill's icon-based pipeline\n(`docs\u002Farchitecture.drawio` + `media\u002Farchitecture.png`):\n\n- **`KNW-001_knowledge_freshness_breach` -- the preferred reference.** Its\n  Azure-scope layout (see \"Reference layout\" below) was confirmed by the\n  user on 2026-11-08 as clearly better than the earlier style. Copy its\n  `.drawio` as the starting point for any control that deploys Azure\n  resources.\n- `QLT-001_hallucination_rate_high` -- the earlier free-floating icon\n  chain. It is still a valid example of a causal chain with no deployed\n  resource boundary to show, but don't copy its group or icon-size\n  conventions into a new diagram.\n\nWhichever tool builds the diagram, **GitHub cannot render it live**: it does\nnot call Mermaid's `registerIconPacks()` for `architecture-beta` icons, and\nit has no draw.io renderer at all for `.drawio` XML. Either way the only\noption is to pre-render the diagram locally to a static PNG and commit that\nimage -- the same \"capture once, commit the artifact\" pattern this\nrepository already uses for screenshots (`scripts\u002Fcapture_teams_card.py`).\nThis means an icon-based architecture diagram is **not** a live-editable\ncode block like this repository's other diagrams: every future edit\nrequires re-running the render step and re-committing the image. Say this\ntrade-off out loud to the user before switching a control over, and keep the\ndiagram source file (`.drawio` or `.mmd`) committed alongside the image so it\ncan be re-rendered.\n\n## When to use\n\n- Creating a new control's \"Demo infrastructure setup (simplified)\" section and real\n  Azure\u002FMicrosoft\u002FGitHub\u002FPython service icons would make the building blocks\n  easier to recognize than colored boxes.\n- The user asks to add or refresh real icons on an existing control's\n  architecture diagram.\n- Do **not** use this for \"Logical design\" diagrams (decision flow, not\n  building blocks) -- keep those as plain `flowchart` code blocks per\n  `.github\u002Finstructions\u002Fgovernance-controls.instructions.md`.\n\n## Which tool: draw.io (preferred) or Mermaid (fallback)\n\nUse **draw.io** (`scripts\u002Frender_drawio_diagram.py`) unless the VS Code\n\"Draw.io Integration\" extension (`hediet.vscode-drawio`) is not installed on\nthis machine. It is the better fit for this repository specifically because\n`media\u002Ficons\u002FAzure_Public_Service_Icons\u002F` already holds the official,\nMicrosoft-published Azure Public Service Icons set (714 SVGs across ~29\ncategories) with a prebuilt search index -- draw.io just needs a relative\npath to one of those files, no icon-pack build step, no CORS server, and\nfree-form pixel-precise layout instead of Mermaid's `architecture-beta`\nauto-layout (which produced label\u002Ficon overlap and awkward spacing on\nearlier attempts).\n\nFall back to **Mermaid** (`scripts\u002Frender_architecture_diagram.py`, see\n\"Mermaid fallback\" below) only when the draw.io extension genuinely is not\navailable and installing it is not an option -- it needs its own local\nIconify icon-pack build step and a CORS-enabled local server for any\nofficial custom icon, which is more moving parts for the same result.\n\n## Reference layout: Azure scope boundaries (preferred)\n\nConfirmed on KNW-001 (2026-11-08). The user compared it with that control's\nearlier diagram (free-floating icons, dashed \"NOT DEPLOYED\"\u002F\"pending\"\nboxes and edges, a \"Remaining integrations\" column) and called the new\nversion clearly better. Use this layout whenever a control deploys or\nconfigures Azure resources. Open\n`controls\u002Fdata_and_knowledge\u002FKNW-001_knowledge_freshness_breach\u002Fdocs\u002Farchitecture.drawio`\nand copy its cells rather than restyling from scratch.\n\nWhy it works: a reader can match each box one to one with what they will\nsee in the Azure Portal after deployment (subscription, then resource\ngroup, then resource, then sub-resource). It shows only what the demo\nactually deploys. Every arrow means the same thing (the caller calls the\nservice the arrow points to), and the legend says so.\n\n**Canvas layout, top to bottom:**\n\n1. **Title and subtitle**, top-left. The title is\n   `\u003CID> · \u003Ccontrol name> — demo infrastructure` (`fontSize=19;fontStyle=1;fontColor=#182B39`).\n   The subtitle is italic gray (`fontSize=12;fontStyle=2;fontColor=#555555`),\n   for example \"Synthetic data only. Arrows point from the caller to the\n   service it calls.\"\n2. **Legend box**, top-right (`fillColor=#FFFFFF;strokeColor=#7F7F7F`,\n   `rounded=1;arcSize=4;absoluteArcSize=1`). It has one short sample line\n   per edge kind (for example \"Data access (Entra ID)\" and \"Notification\n   (HTTPS)\") and one sample box per boundary meaning (for example \"Deployed\n   for the demo; removed by cleanup\"). Every edge colour and boundary style\n   in the diagram must appear in the legend, and nothing else should.\n3. **Subscription boundary**: a square-cornered rectangle with\n   `fillColor=#CFE2F7;strokeColor=#9DBFE6`, plus a header tab above its\n   top-left corner. The tab is a `fillColor=#1F4E8C;strokeColor=none`\n   rectangle with a white bold text cell on top reading\n   \"Azure subscription (demo)\".\n4. **Resource group panel** inside it (`fillColor=#FAFAFA;strokeColor=#A6A6A6`,\n   `arcSize=4` absolute). Its header is the Resource Groups icon (28px)\n   followed by one text line: `Resource group \u003Cb>rg-…-demo\u003C\u002Fb> · \u003Cregion> ·\n   every resource tagged \u003Ci>control-id=\u003CID>\u003C\u002Fi>`. This turns the tagging\n   convention from `copilot-instructions.md` into something visible.\n5. **One white panel per resource or capability**\n   (`fillColor=#FFFFFF;strokeColor=#BFBFBF` or `#7F7F7F`, `arcSize=4`\n   absolute). Lay them out on a grid with equal gutters (20px in KNW-001).\n   Each panel header is a 32-40px icon plus a two-line label:\n   `\u003Cb>Resource type\u003C\u002Fb>\u003Cbr>\u003Ci>SKU · region\u003C\u002Fi>`.\n6. **Sub-resources inside a panel**, such as Blob containers, go in an\n   inner tinted panel (`fillColor=#F4F7FB;strokeColor=#BFBFBF`) with a small\n   italic caption (\"Blob containers\"). Use one 30px icon plus a\n   `\u003Cb>name\u003C\u002Fb>\u003Cbr>\u003Ci>purpose\u003C\u002Fi>` label per item. Show sub-resources only\n   when the control reads or writes them separately.\n7. **Function apps: one card per function**, not one icon per app. Use a\n   `120x72` card (`strokeColor=#E8B53A;strokeWidth=1.5;fillColor=#FFFFFF`,\n   `arcSize=6` absolute) with a 28px Functions icon centered at the top and\n   the label `\u003Cb>Function name\u003C\u002Fb>\u003Cbr>\u003Ci>trigger · auth\u003C\u002Fi>` below it. Put\n   the app's own header (icon + `\u003Cb>Function App\u003C\u002Fb>\u003Cbr>\u003Ci>plan · runtime\u003C\u002Fi>`)\n   at the bottom-left of the panel. That way edges leave from the specific\n   function that makes the call.\n8. **Identity and RBAC panel** (only when the control relies on a managed\n   identity): show the managed identity (`\u003Ci>system-assigned · no stored\n   secrets\u003C\u002Fi>`) and one \"RBAC role assignments\" row listing the actual role\n   names. Draw this as a passive panel with no edges. The legend's \"Data\n   access (Entra ID)\" entry already explains how the calls authenticate.\n   This narrows step 1's \"leave auth out of the diagram\" rule rather than\n   contradicting it: no `authenticates via` edges or auth nodes, but a\n   least-privilege access model the README's \"Inspect in Azure\" asks the\n   reader to verify does belong on the diagram.\n9. **Outside-scope band** below the subscription, for anything the\n   control uses but does not own or delete, such as Microsoft Entra ID and\n   external notification sinks (Teams, HTTPS endpoints). Use a\n   `fillColor=#FFF8E1;strokeColor=#F2B705;strokeWidth=3` rectangle with a\n   corner tag at its bottom-right (`fillColor=#F9D86B`, bold right-aligned\n   text \"Outside the control's resource group\"). Write \"(optional)\" in the\n   label of anything that is optional.\n10. **Human actors** (for example the Data Owner) stand outside every\n    boundary, usually on the left. Use the Azure \"Users\" icon with a bold\n    role name under it, and put their action on the edge label (\"signs in,\n    confirms the shown revision\").\n\n**Icon sizes by tier, not one size for everything.** Inside one tier, keep\nevery icon the same size. Between tiers, size icons by role:\n\n| Tier | Size | Examples |\n|---|---|---|\n| Primary service or actor | 48px | Azure AI Search, Foundry agent, model deployment, Entra ID, Teams, a human actor |\n| Resource panel header | 32-40px | Storage account, Foundry project, Function App, managed identity, RBAC |\n| Small header badge or sub-resource | 28-30px | Resource Groups badge, Blob containers, per-function icon in a card |\n\nThis replaces the older \"every icon, badges included, at 64x64\" rule. That\nrule fit a flat chain of four nodes, but in a nested layout the hierarchy\nis what makes it readable. Keep the \"visual weight\" check from\n\"Verify icon sizing\" below: a thin ribbon-style logo can still look smaller\nthan a solid icon in the same tier.\n\n**Edges: two kinds, both solid, directed caller to callee.**\n\n- Near-black data access: `strokeColor=#1A1A1A;strokeWidth=1.5;endArrow=block;endFill=1;endSize=7`.\n- Teal notification: the same style with `strokeColor=#00A3BF`, and a teal\n  label.\n\nUse `edgeStyle=orthogonalEdgeStyle;rounded=0` with pinned\n`exitX\u002FexitY\u002FentryX\u002FentryY` on every edge (see \"Route edges deliberately\").\nWrite labels as short verb phrases from the caller's side (\"reads source\nmetadata, writes evidence\", \"retrieves via project connection\", \"calls\").\nPut a schedule or other qualifier in italics on a second line\n(\"Blob indexer\u003Cbr>\u003Ci>(24-hour schedule)\u003C\u002Fi>\").\n\n**Match the label backdrop to the panel it sits on.** The two-cell label\npattern (see \"Differentiate edges by meaning\") still applies, but the\nbackdrop rectangle's `fillColor` must equal the fill of the panel under it:\n`#FAFAFA` on the resource-group panel, `#FFFFFF` on a white resource panel.\nA white backdrop on the light-gray resource-group fill shows up as a\nvisible white patch.\n\n**Show only what is deployed.** Do not draw planned, pending, or\n\"NOT DEPLOYED\" components with dashed boxes and edges. The earlier KNW-001\ndiagram did this, and it made the picture about project status instead of\nthe control. Status belongs in the README status line and\n`docs\u002FVALIDATION.md`. Until a component exists, leave it out of the\ndiagram, or mark it \"(optional)\" if it really is optional.\n\n**Size and embedding.** KNW-001's canvas is about 1340 x 770 and is\nembedded at `width=\"1100\"` after resizing. The alt text should list every\nboundary and component in reading order, so the image's content is\navailable without seeing it.\n\n## draw.io workflow (preferred)\n\n### One-time setup (author-only, per machine)\n\nInstall the \"Draw.io Integration\" VS Code extension\n(`hediet.vscode-drawio`, marketplace id `hediet.vscode-drawio`) if it is not\nalready present. Nothing else to install: `scripts\u002Frender_drawio_diagram.py`\ndrives the extension's own bundled copy of the diagrams.net web app with\nPlaywright (already a repository dependency via `capture_teams_card.py`),\nserving it over a throwaway local HTTP server (it needs http:\u002F\u002F, not\nfile:\u002F\u002F, for its own internal resource fetches) and reusing the system\nChrome via `--channel chrome` by default.\n\n### Steps\n\n1. **Decide what belongs in the diagram before listing building blocks.**\n   Default to showing the *core mechanism* -- what a first-time reader needs\n   to understand why this control works -- not every plumbing detail of how\n   it happens to be run today. Confirmed the hard way on QLT-001\n   (2026-09-24), across several rounds of feedback: an early version made\n   authentication (`az`\u002F`azd auth login`) and the execution environment\n   (\"Local developer workstation (not an Azure resource)\") into the most\n   visually prominent nodes, each with its own box, badge, and long\n   connecting line -- and the reviewer's reaction was that authentication\n   \"is not really the key thing to show here,\" and that naming the exact\n   current execution environment \"feels cumbersome\" for a detail that could\n   change (it could just as well be an Azure Function tomorrow). The fix\n   that stuck: cut auth and the execution environment out of the diagram\n   entirely and cover them in one prose sentence *above* the image instead\n   (for example \"This control's infrastructure is minimal: `demo.py`, run\n   locally and authenticated via `az`\u002F`azd auth login`, orchestrates every\n   step below against an already-deployed Foundry project\") -- then draw\n   only the causal chain that explains the control's actual mechanism (a\n   hosted agent's output is scored, the score becomes a decision, a\n   breaching decision notifies someone). Treat \"does every node in this\n   diagram help someone understand why this control works, or does it just\n   describe today's deployment convenience\" as the filter, and default to\n   prose for anything that fails it. A hosting detail earns a diagram node\n   only when it is itself the notable fact (for example, a control whose\n   whole point is a specific network boundary or managed identity). For a\n   `DEPLOYABLE_DEMO` or `HYBRID_DEMO` with an \"Inspect in Azure\" section,\n   the deployed resources and their scope *are* the notable fact. Show\n   them with the \"Reference layout\" above, but still leave out deployment\n   tooling (`az`, `azd`, the operator's workstation).\n\n2. **List the real building blocks** that survive that filter: the hosted\n   agent\u002Fservice, the platform capability that provides its signal, the\n   component that turns the signal into a decision, and any external\n   destination (Teams, GitHub Actions).\n\n3. **Differentiate from this control's \"Logical design\" section.** Every\n   control README already has a \"Logical design\" Mermaid flowchart showing\n   the decision *branches* (which threshold produces which outcome).\n   Demo infrastructure setup (simplified) should not redraw the same branches with\n   icons instead of colored boxes -- that is pure duplication with no new\n   information. Show the building blocks and the *data flow* between them\n   instead (what calls what, what artifact produces what), and say so\n   explicitly in the prose above the image so the two sections' distinct\n   jobs are legible to the reader, not just to whoever designed them (for\n   example: \"This is a different view from 'Logical design' above, not a\n   repeat of it: Logical design shows the three decision branches; this\n   diagram shows the building blocks and data flow that produce the score\n   those branches decide on\").\n\n4. **Find a real icon for each node** by searching the index instead of\n   guessing a filename:\n\n   ```zsh\n   grep -i \"foundry agent\" media\u002Ficons\u002FAzure_Public_Service_Icons\u002Ficon-index.jsonl\n   ```\n\n   Each match is one JSON object with a `path` (relative to\n   `media\u002Ficons\u002FAzure_Public_Service_Icons\u002FIcons\u002F`), `category`, `name`, and\n   `slug`. Prefer the most specific official match over a generic one --\n   confirmed the hard way on QLT-001 (2026-09-24): this set has precise\n   icons like \"Foundry Agent Service\" and \"Foundry Project\", which are a\n   real, correct match for a Foundry hosted agent and its containing\n   project, not a stand-in. Re-run `scripts\u002Findex_azure_icons.py` if the\n   icon set folder has been updated and the index looks stale (it is\n   deterministic and diffable, so a re-run's diff shows exactly what\n   changed). For anything that is not an Azure service at all (a local\n   Python script, Microsoft Teams, another non-Azure product), do not force\n   an Azure icon onto it. Check `media\u002Ficons\u002F` (repo root) for an existing\n   real asset first; if none exists but the official brand SVG is already\n   cached locally in `.tooling\u002Fmermaid\u002Fnode_modules\u002F@iconify-json\u002Flogos\u002Ficons.json`\n   (installed for the Mermaid fallback below, but its icons are legitimate\n   official brand SVGs regardless of which renderer uses them), extract it\n   into a standalone file once:\n\n   ```zsh\n   python3 -c \"\n   import json\n   with open('.tooling\u002Fmermaid\u002Fnode_modules\u002F@iconify-json\u002Flogos\u002Ficons.json') as f:\n       d = json.load(f)\n   icon = d['icons']['python']  # or 'microsoft-teams', etc.\n   w, h = icon.get('width', d['width']), icon.get('height', d['height'])\n   open('media\u002Ficons\u002Fpython-language.svg', 'w').write(\n       f'\u003Csvg xmlns=\\\"http:\u002F\u002Fwww.w3.org\u002F2000\u002Fsvg\\\" width=\\\"{w}\\\" height=\\\"{h}\\\" viewBox=\\\"0 0 {w} {h}\\\">{icon[\\\"body\\\"]}\u003C\u002Fsvg>'\n   )\"\n   ```\n\n   (an iconify pack entry is just an inner `\u003Cbody>` fragment, not a\n   standalone file -- it must be wrapped in a real `\u003Csvg>` root before\n   `icon:` placeholder expansion or `build_icon_pack.py` can use it). Only\n   if no real asset exists anywhere should a node fall back to a plain\n   labeled box with no icon.\n\n5. **Write the `.drawio` source** (an `\u003Cmxfile>` containing one `\u003Cdiagram>`\n   with a plain `\u003CmxGraphModel>`) in the control's own directory, for\n   example `docs\u002Farchitecture.drawio`. Reference each icon with an\n   `icon:\u003Crelative-path>` placeholder in a `shape=image` style -- the\n   render script resolves this to a real embedded image, you never write a\n   raw `data:` URI by hand:\n\n   ```xml\n   \u003CmxCell id=\"agent\" value=\"Hosted agent\"\n           style=\"shape=image;image=icon:..\u002F..\u002F..\u002F..\u002Fmedia\u002Ficons\u002FAzure_Public_Service_Icons\u002FIcons\u002Fai + machine learning\u002F038470523-icon-service-Foundry-Agent-Service.svg;verticalLabelPosition=bottom;verticalAlign=top;fontSize=12;labelBackgroundColor=#ffffff;\"\n           vertex=\"1\" parent=\"1\">\n     \u003CmxGeometry x=\"608\" y=\"110\" width=\"64\" height=\"64\" as=\"geometry\" \u002F>\n   \u003C\u002FmxCell>\n   ```\n\n   The path is relative to the `.drawio` file's own directory. Use a plain\n   rounded rectangle with a real icon (`shape=image` as above) for anything\n   with an official match, and only fall back to a plain\n   `style=\"rounded=1;whiteSpace=wrap;html=1;fillColor=#EEF2FF;strokeColor=#6E56CF;fontSize=12;\"`\n   box when nothing fits -- confirmed on QLT-001 (2026-09-24) that swapping\n   plain boxes for real per-node icons (the Microsoft Teams logo for a\n   \"Teams Workflows\" node, the Python logo for each Python script node) made\n   the rendered diagram noticeably more compelling than text-only boxes,\n   even where no Azure-specific icon exists.\n\n   **For a control that deploys Azure resources, use the nested Azure-scope\n   boundaries from \"Reference layout\" above instead of the dashed tinted\n   groups and uniform 64x64 icons described in the rest of this paragraph.**\n   The rest of this paragraph still applies to a flat causal chain with no\n   deployed resource boundary (the QLT-001 shape).\n\n   Draw a dashed rounded rectangle *with a light fill tint*\n   (`fillColor=#F5F3FF` for a Foundry\u002Fgovernance boundary,\n   `fillColor=#EFF6FF` for a platform boundary, matching each group's\n   `strokeColor`) *behind* a group of related nodes (added earlier in the\n   XML so it renders behind, not as a true mxGraph parent\u002Fchild container)\n   to visually group them -- a filled tint reads as more finished than a\n   transparent outline. Badge the group with a real icon representing what\n   the group actually is, as a separate `shape=image` cell layered near the\n   group's top-left corner, with the text label (a separate plain\n   `style=\"text;html=1;...\"` cell, not the group rectangle's own `value`)\n   offset to the right of the badge rather than overlapping it -- confirmed\n   on QLT-001 (2026-09-24) that a \"Microsoft Foundry project\" group with no\n   Foundry badge and a \"Local developer workstation\" group with no device\n   badge both read as incomplete once a reviewer compared them to the\n   fully-iconed nodes inside. **Give every icon in the diagram the same\n   geometry (for example 64x64) -- badges included.** A first pass at this\n   used a smaller size (24-28px) for group badges than for the main nodes;\n   the user immediately flagged it as inconsistent, and separately, some\n   official icons (a thin ribbon mark like \"AI Foundry\") visually read as\n   smaller than a bolder icon (a solid hexagon) even at the *exact same*\n   bounding box, because the artwork itself uses less of its own canvas --\n   render a same-size comparison strip (see the size-check pattern below)\n   before assuming equal geometry means equal visual weight. **Center a\n   group's main icon(s) within the group's width, not flush against its\n   left edge next to the badge column.** A first pass placed the badge and\n   the main icons in the same left-aligned column, leaving a wide unused\n   strip down the right side of every group -- confirmed on QLT-001\n   (2026-09-24) that this reads as unfinished (\"icons hugging the wall\n   instead of standing in the room\"). Compute `icon_x = group_x + (group_\n   width - icon_width) \u002F 2` for the main icons; leave the header badge\n   left-aligned next to its label, since a badge-plus-label header is\n   conventionally left-aligned like a title bar and centering it would look\n   stranger, not better. Use a small, fixed corner radius on group\n   rectangles instead of `rounded=1`'s default (which reads as an oversized\n   pill on a large box): `rounded=1;arcSize=5;absoluteArcSize=1;` fixes the\n   radius at 5px regardless of the rectangle's size, rather than scaling\n   the radius as a percentage of the shorter side. Connect nodes\n   with edges styled per relationship type, not one identical arrow for\n   everything -- see \"Differentiate edges by meaning\" below. Keep node count\n   small and labels short -- this is still a bite-sized diagram, not a full\n   topology map.\n\n### Differentiate edges by meaning\n\nA diagram where every edge is an identical black arrow forces the reader to\ninfer what kind of relationship each one is. Give each distinct kind of\nrelationship its own color, dash pattern, and short label, reusing this\nrepository's palette so the meaning stays consistent across controls:\n\n- Solid black or gray, no label or a short factual label -- plain\n  sequential\u002Fdata flow (one node's output directly becomes the next node's\n  input).\n- Teal (`strokeColor=#00A3BF`) labeled \"notifies\" -- a message sent to a\n  human or a notification channel.\n- Purple (`strokeColor=#A855F7` or `#7E22CE`) labeled \"invokes\" -- a call\n  into a governed\u002Fhosted component.\n\nNote: an earlier version of this guidance recommended a dashed amber edge\nlabeled \"authenticates via\" for auth\u002Fidentity steps. Per \"Decide what\nbelongs in the diagram\" above, authentication is now a prose note above the\nimage, not a node or edge -- if a control's diagram still has an\n\"authenticates via\" edge, that is a sign it should be simplified, not a\npattern to copy into a new diagram.\n\n**Prefer solid over dashed once dashed no longer carries real meaning.**\nDashed strokes are useful for a genuine distinction (for example \"Foundry's\nown internal mechanism\" vs. \"this control's own code calling out\"), but two\nreal problems show up otherwise: (1) a dash's phase can land exactly at a\nlabel's edge and peek a couple of pixels beyond it -- switching the edge to\nsolid avoids this specific symptom, though see the more general\n`labelBackgroundColor` problem below, which affects solid edges too; (2)\nonce a diagram is simplified down to a single causal chain (see above),\nevery edge in it is the same kind of \"this produces that\" relationship, so\na dashed\u002Fsolid split stops encoding any real distinction and is just\ninconsistent for its own sake -- confirmed on QLT-001 (2026-09-24), where\ndashed styling left over from a more complex, multi-actor version of the\ndiagram no longer matched anything once the diagram was cut down to four\nnodes.\n\n**`labelBackgroundColor` on an edge's own `value`, or on a standalone\n`style=\"text;...\"` cell used as a label, does not reliably produce a padded\nbackground -- confirmed on QLT-001 across several attempts (2026-09-25).**\nThe symptom: a connecting line appears to touch or run directly through the\nlabel's text on both sides, as if the white background box were sized\nexactly to the glyphs with zero padding. This is not a dash-phase artifact\n(it persists on solid edges too) and is not fixed by any of the following,\neach tried and confirmed *not* to work: padding the label's own text value\nwith leading\u002Ftrailing spaces (draw.io's own model strips or ignores this\nfor width purposes); giving a standalone label cell an explicit, generous\n`width`\u002F`height` in its `mxGeometry` (a plain `text;` style shape auto-sizes\nto fit its rendered content in draw.io's graph model on load, silently\noverriding whatever geometry the source XML declares); adding\n`whiteSpace=wrap` to that same text cell (does not override the auto-sizing\nbehavior either). **The fix that actually worked:** stop relying on any\ntext shape's own background entirely. Pair every label with two separate\ncells at the identical position and size: a plain rectangle with a real\nfill and no text\n(`style=\"rounded=0;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=none;\"`)\nsized generously wider than the text it will cover, plus a `style=\"text;...\"`\ncell on top with no `labelBackgroundColor` of its own. Rectangles reliably\nhonor their declared `mxGeometry` (proven by every icon and group box in\nthis same diagram), so this is what actually creates real, verifiable\npadding -- confirm it by rendering, then cropping and viewing the label\nregion at full (pre-resize) resolution, not by eyeballing the downscaled\nembed image, since the gap this fix produces is only a few pixels wide.\n\n**Don't duplicate a fact the prose above the diagram already states.**\nIf a detail is already established in the sentence introducing the image\n(for example \"scored by a *batch* evaluation run\"), don't also cram it into\nan edge label -- confirmed on QLT-001 (2026-09-24): adding \"(batch eval\nrun)\" to an edge label that already had a full-sentence-worth of text made\nthe label wide enough to visually collide with the arrowhead at the far end\nof its own routing segment. Add the qualifier to the prose (or shorten the\nsegment\u002Fwiden the gap) rather than to an already-long label.\n\n```xml\n\u003CmxCell id=\"e1\" value=\"\" edge=\"1\" parent=\"1\" source=\"runner\" target=\"teams\"\n        style=\"edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=block;strokeWidth=2;strokeColor=#00A3BF;exitX=0;exitY=0.5;entryX=0;entryY=0.5;\">\n  \u003CmxGeometry relative=\"1\" as=\"geometry\" \u002F>\n\u003C\u002FmxCell>\n\u003C!-- Label as two separate cells at the same position, not the edge's own\n     value\u002FlabelBackgroundColor -- see above for why. -->\n\u003CmxCell id=\"e1-bg\" parent=\"1\" style=\"rounded=0;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=none;\" value=\"\" vertex=\"1\">\n  \u003CmxGeometry x=\"640\" y=\"121\" width=\"70\" height=\"18\" as=\"geometry\" \u002F>\n\u003C\u002FmxCell>\n\u003CmxCell id=\"e1-label\" parent=\"1\" style=\"text;html=1;align=center;verticalAlign=middle;fontSize=11;fontColor=#00A3BF;\" value=\"notifies\" vertex=\"1\">\n  \u003CmxGeometry x=\"640\" y=\"121\" width=\"70\" height=\"18\" as=\"geometry\" \u002F>\n\u003C\u002FmxCell>\n```\n\n### Route edges deliberately -- floating connections cross and collide\n\nmxGraph's default \"floating\" connection (no `exitX`\u002F`exitY`\u002F`entryX`\u002F`entryY`,\nno waypoints) picks whatever point on each shape's perimeter is closest to\nthe other shape's center. This looks fine for one isolated edge and produces\ntwo real, confirmed failure modes once a diagram has several:\n\n1. **Edges cross each other** when two edges leave the same source toward\n   targets on opposite sides, because each one's floating exit point can end\n   up more central than expected. Fix: pin `exitX`\u002F`exitY` and\n   `entryX`\u002F`entryY` explicitly (fractions 0-1 of the shape's own bounding\n   box) on every edge, and add `edgeStyle=orthogonalEdgeStyle;rounded=0;` so\n   the line bends at right angles instead of drawing a diagonal.\n2. **An edge cuts straight through an unrelated icon or label** when its\n   shortest path happens to pass through a group's badge\u002Flabel header on the\n   way from an interior node to a target outside the group. Fix: give the\n   edge explicit waypoints (`\u003CArray as=\"points\">\u003CmxPoint x=\"..\" y=\"..\"\u002F>...\u003C\u002FArray>`\n   inside the edge's `\u003CmxGeometry>`) that route it outside the group's\n   bounding box first, then up or across to the target, instead of straight\n   through the group's interior. Confirmed on QLT-001 (2026-09-24): two\n   edges from a node inside a group to two nodes above the group both\n   originally cut straight through that group's badge icon; adding one\n   waypoint just outside each side of the group's bounding box before\n   turning toward the target fixed it.\n\nSeparately, **an edge's own auto-placed label can land exactly on top of a\nnearby node's label** if the edge's midpoint happens to coincide with where\nthat node's label sits below it -- confirmed on QLT-001 (2026-09-24), where\na vertical edge's default centered label overlapped the source node's own\nlabel directly above it, rendering as garbled overlapping text. Fix: give\nthe edge no `value` and add a separate manually positioned `style=\"text;...\"`\ncell for its label instead, positioned in whatever free space actually\nexists (increase the gap between the two connected nodes first if none\ndoes), rather than trusting the edge's automatic midpoint placement.\n\n**A chain of nodes at the same height needs its connecting edges routed\nabove or below the icon row, never through the icons' own vertical\ncenter.** `entryY=0.5`\u002F`exitY=0.5` connects at each icon's vertical\nmidpoint, which is *inside* the icon artwork when both nodes sit at the\nsame height -- confirmed on QLT-001 (2026-09-24): a simplified left-to-right\nchain of four same-height icons rendered its connecting lines and labels\ndirectly behind the icon glyphs, invisible against the artwork. Fix: route\nevery edge in the chain along a shared horizontal \"spine\" a fixed distance\nabove the icon row instead -- `exitX=0.5;exitY=0` (icon's top-center) with a\nwaypoint at the same `x` a fixed offset above the icons (for example 20px),\nacross to the target's `x` at that same spine height, then down into\n`entryX=0.5;entryY=0` (target's top-center). Because the segments between\ndifferent node pairs in a simple left-to-right chain don't share an `x`\nrange, every edge can use the *same* spine height without colliding with\nits neighbors -- there's no need to stagger heights unless two edges\nactually cross the same `x` range.\n\n### Verify icon sizing and edge layout before calling it done\n\nTwo verification passes catch what \"does it render at all\" does not:\n\n1. **Size comparison.** Render every candidate icon at the same fixed\n   geometry (for example a row of `shape=image` cells all sized 64x64) in a\n   disposable test diagram before wiring them into the real one, and look\n   at whether they read as visually equal -- not just whether the bounding\n   box matches. A thin ribbon-style logo can look smaller than a solid\n   geometric icon at an identical box size.\n2. **Full-diagram visual review**, specifically checking for: any label\n   touching or overlapping the icon above it, any two edges crossing each\n   other, any edge passing through an icon or a label instead of empty\n   space, and how much unused white space the group boxes contain relative\n   to their actual content (a box sized for content that got trimmed later\n   reads as an unfinished layout). Treat \"the command exited 0 and produced\n   a PNG\" as necessary, not sufficient.\n3. **Scope review**: does any node exist only to describe today's\n   deployment\u002Fexecution convenience rather than to explain why the control\n   works (see \"Decide what belongs in the diagram\" above)? Does the diagram\n   redraw the same decision branches \"Logical design\" already shows instead\n   of showing building blocks and data flow? Both were real, repeated\n   findings on QLT-001, not hypothetical risks -- check for them explicitly\n   rather than assuming a diagram that renders cleanly is also well-scoped.\n   For the Azure-scope layout, also check: does every box nest under the\n   scope it really lives in (subscription, resource group, resource)? Does\n   the outside-scope band hold exactly the things cleanup does not delete?\n   Does the legend list every edge colour and boundary style and nothing\n   else? Is nothing drawn as planned or pending? Does every label backdrop\n   match the fill of the panel under it?\n4. **A group's own boundary stroke can bisect a node's label that sits just\n   inside it.** Confirmed on QLT-001 (2026-09-25): a group box sized to end\n   right at its icon row's bottom, with the icon's text label positioned\n   just below that (a common layout, since labels conventionally sit under\n   their icon), placed the group's dashed bottom edge exactly through the\n   vertical middle of that label's text, rendering as a strikethrough. This\n   is a distinct failure mode from \"label overlaps the icon above it\" in\n   item 2 above -- the label doesn't touch its own icon at all, it collides\n   with the *group container's* edge instead, so a review pass that only\n   checks label-vs-icon overlap misses it. **A first attempted fix --\n   enlarging the group to enclose the label with a 10px+ margin below it --\n   did not reliably resolve this** (confirmed on a second render pass, same\n   control, same day: the boundary still read as touching\u002Funderlining the\n   label even after adding margin). The fix: keep every contained node's\n   label fully *outside* the group -- matching how every other (non-grouped)\n   node's label already sits outside any box in the same diagram -- rather\n   than trying to size the group to enclose the label with margin. Don't\n   stop at \"outside,\" though: a first pass at this shrank the group down to\n   just 4px of clearance below the icon row, which fixed the text collision\n   but then read as visually cramped -- box edge nearly touching the icons\n   -- next to the generous, un-boxed white space around every other node in\n   the same diagram (confirmed on a third render pass, same control, same\n   day, after the user flagged the cramped result as still not right). The\n   padding that actually read as correct: roughly 20px of clear space\n   between the icon row's bottom and the group's bottom edge, achieved by\n   moving *every* node's label (grouped and ungrouped alike) down together\n   by the same offset to open up that room, keeping every label row aligned\n   at the same height across the whole diagram. Verify at full render\n   resolution (crop and inspect the group region directly, not just\n   eyeballing the full downscaled image), not only at the final resized\n   embed dimensions -- and judge padding by comparison against the\n   un-grouped nodes' own white space in the same image, not in isolation.\n5. **Multiple edges converging on the same target's entry side need\n   real visual separation, not just distinct `entryX` values.** Confirmed\n   on QLT-001 (2026-09-25): two edges entering the same icon with\n   `entryX=0.4` and `entryX=0.6` (a 0.2 spread, roughly 13px apart on a\n   64px-wide icon) still read as one merged arrowhead at a glance. Spread\n   convergent entries much further apart -- `entryX=0.2`\u002F`entryX=0.8` (a\n   0.6 spread) reads as two clearly distinct arrows. The same applies in\n   reverse to multiple edges leaving the same source: give each its own\n   `exitX` spread this wide too, not just a technically-different value,\n   so the lines visibly diverge right from their source instead of\n   overlapping for their first stretch.\n\n6. **Render it**:\n\n   ```zsh\n   .venv\u002Fbin\u002Fpython scripts\u002Frender_drawio_diagram.py \\\n       --input controls\u002F\u003Ccategory>\u002F\u003CID>\u002Fdocs\u002Farchitecture.drawio \\\n       --output controls\u002F\u003Ccategory>\u002F\u003CID>\u002Fmedia\u002Farchitecture.png\n   ```\n\n   The export format embeds the source XML in the PNG's own metadata\n   (`xmlpng`), so the committed image is also directly re-openable and\n   re-editable in the VS Code draw.io extension, not just a dead-end\n   raster -- a nice side benefit over the Mermaid pipeline's plain PNG.\n\n7. **Verify the output visually** before committing: open the rendered\n   image and confirm every icon shows a real logo\u002Fglyph, not a broken-image\n   placeholder. A broken image most often means either the `icon:` path is\n   wrong relative to the `.drawio` file's directory, or (if hand-editing\n   the style outside this script's placeholder mechanism) a raw `;` snuck\n   into an embedded `data:` URI -- mxGraph's style parser does a naive\n   `style.split(';')` (confirmed 2026-09-24 by reading\n   `mxgraph\u002Fsrc\u002Fview\u002FmxStylesheet.js` in the bundled extension), so any\n   literal semicolon inside a value silently truncates it. This is exactly\n   why the render script's `icon:` placeholder expands to a **non-base64**,\n   fully percent-encoded `data:image\u002Fsvg+xml,...` URI instead of the more\n   common `data:image\u002Fsvg+xml;base64,...` form: the base64 form's own\n   `;base64,` segment contains the one semicolon that breaks it.\n\n8. **Embed the image in the README**, following this repository's existing\n   `\u003Cimg>`-with-caption convention:\n\n   ```html\n   \u003Cp align=\"center\">\n       \u003Cimg src=\"media\u002Farchitecture.png\" alt=\"\u003Cdescribe what the diagram shows>\" width=\"900\">\n   \u003C\u002Fp>\n   ```\n\n   Do **not** add a \"Source: docs\u002Farchitecture.drawio ... re-render it with\n   `scripts\u002Frender_drawio_diagram.py`\" caption sentence after the image --\n   confirmed on VAL-001 and QLT-001 (2026-09-25) that this is authoring\n   information (how a maintainer regenerates the picture), not something\n   the reader of the control needs, and it was removed from both. The\n   `.drawio` source being committed next to the image (see the next step)\n   is enough for a future editor to find it; a diffable git history and the\n   file's own presence in `docs\u002F` already answer \"where does this come\n   from\" without spending a reader-facing sentence on it.\n\n   The declared `width` must equal the actual rendered image's pixel width\n   (this repository's own tests enforce that) -- resize the PNG first if\n   the raw render is wider than is comfortable to read, and update `width`\n   to match the resized file, not the original.\n\n9. **Keep the `.drawio` source committed** next to the image so a future\n   edit only needs to change the source and re-run step 4.\n\n## Mermaid fallback (when the draw.io extension is unavailable)\n\nThe same pipeline this skill previously used exclusively still works and is\nstill the right choice for a machine without the draw.io extension\ninstalled:\n\n1. One-time setup: `mkdir -p .tooling\u002Fmermaid && cd .tooling\u002Fmermaid && npm init -y && npm install @mermaid-js\u002Fmermaid-cli @iconify-json\u002Flogos && cd -`\n   (`.tooling\u002F` is gitignored; never add these packages to a control's own\n   dependency files).\n2. Write `docs\u002Farchitecture.mmd` using `architecture-beta` syntax\n   (`service name(logos:microsoft-teams)[Teams Workflows]`, `group id(icon)[Label]`,\n   edges as `from:SIDE --> SIDE:to`).\n3. Pick icons from, in order: a user-supplied official asset in\n   `media\u002Ficons\u002F` turned into a local pack with `scripts\u002Fbuild_icon_pack.py`\n   (referenced as `--local-icon-pack fwf#media\u002Ficons\u002Ffwf-icons.json`, served\n   with a CORS header the script already adds -- a locally-built pack\n   fetched without one silently fails and renders a \"?\"); `logos:\u003Cname>`\n   from the installed `@iconify-json\u002Flogos` set; `azure:\u003Cname>` from the\n   community pack fetched by URL via `--iconPacksNamesAndUrls`; no icon at\n   all if nothing fits.\n4. Render: `python3 scripts\u002Frender_architecture_diagram.py --input docs\u002Farchitecture.mmd --output media\u002Farchitecture.png [--local-icon-pack ... ] [--chrome \"\u002FApplications\u002FGoogle Chrome.app\u002FContents\u002FMacOS\u002FGoogle Chrome\"]`.\n5. Verify visually, embed in the README, and keep the `.mmd` committed --\n   same as steps 5-7 of the draw.io workflow above.\n\n### Verify relationships against the actual code, not memory or a prior summary\n\nBefore drawing an edge between two building blocks, confirm what actually\ncalls what by reading the control's own entry point (`demo.py` or\nequivalent), not by reasoning from an earlier design description or a\nmental model carried over from a previous session. Confirmed the hard way\non QLT-001 (2026-09-24): an earlier pass drew `az \u002F azd auth login` as the\nnode that invokes the hosted agent, and drew the agent's output as flowing\ninto a passive downstream \"Eval definition\" scorer. Reading `demo.py`\ndirectly showed both were wrong -- authentication is a one-time prerequisite\nwith no outgoing calls of its own, and `demo.py` itself is the caller that\ndirectly invokes the agent (`azd ai agent invoke`) *and* directly triggers\nand reads the eval run (`azd ai agent eval run`, then\n`openai_client.evals.runs.output_items.list`); the agent's involvement in\nscoring happens through Foundry's own eval-run mechanism, not through a\ncall chain `demo.py` orchestrates end to end. A visually polished diagram\nthat draws the wrong caller is worse than an ugly one that draws the right\none -- treat \"does this match what the code actually does\" as a required\ncheck, equal in weight to the visual checks in the previous section.\n\n### Do not add step numbers, even if asked for \"reading order\"\n\nThe Demo infrastructure setup (simplified) diagram is a component overview, not an\nexecution trace -- `docs\u002Fcontrol-readme-template.md` says so explicitly\n(\"This is a component overview, not a numbered execution trace\"). If a\nreviewer asks for a way to tell reading order from the image, resist adding\n①②③-style sequence numbers to nodes or edges; that reintroduces the exact\ncall-order framing the template rules out, and this control's own several\nCLI subcommands (`run`, `evaluate`, `notify`) are invoked as separate,\nindependently-runnable steps by an operator, not one atomic top-to-bottom\nsequence a numbered diagram would honestly represent. Address the concern\nwith descriptive edge labels (what relationship this is) instead of\nsequence numbers (when it happens).\n\n## What this does not replace\n\n- \"Logical design\" diagrams stay plain `flowchart` code blocks -- decision\n  flow, not building blocks, and no rendering pipeline is needed for them.\n- A control with no interesting real-world services to show (for example, a\n  guided exercise with no deployed components) should keep stating\n  \"Not applicable\" rather than forcing an icon diagram where none is\n  warranted.\n",{"name":5,"license":15,"metadata":24,"description":7,"user-invocable":26},{"authors":12,"spec_version":25},"2.0",true,"main","e51c6b933afa0091b74eb2ae277466a8a39a929d",".claude\u002Fskills\u002Fmermaid-infra-diagram",1,"https:\u002F\u002Fgithub.com\u002Fdoruit\u002Fforged-with-foundry","https:\u002F\u002Fgithub.com\u002Fdoruit","MVP Microsoft AI Platform","2026-11-15 00:34:55",{"source":8,"skillName":5,"commands":36,"prompt":46,"zipAvailable":26},[37,40,43],{"tool":38,"command":39},"npx","npx skills add doruit\u002Fforged-with-foundry --skill mermaid-infra-diagram",{"tool":41,"command":42},"bunx","bunx skills add doruit\u002Fforged-with-foundry --skill mermaid-infra-diagram",{"tool":44,"command":45},"pnpm","pnpm dlx skills add doruit\u002Fforged-with-foundry --skill mermaid-infra-diagram","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fdoruit\u002Fforged-with-foundry\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fmermaid-infra-diagram\u002FSKILL.md",[],[49,56,63,70,75,80],{"skillNo":50,"name":51,"nameZh":6,"description":52,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":53,"categories":54,"keywords":55,"publishedAt":19},"01M7BV6R1JZ71GKYFK224G3343","linkedin-post-writer","Generates rich, engagement-optimized LinkedIn posts announcing new AI governance control demos, weekly\u002Fmonthly repo updates, and category-completion milestones for Forged with Foundry","https:\u002F\u002Fgithub.com\u002Fdoruit\u002Fforged-with-foundry\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Flinkedin-post-writer\u002FSKILL.md",[],[],{"skillNo":57,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":19},"01M7BV6M4TDHDYMYZSZZMMDC9K","markdown-doc-quality","Detects AI-slop patterns in Markdown documentation: heading\u002Fbody contradictions, unverified external claims, hedging filler, missing evidence examples, and inconsistent terminology across .md files","https:\u002F\u002Fgithub.com\u002Fdoruit\u002Fforged-with-foundry\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fcoding-standards\u002Fmarkdown-doc-quality\u002FSKILL.md",[],[],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":19},"01M7BV6J19CM0HVX2RQN98R920","assess-governance-control","Assess a governance control before implementation","https:\u002F\u002Fgithub.com\u002Fdoruit\u002Fforged-with-foundry\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fassess-governance-control\u002FSKILL.md",[],[],{"skillNo":71,"name":58,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":19},"01M7BV66RP0PDAED33QNKPFK2W","https:\u002F\u002Fgithub.com\u002Fdoruit\u002Fforged-with-foundry\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fmarkdown-doc-quality\u002FSKILL.md",[],[],{"skillNo":76,"name":51,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":19},"01M7BV64PGDQFN5K5YVGFV70ZG","https:\u002F\u002Fgithub.com\u002Fdoruit\u002Fforged-with-foundry\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Flinkedin-post-writer\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":19},"01M7BV5YV8MZ10RES3SD4SQV3E","control-demo-roast","Adversarial pre-announcement review of a Forged with Foundry control demo -- run before linkedin-post-writer, not instead of it -- to catch overclaiming, unproven mechanisms, and stale estimates that would embarrass the team once a technical community actually tries the demo","https:\u002F\u002Fgithub.com\u002Fdoruit\u002Fforged-with-foundry\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fcontrol-demo-roast\u002FSKILL.md",[],[]]