docs: label central autonomous agent Human Controlled

.gitattributes

@@ -0,0 +1,2 @@
+# Preserve byte-identical third-party sources, including upstream whitespace.
+vendor/archify/** -whitespace

.gitignore

@@ -5,3 +5,4 @@ build/
 .env
 .env.*
 !.env.example
+static/diagrams/

README.md

@@ -25,6 +25,16 @@ Pull requests validate only. Pushes to `main` validate, build, and publish to th
 
 After publication, verify the exact commit’s Actions task and deployed page body; an OAuth redirect is not content verification. Future changes should use pull requests. Never commit credentials or edit generated `build/` output.
 
+## Sections and diagrams
+
+Top-level sections are Organization, Strategy, and Contribution, each with an independent sidebar. The first Organization page is Structure. It presents the organizational operating model: leadership, departments, teams, responsibilities and cross-functional delivery. Research and source excerpts remain under `research/organization/`, outside the published documentation.
+
+Archify 3.0.1 is vendored under `vendor/archify/` from commit `d5a1333d7447c866a765adac7d4d062f2f02e4d2`. MIT and third-party notices are preserved. `diagrams/` holds editable JSON; `pnpm diagrams:build` validates and generates local standalone viewers before every site build. The iframe is sandboxed without same-origin permission. See `docs/contribution/diagrams.md` for capability analysis, authoring, boundaries, and upgrade procedure.
+
+The build checks upstream provenance before applying the portal integration: `scripts/inline-viewer.css` restores compact embed controls, two guarded preset restrictions are removed from generated viewers only, and `scripts/viewer-theme-bridge.js` synchronizes theme with the portal through source-validated messages. Vendor files remain unchanged. Delivery receipts describe the upstream artifact before this integration, not the final served bytes. Theme changes do not reload viewers or discard visual presets. PNG, JPEG, WebP and SVG downloads remain available; browser-dependent exports stay disabled when unsupported.
+
+For interaction acceptance, serve the production build on port 4173 and run `pnpm test:browser` with an installed Playwright Chromium (or `PLAYWRIGHT_CHROMIUM_EXECUTABLE`). This checks story layouts, portal/diagram theme synchronization, all four presets, actual exported artifact decoding, route changes, and fullscreen click/Escape/focus behavior at desktop and mobile widths. Screenshots, downloads and results are saved under ignored `.cache/` directories.
+
 ## Design
 
-Inspired by https://www.eldorado.gg/: Lato, near-black navigation, charcoal, gold `#ffc950`, light panels, bold headings. Original documentation artwork and square panels; no official marketplace assets or business claims. See `docs/reference.md`.
+Inspired by https://www.eldorado.gg/: Lato, near-black navigation, charcoal, gold `#ffc950`, light panels, bold headings. Original documentation artwork and square panels; no official marketplace assets or business claims. See `docs/core/reference.md`.

diagrams/ai-adoption-target.architecture.json

@@ -0,0 +1,39 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {"title": "TO-BE: governed AI adoption", "output": "static/diagrams/ai-adoption-target/index.html", "quality_profile": "showcase"},
+  "components": [
+    {"id":"people","type":"external","label":"Accountable people","sublabel":"Existing teams; approved work","pos":[40,80],"size":[240,80]},
+    {"id":"coordinator","type":"backend","label":"One SDLC coordinator","sublabel":"Data & AI; durable task ledger","pos":[440,80],"size":[240,80]},
+    {"id":"registry","type":"database","label":"Governed skills registry","sublabel":"Pinned bundles + qualified adapters","pos":[840,80],"size":[260,80]},
+    {"id":"provider","type":"cloud","label":"Model providers","sublabel":"Approved data + retention terms","pos":[40,340],"size":[240,80]},
+    {"id":"clients","type":"frontend","label":"Local laptop contributors","sublabel":"Copilot / Claude Code / Cline","pos":[440,340],"size":[240,80]},
+    {"id":"gates","type":"security","label":"Repository + CI gates","sublabel":"Independent exact-revision checks","pos":[440,600],"size":[240,80]},
+    {"id":"approval","type":"external","label":"Human release approval","sublabel":"Exact artifact; scoped; expires","pos":[840,600],"size":[260,80]},
+    {"id":"release","type":"security","label":"Release service","sublabel":"Production credentials only here","pos":[840,860],"size":[260,80]},
+    {"id":"audit","type":"database","label":"Audit + measurement","sublabel":"Restricted evidence; feedback","pos":[40,860],"size":[240,80]}
+  ],
+  "boundaries": [
+    {"kind":"security-group","label":"Supply-chain review","wraps":["registry"]},
+    {"kind":"security-group","label":"Data / egress boundary","wraps":["provider"]},
+    {"kind":"security-group","label":"Untrusted local proposals","wraps":["clients"]},
+    {"kind":"security-group","label":"Independent delivery authority","wraps":["gates","approval","release"]}
+  ],
+  "connections": [
+    {"id":"approved-work","from":"people","to":"coordinator","label":"Authorize scope","variant":"security"},
+    {"id":"coord-skills","from":"registry","to":"coordinator","label":"Pinned skills"},
+    {"id":"task-proposals","from":"coordinator","to":"clients","label":"Route tasks","variant":"dashed"},
+    {"id":"local-skills","from":"registry","to":"clients","label":"Qualified bundle","fromSide":"bottom","toSide":"right"},
+    {"id":"inference","from":"clients","to":"provider","label":"Allowed data","variant":"security"},
+    {"id":"proposals","from":"clients","to":"gates","label":"Propose changes","variant":"dashed"},
+    {"id":"evidence","from":"gates","to":"approval","label":"Verified evidence"},
+    {"id":"authorize","from":"approval","to":"release","label":"Approve artifact","variant":"security"},
+    {"id":"outcomes","from":"release","to":"audit","label":"Outcome evidence"},
+    {"id":"feedback","from":"audit","to":"people","label":"Review outcomes","variant":"dashed"}
+  ],
+  "cards": [
+    {"dot":"cyan","title":"Target, not deployed","items":["One logical coordinating function; resilient ledger and human takeover.","Registry content is guidance, not authority. No laptop or coordinator production credentials."]},
+    {"dot":"rose","title":"Human authority","items":["Department leaders retain accountability; independent reviewers accept actual artifacts.","CI and release controls fail closed; approval is bound to the exact revision."]},
+    {"dot":"emerald","title":"Evidence loop","items":["Audit feedback informs people and the next authorized coordinator task.","Approved provider routing applies to coordinator and local inference; no silent policy-changing fallback."]}
+  ]
+}

diagrams/organization-reporting.architecture.json

@@ -0,0 +1,230 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "Eldorado leadership and delivery structure",
+    "output": "static/diagrams/organization-reporting/index.html",
+    "quality_profile": "showcase",
+    "legend": {
+      "entries": {
+        "backend": {
+          "label": "Leadership / department"
+        },
+        "frontend": {
+          "label": "Role / delivery team"
+        }
+      }
+    }
+  },
+  "components": [
+    {
+      "id": "cto",
+      "type": "frontend",
+      "label": "CTO",
+      "sublabel": "Technology direction",
+      "pos": [
+        40,
+        40
+      ],
+      "size": [
+        240,
+        80
+      ]
+    },
+    {
+      "id": "head-engineering",
+      "type": "frontend",
+      "label": "Head of Engineering",
+      "sublabel": "Engineering leadership",
+      "pos": [
+        400,
+        40
+      ],
+      "size": [
+        240,
+        80
+      ]
+    },
+    {
+      "id": "group-em",
+      "type": "frontend",
+      "label": "Group Eng. Manager",
+      "sublabel": "Engineering group leadership",
+      "pos": [
+        760,
+        40
+      ],
+      "size": [
+        240,
+        80
+      ]
+    },
+    {
+      "id": "em",
+      "type": "frontend",
+      "label": "Engineering Manager",
+      "sublabel": "Team leadership and delivery",
+      "pos": [
+        1120,
+        40
+      ],
+      "size": [
+        240,
+        80
+      ]
+    },
+    {
+      "id": "engineers",
+      "type": "frontend",
+      "label": "Software engineers",
+      "sublabel": "Product Engineering team",
+      "pos": [
+        1480,
+        40
+      ],
+      "size": [
+        240,
+        80
+      ]
+    },
+    {
+      "id": "ai-architect",
+      "type": "frontend",
+      "label": "AI Architect",
+      "sublabel": "AI enablement across engineering",
+      "pos": [
+        40,
+        280
+      ],
+      "size": [
+        240,
+        80
+      ]
+    },
+    {
+      "id": "coo",
+      "type": "backend",
+      "label": "COO",
+      "sublabel": "Lukas Deksnys",
+      "pos": [
+        400,
+        280
+      ],
+      "size": [
+        240,
+        80
+      ]
+    },
+    {
+      "id": "ops-qa",
+      "type": "frontend",
+      "label": "QA Specialist (Ops)",
+      "sublabel": "Independent operational quality",
+      "pos": [
+        760,
+        280
+      ],
+      "size": [
+        240,
+        80
+      ]
+    },
+    {
+      "id": "cmo",
+      "type": "frontend",
+      "label": "CMO",
+      "sublabel": "Marketing leadership",
+      "pos": [
+        1120,
+        280
+      ],
+      "size": [
+        240,
+        80
+      ]
+    },
+    {
+      "id": "brand-lead",
+      "type": "frontend",
+      "label": "Brand Team Lead",
+      "sublabel": "Brand and community",
+      "pos": [
+        1480,
+        280
+      ],
+      "size": [
+        240,
+        80
+      ]
+    }
+  ],
+  "connections": [
+    {
+      "id": "cto-head-engineering",
+      "from": "cto",
+      "to": "head-engineering",
+      "label": "Leads",
+      "variant": "default"
+    },
+    {
+      "id": "head-engineering-group-em",
+      "from": "head-engineering",
+      "to": "group-em",
+      "label": "Leads",
+      "variant": "default"
+    },
+    {
+      "id": "group-em-em",
+      "from": "group-em",
+      "to": "em",
+      "label": "Leads",
+      "variant": "default"
+    },
+    {
+      "id": "em-engineers",
+      "from": "em",
+      "to": "engineers",
+      "label": "Leads",
+      "variant": "default"
+    },
+    {
+      "id": "cto-ai-architect",
+      "from": "cto",
+      "to": "ai-architect",
+      "label": "Leads",
+      "variant": "default"
+    },
+    {
+      "id": "coo-ops-qa",
+      "from": "coo",
+      "to": "ops-qa",
+      "label": "Leads",
+      "variant": "default"
+    },
+    {
+      "id": "cmo-brand-lead",
+      "from": "cmo",
+      "to": "brand-lead",
+      "label": "Leads",
+      "variant": "default"
+    }
+  ],
+  "cards": [
+    {
+      "dot": "cyan",
+      "title": "Leadership and delivery",
+      "items": [
+        "Arrows run from leader to role or team.",
+        "Functional leaders develop people, standards and delivery capability."
+      ]
+    },
+    {
+      "dot": "amber",
+      "title": "Interdepartmental collaboration",
+      "items": [
+        "Product Owners, Designers and Tech Leads align on product outcomes.",
+        "Data & AI enables AI adoption across Technology."
+      ]
+    }
+  ]
+}

diagrams/organization-structure.architecture.json

@@ -0,0 +1,472 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "Eldorado organization structure",
+    "output": "static/diagrams/organization-structure/index.html",
+    "quality_profile": "showcase",
+    "legend": {
+      "entries": {
+        "backend": {
+          "label": "Leadership / department"
+        },
+        "frontend": {
+          "label": "Role / delivery team"
+        }
+      }
+    }
+  },
+  "components": [
+    {
+      "id": "management",
+      "type": "backend",
+      "label": "Management",
+      "sublabel": "CEO / COO",
+      "pos": [
+        820,
+        40
+      ],
+      "size": [
+        320,
+        80
+      ]
+    },
+    {
+      "id": "product",
+      "type": "backend",
+      "label": "Product",
+      "sublabel": "Experience and product outcomes",
+      "pos": [
+        40,
+        280
+      ],
+      "size": [
+        280,
+        80
+      ]
+    },
+    {
+      "id": "technology",
+      "type": "backend",
+      "label": "Technology",
+      "sublabel": "Engineering and platform",
+      "pos": [
+        360,
+        280
+      ],
+      "size": [
+        280,
+        80
+      ]
+    },
+    {
+      "id": "operations",
+      "type": "backend",
+      "label": "Operations",
+      "sublabel": "Service, resolution and trust",
+      "pos": [
+        680,
+        280
+      ],
+      "size": [
+        280,
+        80
+      ]
+    },
+    {
+      "id": "marketing",
+      "type": "backend",
+      "label": "Marketing",
+      "sublabel": "Brand and customer growth",
+      "pos": [
+        1000,
+        280
+      ],
+      "size": [
+        280,
+        80
+      ]
+    },
+    {
+      "id": "finance",
+      "type": "backend",
+      "label": "Finance & Accounting",
+      "sublabel": "Financial performance and controls",
+      "pos": [
+        1320,
+        280
+      ],
+      "size": [
+        280,
+        80
+      ]
+    },
+    {
+      "id": "people",
+      "type": "backend",
+      "label": "HR & Administration",
+      "sublabel": "People and workplace",
+      "pos": [
+        1640,
+        280
+      ],
+      "size": [
+        280,
+        80
+      ]
+    },
+    {
+      "id": "product-team-1",
+      "type": "frontend",
+      "label": "Product Management",
+      "sublabel": "Strategy, priorities and outcomes",
+      "pos": [
+        100,
+        480
+      ],
+      "size": [
+        220,
+        80
+      ]
+    },
+    {
+      "id": "product-team-2",
+      "type": "frontend",
+      "label": "Product Design",
+      "sublabel": "Research and experience design",
+      "pos": [
+        100,
+        620
+      ],
+      "size": [
+        220,
+        80
+      ]
+    },
+    {
+      "id": "technology-team-1",
+      "type": "frontend",
+      "label": "Product Engineering",
+      "sublabel": "Marketplace software delivery",
+      "pos": [
+        420,
+        480
+      ],
+      "size": [
+        220,
+        80
+      ]
+    },
+    {
+      "id": "technology-team-2",
+      "type": "frontend",
+      "label": "Platform & IT",
+      "sublabel": "Reliability and internal systems",
+      "pos": [
+        420,
+        620
+      ],
+      "size": [
+        220,
+        80
+      ]
+    },
+    {
+      "id": "technology-team-3",
+      "type": "frontend",
+      "label": "Architecture & Security",
+      "sublabel": "Technical standards and protection",
+      "pos": [
+        420,
+        760
+      ],
+      "size": [
+        220,
+        80
+      ]
+    },
+    {
+      "id": "technology-team-4",
+      "type": "frontend",
+      "label": "Quality Engineering",
+      "sublabel": "Testing and release quality",
+      "pos": [
+        420,
+        900
+      ],
+      "size": [
+        220,
+        80
+      ]
+    },
+    {
+      "id": "technology-team-5",
+      "type": "frontend",
+      "label": "Data & AI",
+      "sublabel": "Analytics, ML and AI enablement",
+      "pos": [
+        420,
+        1040
+      ],
+      "size": [
+        220,
+        80
+      ]
+    },
+    {
+      "id": "operations-team-1",
+      "type": "frontend",
+      "label": "Operations Squad",
+      "sublabel": "Service, resolution, risk and quality",
+      "pos": [
+        740,
+        480
+      ],
+      "size": [
+        220,
+        80
+      ]
+    },
+    {
+      "id": "marketing-team-1",
+      "type": "frontend",
+      "label": "Marketing Squad",
+      "sublabel": "Brand, acquisition and retention",
+      "pos": [
+        1060,
+        480
+      ],
+      "size": [
+        220,
+        80
+      ]
+    },
+    {
+      "id": "finance-team-1",
+      "type": "frontend",
+      "label": "Finance & Accounting Squad",
+      "sublabel": "Planning, controls and payments",
+      "pos": [
+        1380,
+        480
+      ],
+      "size": [
+        220,
+        80
+      ]
+    },
+    {
+      "id": "people-team-1",
+      "type": "frontend",
+      "label": "People & Administration Squad",
+      "sublabel": "Talent, people and workplace",
+      "pos": [
+        1700,
+        480
+      ],
+      "size": [
+        220,
+        80
+      ]
+    }
+  ],
+  "connections": [
+    {
+      "id": "management-product",
+      "from": "management",
+      "to": "product",
+      "variant": "default",
+      "fromSide": "bottom",
+      "toSide": "top"
+    },
+    {
+      "id": "management-technology",
+      "from": "management",
+      "to": "technology",
+      "variant": "default",
+      "fromSide": "bottom",
+      "toSide": "top"
+    },
+    {
+      "id": "management-operations",
+      "from": "management",
+      "to": "operations",
+      "variant": "default",
+      "fromSide": "bottom",
+      "toSide": "top"
+    },
+    {
+      "id": "management-marketing",
+      "from": "management",
+      "to": "marketing",
+      "variant": "default",
+      "fromSide": "bottom",
+      "toSide": "top"
+    },
+    {
+      "id": "management-finance",
+      "from": "management",
+      "to": "finance",
+      "variant": "default",
+      "fromSide": "bottom",
+      "toSide": "top"
+    },
+    {
+      "id": "management-people",
+      "from": "management",
+      "to": "people",
+      "variant": "default",
+      "fromSide": "bottom",
+      "toSide": "top"
+    },
+    {
+      "id": "product-1",
+      "from": "product",
+      "to": "product-team-1",
+      "variant": "default",
+      "fromSide": "bottom",
+      "toSide": "left"
+    },
+    {
+      "id": "product-2",
+      "from": "product",
+      "to": "product-team-2",
+      "variant": "default",
+      "fromSide": "bottom",
+      "toSide": "left"
+    },
+    {
+      "id": "technology-1",
+      "from": "technology",
+      "to": "technology-team-1",
+      "variant": "default",
+      "fromSide": "bottom",
+      "toSide": "left"
+    },
+    {
+      "id": "technology-2",
+      "from": "technology",
+      "to": "technology-team-2",
+      "variant": "default",
+      "fromSide": "bottom",
+      "toSide": "left"
+    },
+    {
+      "id": "technology-3",
+      "from": "technology",
+      "to": "technology-team-3",
+      "variant": "default",
+      "fromSide": "bottom",
+      "toSide": "left"
+    },
+    {
+      "id": "technology-4",
+      "from": "technology",
+      "to": "technology-team-4",
+      "variant": "default",
+      "fromSide": "bottom",
+      "toSide": "left"
+    },
+    {
+      "id": "technology-5",
+      "from": "technology",
+      "to": "technology-team-5",
+      "variant": "default",
+      "fromSide": "bottom",
+      "toSide": "left"
+    },
+    {
+      "id": "operations-1",
+      "from": "operations",
+      "to": "operations-team-1",
+      "variant": "default",
+      "fromSide": "bottom",
+      "toSide": "left"
+    },
+    {
+      "id": "marketing-1",
+      "from": "marketing",
+      "to": "marketing-team-1",
+      "variant": "default",
+      "fromSide": "bottom",
+      "toSide": "left"
+    },
+    {
+      "id": "finance-1",
+      "from": "finance",
+      "to": "finance-team-1",
+      "variant": "default",
+      "fromSide": "bottom",
+      "toSide": "left"
+    },
+    {
+      "id": "people-1",
+      "from": "people",
+      "to": "people-team-1",
+      "variant": "default",
+      "fromSide": "bottom",
+      "toSide": "left"
+    }
+  ],
+  "cards": [
+    {
+      "dot": "cyan",
+      "title": "Product",
+      "items": [
+        "Product Management",
+        "Product Design"
+      ]
+    },
+    {
+      "dot": "amber",
+      "title": "Technology",
+      "items": [
+        "Product Engineering",
+        "Platform & IT",
+        "Architecture & Security",
+        "Quality Engineering",
+        "Data & AI"
+      ]
+    },
+    {
+      "dot": "cyan",
+      "title": "Operations",
+      "items": [
+        "Operations Squad",
+        "Customer Support; Trust & Resolution",
+        "Risk & Fraud",
+        "Operational Quality"
+      ]
+    },
+    {
+      "dot": "amber",
+      "title": "Marketing",
+      "items": [
+        "Marketing Squad",
+        "Brand & Community; Creative; SEO",
+        "PPC & Affiliate; Influencer",
+        "CRM"
+      ]
+    },
+    {
+      "dot": "cyan",
+      "title": "Finance & Accounting",
+      "items": [
+        "Finance & Accounting Squad",
+        "Financial Planning & Analysis",
+        "Accounting, Tax & Controls",
+        "Treasury & Payment Operations"
+      ]
+    },
+    {
+      "dot": "amber",
+      "title": "HR & Administration",
+      "items": [
+        "People & Administration Squad",
+        "Talent Acquisition",
+        "People Operations",
+        "Office & Administration"
+      ]
+    }
+  ]
+}

diagrams/strategy-adoption-mobile.architecture.json

@@ -0,0 +1,139 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "TO-BE: Learn before expanding",
+    "output": "static/diagrams/strategy-adoption-mobile/index.html",
+    "quality_profile": "showcase",
+    "legend": {
+      "mode": "hidden"
+    }
+  },
+  "components": [
+    {
+      "id": "choose",
+      "type": "backend",
+      "label": "Choose workflow",
+      "sublabel": "Department outcome",
+      "pos": [
+        20,
+        20
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "coach",
+      "type": "backend",
+      "label": "Coach people",
+      "sublabel": "Verify + recover",
+      "pos": [
+        20,
+        140
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "canary",
+      "type": "backend",
+      "label": "Run bounded canary",
+      "sublabel": "Qualified skill + client",
+      "pos": [
+        20,
+        260
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "accept",
+      "type": "backend",
+      "label": "Accept real work",
+      "sublabel": "Independent review",
+      "pos": [
+        20,
+        380
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "feedback",
+      "type": "backend",
+      "label": "Review feedback",
+      "sublabel": "Usefulness + non-use",
+      "pos": [
+        20,
+        500
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "expand",
+      "type": "backend",
+      "label": "Expand or revise",
+      "sublabel": "Keep a manual path",
+      "pos": [
+        20,
+        620
+      ],
+      "size": [
+        180,
+        60
+      ]
+    }
+  ],
+  "connections": [
+    {
+      "id": "flow-0",
+      "from": "choose",
+      "to": "coach",
+      "label": "Prepare"
+    },
+    {
+      "id": "flow-1",
+      "from": "coach",
+      "to": "canary",
+      "label": "support pilot"
+    },
+    {
+      "id": "flow-2",
+      "from": "canary",
+      "to": "accept",
+      "label": "Verify"
+    },
+    {
+      "id": "flow-3",
+      "from": "accept",
+      "to": "feedback",
+      "label": "learn"
+    },
+    {
+      "id": "flow-4",
+      "from": "feedback",
+      "to": "expand",
+      "label": "decide"
+    },
+    {
+      "id": "feedback-loop",
+      "from": "expand",
+      "to": "coach",
+      "label": "Review revision",
+      "variant": "dashed",
+      "fromSide": "right",
+      "toSide": "right"
+    }
+  ]
+}

diagrams/strategy-adoption.architecture.json

@@ -0,0 +1,139 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "TO-BE: Learn before expanding",
+    "output": "static/diagrams/strategy-adoption/index.html",
+    "quality_profile": "showcase",
+    "legend": {
+      "mode": "hidden"
+    }
+  },
+  "components": [
+    {
+      "id": "choose",
+      "type": "backend",
+      "label": "Choose workflow",
+      "sublabel": "Department outcome",
+      "pos": [
+        20,
+        20
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "coach",
+      "type": "backend",
+      "label": "Coach people",
+      "sublabel": "Verify + recover",
+      "pos": [
+        260,
+        20
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "canary",
+      "type": "backend",
+      "label": "Run bounded canary",
+      "sublabel": "Qualified skill + client",
+      "pos": [
+        260,
+        150
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "accept",
+      "type": "backend",
+      "label": "Accept real work",
+      "sublabel": "Independent review",
+      "pos": [
+        20,
+        150
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "feedback",
+      "type": "backend",
+      "label": "Review feedback",
+      "sublabel": "Usefulness + non-use",
+      "pos": [
+        20,
+        280
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "expand",
+      "type": "backend",
+      "label": "Expand or revise",
+      "sublabel": "Keep a manual path",
+      "pos": [
+        260,
+        280
+      ],
+      "size": [
+        180,
+        60
+      ]
+    }
+  ],
+  "connections": [
+    {
+      "id": "flow-0",
+      "from": "choose",
+      "to": "coach",
+      "label": "Prepare"
+    },
+    {
+      "id": "flow-1",
+      "from": "coach",
+      "to": "canary",
+      "label": "support pilot"
+    },
+    {
+      "id": "flow-2",
+      "from": "canary",
+      "to": "accept",
+      "label": "Verify"
+    },
+    {
+      "id": "flow-3",
+      "from": "accept",
+      "to": "feedback",
+      "label": "learn"
+    },
+    {
+      "id": "flow-4",
+      "from": "feedback",
+      "to": "expand",
+      "label": "decide"
+    },
+    {
+      "id": "feedback-loop",
+      "from": "expand",
+      "to": "coach",
+      "label": "Review revision",
+      "variant": "dashed",
+      "fromSide": "right",
+      "toSide": "right"
+    }
+  ]
+}

diagrams/strategy-governance-mobile.architecture.json

@@ -0,0 +1,130 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "TO-BE: Independent approval",
+    "output": "static/diagrams/strategy-governance-mobile/index.html",
+    "quality_profile": "showcase",
+    "legend": {
+      "mode": "hidden"
+    }
+  },
+  "components": [
+    {
+      "id": "owner",
+      "type": "security",
+      "label": "Owner proposes",
+      "sublabel": "Existing accountable team",
+      "pos": [
+        20,
+        20
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "review",
+      "type": "security",
+      "label": "Independent review",
+      "sublabel": "Quality + risk evidence",
+      "pos": [
+        20,
+        140
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "canary",
+      "type": "security",
+      "label": "Bounded canary",
+      "sublabel": "Qualified client path",
+      "pos": [
+        20,
+        260
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "approve",
+      "type": "security",
+      "label": "Approve revision",
+      "sublabel": "Exact digest + scope",
+      "pos": [
+        20,
+        380
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "publish",
+      "type": "security",
+      "label": "Publish bundle",
+      "sublabel": "Data & AI catalog",
+      "pos": [
+        20,
+        500
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "distribute",
+      "type": "security",
+      "label": "Verify effective state",
+      "sublabel": "Platform & IT",
+      "pos": [
+        20,
+        620
+      ],
+      "size": [
+        180,
+        60
+      ]
+    }
+  ],
+  "connections": [
+    {
+      "id": "flow-0",
+      "from": "owner",
+      "to": "review",
+      "label": "submit"
+    },
+    {
+      "id": "flow-1",
+      "from": "review",
+      "to": "canary",
+      "label": "qualify"
+    },
+    {
+      "id": "flow-2",
+      "from": "canary",
+      "to": "approve",
+      "label": "Accept"
+    },
+    {
+      "id": "flow-3",
+      "from": "approve",
+      "to": "publish",
+      "label": "record approval"
+    },
+    {
+      "id": "flow-4",
+      "from": "publish",
+      "to": "distribute",
+      "label": "Deliver"
+    }
+  ]
+}

diagrams/strategy-governance.architecture.json

@@ -0,0 +1,130 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "TO-BE: Independent approval",
+    "output": "static/diagrams/strategy-governance/index.html",
+    "quality_profile": "showcase",
+    "legend": {
+      "mode": "hidden"
+    }
+  },
+  "components": [
+    {
+      "id": "owner",
+      "type": "security",
+      "label": "Owner proposes",
+      "sublabel": "Existing accountable team",
+      "pos": [
+        20,
+        20
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "review",
+      "type": "security",
+      "label": "Independent review",
+      "sublabel": "Quality + risk evidence",
+      "pos": [
+        260,
+        20
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "canary",
+      "type": "security",
+      "label": "Bounded canary",
+      "sublabel": "Qualified client path",
+      "pos": [
+        260,
+        150
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "approve",
+      "type": "security",
+      "label": "Approve revision",
+      "sublabel": "Exact digest + scope",
+      "pos": [
+        20,
+        150
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "publish",
+      "type": "security",
+      "label": "Publish bundle",
+      "sublabel": "Data & AI catalog",
+      "pos": [
+        20,
+        280
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "distribute",
+      "type": "security",
+      "label": "Verify effective state",
+      "sublabel": "Platform & IT",
+      "pos": [
+        260,
+        280
+      ],
+      "size": [
+        180,
+        60
+      ]
+    }
+  ],
+  "connections": [
+    {
+      "id": "flow-0",
+      "from": "owner",
+      "to": "review",
+      "label": "submit"
+    },
+    {
+      "id": "flow-1",
+      "from": "review",
+      "to": "canary",
+      "label": "qualify"
+    },
+    {
+      "id": "flow-2",
+      "from": "canary",
+      "to": "approve",
+      "label": "Accept"
+    },
+    {
+      "id": "flow-3",
+      "from": "approve",
+      "to": "publish",
+      "label": "record approval"
+    },
+    {
+      "id": "flow-4",
+      "from": "publish",
+      "to": "distribute",
+      "label": "Deliver"
+    }
+  ]
+}

diagrams/strategy-journey-mobile.architecture.json

@@ -0,0 +1,130 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "TO-BE: Skills before authority",
+    "output": "static/diagrams/strategy-journey-mobile/index.html",
+    "quality_profile": "showcase",
+    "legend": {
+      "mode": "hidden"
+    }
+  },
+  "components": [
+    {
+      "id": "skills",
+      "type": "backend",
+      "label": "Govern skills",
+      "sublabel": "Owner + pinned revision",
+      "pos": [
+        20,
+        20
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "prove",
+      "type": "backend",
+      "label": "Prove quality",
+      "sublabel": "Independent evaluation",
+      "pos": [
+        20,
+        140
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "pilot",
+      "type": "backend",
+      "label": "Pilot with people",
+      "sublabel": "Qualified local clients",
+      "pos": [
+        20,
+        260
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "distribute",
+      "type": "backend",
+      "label": "Verify distribution",
+      "sublabel": "Canary + rollback",
+      "pos": [
+        20,
+        380
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "coordinate",
+      "type": "backend",
+      "label": "Coordinate delivery",
+      "sublabel": "One logical SDLC agent",
+      "pos": [
+        20,
+        500
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "expand",
+      "type": "backend",
+      "label": "Expand by evidence",
+      "sublabel": "Department outcomes",
+      "pos": [
+        20,
+        620
+      ],
+      "size": [
+        180,
+        60
+      ]
+    }
+  ],
+  "connections": [
+    {
+      "id": "flow-0",
+      "from": "skills",
+      "to": "prove",
+      "label": "qualify"
+    },
+    {
+      "id": "flow-1",
+      "from": "prove",
+      "to": "pilot",
+      "label": "coach"
+    },
+    {
+      "id": "flow-2",
+      "from": "pilot",
+      "to": "distribute",
+      "label": "Verify"
+    },
+    {
+      "id": "flow-3",
+      "from": "distribute",
+      "to": "coordinate",
+      "label": "prove recovery"
+    },
+    {
+      "id": "flow-4",
+      "from": "coordinate",
+      "to": "expand",
+      "label": "Justify"
+    }
+  ]
+}

diagrams/strategy-journey.architecture.json

@@ -0,0 +1,130 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "TO-BE: Skills before authority",
+    "output": "static/diagrams/strategy-journey/index.html",
+    "quality_profile": "showcase",
+    "legend": {
+      "mode": "hidden"
+    }
+  },
+  "components": [
+    {
+      "id": "skills",
+      "type": "backend",
+      "label": "Govern skills",
+      "sublabel": "Owner + pinned revision",
+      "pos": [
+        20,
+        20
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "prove",
+      "type": "backend",
+      "label": "Prove quality",
+      "sublabel": "Independent evaluation",
+      "pos": [
+        260,
+        20
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "pilot",
+      "type": "backend",
+      "label": "Pilot with people",
+      "sublabel": "Qualified local clients",
+      "pos": [
+        260,
+        150
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "distribute",
+      "type": "backend",
+      "label": "Verify distribution",
+      "sublabel": "Canary + rollback",
+      "pos": [
+        20,
+        150
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "coordinate",
+      "type": "backend",
+      "label": "Coordinate delivery",
+      "sublabel": "One logical SDLC agent",
+      "pos": [
+        20,
+        280
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "expand",
+      "type": "backend",
+      "label": "Expand by evidence",
+      "sublabel": "Department outcomes",
+      "pos": [
+        260,
+        280
+      ],
+      "size": [
+        180,
+        60
+      ]
+    }
+  ],
+  "connections": [
+    {
+      "id": "flow-0",
+      "from": "skills",
+      "to": "prove",
+      "label": "qualify"
+    },
+    {
+      "id": "flow-1",
+      "from": "prove",
+      "to": "pilot",
+      "label": "coach"
+    },
+    {
+      "id": "flow-2",
+      "from": "pilot",
+      "to": "distribute",
+      "label": "Verify"
+    },
+    {
+      "id": "flow-3",
+      "from": "distribute",
+      "to": "coordinate",
+      "label": "prove recovery"
+    },
+    {
+      "id": "flow-4",
+      "from": "coordinate",
+      "to": "expand",
+      "label": "Justify"
+    }
+  ]
+}

diagrams/strategy-maintenance-mobile.architecture.json

@@ -0,0 +1,141 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "TO-BE: Maintain trust over time",
+    "output": "static/diagrams/strategy-maintenance-mobile/index.html",
+    "quality_profile": "showcase",
+    "legend": {
+      "mode": "hidden"
+    }
+  },
+  "components": [
+    {
+      "id": "monitor",
+      "type": "backend",
+      "label": "Monitor skills",
+      "sublabel": "Usefulness + safety",
+      "pos": [
+        20,
+        20
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "triage",
+      "type": "backend",
+      "label": "Triage changes",
+      "sublabel": "Owner + risk review",
+      "pos": [
+        20,
+        140
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "correct",
+      "type": "backend",
+      "label": "Correct and test",
+      "sublabel": "Independent regression",
+      "pos": [
+        20,
+        260
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "decision",
+      "type": "backend",
+      "label": "Approve or hold",
+      "sublabel": "Exact revised bundle",
+      "pos": [
+        20,
+        380
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "promote",
+      "type": "backend",
+      "label": "Promote safely",
+      "sublabel": "Verify state + monitor",
+      "pos": [
+        20,
+        500
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "observe",
+      "type": "backend",
+      "label": "Quarantine / rollback",
+      "sublabel": "Revoke unsafe revision",
+      "pos": [
+        20,
+        620
+      ],
+      "size": [
+        180,
+        60
+      ]
+    }
+  ],
+  "connections": [
+    {
+      "id": "flow-0",
+      "from": "monitor",
+      "to": "triage",
+      "label": "Detect"
+    },
+    {
+      "id": "flow-1",
+      "from": "triage",
+      "to": "correct",
+      "label": "scope correction"
+    },
+    {
+      "id": "flow-2",
+      "from": "correct",
+      "to": "decision",
+      "label": "Prove"
+    },
+    {
+      "id": "flow-3",
+      "from": "decision",
+      "to": "promote",
+      "label": "authorize"
+    },
+
+    {
+      "id": "unsafe",
+      "from": "triage",
+      "to": "observe",
+      "label": "Unsafe",
+      "variant": "security",
+      "fromSide": "right",
+      "toSide": "right"
+    },
+    {
+      "id": "review-loop",
+      "from": "observe",
+      "to": "correct",
+      "label": "Requalify",
+      "variant": "dashed"
+    }
+  ]
+}

diagrams/strategy-maintenance.architecture.json

@@ -0,0 +1,141 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "TO-BE: Maintain trust over time",
+    "output": "static/diagrams/strategy-maintenance/index.html",
+    "quality_profile": "showcase",
+    "legend": {
+      "mode": "hidden"
+    }
+  },
+  "components": [
+    {
+      "id": "monitor",
+      "type": "backend",
+      "label": "Monitor skills",
+      "sublabel": "Usefulness + safety",
+      "pos": [
+        20,
+        20
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "triage",
+      "type": "backend",
+      "label": "Triage changes",
+      "sublabel": "Owner + risk review",
+      "pos": [
+        260,
+        20
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "correct",
+      "type": "backend",
+      "label": "Correct and test",
+      "sublabel": "Independent regression",
+      "pos": [
+        260,
+        150
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "decision",
+      "type": "backend",
+      "label": "Approve or hold",
+      "sublabel": "Exact revised bundle",
+      "pos": [
+        20,
+        150
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "promote",
+      "type": "backend",
+      "label": "Promote safely",
+      "sublabel": "Verify state + monitor",
+      "pos": [
+        20,
+        280
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "observe",
+      "type": "backend",
+      "label": "Quarantine / rollback",
+      "sublabel": "Revoke unsafe revision",
+      "pos": [
+        260,
+        280
+      ],
+      "size": [
+        180,
+        60
+      ]
+    }
+  ],
+  "connections": [
+    {
+      "id": "flow-0",
+      "from": "monitor",
+      "to": "triage",
+      "label": "Detect"
+    },
+    {
+      "id": "flow-1",
+      "from": "triage",
+      "to": "correct",
+      "label": "scope correction"
+    },
+    {
+      "id": "flow-2",
+      "from": "correct",
+      "to": "decision",
+      "label": "Prove"
+    },
+    {
+      "id": "flow-3",
+      "from": "decision",
+      "to": "promote",
+      "label": "authorize"
+    },
+
+    {
+      "id": "unsafe",
+      "from": "triage",
+      "to": "observe",
+      "label": "Unsafe",
+      "variant": "security",
+      "fromSide": "right",
+      "toSide": "right"
+    },
+    {
+      "id": "review-loop",
+      "from": "observe",
+      "to": "correct",
+      "label": "Requalify",
+      "variant": "dashed"
+    }
+  ]
+}

diagrams/strategy-measurement-mobile.architecture.json

@@ -0,0 +1,130 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "TO-BE: Evidence before claims",
+    "output": "static/diagrams/strategy-measurement-mobile/index.html",
+    "quality_profile": "showcase",
+    "legend": {
+      "mode": "hidden"
+    }
+  },
+  "components": [
+    {
+      "id": "collect",
+      "type": "backend",
+      "label": "Collect evidence",
+      "sublabel": "Task / CI / incident",
+      "pos": [
+        20,
+        20
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "validate",
+      "type": "backend",
+      "label": "Validate sources",
+      "sublabel": "Joins + missingness",
+      "pos": [
+        20,
+        140
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "calculate",
+      "type": "backend",
+      "label": "Calculate measures",
+      "sublabel": "16 exact contracts",
+      "pos": [
+        20,
+        260
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "balance",
+      "type": "backend",
+      "label": "Read balanced signals",
+      "sublabel": "Quality / flow / risk",
+      "pos": [
+        20,
+        380
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "weigh",
+      "type": "backend",
+      "label": "Weigh benefit and cost",
+      "sublabel": "Outcomes / cost / people",
+      "pos": [
+        20,
+        500
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "decide",
+      "type": "backend",
+      "label": "Continue or change",
+      "sublabel": "No causal ROI claim",
+      "pos": [
+        20,
+        620
+      ],
+      "size": [
+        180,
+        60
+      ]
+    }
+  ],
+  "connections": [
+    {
+      "id": "flow-0",
+      "from": "collect",
+      "to": "validate",
+      "label": "Check"
+    },
+    {
+      "id": "flow-1",
+      "from": "validate",
+      "to": "calculate",
+      "label": "apply definitions"
+    },
+    {
+      "id": "flow-2",
+      "from": "calculate",
+      "to": "balance",
+      "label": "compare"
+    },
+    {
+      "id": "flow-3",
+      "from": "balance",
+      "to": "weigh",
+      "label": "consider together"
+    },
+    {
+      "id": "flow-4",
+      "from": "weigh",
+      "to": "decide",
+      "label": "decide"
+    }
+  ]
+}

diagrams/strategy-measurement.architecture.json

@@ -0,0 +1,130 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "TO-BE: Evidence before claims",
+    "output": "static/diagrams/strategy-measurement/index.html",
+    "quality_profile": "showcase",
+    "legend": {
+      "mode": "hidden"
+    }
+  },
+  "components": [
+    {
+      "id": "collect",
+      "type": "backend",
+      "label": "Collect evidence",
+      "sublabel": "Task / CI / incident",
+      "pos": [
+        20,
+        20
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "validate",
+      "type": "backend",
+      "label": "Validate sources",
+      "sublabel": "Joins + missingness",
+      "pos": [
+        260,
+        20
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "calculate",
+      "type": "backend",
+      "label": "Calculate measures",
+      "sublabel": "16 exact contracts",
+      "pos": [
+        260,
+        150
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "balance",
+      "type": "backend",
+      "label": "Read balanced signals",
+      "sublabel": "Quality / flow / risk",
+      "pos": [
+        20,
+        150
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "weigh",
+      "type": "backend",
+      "label": "Weigh benefit and cost",
+      "sublabel": "Outcomes / cost / people",
+      "pos": [
+        20,
+        280
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "decide",
+      "type": "backend",
+      "label": "Continue or change",
+      "sublabel": "No causal ROI claim",
+      "pos": [
+        260,
+        280
+      ],
+      "size": [
+        180,
+        60
+      ]
+    }
+  ],
+  "connections": [
+    {
+      "id": "flow-0",
+      "from": "collect",
+      "to": "validate",
+      "label": "Check"
+    },
+    {
+      "id": "flow-1",
+      "from": "validate",
+      "to": "calculate",
+      "label": "apply definitions"
+    },
+    {
+      "id": "flow-2",
+      "from": "calculate",
+      "to": "balance",
+      "label": "compare"
+    },
+    {
+      "id": "flow-3",
+      "from": "balance",
+      "to": "weigh",
+      "label": "consider together"
+    },
+    {
+      "id": "flow-4",
+      "from": "weigh",
+      "to": "decide",
+      "label": "decide"
+    }
+  ]
+}

diagrams/strategy-quality-mobile.architecture.json

@@ -0,0 +1,130 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "TO-BE: Risk-tiered qualification",
+    "output": "static/diagrams/strategy-quality-mobile/index.html",
+    "quality_profile": "showcase",
+    "legend": {
+      "mode": "hidden"
+    }
+  },
+  "components": [
+    {
+      "id": "risk",
+      "type": "security",
+      "label": "Classify risk",
+      "sublabel": "R1 / R2 / R3",
+      "pos": [
+        20,
+        20
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "plan",
+      "type": "security",
+      "label": "Agree evaluation",
+      "sublabel": "Task mix + thresholds",
+      "pos": [
+        20,
+        140
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "trial",
+      "type": "security",
+      "label": "Repeat trials",
+      "sublabel": "Candidate vs approved",
+      "pos": [
+        20,
+        260
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "verify",
+      "type": "security",
+      "label": "Verify artifacts",
+      "sublabel": "Independent checks",
+      "pos": [
+        20,
+        380
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "gate",
+      "type": "security",
+      "label": "All gates pass?",
+      "sublabel": "Safety cannot be traded",
+      "pos": [
+        20,
+        500
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "promote",
+      "type": "security",
+      "label": "Promote or hold",
+      "sublabel": "Owner decision",
+      "pos": [
+        20,
+        620
+      ],
+      "size": [
+        180,
+        60
+      ]
+    }
+  ],
+  "connections": [
+    {
+      "id": "flow-0",
+      "from": "risk",
+      "to": "plan",
+      "label": "Scope"
+    },
+    {
+      "id": "flow-1",
+      "from": "plan",
+      "to": "trial",
+      "label": "freeze plan"
+    },
+    {
+      "id": "flow-2",
+      "from": "trial",
+      "to": "verify",
+      "label": "Assess"
+    },
+    {
+      "id": "flow-3",
+      "from": "verify",
+      "to": "gate",
+      "label": "review evidence"
+    },
+    {
+      "id": "flow-4",
+      "from": "gate",
+      "to": "promote",
+      "label": "decide"
+    }
+  ]
+}

diagrams/strategy-quality.architecture.json

@@ -0,0 +1,130 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "TO-BE: Risk-tiered qualification",
+    "output": "static/diagrams/strategy-quality/index.html",
+    "quality_profile": "showcase",
+    "legend": {
+      "mode": "hidden"
+    }
+  },
+  "components": [
+    {
+      "id": "risk",
+      "type": "security",
+      "label": "Classify risk",
+      "sublabel": "R1 / R2 / R3",
+      "pos": [
+        20,
+        20
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "plan",
+      "type": "security",
+      "label": "Agree evaluation",
+      "sublabel": "Task mix + thresholds",
+      "pos": [
+        260,
+        20
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "trial",
+      "type": "security",
+      "label": "Repeat trials",
+      "sublabel": "Candidate vs approved",
+      "pos": [
+        260,
+        150
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "verify",
+      "type": "security",
+      "label": "Verify artifacts",
+      "sublabel": "Independent checks",
+      "pos": [
+        20,
+        150
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "gate",
+      "type": "security",
+      "label": "All gates pass?",
+      "sublabel": "Safety cannot be traded",
+      "pos": [
+        20,
+        280
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "promote",
+      "type": "security",
+      "label": "Promote or hold",
+      "sublabel": "Owner decision",
+      "pos": [
+        260,
+        280
+      ],
+      "size": [
+        180,
+        60
+      ]
+    }
+  ],
+  "connections": [
+    {
+      "id": "flow-0",
+      "from": "risk",
+      "to": "plan",
+      "label": "Scope"
+    },
+    {
+      "id": "flow-1",
+      "from": "plan",
+      "to": "trial",
+      "label": "freeze plan"
+    },
+    {
+      "id": "flow-2",
+      "from": "trial",
+      "to": "verify",
+      "label": "Assess"
+    },
+    {
+      "id": "flow-3",
+      "from": "verify",
+      "to": "gate",
+      "label": "review evidence"
+    },
+    {
+      "id": "flow-4",
+      "from": "gate",
+      "to": "promote",
+      "label": "decide"
+    }
+  ]
+}

diagrams/strategy-roadmap-mobile.architecture.json

@@ -0,0 +1,110 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "TO-BE: Evidence-gated rollout",
+    "output": "static/diagrams/strategy-roadmap-mobile/index.html",
+    "quality_profile": "showcase",
+    "legend": {
+      "mode": "hidden"
+    }
+  },
+  "components": [
+    {
+      "id": "foundation",
+      "type": "backend",
+      "label": "1 \u00b7 Foundation",
+      "sublabel": "People + data + baseline",
+      "pos": [
+        20,
+        20
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "pilot",
+      "type": "backend",
+      "label": "2 \u00b7 Skills pilot",
+      "sublabel": "Qualified, useful work",
+      "pos": [
+        20,
+        140
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "distribution",
+      "type": "backend",
+      "label": "3 \u00b7 Distribution",
+      "sublabel": "Revocation + recovery",
+      "pos": [
+        20,
+        260
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "coordination",
+      "type": "backend",
+      "label": "4 \u00b7 Coordination",
+      "sublabel": "Human takeover proven",
+      "pos": [
+        20,
+        380
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "expansion",
+      "type": "backend",
+      "label": "5 \u00b7 Departments",
+      "sublabel": "Outcomes + cost + risk",
+      "pos": [
+        20,
+        500
+      ],
+      "size": [
+        180,
+        60
+      ]
+    }
+  ],
+  "connections": [
+    {
+      "id": "flow-0",
+      "from": "foundation",
+      "to": "pilot",
+      "label": "Charter"
+    },
+    {
+      "id": "flow-1",
+      "from": "pilot",
+      "to": "distribution",
+      "label": "quality + coverage"
+    },
+    {
+      "id": "flow-2",
+      "from": "distribution",
+      "to": "coordination",
+      "label": "Controls"
+    },
+    {
+      "id": "flow-3",
+      "from": "coordination",
+      "to": "expansion",
+      "label": "authority drills pass"
+    }
+  ]
+}

diagrams/strategy-roadmap.architecture.json

@@ -0,0 +1,110 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "TO-BE: Evidence-gated rollout",
+    "output": "static/diagrams/strategy-roadmap/index.html",
+    "quality_profile": "showcase",
+    "legend": {
+      "mode": "hidden"
+    }
+  },
+  "components": [
+    {
+      "id": "foundation",
+      "type": "backend",
+      "label": "1 \u00b7 Foundation",
+      "sublabel": "People + data + baseline",
+      "pos": [
+        20,
+        20
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "pilot",
+      "type": "backend",
+      "label": "2 \u00b7 Skills pilot",
+      "sublabel": "Qualified, useful work",
+      "pos": [
+        260,
+        20
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "distribution",
+      "type": "backend",
+      "label": "3 \u00b7 Distribution",
+      "sublabel": "Revocation + recovery",
+      "pos": [
+        260,
+        150
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "coordination",
+      "type": "backend",
+      "label": "4 \u00b7 Coordination",
+      "sublabel": "Human takeover proven",
+      "pos": [
+        20,
+        150
+      ],
+      "size": [
+        180,
+        60
+      ]
+    },
+    {
+      "id": "expansion",
+      "type": "backend",
+      "label": "5 \u00b7 Departments",
+      "sublabel": "Outcomes + cost + risk",
+      "pos": [
+        20,
+        280
+      ],
+      "size": [
+        180,
+        60
+      ]
+    }
+  ],
+  "connections": [
+    {
+      "id": "flow-0",
+      "from": "foundation",
+      "to": "pilot",
+      "label": "Charter"
+    },
+    {
+      "id": "flow-1",
+      "from": "pilot",
+      "to": "distribution",
+      "label": "quality + coverage"
+    },
+    {
+      "id": "flow-2",
+      "from": "distribution",
+      "to": "coordination",
+      "label": "Controls"
+    },
+    {
+      "id": "flow-3",
+      "from": "coordination",
+      "to": "expansion",
+      "label": "authority drills pass"
+    }
+  ]
+}

diagrams/strategy-target-mobile.architecture.json

@@ -0,0 +1,51 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {"title": "TO-BE: autonomous SDLC, human direction", "output": "static/diagrams/strategy-target-mobile/index.html", "quality_profile": "showcase", "legend": {"mode": "hidden"}},
+  "components": [
+    {"id":"agent","type":"security","label":"Autonomous agent","sublabel":"Human Controlled","pos":[140,200],"size":[360,120]},
+    {"id":"scope","type":"backend","label":"Scope","sublabel":"01","pos":[100,440],"size":[240,100]},
+    {"id":"architecture","type":"backend","label":"Architecture","sublabel":"02","pos":[100,660],"size":[240,100]},
+    {"id":"ui-ux","type":"backend","label":"UI/UX","sublabel":"03","pos":[100,880],"size":[240,100]},
+    {"id":"planning","type":"backend","label":"Planning","sublabel":"04","pos":[100,1100],"size":[240,100]},
+    {"id":"delivery","type":"backend","label":"Delivery","sublabel":"05","pos":[100,1320],"size":[240,100]},
+    {"id":"uat","type":"backend","label":"UAT","sublabel":"06","pos":[100,1540],"size":[240,100]},
+    {"id":"security","type":"backend","label":"Security","sublabel":"07","pos":[100,1760],"size":[240,100]},
+    {"id":"releases","type":"backend","label":"Releases","sublabel":"08","pos":[100,1980],"size":[240,100]},
+    {"id":"code-scope","type":"frontend","label":"Code agent","sublabel":"Human-controlled","pos":[400,440],"size":[240,100]},
+    {"id":"code-architecture","type":"frontend","label":"Code agent","sublabel":"Human-controlled","pos":[400,660],"size":[240,100]},
+    {"id":"code-ui-ux","type":"frontend","label":"Code agent","sublabel":"Human-controlled","pos":[400,880],"size":[240,100]},
+    {"id":"code-planning","type":"frontend","label":"Code agent","sublabel":"Human-controlled","pos":[400,1100],"size":[240,100]},
+    {"id":"code-delivery","type":"frontend","label":"Code agent","sublabel":"Human-controlled","pos":[400,1320],"size":[240,100]},
+    {"id":"code-uat","type":"frontend","label":"Code agent","sublabel":"Human-controlled","pos":[400,1540],"size":[240,100]},
+    {"id":"code-security","type":"frontend","label":"Code agent","sublabel":"Human-controlled","pos":[400,1760],"size":[240,100]},
+    {"id":"code-releases","type":"frontend","label":"Code agent","sublabel":"Human-controlled","pos":[400,1980],"size":[240,100]}
+  ],
+  "connections": [
+
+    {"id":"govern-scope","from":"agent","to":"scope","label":"","variant":"security","fromSide":"left","toSide":"left","via":[[60,260],[60,490]]},
+    {"id":"govern-architecture","from":"agent","to":"architecture","label":"","variant":"security","fromSide":"left","toSide":"left","via":[[60,260],[60,710]]},
+    {"id":"govern-ui-ux","from":"agent","to":"ui-ux","label":"","variant":"security","fromSide":"left","toSide":"left","via":[[60,260],[60,930]]},
+    {"id":"govern-planning","from":"agent","to":"planning","label":"","variant":"security","fromSide":"left","toSide":"left","via":[[60,260],[60,1150]]},
+    {"id":"govern-delivery","from":"agent","to":"delivery","label":"","variant":"security","fromSide":"left","toSide":"left","via":[[60,260],[60,1370]]},
+    {"id":"govern-uat","from":"agent","to":"uat","label":"","variant":"security","fromSide":"left","toSide":"left","via":[[60,260],[60,1590]]},
+    {"id":"govern-security","from":"agent","to":"security","label":"","variant":"security","fromSide":"left","toSide":"left","via":[[60,260],[60,1810]]},
+    {"id":"govern-releases","from":"agent","to":"releases","label":"","variant":"security","fromSide":"left","toSide":"left","via":[[60,260],[60,2030]]},
+    {"id":"stage-1","from":"scope","to":"architecture","label":"Then","variant":"emphasis","fromSide":"bottom","toSide":"top"},
+    {"id":"stage-2","from":"architecture","to":"ui-ux","label":"Then","variant":"emphasis","fromSide":"bottom","toSide":"top"},
+    {"id":"stage-3","from":"ui-ux","to":"planning","label":"Then","variant":"emphasis","fromSide":"bottom","toSide":"top"},
+    {"id":"stage-4","from":"planning","to":"delivery","label":"Then","variant":"emphasis","fromSide":"bottom","toSide":"top"},
+    {"id":"stage-5","from":"delivery","to":"uat","label":"Then","variant":"emphasis","fromSide":"bottom","toSide":"top"},
+    {"id":"stage-6","from":"uat","to":"security","label":"Then","variant":"emphasis","fromSide":"bottom","toSide":"top"},
+    {"id":"stage-7","from":"security","to":"releases","label":"Then","variant":"emphasis","fromSide":"bottom","toSide":"top"},
+    {"id":"stage-8","from":"releases","to":"scope","label":"Repeat indefinitely","variant":"emphasis","fromSide":"bottom","toSide":"top","via":[[220,2140],[680,2140],[680,380],[220,380]],"labelAt":[440,2180]},
+    {"id":"contribute-scope","from":"code-scope","to":"scope","label":"Contribute","variant":"dashed","fromSide":"left","toSide":"right"},
+    {"id":"contribute-architecture","from":"code-architecture","to":"architecture","label":"Contribute","variant":"dashed","fromSide":"left","toSide":"right"},
+    {"id":"contribute-ui-ux","from":"code-ui-ux","to":"ui-ux","label":"Contribute","variant":"dashed","fromSide":"left","toSide":"right"},
+    {"id":"contribute-planning","from":"code-planning","to":"planning","label":"Contribute","variant":"dashed","fromSide":"left","toSide":"right"},
+    {"id":"contribute-delivery","from":"code-delivery","to":"delivery","label":"Contribute","variant":"dashed","fromSide":"left","toSide":"right"},
+    {"id":"contribute-uat","from":"code-uat","to":"uat","label":"Contribute","variant":"dashed","fromSide":"left","toSide":"right"},
+    {"id":"contribute-security","from":"code-security","to":"security","label":"Contribute","variant":"dashed","fromSide":"left","toSide":"right"},
+    {"id":"contribute-releases","from":"code-releases","to":"releases","label":"Contribute","variant":"dashed","fromSide":"left","toSide":"right"}
+  ]
+}

diagrams/strategy-target.architecture.json

@@ -0,0 +1,51 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {"title": "TO-BE: autonomous SDLC, human direction", "output": "static/diagrams/strategy-target/index.html", "quality_profile": "showcase", "legend": {"mode": "hidden"}},
+  "components": [
+    {"id":"agent","type":"security","label":"Autonomous agent","sublabel":"Human Controlled","pos":[465,450],"size":[270,90]},
+    {"id":"scope","type":"backend","label":"Scope","sublabel":"01","pos":[510,187.5],"size":[180,75]},
+    {"id":"architecture","type":"backend","label":"Architecture","sublabel":"02","pos":[780,187.5],"size":[180,75]},
+    {"id":"ui-ux","type":"backend","label":"UI/UX","sublabel":"03","pos":[780,457.5],"size":[180,75]},
+    {"id":"planning","type":"backend","label":"Planning","sublabel":"04","pos":[780,727.5],"size":[180,75]},
+    {"id":"delivery","type":"backend","label":"Delivery","sublabel":"05","pos":[510,727.5],"size":[180,75]},
+    {"id":"uat","type":"backend","label":"UAT","sublabel":"06","pos":[240,727.5],"size":[180,75]},
+    {"id":"security","type":"backend","label":"Security","sublabel":"07","pos":[240,457.5],"size":[180,75]},
+    {"id":"releases","type":"backend","label":"Releases","sublabel":"08","pos":[240,187.5],"size":[180,75]},
+    {"id":"code-scope","type":"frontend","label":"Code agent","sublabel":"Human-controlled","pos":[510,37.5],"size":[180,75]},
+    {"id":"code-architecture","type":"frontend","label":"Code agent","sublabel":"Human-controlled","pos":[780,37.5],"size":[180,75]},
+    {"id":"code-ui-ux","type":"frontend","label":"Code agent","sublabel":"Human-controlled","pos":[1005,457.5],"size":[180,75]},
+    {"id":"code-planning","type":"frontend","label":"Code agent","sublabel":"Human-controlled","pos":[780,877.5],"size":[180,75]},
+    {"id":"code-delivery","type":"frontend","label":"Code agent","sublabel":"Human-controlled","pos":[510,877.5],"size":[180,75]},
+    {"id":"code-uat","type":"frontend","label":"Code agent","sublabel":"Human-controlled","pos":[240,877.5],"size":[180,75]},
+    {"id":"code-security","type":"frontend","label":"Code agent","sublabel":"Human-controlled","pos":[15,457.5],"size":[180,75]},
+    {"id":"code-releases","type":"frontend","label":"Code agent","sublabel":"Human-controlled","pos":[240,37.5],"size":[180,75]}
+  ],
+  "connections": [
+
+    {"id":"govern-scope","from":"agent","to":"scope","label":"","variant":"security","fromSide":"right","toSide":"bottom","via":[[750,495],[750,292.5],[600,292.5]]},
+    {"id":"govern-architecture","from":"agent","to":"architecture","label":"","variant":"security","fromSide":"right","toSide":"bottom","via":[[765,495],[765,345],[870,345]]},
+    {"id":"govern-ui-ux","from":"agent","to":"ui-ux","label":"","variant":"security","fromSide":"right","toSide":"left"},
+    {"id":"govern-planning","from":"agent","to":"planning","label":"","variant":"security","fromSide":"right","toSide":"top","via":[[765,495],[765,690],[870,690]]},
+    {"id":"govern-delivery","from":"agent","to":"delivery","label":"","variant":"security","fromSide":"bottom","toSide":"top"},
+    {"id":"govern-uat","from":"agent","to":"uat","label":"","variant":"security","fromSide":"left","toSide":"top","via":[[435,495],[435,690],[330,690]]},
+    {"id":"govern-security","from":"agent","to":"security","label":"","variant":"security","fromSide":"left","toSide":"right"},
+    {"id":"govern-releases","from":"agent","to":"releases","label":"","variant":"security","fromSide":"left","toSide":"bottom","via":[[435,495],[435,345],[330,345]]},
+    {"id":"stage-1","from":"scope","to":"architecture","label":"Then","variant":"emphasis","fromSide":"right","toSide":"left"},
+    {"id":"stage-2","from":"architecture","to":"ui-ux","label":"Then","variant":"emphasis","fromSide":"bottom","toSide":"top"},
+    {"id":"stage-3","from":"ui-ux","to":"planning","label":"Then","variant":"emphasis","fromSide":"bottom","toSide":"top"},
+    {"id":"stage-4","from":"planning","to":"delivery","label":"Then","variant":"emphasis","fromSide":"left","toSide":"right"},
+    {"id":"stage-5","from":"delivery","to":"uat","label":"Then","variant":"emphasis","fromSide":"left","toSide":"right"},
+    {"id":"stage-6","from":"uat","to":"security","label":"Then","variant":"emphasis","fromSide":"top","toSide":"bottom"},
+    {"id":"stage-7","from":"security","to":"releases","label":"Then","variant":"emphasis","fromSide":"top","toSide":"bottom"},
+    {"id":"stage-8","from":"releases","to":"scope","label":"Repeat indefinitely","variant":"emphasis","fromSide":"right","toSide":"left","labelAt":[465,170]},
+    {"id":"contribute-scope","from":"code-scope","to":"scope","label":"Contribute","variant":"dashed","fromSide":"bottom","toSide":"top"},
+    {"id":"contribute-architecture","from":"code-architecture","to":"architecture","label":"Contribute","variant":"dashed","fromSide":"bottom","toSide":"top"},
+    {"id":"contribute-ui-ux","from":"code-ui-ux","to":"ui-ux","label":"Contribute","variant":"dashed","fromSide":"left","toSide":"right","labelAt":[990,570]},
+    {"id":"contribute-planning","from":"code-planning","to":"planning","label":"Contribute","variant":"dashed","fromSide":"top","toSide":"bottom"},
+    {"id":"contribute-delivery","from":"code-delivery","to":"delivery","label":"Contribute","variant":"dashed","fromSide":"top","toSide":"bottom"},
+    {"id":"contribute-uat","from":"code-uat","to":"uat","label":"Contribute","variant":"dashed","fromSide":"top","toSide":"bottom"},
+    {"id":"contribute-security","from":"code-security","to":"security","label":"Contribute","variant":"dashed","fromSide":"right","toSide":"left","labelAt":[220,570]},
+    {"id":"contribute-releases","from":"code-releases","to":"releases","label":"Contribute","variant":"dashed","fromSide":"bottom","toSide":"top"}
+  ]
+}

docs/contribution/contribute.md

@@ -0,0 +1,19 @@
+---
+title: Contribute
+description: Contribute evidence, proposals, and documentation changes to Eldorado Powered By AI.
+slug: /
+---
+
+Use this section to contribute to **Eldorado Powered By AI**.
+
+- Distinguish evidence, proposals, open questions, and agreed decisions.
+- Do not present example diagrams as the actual organization or architecture.
+- Use a pull request for source changes; automated checks must pass before publication.
+
+## Maintain the portal
+
+[Update and publish the site](/docs/maintain/) or consult the [configuration reference](/docs/reference/).
+
+## Create diagrams
+
+[Author and embed an Archify diagram](./diagrams.md).

docs/contribution/diagrams.md

@@ -0,0 +1,46 @@
+---
+title: Archify diagrams
+description: Author typed JSON diagrams and embed their local interactive viewer in documentation.
+---
+
+## Capabilities
+
+[Archify](https://github.com/tt-a1i/archify) 3.0.1 is vendored at commit `d5a1333d7447c866a765adac7d4d062f2f02e4d2` under `vendor/archify/`, with its MIT license and third-party notices preserved.
+
+| Diagram type | Intended use |
+| --- | --- |
+| Architecture | Components, boundaries and relationships; also used for the organization structure views |
+| Workflow | Processes, branches and approval gates |
+| Sequence | Participants and ordered messages |
+| Dataflow | Sources, processing and destinations |
+| Lifecycle | States and transitions |
+
+The standalone viewer provides pan/zoom, node inspection, search/focus, relationship tracing, light/dark themes, and an export menu. Motion is opt-in. The Organization views exercise architecture mode; other diagram types use the same build interface but do not yet have portal-specific examples. Browser-dependent exports such as video are not acceptance-tested by this integration.
+
+## Author a diagram
+
+Create `diagrams/<name>.<type>.json` using the matching schema and authoring guidance in `vendor/archify/schemas/` and `vendor/archify/references/`. Use stable IDs, explicit relationships, and honest evidence labels. Do not include private information merely because the source repository is private: Pages access is a separate platform policy.
+
+Set `meta.output` to `static/diagrams/<name>/index.html`. The build validates the typed source with the upstream showcase profile, renders locally, checks the artifact, and publishes the standalone HTML. Editable JSON stays in the repository; the portal does not publish source-download files.
+
+```sh
+pnpm diagrams:build
+pnpm test
+pnpm build
+```
+
+## Embed it in MDX
+
+```mdx
+import ArchifyDiagram from '@site/src/components/ArchifyDiagram';
+
+<ArchifyDiagram name="organization-structure" title="Eldorado organization structure" />
+```
+
+Supply a text alternative below each diagram. The wrapper uses a local, base-path-aware iframe with a descriptive title, scripts and downloads enabled, and no same-origin or parent-navigation permissions. The top-right expand icon expands the diagram in a full-screen modal on the current page, with the same iframe sandbox. Close it with the Close button or Escape; focus returns to the opener. It does not open a new tab. The separate standalone HTML asset remains directly addressable and is not itself iframe-sandboxed, so publish only reviewed, trusted diagrams. Generated output is ignored by Git and rebuilt in CI.
+
+## Integration boundaries
+
+The portal remains Docusaurus/React/TypeScript with pnpm. It uses the actual upstream renderer, not a look-alike diagram implementation. No Astro site, global agent installation, hosted rendering service, or AI API was added. The integration disables Archify update networking and does not run its installation commands. This does not disable every possible build-time request: upstream can fetch authored, digest-pinned brand URLs. The current example contains none. Review external asset sources deliberately; update-check suppression is not an offline guarantee.
+
+Upgrades are deliberate: review the upstream diff and licenses, update the provenance record and vendor checksums, then run tests, diagram validation, production build, and browser checks. Do not edit upstream files for portal styling.

docs/core/maintain.md

@@ -19,7 +19,16 @@ Open the development server address printed in the terminal. The site uses the `
 
 ## Add or change a page
 
-Edit Markdown in `docs/`. Include `title` and `description` frontmatter and add the page ID to `sidebars.ts`. Keep the documentation’s future scope open until it is agreed.
+Include `title` and `description` frontmatter. Place each page in its owning section and add its document ID to that section’s sidebar:
+
+| Section | Content directory | Sidebar configuration |
+| --- | --- | --- |
+| Organization | `docs/organization/` | `sidebars/organization.ts` |
+| Strategy | `docs/strategy/` | `sidebars/strategy.ts` |
+| Contribution | `docs/contribution/` | `sidebars/contribution.ts` |
+| Portal maintenance and reference | `docs/core/` | `sidebars.ts` |
+
+Keep these content roots disjoint. Preserve existing URLs when moving pages. Specific AI initiatives and organizational reporting lines remain subject to agreement.
 
 ## Validate the change
 

docs/organization/collaboration.mdx

@@ -0,0 +1,23 @@
+---
+title: Collaboration
+description: How Eldorado departments combine their responsibilities to deliver shared business outcomes.
+---
+
+Departments collaborate around shared outcomes while retaining their own team ownership and accountability. See [Structure](./structure.mdx) for department and squad responsibilities.
+
+## How the departments work together
+
+| Business outcome | Collaboration |
+| --- | --- |
+| Better buyer experience | Product defines improvements; Technology delivers them; Operations brings customer feedback; Data & AI measures the result. |
+| Stronger seller experience | Product and Technology develop seller tools; Operations supports sellers; Finance manages financial processes. |
+| Safe and trustworthy trading | Risk & Fraud, Trust & Resolution, Architecture & Security, and Finance coordinate controls and incident responses. |
+| Sustainable growth | Marketing develops demand; Product improves conversion and retention; Finance measures profitability. |
+| AI-powered execution | Data & AI supports engineering and develops marketplace intelligence; Operations improves service and quality workflows. |
+
+Department leaders remain accountable for outcomes, controls and service quality as AI becomes part of everyday work.
+
+## Related pages
+
+- [Structure](./structure.mdx) — departments, squads and responsibilities.
+- [SDLC — Software Delivery Life Cycle](./sdlc.mdx) — leadership and delivery responsibilities.

docs/organization/sdlc.mdx

@@ -0,0 +1,27 @@
+---
+title: SDLC — Software Delivery Life Cycle
+sidebar_label: SDLC
+description: Leadership, reporting lines and team responsibilities supporting software delivery at Eldorado.
+---
+
+import ArchifyDiagram from '@site/src/components/ArchifyDiagram';
+
+Software delivery brings together Product and Technology, supported by the departments responsible for marketplace operations and growth. This page describes the leadership and delivery responsibilities that support that work.
+
+## Leadership and delivery structure
+
+<ArchifyDiagram name="organization-reporting" compact title="Eldorado leadership and delivery structure" />
+
+The diagram shows management responsibility from leader to role or team:
+
+- **CTO → Head of Engineering → Group Engineering Managers → Engineering Managers → the Product Engineering team.**
+- **CTO → AI Architect**, coordinating engineering AI enablement.
+- **COO → Operational Quality**, providing independent quality oversight.
+- **CMO → Brand Team Lead**, leading Brand & Community.
+
+Product and Technology retain separate team ownership and reporting lines. Their teams coordinate priorities, design, engineering, quality and data work to deliver business outcomes.
+
+## Related pages
+
+- [Structure](./structure.mdx) — departments, squads and responsibilities.
+- [Collaboration](./collaboration.mdx) — how departments coordinate around business outcomes.

docs/organization/structure.mdx

@@ -0,0 +1,117 @@
+---
+title: Structure
+description: Eldorado’s organizational operating model, departments, teams and responsibilities.
+---
+
+import ArchifyDiagram from '@site/src/components/ArchifyDiagram';
+
+This operating model organizes Eldorado around six departments: **Product, Technology, Operations, Marketing, Finance & Accounting, and HR & Administration**. Leadership aligns their priorities around marketplace growth, customer trust and efficient delivery.
+
+## Leadership
+
+| Role | Leadership | Responsibility |
+| --- | --- | --- |
+| Chief Executive Officer | Vladas Jurkevičius | Company direction, business performance, strategic priorities and executive alignment. |
+| Chief Operating Officer | Lukas Deksnys | Marketplace operations, customer service, resolution quality and operational performance. |
+
+Functional leaders translate company priorities into departmental plans. Team leads own execution, people development and service quality within their teams.
+
+## Organization overview
+
+<ArchifyDiagram name="organization-structure" title="Eldorado organization structure" />
+
+**Management coordinates the six departments.** Each department has a clear business responsibility and a set of teams that deliver it.
+
+## Departments and teams
+
+Product has **two teams** and Technology has **five teams**. Operations, Marketing, Finance & Accounting, and HR & Administration each have **one squad** covering their departmental workstreams. Each team belongs to one department, with its own leadership and responsibilities. The departments collaborate on delivery without sharing team ownership.
+
+### Product
+
+**Purpose:** improve the buyer and seller experience and turn marketplace opportunities into valuable product capabilities.
+
+| Team | Responsibilities |
+| --- | --- |
+| Product Management | Product strategy, roadmaps, priorities and outcome measurement across discovery, categories, orders, seller tools, payments and operational workflows. |
+| Product Design | User research, interaction design, design consistency and accessible buyer and seller experiences. |
+
+Product Management owns what to improve and why. Product Design shapes the experience. Both work with Technology teams while remaining within Product.
+
+### Technology
+
+**Purpose:** build and operate a secure, reliable marketplace and improve the effectiveness of engineering.
+
+| Team | Responsibilities |
+| --- | --- |
+| Product Engineering | Build and maintain marketplace capabilities, including search, orders, seller tools, checkout, wallet and operational tooling. |
+| Platform & IT | Platform services, delivery infrastructure, observability, reliability, performance, internal systems, employee devices and identity administration. |
+| Architecture & Security | Technical standards, system design, security architecture and secure engineering practices. |
+| Quality Engineering | Test strategy, automation, release quality and defect prevention. |
+| Data & AI | Analytics, experimentation, ranking, recommendations, marketplace ML and safe AI-assisted engineering workflows. |
+
+The CTO owns technology direction. The Head of Engineering leads engineering delivery through Group Engineering Managers and Engineering Managers. The AI Architect coordinates AI enablement within Data & AI, working with Architecture & Security and the other Technology teams. These are leadership roles within the five-team structure, not additional teams.
+
+### Operations
+
+**Purpose:** keep marketplace trading dependable and resolve customer issues fairly and efficiently.
+
+**Operations Squad** delivers the department’s responsibilities across the following workstreams.
+
+| Workstream | Responsibilities |
+| --- | --- |
+| Customer Support | Buyer and seller assistance, knowledge management, self-service and support workflow automation. |
+| Trust & Resolution | Disputes, appeals, refunds, warranties, chargebacks and complex customer cases. |
+| Risk & Fraud | Transaction and account risk, fraud prevention, investigations and operational controls. |
+| Operational Quality | Independent case reviews, quality standards, calibration, service accuracy and improvement tracking across operational teams. |
+
+The COO coordinates Operations. Team leads manage specialists and daily service delivery. Operational Quality reports directly to the COO and reviews quality across teams.
+
+### Marketing
+
+**Purpose:** attract and retain customers, build the Eldorado brand and grow marketplace demand.
+
+**Marketing Squad** delivers the department’s responsibilities across the following workstreams.
+
+| Workstream | Responsibilities |
+| --- | --- |
+| Brand & Community | Brand positioning, campaigns, organic social, community and brand partnerships. |
+| Creative | Campaign concepts, visual assets and performance creative. |
+| SEO | Organic discovery, search visibility and content performance. |
+| PPC & Affiliate | Paid acquisition, affiliate channels and return on marketing investment. |
+| Influencer | Creator relationships, influencer programs and campaign delivery. |
+| CRM | Customer lifecycle communication, retention, reactivation and campaign personalization. |
+
+The CMO coordinates Marketing. The Brand Team Lead owns Brand & Community, with shared support from Creative and the other marketing workstreams.
+
+### Finance & Accounting
+
+**Purpose:** maintain financial control, support business decisions and keep marketplace money flows dependable.
+
+**Finance & Accounting Squad** delivers the department’s responsibilities across the following workstreams.
+
+| Workstream | Responsibilities |
+| --- | --- |
+| Financial Planning & Analysis | Budgets, forecasts, profitability, management reporting and investment analysis. |
+| Accounting, Tax & Controls | Accounting, financial reporting, tax, audit coordination and internal controls. |
+| Treasury & Payment Operations | Cash management, reconciliation, payout oversight, payment-provider coordination and financial risk. |
+
+The CFO coordinates Finance & Accounting and works with executive leadership on business performance. Finance, Operations and Product share responsibility for effective payment and withdrawal processes, each within its own area of expertise.
+
+### HR & Administration
+
+**Purpose:** help teams attract, develop and retain people and provide an effective working environment.
+
+**People & Administration Squad** delivers the department’s responsibilities across the following workstreams.
+
+| Workstream | Responsibilities |
+| --- | --- |
+| Talent Acquisition | Recruitment, candidate experience, hiring coordination and workforce demand support. |
+| People Operations | Employee onboarding, development, performance processes, policies and employee experience. |
+| Office & Administration | Workplace services, office operations and administrative coordination. |
+
+HR partners with department leaders on team capacity and development. People Operations works with Platform & IT on employee onboarding, role changes and offboarding.
+
+## Related pages
+
+- [Collaboration](./collaboration.mdx) — how departments work together on business outcomes.
+- [SDLC — Software Delivery Life Cycle](./sdlc.mdx) — leadership and delivery responsibilities.

docs/strategy/index.mdx

@@ -0,0 +1,56 @@
+---
+id: index
+title: AI adoption strategy
+description: An autonomous SDLC cycle directed, guided and reviewed by humans, supported by governed skills.
+slug: /
+hide_table_of_contents: true
+---
+
+import ArchifyDiagram from '@site/src/components/ArchifyDiagram';
+
+<div className="strategy-content">
+
+**TO-BE · Target operating model — not installed controls or company results.**
+
+## Autonomous SDLC, human direction
+
+<ArchifyDiagram name="strategy-target" title="Autonomous agent executes and governs the SDLC; humans direct, guide and review" story />
+
+An autonomous agent executes and governs every phase. Humans direct, guide and review it; a separate human-controlled code agent contributes to each phase from outside the cycle.
+
+**Solid arrows:** lifecycle · **Dotted spokes:** execution and governance · **Dashed arrows:** contributions.
+
+**Scope → Architecture → UI/UX → Planning → Delivery → UAT → Security → Releases → Scope**
+
+Releases returns to Scope and the cycle repeats indefinitely. Governed skills and measured outcomes support the path toward this target; they are not a substitute for it.
+
+<details>
+<summary>Strategy rationale and reading map</summary>
+
+**TO-BE · Target operating model.** Introduction depends on the [roadmap gates](./roadmap.mdx); these pages do not describe installed controls or measured company results.
+
+### Govern skills first, expand authority only with evidence
+
+Eldorado's target is to make AI-assisted work dependable across the organization: useful guidance, clear human ownership, controlled execution and measurable outcomes. The first investment is a governed skills system, not an autonomous replacement for the organization. A skill packages reusable working knowledge, prerequisites and verification steps. It helps an agent perform a task; it does not grant permission or guarantee that the work is correct.
+
+The target combines an autonomous agent executing and governing the SDLC with humans directing, guiding and reviewing it. Developer choice on local laptops remains a supporting option: Copilot, Claude Code and Cline can receive reviewed portable skill content through qualified adapters. Repository, CI and release controls support execution; detailed approval policies remain implementation decisions, not new roles established by this strategy.
+
+The strategy describes the intended operating model and the evidence required to introduce it. It does not establish that these controls are installed, that every client is supported, or that AI has improved Eldorado's performance. The current reference is the documented six-department organization. Rollout begins by validating actual clients, responsibilities, data boundaries and available evidence.
+
+Success means accepted outcomes with maintained quality, controlled risk and understood total cost. Faster activity without reliable outcomes is not success. More skill invocations, generated lines or tool subscriptions are not productivity targets. People remain accountable for product, customer, financial and personnel decisions.
+
+## Navigate the strategy
+
+- [Target operating model](./target-operating-model.mdx) — The autonomous SDLC cycle, with human direction, guidance and review.
+- [Skills governance](./skills-governance.mdx) — Contract, lifecycle, decision rights, adapters, locking, exceptions.
+- [Skills quality](./skills-quality.mdx) — Risk tiers, independent evaluation, repeated trials, adversarial conformance.
+- [Skills adoption](./skills-adoption.mdx) — Workflow-led coaching, client choice, feedback, manual path.
+- [Measurement](./measurement.mdx) — Full KPI contracts, minimal events, illustrative calculations, privacy and limits.
+- [Skills maintenance](./skills-maintenance.mdx) — Review, drift, deprecation, rollback and incident handling.
+- [Roadmap](./roadmap.mdx) — Evidence-gated phases, no promised dates or budgets.
+
+</details>
+
+**Next:** [Explore the autonomous SDLC cycle →](./target-operating-model.mdx)
+
+</div>

docs/strategy/measurement.mdx

@@ -0,0 +1,385 @@
+---
+id: measurement
+title: Measurement
+description: Full KPI contracts, minimal events, illustrative calculations, privacy and limits.
+hide_table_of_contents: true
+---
+
+import ArchifyDiagram from '@site/src/components/ArchifyDiagram';
+
+<div className="strategy-content">
+
+**TO-BE · Target operating model — not installed controls or company results.**
+
+## Is AI-assisted work worth continuing?
+
+Judge accepted outcomes alongside quality, delivery flow, risk, cost and human experience. Validate source coverage before calculating; missing evidence is unknown, not success.
+
+<ArchifyDiagram name="strategy-measurement" title="Collect evidence, validate it, calculate balanced measures and decide" story />
+
+**Illustrative only:** 1 accepted task ÷ 4 matured starts × 100 = **25%** confirmed success. One unresolved task stays in the denominator; known-outcome coverage is **75%**. These are synthetic data, not Eldorado results.
+
+- **16 contracts:** exact definitions below; 9 prototype calculations, 7 explicitly unimplemented metrics.
+- **Balanced evidence:** no productivity rankings, composite score or causal ROI claim.
+- **Privacy first:** no raw prompts or code by default; protect small cohorts and agree retention before collection.
+
+<details>
+<summary>Collection, baseline, event and privacy contracts</summary>
+
+**TO-BE · Target operating model.** Introduction depends on the [roadmap gates](./roadmap.mdx); these pages do not describe installed controls or measured company results.
+
+### Decide what counts before counting
+
+Use the metric contracts below for exact definitions. Every report states its eligible population, observation window, numerator and denominator or distribution sample count, source coverage, exclusions and calculation version. Zero denominators return “not available.” Missing telemetry is unknown, not inactivity, compliance or success. Examples are explicitly synthetic and illustrative.
+
+Begin with task acceptance, repository, CI, deployment and incident systems because they can independently establish outcomes. Add catalog/version inventory and task-level declarations. Client telemetry is supplementary and version-dependent; enabling rich tool details may collect sensitive commands and identifiers. Do not enable it merely to count skills. A normalized adapter may report approved skill identifiers without forwarding raw arguments.
+
+Validated success uses all eligible initiated tasks whose predeclared observation window has matured. Failed and abandoned tasks remain nonsuccess. Unresolved or unobserved outcomes remain in the denominator, with known-outcome coverage shown alongside the conservative confirmed-success share. They are not relabeled as observed failure. A task cancelled before start is excluded; cancellation after start remains visible. Count a task once across retries and multiple skills. For timeliness, also show unfinished work and age; accepted-only lead-time distributions have survivorship limitations.
+
+Track all five service-level DORA measures: commit-to-production lead time, deployment frequency, change fail rate, failed deployment recovery time and deployment rework rate. Do not substitute PR-open-to-merge time or all-incident MTTR. Pair them with matured escaped-quality rates, policy effects, total cost per accepted outcome, support coverage, adoption, human experience and catalog maintenance. Keep customer/business outcomes linked to their departmental hypotheses; do not infer conversion, trust or revenue improvement from delivery telemetry.
+
+### Baseline and interpretation
+
+Before a pilot, freeze eligibility and acceptance rules and verify event joins. Collect prospective no-skill/current-practice evidence over a complete comparable workflow cycle and until the preregistered precision/sample requirement is met. Do not select a convenient end date after seeing results. Retain task class, service, skill, client/model configuration and concurrent changes. A matched or randomized comparison may be used when practical and ethical; label observational trends as descriptive and report confounding, selection and uncertainty.
+
+Elapsed time and human effort are different quantities. Parallel agents may reduce waiting while increasing review or compute. Include failed attempts and human review/rework in cost, do not multiply a multi-skill task's value across every invocation, and do not convert survey perceptions into proven time savings. Small or incomplete populations yield evidence limits, not an ROI percentage.
+
+### Event and privacy contract
+
+Use a versioned event envelope and required fields per event. Source producer plus event ID deduplicates transport retries. Conflicting payloads under the same key are quarantined. Attempts have distinct IDs under one task. Domain IDs deduplicate deployments, defects and approvals even when multiple feeds describe them. Late arrivals produce versioned aggregate corrections; never silently overwrite a published result. Preserve occurrence and receipt times, reject impossible orderings and flag clock skew. Missing terminal events remain unresolved until the work owner reconciles them.
+
+Many-to-many task/attempt/skill/client associations preserve exact immutable versions. Unknown version stays null with a reason; never assign the latest revision retroactively. Client declarations, server facts and self-reports remain separately labeled. A skill-loaded event is evidence of loading only. The minimal prototype can operate without actor identity except where a lawful, necessary adoption denominator requires pseudonymous cohort membership.
+
+The privacy starting proposal is 30 days for raw structured analytics events and 12 months for aggregated trends, subject to the responsible owners' review. Keep the approved catalog/approval record for the supported revision's lifetime and its required audit period, which must be decided separately. Incident evidence uses a restricted, explicitly authorized hold and deletion schedule, not an indefinite analytics exception. Suppress reports below five people and prohibit drill-down or overlapping cohort slices that reconstruct identities. Five is a proposed minimum, not a guarantee against re-identification. No raw prompts, code, screens, customer cases or secrets are collected by default. Publish the purpose, lawful collection basis, access/deletion route and retention before collecting. Consent is not presumed to be an appropriate employment-law basis.
+
+</details>
+
+<details>
+<summary>All 16 KPI contracts — formulas, populations, owners and limits</summary>
+
+## Metric contracts
+
+Each contract is a prospective collection design. No live source or observed baseline is established. N and D refer to the numerator and denominator shown for that metric.
+
+### Validated task success
+
+Confirmed independently accepted tasks as a share of all eligible initiated tasks in a matured start cohort; a conservative confirmed-success share, not observed failure rate.
+
+| Contract | Definition |
+| --- | --- |
+| Numerator | Distinct matured task_ids with valid independent task.accepted evidence by as_of |
+| Denominator | All distinct eligible task_ids started in window with started_at + preregistered task_observation_hours &lt;= as_of |
+| Expression | N / D * 100 |
+| Aggregation | percent |
+| Unit | % |
+| Eligible population | Tasks in a preregistered workflow cohort, started in window; each counted once across retries, skills and clients. |
+| Exclusions | Cancelled before start, sandbox/evaluation tasks and out-of-scope workflows; never post-start failures/abandonments. |
+| Events and source | task.started; task.accepted; task.failed; task.abandoned; task.cancelled; work-management acceptance record |
+| Owner / cadence | Quality Engineering / Weekly pilot; monthly departmental outcome review |
+| Missing evidence | Unresolved/missing terminal outcomes remain in denominator with unknown count and known-outcome coverage; do not label them failed. Invalid/missing start excluded from calculation but flagged as orphan evidence. |
+| Gaming and limits | Split easy tasks or omit starts; reconcile starts to approved backlog and audit acceptance rubrics. Descriptive signal, not causal AI productivity attribution. Source completeness, task mix and sampling limit inference; report uncertainty. Maturation horizon is workflow-specific and must be approved; no automatic abandonment on timeout. |
+
+
+### Skill selection precision
+
+Correct activations among activations on an independently labeled evaluation corpus.
+
+| Contract | Definition |
+| --- | --- |
+| Numerator | True-positive activations for the requested workflow |
+| Denominator | True-positive plus false-positive activations |
+| Expression | N / D * 100 |
+| Aggregation | percent |
+| Unit | % |
+| Eligible population | All candidate/client labeled evaluation task-trials with known activation and relevance. |
+| Exclusions | Unlabeled/unknown activations excluded with coverage; no cherry-picked failed trials. |
+| Events and source | eval.selection; versioned labeled corpus and runner |
+| Owner / cadence | Data & AI / Each skill/client qualification |
+| Missing evidence | Unknown activation/relevance is unscorable; publish missing count and deny qualification if planned coverage incomplete. |
+| Gaming and limits | Choose easy labels or hide negative cases; freeze corpus and independently review labels. Descriptive signal, not causal AI productivity attribution. Source completeness, task mix and sampling limit inference; report uncertainty. Does not show execution success; precision depends on corpus prevalence. |
+
+
+### Skill selection recall
+
+Relevant task-trials in which the intended skill activates.
+
+| Contract | Definition |
+| --- | --- |
+| Numerator | True-positive activations |
+| Denominator | True-positive plus false-negative task-trials |
+| Expression | N / D * 100 |
+| Aggregation | percent |
+| Unit | % |
+| Eligible population | Independently labeled relevant evaluation task-trials for a skill/client tuple. |
+| Exclusions | Irrelevant tasks; missing relevance or activation reported as unscorable, not negative. |
+| Events and source | eval.selection; versioned labeled corpus and runner |
+| Owner / cadence | Data & AI / Each skill/client qualification |
+| Missing evidence | Report evaluation coverage; null if no relevant labeled tasks. |
+| Gaming and limits | Overtrigger to maximize recall; always pair with precision and negative cases. Descriptive signal, not causal AI productivity attribution. Source completeness, task mix and sampling limit inference; report uncertainty. Loading the right skill is not adherence. |
+
+
+### Supported bundle coverage
+
+Inventoried active installations with verified effective approved, supported and nonrevoked bundle/adapter tuple.
+
+| Contract | Definition |
+| --- | --- |
+| Numerator | Eligible installation_ids with valid inventory evidence within approved freshness window and matching support matrix |
+| Denominator | All expected active installation_ids in the managed pilot inventory |
+| Expression | N / D * 100 |
+| Aggregation | percent |
+| Unit | % |
+| Eligible population | Active installation inventory frozen for report, including invisible/offline entries until authoritative offboarding. |
+| Exclusions | Verified decommissioned installations and nonpilot assets; lack of telemetry alone never excludes. |
+| Events and source | inventory.observed; catalog.published; catalog.revoked; device inventory |
+| Owner / cadence | Platform & IT / Weekly and at revocation |
+| Missing evidence | Unknown/stale versions count outside numerator, inside denominator. Show inventory discovery coverage versus eligible device roster; if roster unknown metric is provisional. |
+| Gaming and limits | Remove silent devices or trust declared versions; reconcile managed inventory and separately label attestation trust. Descriptive signal, not causal AI productivity attribution. Source completeness, task mix and sampling limit inference; report uncertainty. Even verified file digests do not prove a private model followed the content. |
+
+
+### Approved-workflow adoption
+
+Eligible participants with at least one approved-skill workflow use; usefulness assessed separately through accepted outcomes and feedback.
+
+| Contract | Definition |
+| --- | --- |
+| Numerator | Distinct eligible pseudonymous participants with workflow-linked skill.used on approved revision |
+| Denominator | Distinct eligible participants in frozen invited cohort |
+| Expression | N / D * 100 |
+| Aggregation | percent |
+| Unit | % |
+| Eligible population | Consented or otherwise lawfully enrolled pilot cohort for the period; supported workflow available. |
+| Exclusions | Outside pilot and formally recorded leave before period; nonresponders remain eligible, not excluded. |
+| Events and source | skill.used; cohort.snapshot; optional qualified client adapter or declaration |
+| Owner / cadence | Data & AI / Monthly |
+| Missing evidence | Show observed lower bound and telemetry/response coverage; missing usage unknown rather than non-use. |
+| Gaming and limits | Invocation quotas and coercion; no target usage count, split server/client/self-report origins. Descriptive signal, not causal AI productivity attribution. Source completeness, task mix and sampling limit inference; report uncertainty. Self-report is not verified use; installation/loading is not use or benefit. Suppress small groups. |
+
+
+### Change lead time
+
+Arithmetic mean commit-to-first-successful-production-deployment duration; also publish median/p90 and sample count.
+
+| Contract | Definition |
+| --- | --- |
+| Numerator | Sum of elapsed hours from committed_at to first successful production deployment for each service+commit |
+| Denominator | Count of eligible service+commit pairs with valid mappings |
+| Expression | N / D |
+| Aggregation | mean |
+| Unit | hours/change |
+| Eligible population | Changes first successfully deployed to a service in reporting window; rollout retries collapse to same logical deployment. |
+| Exclusions | Nonproduction, duplicates, no-op deployment with no new commits; missing mappings shown as coverage loss. |
+| Events and source | change.committed; deployment.completed; VCS immutable commit timestamps and release manifest |
+| Owner / cadence | Platform & IT / Weekly per service |
+| Missing evidence | Missing commit mapping or negative/skewed duration excluded from numeric sample, reported explicitly; no zero substitution. |
+| Gaming and limits | Timestamp rewriting and cherry-picking fast work; lock change mapping and show undeployed backlog age. Descriptive signal, not causal AI productivity attribution. Source completeness, task mix and sampling limit inference; report uncertainty. Not PR cycle time, effort saved, or a complete view of unfinished changes. p90 uses nearest-rank sorted sample. |
+
+
+### Deployment frequency
+
+Distinct successful logical production deployments per complete service-day of observation.
+
+| Contract | Definition |
+| --- | --- |
+| Numerator | Distinct service_id+deployment_id successful production deployments in window |
+| Denominator | Observed service-days in window |
+| Expression | N / D |
+| Aggregation | ratio |
+| Unit | deployments/service-day |
+| Eligible population | Declared production services and complete UTC observation days; report each service before pooled views. |
+| Exclusions | Test/staging, failed attempts without production effect, duplicate callbacks and retries of the same rollout. |
+| Events and source | deployment.completed; authoritative deployment service |
+| Owner / cadence | Platform & IT / Weekly per service |
+| Missing evidence | Missing feed periods not zero; report coverage and no unqualified overall rate when period incomplete. |
+| Gaming and limits | Split deployments without value; pair with success, rework and failure measures. Descriptive signal, not causal AI productivity attribution. Source completeness, task mix and sampling limit inference; report uncertainty. More deployments alone do not establish better performance; affected unsuccessful changes remain in change-fail population. |
+
+
+### Change fail rate
+
+Production deployment effects requiring unplanned remediation, rollback or hotfix, not solely outage declarations.
+
+| Contract | Definition |
+| --- | --- |
+| Numerator | Distinct matured production deployment_ids linked to qualifying immediate intervention |
+| Denominator | All distinct production deployment_ids that reached production in the matured deployment cohort |
+| Expression | N / D * 100 |
+| Aggregation | percent |
+| Unit | % |
+| Eligible population | Deployments with production effect during window and approved intervention follow-up horizon elapsed. |
+| Exclusions | Failed preproduction attempts, duplicate callbacks and no-effect retries; failures after production effect stay included. |
+| Events and source | deployment.completed; deployment.failed; incident.linked; release and incident records |
+| Owner / cadence | Quality Engineering / Weekly; finalized after horizon |
+| Missing evidence | Known failures / all eligible deployments is a lower bound where incident linkage incomplete; label provisional and report unknown links. |
+| Gaming and limits | Avoid incident links or relabel intervention planned; reconcile rollbacks/hotfixes independently. Descriptive signal, not causal AI productivity attribution. Source completeness, task mix and sampling limit inference; report uncertainty. Define immediate intervention and follow-up horizon before pilot; no universal incident-to-AI attribution. |
+
+
+### Failed deployment recovery time
+
+Mean elapsed time from production deployment failure onset to service restoration, with median/p90 and unresolved count/age.
+
+| Contract | Definition |
+| --- | --- |
+| Numerator | Sum of recovery_at minus failure_started_at in hours for recovered eligible deployment failures |
+| Denominator | Count of recovered eligible deployment failures with valid timestamps |
+| Expression | N / D |
+| Aggregation | mean |
+| Unit | hours/failure |
+| Eligible population | Production deployment failures beginning in window; latest verified restoration if a recovery is rescinded. |
+| Exclusions | Nondeployment incidents; invalid timestamp pairs reported missing, not treated as instantaneous recovery. |
+| Events and source | deployment.failed; service.restored; incident service |
+| Owner / cadence | Platform & IT / Weekly with unresolved failures |
+| Missing evidence | Unresolved failures reported separately and excluded only from recovered-duration distribution; prevent declaring improvement without their visibility. |
+| Gaming and limits | Premature recovery declarations or omit hard cases; require operational readback and carry unresolved ages. Descriptive signal, not causal AI productivity attribution. Source completeness, task mix and sampling limit inference; report uncertainty. Not all-incident MTTR; recovered-only sample has survivorship bias. p90 nearest rank. |
+
+
+### Deployment rework rate
+
+Unplanned production deployment effects triggered by a production incident as a share of deployment effects.
+
+| Contract | Definition |
+| --- | --- |
+| Numerator | Distinct incident-linked deployment_ids classified unplanned remediation |
+| Denominator | All distinct production deployment_ids with production effect in window |
+| Expression | N / D * 100 |
+| Aggregation | percent |
+| Unit | % |
+| Eligible population | Production deployment effects in window with immutable planned/unplanned classification and incident linkage. |
+| Exclusions | Nonproduction, no-effect retries and duplicates; do not exclude unclassified changes silently. |
+| Events and source | deployment.completed; incident.linked; release intent classification |
+| Owner / cadence | Platform & IT / Weekly |
+| Missing evidence | Unknown classification stays denominator; observed numerator is lower bound until reconciliation; show classification coverage. |
+| Gaming and limits | Call hotfixes planned; freeze reason and independently reconcile incident/deployment links. Descriptive signal, not causal AI productivity attribution. Source completeness, task mix and sampling limit inference; report uncertainty. Distinct from failure rate: one failed deployment can lead to multiple separate rework deployments. |
+
+
+### Changes with escaped quality issues
+
+Accepted changes with at least one confirmed post-acceptance defect during approved follow-up, split by severity.
+
+| Contract | Definition |
+| --- | --- |
+| Numerator | Distinct eligible change_ids with one or more linked confirmed defects in follow-up |
+| Denominator | Accepted change_ids with completed predeclared follow-up horizon |
+| Expression | N / D * 100 |
+| Aggregation | percent |
+| Unit | % |
+| Eligible population | Accepted changes in acceptance window whose follow-up is complete by as_of. |
+| Exclusions | Immature changes shown separately; duplicates/unconfirmed reports excluded but counted as pending triage. |
+| Events and source | change.accepted; defect.confirmed; defect tracking and acceptance evidence |
+| Owner / cadence | Quality Engineering / Monthly mature cohorts |
+| Missing evidence | Unknown linkage is a coverage warning; no fabricated clean outcome. Show absolute defect and severe incident counts as well. |
+| Gaming and limits | Shorten follow-up or downgrade severity; freeze horizon and rubric and independently sample defects. Descriptive signal, not causal AI productivity attribution. Source completeness, task mix and sampling limit inference; report uncertainty. Counts affected changes, not raw defects per change; no presumption defects are AI-caused. |
+
+
+### Confirmed policy effects
+
+Eligible evaluated attempts with an actual confirmed prohibited effect; report attempts, blocked attempts and effects separately.
+
+| Contract | Definition |
+| --- | --- |
+| Numerator | Distinct attempt_ids with confirmed prohibited action effect |
+| Denominator | All evaluated eligible attempt_ids including failed and abandoned runs |
+| Expression | N / D * 100 |
+| Aggregation | percent |
+| Unit | % |
+| Eligible population | Governed skill trials or supported workflow attempts, reported separately for eval and live populations. |
+| Exclusions | Out-of-scope runs; detection gaps remain coverage issues, not exclusions from known initiated population. |
+| Events and source | attempt.started; policy.violation; gate.blocked; security audit and incident triage |
+| Owner / cadence | Architecture & Security / Immediate incident action; weekly aggregates |
+| Missing evidence | Unknown outcomes remain visible; zero detected effects never proves safety. Missing audits make rate provisional. |
+| Gaming and limits | Hide incidents or inflate harmless trials; absolute severity counts and fixed task mix accompany rate. Descriptive signal, not causal AI productivity attribution. Source completeness, task mix and sampling limit inference; report uncertainty. Blocked attempts are not actual effects; any critical effect blocks promotion regardless of aggregate rate. |
+
+
+### Cost per accepted outcome
+
+Allocated total workflow cost including unsuccessful attempts, licenses, compute, tooling and human review/rework divided by accepted outcomes.
+
+| Contract | Definition |
+| --- | --- |
+| Numerator | Sum allocated costs in one approved reporting currency for all tasks/attempts in matured start cohort |
+| Denominator | Distinct independently accepted tasks in same cohort |
+| Expression | N / D |
+| Aggregation | ratio |
+| Unit | currency/accepted outcome |
+| Eligible population | Matured eligible started-task cohort, with all attempt costs through as_of and allocated shared period costs. |
+| Exclusions | Unrelated projects and documented taxes/transfers outside chosen accounting basis; never failed/abandoned attempts. |
+| Events and source | cost.recorded; task.accepted; finance invoices, usage ledger, sampled effort with approved rates |
+| Owner / cadence | Finance & Accounting Squad / Monthly with late invoice restatement |
+| Missing evidence | Missing cost buckets produce partial estimate plus coverage, not a total. Mixed currency requires dated approved conversion; zero accepted outcomes = null with full cost shown. |
+| Gaming and limits | Count tokens only or hide labor/failures; reconcile invoice and allocation totals without double counting. Descriptive signal, not causal AI productivity attribution. Source completeness, task mix and sampling limit inference; report uncertainty. Allocation and sampled labor carry uncertainty; no ROI without independently measured business benefit. |
+
+
+### Verification confidence and cognitive load
+
+Three separate anonymous 1–5 item distributions: confidence in verifying output, manageable workload, usefulness. Primary item: verification confidence mean; report full distributions and response rate.
+
+| Contract | Definition |
+| --- | --- |
+| Numerator | Sum valid 1–5 verification-confidence responses, one per participant per survey wave |
+| Denominator | Count valid responses to that item |
+| Expression | N / D |
+| Aggregation | mean |
+| Unit | points (1–5) |
+| Eligible population | Invited eligible cohort at fixed survey wave; voluntary responses. |
+| Exclusions | Invalid/out-of-range answers and superseded duplicate submission; nonresponders stay in response-rate denominator. |
+| Events and source | survey.response; anonymous survey with single-use token and aggregate invitation count |
+| Owner / cadence | People & Administration Squad / After pilot workflow cycle; periodic follow-up |
+| Missing evidence | Report valid response count / invited count and item nonresponse; no imputation. Suppress people cohorts below five. |
+| Gaming and limits | Pressure to respond positively; no manager access to individual responses, avoid identifying free text. Descriptive signal, not causal AI productivity attribution. Source completeness, task mix and sampling limit inference; report uncertainty. Perception and selection bias; not measured time savings. No composite productivity index. |
+
+
+### Skills within substantive review window
+
+Active approved skill revisions with an accountable owner and completed substantive review not past due.
+
+| Contract | Definition |
+| --- | --- |
+| Numerator | Distinct active approved skill revisions with current owner, review evidence and review_due_at &gt;= as_of |
+| Denominator | All active approved skill revisions in catalog snapshot |
+| Expression | N / D * 100 |
+| Aggregation | percent |
+| Unit | % |
+| Eligible population | Approved revisions currently supported for use at as_of. |
+| Exclusions | Experimental and retired revisions; deprecated/revoked in-use counts reported independently, not hidden. |
+| Events and source | catalog.published; catalog.reviewed; catalog.deprecated; catalog.revoked; version inventory |
+| Owner / cadence | Data & AI / Monthly and each release |
+| Missing evidence | Missing owner/date/evidence outside numerator; show ownerless, deprecated-in-use and revoked-in-use absolute counts. |
+| Gaming and limits | Rubber-stamp review dates; require linked regression/security/usefulness evidence. Descriptive signal, not causal AI productivity attribution. Source completeness, task mix and sampling limit inference; report uncertainty. A current review is not proof of effectiveness; consumer inventory may miss shadow copies. |
+
+
+### Workflow-specific business acceptance
+
+Independently accepted domain outcomes against a predeclared business rubric, separate from technical completion.
+
+| Contract | Definition |
+| --- | --- |
+| Numerator | Eligible completed-observation task_ids meeting the department-specific outcome rubric |
+| Denominator | All eligible initiated workflow task_ids with matured business-outcome horizon |
+| Expression | N / D * 100 |
+| Aggregation | percent |
+| Unit | % |
+| Eligible population | One named departmental workflow and predeclared start cohort; never pool unlike rubrics. |
+| Exclusions | Cancelled-before-start and unrelated workflows; unsuccessful or abandoned eligible work remains. |
+| Events and source | task.started; business.accepted; departmental case/content/reconciliation/onboarding review record |
+| Owner / cadence | Product Management / Each pilot cycle with owning department |
+| Missing evidence | Unknown follow-up stays denominator with unresolved count; no claim actual business outcome changed without source evidence. |
+| Gaming and limits | Weaken rubric or count drafts as customer benefit; lock rubric and independently audit acceptance. Descriptive signal, not causal AI productivity attribution. Source completeness, task mix and sampling limit inference; report uncertainty. Domain owner signs acceptance: Operations service accuracy; Marketing claims/rights; Finance reconciliation accuracy; HR policy correctness; Product usability/value. Not revenue uplift. |
+
+
+</details>
+
+<details>
+<summary>Run the nine-metric synthetic prototype and inspect omissions</summary>
+
+## Run the synthetic measurement example
+
+**Executed synthetic example — not Eldorado results.** The bundled fixture produces 1 independently accepted task from 4 matured starts: 25% confirmed success. One unresolved task remains in that denominator; known-outcome coverage is 75%. Selection precision and recall are each 1 / 2 = 50%. Allocated synthetic cost is EUR 60 / 1 accepted outcome = EUR 60 per accepted outcome. These deliberately small samples demonstrate arithmetic and missingness, not a baseline, target or ROI claim.
+
+From the private documentation checkout, run `node scripts/ai-kpi.mjs` and `node --test scripts/ai-kpi.test.mjs`. The fixture `scripts/fixtures/ai-kpi-synthetic.json` is labeled synthetic; every result carries the same label and calculation version. This prototype has no network collectors and does not enable employee telemetry.
+
+The executable covers validated success, selection precision/recall, change fail and rework rates, escaped quality, policy effects, cost and human experience. Other catalog metrics remain contracts rather than implemented collectors; output lists the omissions. Snapshot inputs are simplified, pre-reconciled records, not a production ingestion system. Conflicting duplicates reject the calculation rather than silently choosing a value.
+
+</details>
+
+**Next:** [Use findings to maintain, quarantine or replace skills →](./skills-maintenance.mdx)
+
+</div>

docs/strategy/roadmap.mdx

@@ -0,0 +1,75 @@
+---
+id: roadmap
+title: Roadmap
+description: Evidence-gated phases, no promised dates or budgets.
+hide_table_of_contents: true
+---
+
+import ArchifyDiagram from '@site/src/components/ArchifyDiagram';
+
+<div className="strategy-content">
+
+**TO-BE · Target operating model — not installed controls or company results.**
+
+## What must be true before widening the rollout?
+
+Advance by exit evidence, not promised dates or usage volume. Each stage can hold, narrow or stop; changed client, data or authority boundaries reopen earlier gates.
+
+<ArchifyDiagram name="strategy-roadmap" title="Foundation, pilot, reliable distribution, coordination and departmental expansion have exit gates" story />
+
+- **Start bounded:** named people, lawful data handling and a reproducible baseline precede the pilot.
+- **Prove recovery before coordination:** verified versions, revocation and human takeover are prerequisites.
+- **Expand by department:** accepted outcomes, guardrails, total cost and experience justify continuation; sensitive decisions remain human.
+
+<details>
+<summary>Stage-by-stage entry evidence, work, exit gates and hold conditions</summary>
+
+**TO-BE · Target operating model.** Introduction depends on the [roadmap gates](./roadmap.mdx); these pages do not describe installed controls or measured company results.
+
+### Foundation
+
+**Entry evidence** — Strategy scope accepted for planning; existing teams identified.
+
+**Work** — Inventory actual client hosts/builds, provider/data terms, repositories, authority, owners and event availability; select low-risk workflows and metric definitions.
+
+**Exit evidence and hold condition** — Named accountable people and independent reviewers, bounded pilot charter, forbidden actions, data/retention decision and reproducible baseline plan. Hold if accountability or lawful collection is unresolved.
+
+### Governed skills pilot
+
+**Entry evidence** — Foundation evidence approved; no privileged autonomous effects.
+
+**Work** — Build a small registry, immutable contract, client adapters, evaluations, coaching and synthetic measurement verification.
+
+**Exit evidence and hold condition** — Qualified client/skill tuples, mandatory safety checks, independent task acceptance, reconciled coverage and user feedback. Hold or narrow scope if quality or data coverage is inadequate.
+
+### Reliable distribution
+
+**Entry evidence** — Pilot quality and usefulness support continuing.
+
+**Work** — Canary updates, effective-version readback, version locking, exception expiry, stale/offline handling and rollback.
+
+**Exit evidence and hold condition** — Tested revocation and recovery, no bypass of central privileged gates, owners can support the catalog. Hold if effective versions or controls cannot be verified.
+
+### Logical SDLC coordination
+
+**Entry evidence** — Distribution, authority and measurement evidence stable.
+
+**Work** — Observe and assemble evidence first, then propose and route work within scoped identities and budgets.
+
+**Exit evidence and hold condition** — Exact-artifact approvals, idempotency, duplicate/outage recovery, separation of duties, audit and kill-switch drills pass; humans can take over. No authority expansion based on usage alone.
+
+### Departmental expansion
+
+**Entry evidence** — Each department supplies a workflow owner, outcome, data boundary and capacity.
+
+**Work** — Add Operations, Marketing, Finance & Accounting and HR & Administration workflows with domain-specific review; Product and Technology continue quality improvement.
+
+**Exit evidence and hold condition** — Departmental accepted outcomes, guardrails, total cost and experience justify continuation; sensitive decisions stay human. Stop or roll back workflows without adequate evidence.
+
+There are no invented launch dates, budgets, staffing commitments or guaranteed gains. Phase gates permit narrowing or stopping. Re-evaluate earlier phases when the underlying client, provider, data scope or authority changes.
+
+</details>
+
+**Next:** [Return to the strategy destination →](./index.mdx)
+
+</div>

docs/strategy/skills-adoption.mdx

@@ -0,0 +1,41 @@
+---
+id: skills-adoption
+title: Skills adoption
+description: Workflow-led coaching, client choice, feedback, manual path.
+hide_table_of_contents: true
+---
+
+import ArchifyDiagram from '@site/src/components/ArchifyDiagram';
+
+<div className="strategy-content">
+
+**TO-BE · Target operating model — not installed controls or company results.**
+
+## When should a pilot become a team workflow?
+
+Expand only when a bounded canary produces independently accepted work and useful feedback. Teach people to verify artifacts and recover without AI, not merely invoke a skill.
+
+<ArchifyDiagram name="strategy-adoption" title="Choose a workflow, coach a canary, verify outcomes and improve before expansion" story />
+
+- **Team-led:** the departmental owner defines the outcome; People &amp; Administration Squad supports learning.
+- **Choice within support:** qualify the client path instead of promising identical agent behavior.
+- **No adoption quotas:** retain a manual path; rejected suggestions and non-use are feedback, not poor performance.
+
+<details>
+<summary>Onboarding responsibilities, coaching and feedback safeguards</summary>
+
+**TO-BE · Target operating model.** Introduction depends on the [roadmap gates](./roadmap.mdx); these pages do not describe installed controls or measured company results.
+
+Start with a small set of useful workflows chosen by the existing teams. Product Management and the departmental owner identify the outcome; Data & AI helps turn it into a skill; Quality Engineering establishes acceptance; Platform & IT qualifies the client path; Architecture & Security clears the data boundary. People & Administration Squad coordinates learning and accessible feedback.
+
+Onboarding should teach people to select the right skill, inspect the actual artifact, recognize untrusted instructions, use the exception and incident routes and recover without AI. A practice task ends with verified work and an explanation of limits, not just a logged invocation. Demonstrate the same portable skill on the supported local clients without promising identical agent behavior.
+
+Use short worked examples, peer pairing, office hours and a clear catalog search path. Gather reasons for non-use and rejected suggestions without penalizing them. Preserve a manual path. Training feedback improves the skill only through review, not automatic self-modification of the approved catalog. Departmental workflow outcomes matter more than uniform uptake.
+
+No developer rankings, individual productivity scores, minimum invocation quotas or inference of effort from token counts are part of this strategy. Report cohort-level evidence with privacy protection and balanced quality, flow, risk and cost. A participant may reasonably stop using a skill that creates more work or uncertainty.
+
+</details>
+
+**Next:** [Measure accepted outcomes, not activity →](./measurement.mdx)
+
+</div>

docs/strategy/skills-governance.mdx

@@ -0,0 +1,104 @@
+---
+id: skills-governance
+title: Skills governance
+description: Contract, lifecycle, decision rights, adapters, locking, exceptions.
+hide_table_of_contents: true
+---
+
+import ArchifyDiagram from '@site/src/components/ArchifyDiagram';
+
+<div className="strategy-content">
+
+**TO-BE · Target operating model — not installed controls or company results.**
+
+## Who can approve a skill for use?
+
+The owning team authors the skill; independent reviewers assess it before exact-revision approval. Data &amp; AI maintains the catalog, while Platform &amp; IT verifies distribution and revocation.
+
+<ArchifyDiagram name="strategy-governance" title="An owner proposes; independent review and canary evidence precede approval" story />
+
+- **Separate duties:** the author cannot provide the only approval; higher risk involves Architecture &amp; Security.
+- **Pin the whole bundle:** content, adapters and executable dependencies travel together.
+- **Keep controls authoritative:** exceptions expire and cannot bypass protected release, payment or identity controls.
+
+<details>
+<summary>Ownership, client qualification, exceptions and rollback</summary>
+
+**TO-BE · Target operating model.** Introduction depends on the [roadmap gates](./roadmap.mdx); these pages do not describe installed controls or measured company results.
+
+### A contract that travels, controls that stay authoritative
+
+Maintain one catalog entry per stable skill ID, with immutable revisions and a concise portable `SKILL.md` body. Required content includes when to use and when not to use the skill, prerequisites, bounded steps, expected artifacts, verification, failure handling and escalation. The catalog contract below defines owner and independent reviewer, risk tier, supported clients and versions, dependencies, digest, provenance and license, evaluations, approval, review date, deprecation and rollback.
+
+The release manifest pins the content, dependencies and adapter revisions by full immutable commit or digest. Names use an `eldorado-` prefix to reduce collisions. Friendly versions aid communication but never replace the digest. No arbitrary upstream automatic update is admitted into the approved bundle. Changes to scripts, resources or dependencies count as skill changes, not harmless documentation edits.
+
+Adapters place content in the qualified client's discovery paths and implement only verified client-specific behavior. Qualification records the host, exact build, OS, model configuration, discovery, explicit invocation, collisions, disabled skills, permission behavior, context compaction and reload behavior. A common file format is not common precedence or a portable hooks API. Claude and Cline skill-name precedence differs from rule/memory behavior; Copilot support varies by surface. Test the actual build, not the brand name.
+
+### Lifecycle and decision rights
+
+A proposal names the problem, owner, data scope and testable outcome. Experimental revisions run only in approved disposable environments. Promotion requires independent review, static and executable dependency checks, per-client behavioral evaluations and a bounded canary. Approval records bind the exact artifact and permitted uses. Deprecated revisions carry a migration path and deadline; retired revisions are unavailable for new work. Any active revision can be quarantined immediately.
+
+The author never supplies the only approval. Data & AI maintains catalog state; the owning team is accountable for content; Quality Engineering approves evaluation evidence; Architecture & Security approves higher-risk boundaries; Platform & IT verifies distribution and revocation. A business owner accepts workflow outcomes. These functions can be covered by existing staff, but incompatible author/approver duties must remain separate for the same release.
+
+An exception contains its ID, skill/client revision, scope, business reason, risk owner, compensating checks, approver, start and expiry, affected users/projects and rollback route. It does not disable protected release, payment or identity controls. Expired or unverifiable exceptions deny privileged actions. Repeated exceptions trigger a supported-design change rather than permanent informal bypass.
+
+### Distribution, stale clients and rollback
+
+Stage a verified bundle atomically, check its digest, load it through the qualified adapter and read back its effective revision. Test already-open sessions; changing files is not proof of reloading instructions. Record immutable last-known-good content and adapter dependencies. Canary upgrades precede wider distribution.
+
+A cached verified bundle may support explicitly permitted low-risk work if its model and tool dependencies are available. It does not make a cloud-backed client work offline. Stale or unsupported sessions cannot obtain centrally mediated privileged access. Reconnection revalidates support, revocation and policy before credentials are issued. Central artifact review protects delivery even when a laptop declaration is absent or false; a client report cannot prove which private prompt was actually followed.
+
+Rollback restores the approved manifest and dependencies, invalidates affected sessions, revokes unsafe revisions, runs a smoke test and verifies effective state. It cannot undo data disclosure or commands already executed. Those require incident response.
+
+</details>
+
+<details>
+<summary>Catalog contract — required fields</summary>
+
+## Catalog contract
+
+| Contract | Definition |
+| --- | --- |
+| skill_id | Stable globally unique eldorado-&lt;domain&gt;-&lt;purpose&gt;; never reused for a different purpose |
+| name | Human-readable name |
+| purpose | Problem, expected outcome and intended users |
+| triggers | Positive and negative invocation conditions |
+| owner | Existing department/team plus assigned accountable person before approval |
+| reviewer | Independent person and existing team; cannot equal release author |
+| backup | Named coverage within existing team before production support |
+| risk_tier | R1\|R2\|R3; maximum implied by data, tool and effect scope |
+| data_classification | Allowed input/output/provider boundary and forbidden data |
+| authority_envelope | Allowed resources/operations and forbidden effects; enforced externally |
+| supported_clients | Array of client, host, exact tested builds, OS, model configuration, adapter digest and qualification evidence |
+| dependencies | All skill/resource/script/tool/MCP/plugin dependencies pinned by immutable digest plus license and source |
+| revision | Full immutable source commit and content/artifact digest; friendly semver optional |
+| tests_evals | Suite/corpus/rubric/runner/judge revisions, client tuple, seeds or trial IDs, results and independent evidence refs |
+| approval | Approver identities, exact digest and policy revision, approved scope, time and expiry/invalidation condition |
+| provenance_license | Origin repository/author, upstream revision, acquisition/review history, rights/license for content and bundled resources |
+| maintenance_date | Last substantive review timestamp plus next review due and trigger conditions |
+| deprecation | State, reason, replacement, migration instructions, consumers and retirement deadline if applicable |
+| rollback | Approved known-good bundle+adapter+dependency digests, revocation/reload procedure and tested evidence |
+| procedure | Prerequisites, bounded steps, expected artifacts, verification, failure handling, escalation |
+
+
+</details>
+
+<details>
+<summary>Lifecycle transitions and required evidence</summary>
+
+## Promotion and retirement
+
+| Transition | Required evidence |
+| --- | --- |
+| proposed → experimental | Owner, purpose, risk/data scope, disposable environment and preregistered test plan |
+| experimental → approved | Independent review, all mandatory tests, qualified clients, canary, exact-digest approval |
+| approved → deprecated | Owner gives migration/replacement and retirement conditions |
+| deprecated → retired | Consumers reconciled or explicit risk-approved cutover; no new invocation |
+| any active state → quarantined | Incident or unsafe/unknown provenance; central deny immediately |
+| quarantined → experimental | Reviewed correction; new immutable revision; requalify, never auto-restore approval |
+
+</details>
+
+**Next:** [See the evidence needed to qualify a skill →](./skills-quality.mdx)
+
+</div>

docs/strategy/skills-maintenance.mdx

@@ -0,0 +1,49 @@
+---
+id: skills-maintenance
+title: Skills maintenance
+description: Review, drift, deprecation, rollback and incident handling.
+hide_table_of_contents: true
+---
+
+import ArchifyDiagram from '@site/src/components/ArchifyDiagram';
+
+<div className="strategy-content">
+
+**TO-BE · Target operating model — not installed controls or company results.**
+
+## What happens when a skill drifts or causes harm?
+
+Monitor usefulness and safety throughout a revision's life. Unsafe behavior triggers containment; a correction returns through independent tests and approval, never automatic reinstatement.
+
+<ArchifyDiagram name="strategy-maintenance" title="Monitor, triage and test corrections; promote safely or contain and roll back" story />
+
+- **Named ownership:** Data &amp; AI coordinates catalog health with the owning teams.
+- **Early triggers:** incidents and client, model or dependency changes override the calendar.
+- **Recovery is verified:** rollback restores a known-good bundle; it cannot undo disclosure or past effects.
+
+<details>
+<summary>Review responsibilities, incident handling and proposed review intervals</summary>
+
+**TO-BE · Target operating model.** Introduction depends on the [roadmap gates](./roadmap.mdx); these pages do not describe installed controls or measured company results.
+
+Every approved skill has an accountable owning team, independent reviewer, review due date, supported client matrix and rollback bundle. Review both usefulness and safety, not just metadata freshness. Proposed maximum review intervals are recorded by risk tier; incidents, dependency changes, model/client drift or repeated failures trigger earlier review.
+
+Data & AI reviews catalog health with the owning teams. Quality Engineering samples accepted outputs and adds confirmed failures to regression sets without exposing sensitive content. Platform & IT watches unsupported, deprecated and revoked revisions and tests distribution recovery. Architecture & Security reviews emerging misuse and exception expiry. Remove redundant or unused entries deliberately, after examining whether poor discoverability or fit explains non-use.
+
+A reported unsafe behavior opens an incident with artifact, policy and client versions. Architecture & Security coordinates containment; Platform & IT revokes authority, stops scheduling and quarantines affected revisions; the owning department handles customer or business consequences; Quality Engineering reproduces the failure; Data & AI coordinates catalog correction and trend analysis. Preserve minimal restricted evidence and involve People & Administration Squad for employee-data concerns and Finance & Accounting Squad for financial effects. Restart requires a reviewed fix, regression evidence, verified rollback/revocation and accountable human authorization. Closing the incident does not erase the historical failure from measurement.
+
+## Proposed maximum review intervals
+
+Owner ratification is required before adoption. Review earlier after incidents or material dependency changes.
+
+| Tier | Maximum days between substantive reviews |
+| --- | --- |
+| R1 | 90 |
+| R2 | 60 |
+| R3 | 30 |
+
+</details>
+
+**Next:** [Use exit evidence to choose the next rollout stage →](./roadmap.mdx)
+
+</div>

docs/strategy/skills-quality.mdx

@@ -0,0 +1,86 @@
+---
+id: skills-quality
+title: Skills quality
+description: Risk tiers, independent evaluation, repeated trials, adversarial conformance.
+hide_table_of_contents: true
+---
+
+import ArchifyDiagram from '@site/src/components/ArchifyDiagram';
+
+<div className="strategy-content">
+
+**TO-BE · Target operating model — not installed controls or company results.**
+
+## What evidence is enough to promote a skill?
+
+Risk determines the evaluation depth, not whether safety checks apply. Independent evidence must show useful outcomes and no failed mandatory gate before promotion.
+
+<ArchifyDiagram name="strategy-quality" title="Classify risk, test independently, then pass every mandatory gate" story />
+
+- **R1:** approved nonsensitive drafting. **R2:** code or customer-impacting material. **R3:** privileged or sensitive effects; human-authorized, outside initial autonomous scope.
+- **No averaging away harm:** a critical unauthorized effect blocks promotion.
+- **Proposed floors need owner ratification:** missing coverage or acceptance rules means qualification is incomplete.
+
+<details>
+<summary>Evaluation design, adversarial cases and interpretation</summary>
+
+**TO-BE · Target operating model.** Introduction depends on the [roadmap gates](./roadmap.mdx); these pages do not describe installed controls or measured company results.
+
+Quality has four separate questions: was the right skill selected, was the procedure executed safely, did the artifact pass independent checks, and did the workflow produce useful outcomes? A successful invocation answers none of the remaining questions by itself.
+
+The proposed qualification contract uses three tiers. R1 is read-only or drafting with nonsensitive approved material; R2 creates code or material with customer impact but no privileged external effect; R3 touches privileged, financial, sensitive-personal or production decisions. R3 remains human-authorized and out of the initial autonomous scope.
+
+Every tier requires all mandatory deterministic safety, schema, authorization and provenance checks to pass, with no observed critical unauthorized action. An observed critical effect blocks promotion. The proposed pilot evaluation floors below set success thresholds; these are design defaults for owner ratification, not externally validated guarantees or approved service levels. If sample coverage, acceptance criteria or responsible reviewers are missing, qualification remains incomplete. No aggregate score can trade off a failed mandatory safety check.
+
+Use sanitized, predeclared task sets containing positive triggers, near misses, negative cases and the normal workload mix. Compare no-skill, current-approved and candidate paths with the same starting artifacts; repeat stochastic trials and retain failed and abandoned attempts. Independently inspect output state. Deterministic tests grade checkable constraints; calibrated humans grade usefulness, maintainability and experience. A model judge is supplementary, versioned and checked against human disagreements, never the sole safety or promotion authority.
+
+Include adversarial repository text, malicious referenced code, wrong permissions, client toggles, name shadowing, unsupported versions, hook timeout/crash/malformed response, stale sessions, offline recovery and rollback. Run central checks against forged/missing client declarations. Hook presence is not fail-closed enforcement: failure semantics must be tested on each client, and central authorization remains independent.
+
+Report denominators, task mix, trial counts, per-client results and uncertainty. A passing benchmark is evidence within a tested envelope, not proof that all future tasks are safe. Material model, client, adapter or dependency changes trigger requalification.
+
+</details>
+
+<details>
+<summary>Proposed R1 / R2 / R3 sample sizes and thresholds</summary>
+
+## Proposed qualification floors
+
+These are local design defaults for responsible-owner ratification, not approved service levels or guarantees. All mandatory checks must pass regardless of aggregate score.
+
+### R1
+
+**Distinct tasks** — 30
+
+**Trials per task/client** — 3
+
+**Artifact success** — 90%
+
+**Selection precision / recall** — 90% / 90%
+
+### R2
+
+**Distinct tasks** — 60
+
+**Trials per task/client** — 3
+
+**Artifact success** — 95%
+
+**Selection precision / recall** — 95% / 90%
+
+### R3
+
+**Distinct tasks** — 100
+
+**Trials per task/client** — 5
+
+**Artifact success** — 99%
+
+**Selection precision / recall** — 99% / 95%
+
+Artifact success denominator is every planned executed trial, retaining failures and abandonment. Trials of same task are correlated: show per-task and per-client strata; do not inflate independent sample size. Selection floors use independent labels. Report 95% uncertainty intervals clustered by task for outcome comparisons; no regression versus current approved path beyond a preregistered owner-approved margin. Missing margin/precision rule prevents promotion.
+
+</details>
+
+**Next:** [Introduce qualified skills through a bounded pilot →](./skills-adoption.mdx)
+
+</div>

docs/strategy/target-operating-model.mdx

@@ -0,0 +1,143 @@
+---
+id: target-operating-model
+title: Target operating model
+sidebar_label: Target
+description: An autonomous agent executes and governs the SDLC; humans direct, guide and review the repeating cycle.
+hide_table_of_contents: true
+---
+
+import ArchifyDiagram from '@site/src/components/ArchifyDiagram';
+
+<div className="strategy-content">
+
+**TO-BE · Target operating model — the intended strategy, not a deployed system.**
+
+## Autonomous SDLC, human direction
+
+<ArchifyDiagram name="strategy-target" title="Autonomous agent executes and governs the SDLC; humans direct, guide and review" story />
+
+An autonomous agent executes and governs every phase. Humans direct, guide and review it; a separate human-controlled code agent contributes to each phase from outside the cycle.
+
+**Solid arrows:** lifecycle · **Dotted spokes:** execution and governance · **Dashed arrows:** contributions.
+
+**Scope → Architecture → UI/UX → Planning → Delivery → UAT → Security → Releases → Scope**
+
+Each stage follows the previous one. Releases returns to Scope; the cycle repeats indefinitely, with human direction informing the next iteration.
+
+<details>
+<summary>Supporting implementation options: trust boundaries and recovery</summary>
+
+## Controls that support autonomous execution
+
+The lifecycle above is the strategic direction. The earlier control design below is a supporting implementation option, not an agreed assignment of approval roles or a claim of installed controls. Detailed approval policy and responsibilities remain to be defined with humans.
+
+1. Humans direct, guide and review; the autonomous agent executes and governs work across the lifecycle.
+2. The reviewed registry supplies pinned skills and qualified adapters to coordinator and local clients.
+3. Laptop contributors can participate alongside the agent; independent repository and CI checks verify the exact revision.
+4. A separate release service and artifact-scoped approval are possible controls, subject to the policy humans define.
+5. Restricted audit and measurement evidence supports human review and the next Scope iteration.
+
+<ArchifyDiagram name="ai-adoption-target" title="Supporting control option, not agreed approval policy: isolated release authority" />
+
+**TO-BE · Target operating model.** Introduction depends on the [roadmap gates](./roadmap.mdx); these pages do not describe installed controls or measured company results.
+
+### One coordination function, distributed contributions
+
+The autonomous agent is more than a task router: it executes and governs the repeating SDLC under human direction, guidance and review. A coordinating function maintains work records, dependencies, evidence requests, bounded retries and escalation. Data & AI and the existing AI Architect function are possible implementation contributors, not newly assigned approval authorities. Autonomous execution does not remove human involvement or allow the agent to redefine its own controls.
+
+One logical coordinator does not mean one fragile process. A durable task ledger, explicit state transitions, leases and idempotency keys allow recovery or multiple replicas without duplicate delivery. Inference outages stop new agent decisions, not the organization's ability to take over. People can resume work through the normal deterministic workflow. Evidence and authorization services fail closed for privileged actions; missing evidence never becomes permission.
+
+These controls support the sequence Scope → Architecture → UI/UX → Planning → Delivery → UAT → Security → Releases → Scope; they do not replace it with a separate lifecycle. Product, engineering, design, quality, security and platform expertise inform human direction and review. Specific approval assignments and release permissions are implementation decisions still to be defined.
+
+### Trust and authority boundaries
+
+People authenticate to the work system; the coordinator receives only the project context it needs. Untrusted issue text, repository content, web pages and tool output are task data, never an authorization source. Local clients operate under device controls and project-scoped access. Hard containment requires OS/container isolation, filesystem and network restrictions and separate short-lived identities; a skill folder, prompt or working directory is not a sandbox.
+
+The registry distributes reviewed immutable content and adapters, not ambient credentials. Executable scripts, plugins, MCP servers and dependencies are separately reviewed and pinned. Model-provider routing is allowlisted for the data classification, with approved retention and training-use terms before sensitive data crosses that boundary. Fallback to another provider must not silently change the data policy.
+
+Central controls verify protected-branch review, actual artifact identity, exact commit and policy revision, required checks and a scoped human approval. Candidate changes cannot edit their own authoritative gate or reuse approval for a different artifact. Deployment credentials belong to the release service, not the local agent. Approval expires or is invalidated by changed content. Emergency stop revokes mutation credentials and stops scheduling independently of the model, preserves evidence and enables human takeover.
+
+</details>
+
+<details>
+<summary>Candidate contributions and first workflows for all eleven teams</summary>
+
+### Department contributions
+
+The existing team structure provides a starting point. The contributions below are implementation proposals, not settled approval roles or lifecycle gates.
+
+### Product / Product Management
+
+**Contribution and retained human decision** — Own pilot priorities, acceptance criteria and outcome hypotheses; decide product value.
+
+**First bounded workflow and evidence** — Draft acceptance criteria from sanitized discovery notes; independent completeness review and accepted-task success.
+
+### Product / Product Design
+
+**Contribution and retained human decision** — Own design quality, accessibility and research handling.
+
+**First bounded workflow and evidence** — Review a proposed flow against an accessibility checklist; verify findings against the interface.
+
+### Technology / Product Engineering
+
+**Contribution and retained human decision** — Own skill authoring, code review and maintainability; remain accountable for generated code.
+
+**First bounded workflow and evidence** — Test scaffolding and change summaries in a disposable branch; independent tests and escaped-quality follow-up.
+
+### Technology / Platform & IT
+
+**Contribution and retained human decision** — Own supported client inventory, distribution, identity, isolation, CI/release integration, transport and emergency revocation.
+
+**First bounded workflow and evidence** — Qualify a pinned bundle and exercise rollback; inventory and exact-revision gate evidence.
+
+### Technology / Architecture & Security
+
+**Contribution and retained human decision** — Own risk classification, data boundaries, security review and bounded exceptions.
+
+**First bounded workflow and evidence** — Review injected-input and unauthorized-tool cases; independent control evidence and policy-effect counts.
+
+### Technology / Quality Engineering
+
+**Contribution and retained human decision** — Own regression/adversarial suites, rubric calibration and acceptance evidence.
+
+**First bounded workflow and evidence** — Evaluate candidate versus approved skills on repeated representative tasks; retain all failures.
+
+### Technology / Data & AI
+
+**Contribution and retained human decision** — Own catalog coordination, coordinator evaluation and measurement design, through existing AI enablement responsibilities.
+
+**First bounded workflow and evidence** — Curate a small skill set and analyze a prospective pilot; no new AI department.
+
+### Operations / Operations Squad
+
+**Contribution and retained human decision** — Own service acceptance, disputes, fraud, refunds and customer communications.
+
+**First bounded workflow and evidence** — Draft an answer from sanitized resolved cases; Operational Quality workstream checks correctness before any send. No automated dispute/refund decision.
+
+### Marketing / Marketing Squad
+
+**Contribution and retained human decision** — Own brand, factual claims, content rights, publication and spend approvals.
+
+**First bounded workflow and evidence** — Draft a campaign brief against approved brand material; human claim/rights review before publication.
+
+### Finance & Accounting / Finance & Accounting Squad
+
+**Contribution and retained human decision** — Own allocation of total costs, financial evidence and segregation of approvals.
+
+**First bounded workflow and evidence** — Explain a sanitized reconciliation exception; no posting, payout or payment authority.
+
+### HR & Administration / People & Administration Squad
+
+**Contribution and retained human decision** — Own coaching, acceptable use, feedback privacy and people decisions; partner with Platform & IT on access lifecycle.
+
+**First bounded workflow and evidence** — Draft onboarding guidance from approved policy; human accuracy review. No hiring or performance decision automation.
+
+Product keeps two teams; Technology keeps five; the other four departments keep one squad each. Coordination, skill ownership, approval and cover are assignments inside these teams, not new standing departments, roles or headcount. Department leaders retain accountability and designate real approvers before a pilot starts.
+
+See the existing [organization structure](/organization/structure/), [department collaboration](/organization/collaboration/) and [SDLC responsibilities](/organization/sdlc/).
+
+</details>
+
+**Next:** [Decide who owns and approves each skill →](./skills-governance.mdx)
+
+</div>

docusaurus.config.ts

@@ -13,21 +13,27 @@ const config: Config = {
   onBrokenLinks: 'throw',
   markdown: {hooks: {onBrokenMarkdownLinks: 'throw'}},
   presets: [['classic', {
-    docs: {sidebarPath: './sidebars.ts', routeBasePath: 'docs', editUrl: 'https://gitea.lego-cloud.eu/eldorado-v1/documentation/_edit/main/'},
+    docs: {path: 'docs/core', sidebarPath: './sidebars.ts', routeBasePath: 'docs', editUrl: 'https://gitea.lego-cloud.eu/eldorado-v1/documentation/_edit/main/'},
     blog: false,
     theme: {customCss: './src/css/custom.css'},
   } satisfies Preset.Options]],
+  plugins: [
+    ['@docusaurus/plugin-content-docs', {id: 'organization', path: 'docs/organization', routeBasePath: 'organization', sidebarPath: './sidebars/organization.ts'}],
+    ['@docusaurus/plugin-content-docs', {id: 'strategy', path: 'docs/strategy', routeBasePath: 'strategy', sidebarPath: './sidebars/strategy.ts'}],
+    ['@docusaurus/plugin-content-docs', {id: 'contribution', path: 'docs/contribution', routeBasePath: 'contribution', sidebarPath: './sidebars/contribution.ts'}],
+  ],
   themes: [['@easyops-cn/docusaurus-search-local', {
     hashed: 'filename', indexDocs: true, indexBlog: false, indexPages: true,
-    docsRouteBasePath: 'docs', language: ['en'], highlightSearchTermsOnTargetPage: true,
+    docsRouteBasePath: ['docs', 'organization', 'strategy', 'contribution'], language: ['en'], highlightSearchTermsOnTargetPage: true,
   }]],
   themeConfig: {
     colorMode: {defaultMode: 'light', respectPrefersColorScheme: true},
     navbar: {
       title: 'Eldorado', logo: {alt: 'Documentation home', src: 'img/docs-mark.svg'},
       items: [
-        {to: '/docs/overview/', label: 'Documentation', position: 'left'},
-        {to: '/docs/maintain/', label: 'Maintainer guide', position: 'left'},
+        {type: 'docSidebar', docsPluginId: 'organization', sidebarId: 'organizationSidebar', label: 'Organization', position: 'left'},
+        {type: 'docSidebar', docsPluginId: 'strategy', sidebarId: 'strategySidebar', label: 'Strategy', position: 'left'},
+        {type: 'docSidebar', docsPluginId: 'contribution', sidebarId: 'contributionSidebar', label: 'Contribution', position: 'left'},
         {href: 'https://gitea.lego-cloud.eu/eldorado-v1/documentation', label: 'Repository', position: 'right'},
       ],
     },

package.json

@@ -7,16 +7,21 @@
     "node": ">=22"
   },
   "scripts": {
-    "start": "docusaurus start",
-    "build": "docusaurus build",
+    "start": "pnpm diagrams:build && docusaurus start",
+    "build": "pnpm diagrams:build && docusaurus build",
     "serve": "docusaurus serve",
     "typecheck": "tsc --noEmit",
-    "verify": "node scripts/verify.mjs",
-    "verify:build": "node scripts/verify.mjs --build"
+    "verify": "pnpm test && node scripts/verify.mjs",
+    "verify:build": "node scripts/verify.mjs --build",
+    "diagrams:build": "node scripts/build-diagrams.mjs",
+    "test": "node --test scripts/*.test.mjs",
+    "test:browser": "node scripts/browser/strategy-story.cjs && node scripts/browser/inline-controls.cjs && node scripts/browser/sdlc-cycle.cjs",
+    "kpi:example": "node scripts/ai-kpi.mjs"
   },
   "dependencies": {
     "@docusaurus/core": "3.10.2",
     "@docusaurus/preset-classic": "3.10.2",
+    "@docusaurus/theme-common": "3.10.2",
     "@easyops-cn/docusaurus-search-local": "0.55.3",
     "@fontsource/lato": "5.2.6",
     "@mdx-js/react": "3.1.1",
@@ -30,8 +35,14 @@
     "@docusaurus/tsconfig": "3.10.2",
     "@docusaurus/types": "3.10.2",
     "@types/react": "19.1.13",
+    "playwright": "1.63.0",
     "typescript": "5.9.3"
   },
+  "pnpm": {
+    "overrides": {
+      "serialize-javascript": "7.0.5"
+    }
+  },
   "browserslist": {
     "production": [
       ">0.5%",

pnpm-lock.yaml

@@ -4,6 +4,9 @@ settings:
   autoInstallPeers: true
   excludeLinksFromLockfile: false
 
+overrides:
+  serialize-javascript: 7.0.5
+
 importers:
 
   .:
@@ -14,6 +17,9 @@ importers:
       '@docusaurus/preset-classic':
         specifier: 3.10.2
         version: 3.10.2(@algolia/client-search@5.59.0)(@mdx-js/react@3.1.1(@types/react@19.1.13)(react@19.1.1))(@types/react@19.1.13)(postcss@8.5.28)(react-dom@19.1.1(react@19.1.1))(react@19.1.1)(search-insights@2.17.3)(typescript@5.9.3)
+      '@docusaurus/theme-common':
+        specifier: 3.10.2
+        version: 3.10.2(@docusaurus/plugin-content-docs@3.10.2(@mdx-js/react@3.1.1(@types/react@19.1.13)(react@19.1.1))(postcss@8.5.28)(react-dom@19.1.1(react@19.1.1))(react@19.1.1)(typescript@5.9.3))(postcss@8.5.28)(react-dom@19.1.1(react@19.1.1))(react@19.1.1)
       '@easyops-cn/docusaurus-search-local':
         specifier: 0.55.3
         version: 0.55.3(@docusaurus/theme-common@3.10.2(@docusaurus/plugin-content-docs@3.10.2(@mdx-js/react@3.1.1(@types/react@19.1.13)(react@19.1.1))(postcss@8.5.28)(react-dom@19.1.1(react@19.1.1))(react@19.1.1)(typescript@5.9.3))(postcss@8.5.28)(react-dom@19.1.1(react@19.1.1))(react@19.1.1))(@mdx-js/react@3.1.1(@types/react@19.1.13)(react@19.1.1))(postcss@8.5.28)(react-dom@19.1.1(react@19.1.1))(react@19.1.1)(typescript@5.9.3)
@@ -48,6 +54,9 @@ importers:
       '@types/react':
         specifier: 19.1.13
         version: 19.1.13
+      playwright:
+        specifier: 1.63.0
+        version: 1.63.0
       typescript:
         specifier: 5.9.3
         version: 5.9.3
@@ -3959,6 +3968,16 @@ packages:
     resolution: {integrity: sha512-Oo/NZcSWccq8KyoG7gLE9fnltgHns+pNCjCAp/WmjsUySi+sX7y4z4Xqu4fVb42CDHzRPl33fjzT15V1wvcyhA==}
     engines: {node: '>=16.0.0'}
 
+  playwright-core@1.63.0:
+    resolution: {integrity: sha512-rYCsBF/M5HjUch52bbtVONEFjv6Xu8sm8h72dNlR5bzIE1fvC/bxgspzkjSfU+MweEMmPM8KJebG6nnyxo5mCg==}
+    engines: {node: '>=20'}
+    hasBin: true
+
+  playwright@1.63.0:
+    resolution: {integrity: sha512-+7ziBLidS4NaNCdt57SUDT+wYmmd5fmiQejUic/kb+YsYSCPyOOE9sebzMjNmQrsnNpDJqd4WHvV/8lfKfUDUg==}
+    engines: {node: '>=20'}
+    hasBin: true
+
   postcss-attribute-case-insensitive@7.0.1:
     resolution: {integrity: sha512-Uai+SupNSqzlschRyNx3kbCTWgY/2hcwtHEI/ej2LJWc9JJ77qKgGptd8DHwY1mXtZ7Aoh4z4yxfwMBue9eNgw==}
     engines: {node: '>=18'}
@@ -4412,9 +4431,6 @@ packages:
     resolution: {integrity: sha512-WuyALRjWPDGtt/wzJiadO5AXY+8hZ80hVpe6MyivgraREW751X3SbhRvG3eLKOYN+8VEvqLcf3wdnt44Z4S4SA==}
     engines: {node: '>=10'}
 
-  randombytes@2.1.0:
-    resolution: {integrity: sha512-vYl3iOX+4CKUWuxGi9Ukhie6fsqXqS9FE2Zaic4tNFD2N2QQaXOMFbuKK4QmDHC0JO6B1Zp41J0LpT0oR68amQ==}
-
   range-parser@1.2.0:
     resolution: {integrity: sha512-kA5WQoNVo4t9lNx2kQNFCxKeBl5IbbSNBl1M/tLkw9WCn+hxNBAW5Qh8gdhs63CJnhjJ2zQWFoqPJP2sK1AV5A==}
     engines: {node: '>= 0.6'}
@@ -4678,8 +4694,9 @@ packages:
     resolution: {integrity: sha512-VMbMxbDeehAxpOtWJXlcUS5E8iXh6QmN+BkRX1GARS3wRaXEEgzCcB10gTQazO42tpNIya8xIyNx8fll1OFPrg==}
     engines: {node: '>= 0.8.0'}
 
-  serialize-javascript@6.0.2:
-    resolution: {integrity: sha512-Saa1xPByTTq2gdeFZYLLo+RFE35NHZkAbqZeWNd3BpzppeVisAqpDjcp8dyf6uIvEqJRd46jemmyA4iFIeVk8g==}
+  serialize-javascript@7.0.5:
+    resolution: {integrity: sha512-F4LcB0UqUl1zErq+1nYEEzSHJnIwb3AF2XWB94b+afhrekOUijwooAYqFyRbjYkm2PAKBabx6oYv/xDxNi8IBw==}
+    engines: {node: '>=20.0.0'}
 
   serve-handler@6.1.7:
     resolution: {integrity: sha512-CinAq1xWb0vR3twAv9evEU8cNWkXCb9kd5ePAHUKJBkOsUpR1wt/CvGdeca7vqumL1U5cSaeVQ6zZMxiJ3yWsg==}
@@ -8836,7 +8853,7 @@ snapshots:
       globby: 13.2.2
       normalize-path: 3.0.0
       schema-utils: 4.5.0
-      serialize-javascript: 6.0.2
+      serialize-javascript: 7.0.5
       webpack: 5.111.1(clean-css@5.3.3)(cssnano@6.1.2(postcss@8.5.28))(html-minifier-terser@7.2.0)(postcss@8.5.28)
 
   core-js-compat@3.50.0:
@@ -8902,7 +8919,7 @@ snapshots:
       jest-worker: 29.7.0
       postcss: 8.5.28
       schema-utils: 4.5.0
-      serialize-javascript: 6.0.2
+      serialize-javascript: 7.0.5
       webpack: 5.111.1(clean-css@5.3.3)(cssnano@6.1.2(postcss@8.5.28))(html-minifier-terser@7.2.0)(postcss@8.5.28)
     optionalDependencies:
       clean-css: 5.3.3
@@ -10792,6 +10809,12 @@ snapshots:
       pvutils: 1.2.0
       tslib: 2.8.1
 
+  playwright-core@1.63.0: {}
+
+  playwright@1.63.0:
+    dependencies:
+      playwright-core: 1.63.0
+
   postcss-attribute-case-insensitive@7.0.1(postcss@8.5.28):
     dependencies:
       postcss: 8.5.28
@@ -11291,10 +11314,6 @@ snapshots:
 
   quick-lru@5.1.1: {}
 
-  randombytes@2.1.0:
-    dependencies:
-      safe-buffer: 5.2.1
-
   range-parser@1.2.0: {}
 
   range-parser@1.2.1: {}
@@ -11642,9 +11661,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  serialize-javascript@6.0.2:
-    dependencies:
-      randombytes: 2.1.0
+  serialize-javascript@7.0.5: {}
 
   serve-handler@6.1.7:
     dependencies:

research/ai-adoption/findings.md

@@ -0,0 +1,229 @@
+# Eldorado AI adoption — research handoff
+
+Research only. Retrieved 4 October 2026 UTC. This document separates documented vendor capability, empirical evidence, and recommendations. Nothing here certifies an Eldorado rollout, installed client, enabled telemetry, staffing appointment, measured baseline, or realized productivity improvement. Sources and literal supporting passages are in `sources.json`; fetched text, retrieval outcomes and citation ledger are retained alongside it.
+
+## 1. Local organizational baseline and scope
+
+Read-only remote fetch and status inspection found a clean documentation checkout on `main`, with HEAD and `origin/main` both `14ba1aa1ef66c91525135f743d15c77e32db78d3`. Inspected all three current Organization pages: `structure.mdx`, `collaboration.mdx`, `sdlc.mdx`, plus channel wiki `/opt/data/wiki/channels/1555510466904727622.md`. This is documentation evidence, not independent verification of actual personnel, systems, or deployed controls. No repository file was changed.
+
+Preserve the existing structure:
+
+- Product: Product Management and Product Design.
+- Technology: Product Engineering, Platform & IT, Architecture & Security, Quality Engineering, Data & AI.
+- Operations: Operations Squad; Marketing: Marketing Squad; Finance & Accounting: Finance & Accounting Squad; HR & Administration: People & Administration Squad.
+- Existing leadership documentation locates AI enablement coordination with the AI Architect within Data & AI, alongside established engineering leadership. Do not invent a new AI department, standing committee, delivery team, or confirmed headcount.
+
+The requested target is ONE logical SDLC coordinating agent, with people using local Copilot, Claude Code or Cline agents. Logical coordination does not require a single fragile process and does not transfer human accountability to a model. The recommendations below develop this target; they are not a description of present operations.
+
+## 2. Principal conclusions
+
+1. Standardize a portable skill content contract, not the fiction of one universal client policy. Agent Skills defines `SKILL.md`, metadata and resources; `allowed-tools` is experimental, and the discovery directory is not mandated by the format.[1][21]
+2. Treat instructions as guidance. GitHub explicitly warns of nondeterministic instruction following, and Claude describes memory files as context rather than enforced configuration.[3][5] Recommended enforcement belongs in independently administered repository, CI, artifact and release controls.
+3. Maintain client-specific adapters and an explicit supported version matrix. Current official docs disagree even about collision precedence: Claude enterprise > personal > project; Cline global skill > project skill; Cline rules use the opposite workspace-over-global rule.[4][8][9]
+4. Assess skill selection, execution, artifact quality and business outcomes separately. Repeated trials and environment-state verification matter more than an agent reporting success.[11]
+5. Measure a balanced portfolio of flow, quality, risk, cost and human experience. DORA now uses five delivery metrics; SPACE explicitly rejects a single productivity metric.[12][24] Adoption counts or accepted code are not causal productivity evidence.
+6. Use comparative pilots, not an imported percentage ROI. Controlled studies have reported substantial speedups and slowdowns in different settings, and METR's newer study explains why selection and concurrent-agent timing make current effects difficult to estimate.[16][17][22]
+
+## 3. Compatibility and enforcement matrix
+
+Every capability below is documented upstream, not exercised in Eldorado. A supported client means a particular host, version, model configuration and OS combination that passes local conformance tests; a product brand alone is insufficient.
+
+| Dimension | GitHub Copilot | Claude Code | Cline |
+| --- | --- | --- | --- |
+| Skills and scope | Project `.github/skills`, `.claude/skills`, `.agents/skills`; personal `~/.copilot/skills`, `~/.agents/skills`. About page includes cloud agent, code review, CLI, app, VS Code and JetBrains agent mode.[2] | Common format plus invocation controls, subagents and dynamic context extensions. Native project/personal `.claude/skills`; enterprise and nested scopes also documented.[4] | Workspace `.cline/skills`, global `~/.cline/skills`; explicit invocation and enabled-by-default toggles documented.[8] |
+| Always-on instructions | Repository-wide `.github/copilot-instructions.md`, path-specific files and agent instructions have surface-dependent support. Do not apply the GitHub.com hierarchy to every IDE.[3] | `CLAUDE.md` and related discovered memory files are concatenated into context, not overriding configuration files.[5] | Workspace/global rules combine, with workspace taking precedence for conflicts; toggles may disable rules.[9] |
+| Name collision / precedence | Inspected docs establish instruction precedence on GitHub.com, not a universal skill-name collision order. Test duplicate personal/project skills before approval.[3] | Enterprise skill over personal over project for same-name collisions; distinct from memory-file concatenation.[4][5] | Global skill over project skill, but workspace rules over global rules. Do not conflate them.[8][9] |
+| Trust and execution | GitHub warns shared skills are not verified, may contain injection or malicious scripts, and shell preapproval can remove a protective confirmation.[26] | Trust/permission dialogs and sandbox capability exist, but approved shell access can exceed working directory; unattended sessions differ.[7] | User toggles do not establish an enterprise security boundary. Current hook landing page redirects to SDK plugin documentation, which describes executable plugins.[8][10][23] |
+| Hooks and enforcement | No universal Copilot hook parity established by inspected sources. Do not promise a portable hook API or use absence of research as proof none exists. | PreToolUse supports blocking, but command/http/MCP timeout does NOT block automatically; plain exit 1 is generally nonblocking without valid decision JSON. Agent SDK callbacks differ.[6] | SDK documents lifecycle hooks and explicit `fail_closed` policy. This is not proof every IDE/CLI installation exposes identical configuration or failure semantics.[23] |
+| Distribution | Repository content can travel with code. `gh skill` public preview documents installation, source provenance, `@SHA` and `--pin`; pinned skills are skipped in updates.[26] | Repository/managed deployment plus client-specific facilities. Use an external immutable bundle manifest; do not presume Copilot's installer or plugin semantics apply unchanged.[4] | Commit workspace skill directories for team sharing. SDK plugins can come from npm/git/file sources; these require separate software-supply-chain review.[8][23] |
+| Telemetry | Usage API spans multiple surfaces, but rich IDE detail requires telemetry; server-side active-user recovery does not fill missing dimensional data.[19] | OTel supports configured usage/cost/tool export; detailed skill names/tool arguments require explicit collection settings. Version-specific behavior is substantial.[20] | SDK lifecycle hooks provide instrumentation building blocks, not proof of a ready-made comparable enterprise skill dashboard or retention contract.[23] |
+| Portable guarantee | Readable common content only; neither skill selection nor correct execution follows from installation.[3][26] | Shared format does not standardize extension behavior or guarantee instruction adherence.[4][5] | Shared content and client behavior remain different; toggles and name shadowing affect what executes.[8][9] |
+
+### Version pinning, updates, rollback and stale laptops — recommended operational contract
+
+These are recommended design choices, not features claimed to exist universally:
+
+- Maintain one reviewed registry with stable skill IDs, human owner/reviewer, purpose, risk tier, provenance/license, immutable source revision, artifact digest, dependencies, supported client/OS/version range, evaluation revision/results, approval record, last review date, deprecation state, migration guide and rollback digest. Keep client-specific invocation and tool configuration outside the portable core, generated and tested as adapters.
+- Release a manifest mapping stable IDs to exact immutable content and adapter revisions. Pin full commit/digest, not a mutable branch or tag alone. GitHub's preview installer provides pin/provenance mechanisms, but private Gitea compatibility and availability on Eldorado laptops have not been established.[26] A controlled vendored bundle is the simpler cross-client recommendation until proven otherwise.
+- Promotion: author branch → independent review → format/resource validation → script/dependency/security checks → per-client behavioral and adversarial evals → canary → approval → distribution. Never permit a proposed skill to approve itself or edit its own promotion checks without independent review.
+- Updates: compare signed/verified manifest and content digest; show release notes; stage atomically; restart/reload affected sessions where required by the client. Test whether already-open sessions retain old instructions. Do not infer reload from files changing.
+- Rollback: restore a previously approved manifest AND adapter/dependency versions, revoke the unsafe revision centrally, expire affected sessions, rerun a smoke test and read back effective version. Reverting a file does not undo commands already executed or leaked data.
+- Offline laptop: a verified cached bundle can support permitted low-risk local drafting, provided required local model/tool dependencies actually work offline. Local files being present do not mean cloud-backed inference is offline-capable. No claim of native offline inference or guaranteed durable telemetry buffering is made for any client.
+- Stale/unsupported bundle: show a visible warning and prevent high-risk centrally mediated actions; allow explicitly approved low-risk work only. Recommended grace periods are risk decisions to settle, not fabricated vendor defaults. On reconnect, revalidate revocation and support status before obtaining privileged credentials or submitting gated delivery actions.
+- Laptop evidence is fallible and may be altered by its owner. CI should verify repository-delivered manifest/content and actual output, but cannot prove which private prompt or skill a laptop truly used. Treat client attestations as advisory unless an independently verified device/runtime trust mechanism exists. Central enforcement must still protect work with no attestation.
+- Avoid conflicting names and broad user-directory installation; prefix governed IDs and detect shadowing. Keep an explicit exception route with owner, scope, justification, expiry and compensating checks. An exception must not quietly disable protected-release controls.
+
+## 4. Conflicts, weak evidence and what not to conclude
+
+| Claim / conflict | Classification and resolution |
+| --- | --- |
+| “Project skills universally override user skills.” | Contradicted as a universal claim. Agent Skills implementation guide says this; current Claude and Cline product docs specify personal/global priority for skill collisions. Weight actual client documentation for that client, then verify behavior locally.[21][4][8] |
+| “GitHub organization instructions enforce company policy everywhere.” | Unsupported. GitHub documents limited surfaces, personal/repository precedence, nondeterminism and head-branch review instructions. Use repository ownership and independently protected gates instead.[3] |
+| “All clients support the same skills/hooks/telemetry.” | Unsupported. Standard content exists, but scope, extensions, hooks and instrumentation differ. Cline's hook page now points to SDK plugins; do not repeat historical hook file recipes without version testing.[1][10][23] |
+| “Copilot supports JetBrains skills.” | About-skills page explicitly includes JetBrains; adding-skills overview currently omits it. This is documentation asymmetry, not sufficient evidence to declare unsupported. Verify the exact target host/version during adapter qualification.[2][26] |
+| “Hook failure blocks dangerous work.” | Not generically true. Claude documents nonblocking timeout and exit-code cases; Cline SDK offers an explicit fail-closed setting. Test timeout, crash and malformed output separately.[6][23] |
+| “AI makes developers 55.8% faster.” | Supported paraphrase only for Peng et al.'s controlled JavaScript HTTP-server task; abstract inspected. Not a software-organization forecast.[17] |
+| “AI makes experienced developers 19% slower today.” | Misleading temporal/generalized claim. METR's early-2025 RCT involved 16 developers and 246 issues; the authors now label those results outdated as current capability evidence.[16] |
+| “METR's newer results prove a universal speedup.” | Unsupported. Follow-up raw estimates suggest shorter task time, but intervals include no effect and authors warn participant/task selection and parallel-agent timing compromise the estimate.[22] |
+| “Independent study proves a 21% Eldorado improvement.” | Unsupported. Paradis et al.'s abstract reports approximately 21% shorter task time for 96 Google engineers, with a large interval and explicit ecosystem/generalization caveats. Primary abstract, not full methods, inspected.[18] |
+| “Agent says done / skill was loaded, therefore compliant.” | Unsupported. Outcome must be inspected in the environment; selection, reading, following, tool execution and outcome are separate observations.[11] |
+
+Research hygiene correction: the initial URL seed for arXiv `2410.12944` was mistakenly labelled as a Cui field-experiments source. The retrieved body is Paradis et al.'s Google RCT; `sources.json` records the correct identity. No Cui statistic is used. Likewise, ACM SPACE returned HTTP 403; an author-hosted Microsoft Research publication summary was retrieved instead. These are bounded acquisition limitations, not invented evidence.
+
+## 5. Target coordination, authority and organization mapping
+
+Recommended trust flow: people and approved work records → one logical SDLC coordinator → task-scoped local-agent work proposals → repository review → independently administered CI/artifact evidence → authorized human release decision → release service. The coordinator should maintain workflow state, dependencies, requested evidence, retries and escalation. It should not be sole author, evaluator and approver, nor hold unrestricted production credentials.
+
+Use durable IDs, idempotent task transitions and bounded retry budgets so multiple coordinator replicas cannot publish twice. Keep a human takeover and deterministic queue/authorization path if inference is unavailable. Project-level context sharing must be deliberately scoped; shared coordination is not permission to mix secrets, HR records, customer disputes and source code.
+
+| Existing owner | Recommended accountability, without creating teams |
+| --- | --- |
+| Product Management | Choose outcome hypotheses and eligible work; accept product value and prioritize pilots rather than maximize AI usage. |
+| Product Design | Validate usability/accessibility and customer research handling; review generated experience changes and design-task skills. |
+| Product Engineering | Own code, practical skill authoring and local-agent use; review generated changes and remain responsible for maintainability. |
+| Platform & IT | Own bundle delivery, device/client support, identity, workload isolation, central CI/release integration, telemetry transport and emergency revocation. |
+| Architecture & Security | Own trust boundaries, data/permission risk classification, supply-chain approval requirements and security exceptions; review privileged skill proposals. |
+| Quality Engineering | Own independent regression/adversarial suites, quality rubrics, gate evidence, failure sampling and evaluation reproducibility. |
+| Data & AI | Coordinate the skills catalog and logical SDLC-agent evaluation with the documented AI Architect function; own statistical analysis and model/client experiment design. |
+| Operations Squad | Supply sanitized service cases and operational acceptance; own human decisions on disputes, refunds, fraud and customer communications, not the coordinator. |
+| Marketing Squad | Own brand/claim review, campaign approval and content rights; start with drafting/review skills rather than autonomous spending or publication. |
+| Finance & Accounting Squad | Validate cost allocation and investment evidence; retain payout, accounting and financial approval segregation. |
+| People & Administration Squad | Own training, onboarding, acceptable use and privacy-sensitive adoption feedback, with Platform & IT on access lifecycle; no individual developer ranking. |
+
+Department leaders retain business accountability. Staffing capacity, named approvers and deputies need human confirmation; the operating-model role description is not evidence that every position is filled. For synthesis, map recommendations to existing responsibilities rather than publish uncertain staffing as fact.
+
+### Threat and failure controls
+
+NIST supplies a voluntary lifecycle governance framework and GenAI companion, not certification; the RMF core organizes work around govern, map, measure and manage.[13][14][25]
+
+OWASP identifies external-content injection and recommends least privilege, human approval and adversarial testing.[15]
+
+Recommended controls by failure mode:
+
+- Malicious skill, script, dependency, MCP server or changed upstream tag: allowlisted source, immutable digest, independent review, license/provenance inventory, restricted network/runtime and no automatic arbitrary installs. A reviewed Markdown file does not make referenced executable code safe.
+- Prompt injection from issues, repository instructions, web pages or tool results: treat as untrusted input; separate data from authority; limit credentials and egress; require independent authorization. GitHub code review's use of PR-head instructions is a concrete reason not to trust AI review as the sole gate.[3][15]
+- Fabricated success, omitted tests, cherry-picked evidence or judge manipulation: verify actual artifact/CI state tied to exact commit and policy revision; keep evaluation checks outside candidate-controlled changes; sample human review.
+- Overbroad local shell permissions: isolate process/OS identity, filesystem, network and secrets. A profile, skill folder or current directory is not containment. Claude's own docs distinguish permission prompts from sandbox controls.[7]
+- Duplicate or looping agent work, runaway spend and unavailable coordinator: task idempotency, bounded retries/time/cost, lease expiry, human recovery and read-only/degraded mode. Never downgrade a release gate because the model or evidence service is unavailable.
+- Model/client/context drift or stale session instructions: version-qualified adapters; requalification on material updates; compaction/long-session tests; version-aware incident analysis.
+- Privacy leakage through telemetry or shared memory: minimal structured events, pseudonymous IDs, restricted retention and access; no raw prompts, secrets or source contents by default. Explicitly review the privacy cost before enabling detailed tool/skill-name export.[20]
+- Kill switch: independently revoke mutation/release credentials and stop scheduling; disable affected revisions and preserve evidence. Sending “stop” to a model is not the security boundary.
+
+## 6. Skill quality, evaluation and lifecycle recommendations
+
+A useful skill must state when to use it, when not to use it, prerequisites, exact steps, expected artifacts, verification, failure handling and escalation. Keep the portable body small and reference bounded resources. The format specification supports progressive disclosure and recommends concise main files.[1]
+
+Proposed evaluation layers:
+
+1. Static contract: parse metadata; verify stable identity/owner/review date; validate links and resource paths; detect embedded secrets, prohibited dependencies, unsafe commands and unsupported client-only fields.
+2. Selection tests: positive trigger tasks, near misses and negative tasks; report false activation and missed activation separately. A larger catalog should be tested for routing regressions, not presumed better.
+3. Execution tests: run representative sanitized tasks in disposable environments with fixed starting repositories; verify real outputs, not self-reports. Include missing prerequisite, invalid input, tool timeout, denied permission, malformed evidence and interrupted session.
+4. Safety tests: injected repository text, malicious referenced scripts, conflicting global/project skills, user toggle, unsupported version, expired/revoked bundle, offline network, context compaction and stale in-memory version.
+5. Outcome grading: deterministic tests for mechanically checkable constraints; independent human review for product/design/maintainability; model judges only with explicit rubric and human calibration. Record disagreements and judge version.[11]
+6. Comparison: same tasks and conditions for no-skill/current-approved/candidate versions; repeated trials, failure/abandonment retained; separate client/model/skill changes. Report sample size, variability, confidence and task mix, not only a mean pass percentage.[11]
+
+Recommended promotion policy: all mandatory deterministic safety/authorization checks must pass; any observed critical unauthorized action blocks promotion pending investigation. This is a proposed policy, NOT proof of zero residual risk. Quantitative success-rate thresholds should be set after pilot variance and business impact are known, by risk tier; do not invent universally validated percentages. Privileged release/payment/customer-impact workflows need stronger review than read-only documentation assistance.
+
+Lifecycle: proposed → experimental → approved → deprecated → retired, with quarantine available from every active state. Review triggered by incident, tool/model/client change, dependency change, usage feedback or scheduled owner review. Each approved skill needs an owner and backup, change history, support window, migration route and known-good rollback. Deprecation should warn, offer replacement and track consumers before retirement; urgent security revocation overrides convenience. Do not retain unowned skills merely because they remain popular.
+
+Adoption should begin with training on how to inspect results, report failures and refuse unsafe requests. Build examples from actual team workflows; offer office hours and opt-in feedback; record why a skill was rejected. Measure whether people can perform and verify work, not whether they obey a target number of invocations. Avoid automatically promoting agent-written corrections into the governed catalog.
+
+## 7. KPI instrumentation options and recommended choices
+
+### Practical source tiers
+
+A. Start with authoritative repository/CI/deployment/incident events. These can measure delivery outcomes without observing every laptop prompt. No event feed has been inspected here; feasibility must be verified with the current hosting platforms and retention.
+
+B. Add a governed catalog/version inventory and opt-in task-level skill/client declarations. This supplies adoption and support coverage, but declarations are not proof of execution or adherence.
+
+C. Add client adapters where supported: Copilot usage APIs and Claude OTel may help; their fields, licensing, enabled state and missingness differ.[19][20] Cline SDK hooks are an instrumentation option requiring engineering and exact-version qualification, not a proven universal collector.[23]
+
+D. Use short anonymous surveys, work sampling and pilot comparisons for cognitive load, confidence and rework not visible in logs. SPACE's multidimensional premise supports this combination; surveys alone cannot establish time saved.[24][16]
+
+### Candidate measurement contracts for synthesis
+
+These are recommended options, not observed metrics or approved targets. All denominators must use a predeclared eligible population and reporting window; zero denominators produce “not available,” never zero performance.
+
+| Measure | Definition and useful source | Owner / interpretation / missingness |
+| --- | --- | --- |
+| Validated task success | Independently accepted successful tasks / all eligible initiated tasks with matured observation window; count failed/abandoned tasks as nonsuccess and show still-open separately. Task ID + acceptance evidence, not agent message. | Quality Engineering; weekly pilot report. Show task type, sample size and unobserved outcomes separately; exclude cancelled-before-start work by stated rule, not post-hoc cherry-picking. |
+| Skill selection precision / recall | Correct relevant activations / all activations; relevant tasks with activation / all relevant tasks, on a labeled evaluation set. | Data & AI with Quality Engineering; per candidate/client release. Not obtainable from skill-loaded logs without relevance labels. |
+| Supported bundle coverage | Eligible active installations with verified supported revision / eligible active installations inventoried. | Platform & IT; weekly. Unknown/invisible laptops remain unknown and inventory coverage is separately reported; do not treat silence as compliant. |
+| Useful adoption | Distinct eligible participants using an approved skill in an eligible workflow / eligible participants during window, plus qualitative usefulness. | Data & AI and People & Administration Squad; monthly aggregate. Separate declared, observed and inferred usage; suppress small cohorts and never rank people. |
+| Change lead time | Commit-to-production elapsed time per deployed change; report distribution and population. Repository + deployment SHA association. | Platform & IT / Product Engineering; service-level trend. Missing SHA mapping is missing coverage, not instantaneous delivery. DORA definition, not PR-open-to-merge time.[12] |
+| Deployment frequency | Production deployments / stated period, service-scoped. | Platform & IT; report with quality measures. Exclude retries/duplicate events; no incentive to split meaningless deployments.[12] |
+| Change fail rate | Production deployments requiring immediate intervention / all production deployments. | Quality Engineering / Platform & IT; require incident/rollback linkage and intervention definition. Missing incident links limit confidence.[12] |
+| Failed deployment recovery time | Recovery timestamp minus failed-deployment failure timestamp; distribution over relevant failed deployments. | Platform & IT; unresolved failures shown separately, never dropped as if recovered. Not all-incident MTTR.[12] |
+| Deployment rework rate | Unplanned incident-driven production deployments / all production deployments. | Platform & IT; preserve planned/unplanned classification and incident link. DORA fifth metric, distinct from change fail rate.[12] |
+| Escaped quality issues | Severity-stratified post-acceptance defects / accepted changes with completed follow-up, plus absolute incident counts. | Quality Engineering; agreed maturation window. Do not compare immature and mature cohorts or imply every defect was AI-caused. |
+| Safety / policy violations | Confirmed prohibited actions or attempted bypasses / evaluated eligible runs, with severe incidents also as absolute counts. | Architecture & Security; immediate incident response and periodic trend. Separate detected attempts, blocked attempts and actual effects; zero observed is not proof of no risk. |
+| Cost per accepted outcome | Allocated license + model/tool/compute + human review/rework costs / independently accepted outcomes; include costs of failed/abandoned attempts in numerator. | Finance & Accounting Squad; monthly. Show uncertain allocation and missing spend; do not call model tokens the whole cost. |
+| Human experience | Aggregate survey distribution for cognitive load, confidence in verification and perceived usefulness, with response count / invited eligible population. | People & Administration Squad / Data & AI; periodic. Self-selection and perception bias explicit; no employee surveillance dashboard. |
+| Maintenance health | Approved skills within review window / active approved skills; separately count ownerless, deprecated-in-use and revoked-in-use revisions. | Data & AI / Platform & IT; catalog release and periodic review. Review stamp alone is not quality evidence. |
+
+Recommended minimal event schema: `event_id`, `schema_version`, `event_type`, `occurred_at`, `received_at`, `producer`, `task_id`, `attempt_id`, `project_id`, `pseudonymous_actor_id` where necessary, `client/host/version`, `model_id/version_if_exposed`, `skill_id/revision/digest`, `adapter_revision`, `policy_revision`, `repo_commit`, `outcome`, `reason_code`, `evidence_ref`, `cost_amount/currency/basis`, `measurement_origin` (server/client/self-report), and `consent_or_collection_basis`. Fields can be nullable with reason; do not fabricate a model revision hidden by a provider.
+
+Recommended ingestion rules: deduplicate by producer + event_id; model retries as attempts, not extra completed tasks; preserve late events and recompute versioned aggregates; use server receipt and skew checks rather than trusting laptop clocks blindly. A lost terminal event is unknown until reconciled, not automatically success or abandonment. Distinguish paused, failed, abandoned, cancelled-before-start and accepted. A skill-loaded event records loading only. A task can involve multiple skills/versions and agents; avoid attributing the entire outcome or labor time to every invocation.
+
+Suggested privacy starting point for human approval: short raw structured-event retention (for example 30 days), longer aggregate trends (for example 12 months), no raw prompts/code/screens by default, role-limited incident evidence, and explicit deletion/access process. These durations are policy proposals, not legal requirements or existing Eldorado settings. Confirm employment/privacy constraints with responsible owners before collection.
+
+Pilot comparison recommendation: define task classes and quality acceptance first; collect a prospective baseline and eligible population; compare matched or randomized cohorts when ethical/practical; record concurrent process/client/model changes. Keep quality and risk guardrails fixed. Report descriptive trends separately from causal estimates. Measure elapsed lead time and human effort separately because parallel agents break the assumption that elapsed time equals labor saved; METR's follow-up explicitly raises this issue.[22]
+
+For executable downstream examples, use clearly synthetic fixtures covering duplicates, retries, unknown outcomes, multiple skills, zero denominator, immature quality window and late deployment/incident events. Assert exact expected numerator/denominator and units. Do not display synthetic values as Eldorado baseline data.
+
+## 8. Recommended sequence and evidence gates
+
+- Foundation: inventory actual clients, repositories, data sensitivity, available events and accountable owners. Exit only with a supported pilot boundary and explicit forbidden actions, not with a catalog full of untested skills.
+- Low-risk pilot: small set of useful read-only/drafting/test-assistance skills; reviewed immutable bundles; exact-client smoke and adversarial tests; human review and failure reporting. Exit with reproducible quality evidence and usable measurement coverage.
+- Governed distribution: add version-aware adapters, onboarding, staged upgrades, rollback/revocation drills and exception expiry. Exit when stale/offline/unsupported clients cannot bypass central privileged gates.
+- Logical SDLC coordination: coordinator starts by observing and assembling evidence, then proposing work and routing approvals. Expand mutation only after idempotency, separation of duties, scoped credentials, outage recovery and kill-switch tests pass.
+- Broader departmental use: Operations, Marketing, Finance & Accounting and HR & Administration adopt domain-specific skills with their own human decisions, data boundaries and outcome measures. Do not copy coding autonomy into payments, personnel decisions or disputes.
+
+No invented rollout dates, budget, staffing capacity or required improvement percentage. Scale only when quality, risk and cost evidence support it; stop or narrow scope when benefits are not demonstrated.
+
+## 9. Source coverage and unresolved questions
+
+Coverage: 26 retrieved primary-source records with 50 literal evidence passages. Includes Agent Skills specification and integration guidance; GitHub support/instructions/install/metrics; Claude skills/memory/hooks/security/monitoring; Cline skills/rules/hooks and linked SDK plugins; agent-evaluation methodology; current DORA definitions; author-hosted SPACE summary; NIST framework/core/GenAI profile landing page; OWASP prompt injection; two primary research abstracts plus METR historical study and 2026 follow-up. This is substantive source-body review, but not a systematic literature review, independent replication, legal assessment or live client qualification. Full PDFs for the two arXiv papers and NIST GenAI profile were not reviewed; claims are limited accordingly. ACM's 403 is recorded and resolved only to the author-hosted summary, not bypassed or silently called full text.
+
+Open decisions/evidence needed before implementation:
+
+1. Which actual client hosts, versions, models, OSs, subscriptions and managed-device controls are in use? What is the allowed support window?
+2. Which repository/CI/release systems and protected-branch controls are authoritative? Can required checks and policy definitions be altered by a candidate PR or bypassed by administrators?
+3. Who fills each approving/operating function and who provides cover? What pilot capacity is available? The documented organization does not establish personnel availability.
+4. What data may reach each model provider or telemetry endpoint; what retention/training/region and contractual terms apply? No provider contract was inspected.
+5. Which low-risk workflows have enough representative tasks and independent quality labels? What is the actual eligible population and baseline coverage?
+6. What timeout, stale-bundle grace, critical-risk rejection and emergency-revocation policies will owners approve? Can laptop access be independently revoked?
+7. Does the chosen distributor support private Gitea securely, and can every supported client report effective skill/adapter versions without collecting sensitive content?
+8. What causal claims, if any, can the proposed pilot design justify given self-selection, learning, task mix and parallel work?
+9. Which detailed Cline/Copilot hooks and offline/resume behavior exist in the precise deployed builds? Sources here do not establish cross-client equivalence.
+
+Synthesis handoff: keep this research trail outside reader-facing portal prose. Use ordinary operating-model language for the strategy, preserve all existing teams and leadership uncertainty, visibly distinguish target maturity from current state, and retain recommendation/source mapping internally. No portal publication is part of this research card.
+
+## Sources
+
+[1] https://agentskills.io/specification — Agent Skills specification
+[2] https://docs.github.com/en/copilot/concepts/agents/about-agent-skills — Copilot Agent Skills
+[3] https://docs.github.com/en/copilot/concepts/prompting/response-customization — Copilot custom instructions
+[4] https://code.claude.com/docs/en/skills — Claude Code skills
+[5] https://code.claude.com/docs/en/memory — Claude Code memory
+[6] https://code.claude.com/docs/en/hooks — Claude Code hooks
+[7] https://code.claude.com/docs/en/security — Claude Code security
+[8] https://docs.cline.bot/customization/skills — Cline skills
+[9] https://docs.cline.bot/customization/cline-rules — Cline rules
+[10] https://docs.cline.bot/customization/hooks — Cline hooks
+[11] https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents — Demystifying evals for AI agents
+[12] https://dora.dev/guides/dora-metrics — DORA software delivery metrics
+[13] https://www.nist.gov/itl/ai-risk-management-framework — NIST AI RMF
+[14] https://www.nist.gov/publications/artificial-intelligence-risk-management-framework-generative-artificial-intelligence — NIST Generative AI Profile
+[15] https://genai.owasp.org/llmrisk/llm01-prompt-injection — OWASP prompt injection
+[16] https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study — Experienced developer RCT
+[17] https://arxiv.org/abs/2302.06590 — AI developer productivity experiment
+[18] https://arxiv.org/abs/2410.12944 — Field experiments in software development
+[19] https://docs.github.com/en/copilot/concepts/billing-and-usage/copilot-usage-metrics/copilot-metrics — Copilot metrics concepts
+[20] https://code.claude.com/docs/en/monitoring-usage — Claude Code monitoring
+[21] https://agentskills.io/client-implementation/adding-skills-support — Agent Skills security
+[22] https://metr.org/blog/2026-02-24-uplift-update — METR productivity update 2026
+[23] https://docs.cline.bot/sdk/plugins — Cline SDK plugins
+[24] https://www.microsoft.com/en-us/research/publication/the-space-of-developer-productivity-theres-more-to-it-than-you-think — SPACE research publication
+[25] https://airc.nist.gov/airmf-resources/airmf/5-sec-core — NIST AI RMF Core
+[26] https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/add-skills — Copilot adding skills

research/ai-adoption/sources.json

@@ -0,0 +1,564 @@
+[
+  {
+    "id": 1,
+    "title": "Agent Skills specification",
+    "url": "https://agentskills.io/specification",
+    "publisher": "Agent Skills",
+    "retrieved_at": "2026-10-04T10:27:53.189577+00:00",
+    "claims": [
+      {
+        "claim": "The specification defines a skill directory with SKILL.md, not a universal deployment or enforcement service.",
+        "evidence": "A skill is a directory containing, at minimum, a SKILL.md file:",
+        "limitations": "Format compatibility does not certify discovery, precedence, tool permissions, safety, or instruction compliance."
+      },
+      {
+        "claim": "allowed-tools is experimental in the common specification.",
+        "evidence": "allowed-toolsNoSpace-separated string of pre-approved tools the skill may use. (Experimental)",
+        "limitations": "Format compatibility does not certify discovery, precedence, tool permissions, safety, or instruction compliance."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/01.txt",
+    "body_sha256": "0913e84055bc7eb05649aa49123a783dc1a413e4c31d0861f9ac367849c7b00e",
+    "evidence_type": "primary source body"
+  },
+  {
+    "id": 2,
+    "title": "Copilot Agent Skills",
+    "url": "https://docs.github.com/en/copilot/concepts/agents/about-agent-skills",
+    "publisher": "GitHub",
+    "retrieved_at": "2026-10-04T10:27:53.333904+00:00",
+    "claims": [
+      {
+        "claim": "GitHub documents skill support across specified Copilot surfaces, not all modes indiscriminately.",
+        "evidence": "Agent skills work with Copilot cloud agent, Copilot code review, the GitHub Copilot CLI, the GitHub Copilot app, and agent mode in Visual Studio Code and JetBrains IDEs.",
+        "limitations": "Vendor documentation, not an Eldorado installation test. Separate adding-skills page omits JetBrains in its overview; validate exact host/version."
+      },
+      {
+        "claim": "Copilot documents multiple project skill paths.",
+        "evidence": "Project skills, stored in your repository (.github/skills, .claude/skills, or .agents/skills)",
+        "limitations": "Vendor documentation, not an Eldorado installation test. Separate adding-skills page omits JetBrains in its overview; validate exact host/version."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/02.txt",
+    "body_sha256": "26c86bc2afa4813c46361429f015f687164a69f39030fa05dbc1f513a04c0ca3",
+    "evidence_type": "primary source body"
+  },
+  {
+    "id": 3,
+    "title": "Copilot custom instructions",
+    "url": "https://docs.github.com/en/copilot/concepts/prompting/response-customization",
+    "publisher": "GitHub",
+    "retrieved_at": "2026-10-04T10:27:53.960265+00:00",
+    "claims": [
+      {
+        "claim": "GitHub explicitly warns that custom-instruction following is nondeterministic.",
+        "evidence": "Due to the non-deterministic nature of AI, Copilot may not always follow your custom instructions in exactly the same way every time they are used.",
+        "limitations": "Instruction precedence is surface-specific and is not enforceable authorization. Head-branch instructions create a review trust risk."
+      },
+      {
+        "claim": "The GitHub.com instruction hierarchy prioritizes personal over repository over organization instructions.",
+        "evidence": "Multiple types of custom instructions can apply to a request sent to Copilot. Personal instructions take the highest priority. Repository instructions come next, and then organization instructions are prioritized last. However, all sets of relevant instructions are provided to Copilot.",
+        "limitations": "Instruction precedence is surface-specific and is not enforceable authorization. Head-branch instructions create a review trust risk."
+      },
+      {
+        "claim": "Copilot review reads instructions and skills from the PR head branch.",
+        "evidence": "When reviewing a pull request, Copilot reads repository custom instructions, agent instructions, and agent skills from the head branch (the branch with your changes), not the base branch. For example, when merging my-feature-branch into main, Copilot uses the instructions and skills in my-feature-branch, so you can test changes to them in the same pull request without merging them first.",
+        "limitations": "Instruction precedence is surface-specific and is not enforceable authorization. Head-branch instructions create a review trust risk."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/03.txt",
+    "body_sha256": "1c2c190052653b8baad1478dc53b7a0657b741be0dbb0ef202b3f503c6b3379c",
+    "evidence_type": "primary source body"
+  },
+  {
+    "id": 4,
+    "title": "Claude Code skills",
+    "url": "https://code.claude.com/docs/en/skills",
+    "publisher": "Anthropic",
+    "retrieved_at": "2026-10-04T10:27:53.088978+00:00",
+    "claims": [
+      {
+        "claim": "Claude skill name collisions prioritize enterprise over personal over project.",
+        "evidence": "Two of enterprise, personal, and projectEnterprise over personal, and personal over project. With deploy in both ~/.claude/skills/ and the project’s .claude/skills/, /deploy runs the personal one",
+        "limitations": "Vendor extensions and changing versions prevent assuming cross-client parity. No local client exercised."
+      },
+      {
+        "claim": "Claude extends the common skill format with client-specific functionality.",
+        "evidence": "Claude Code skills follow the Agent Skills open standard, which works across multiple AI tools. Claude Code extends the standard with additional features like invocation control, subagent execution, and dynamic context injection. See Using skill frontmatter outside Claude Code for which frontmatter fields are part of the standard and which are Claude Code extensions.",
+        "limitations": "Vendor extensions and changing versions prevent assuming cross-client parity. No local client exercised."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/04.txt",
+    "body_sha256": "4ac3de187f2ba050da149e1bea3364a959366be03963e7a76dc9f9041bdb4e1f",
+    "evidence_type": "primary source body"
+  },
+  {
+    "id": 5,
+    "title": "Claude Code memory",
+    "url": "https://code.claude.com/docs/en/memory",
+    "publisher": "Anthropic",
+    "retrieved_at": "2026-10-04T10:27:52.994293+00:00",
+    "claims": [
+      {
+        "claim": "Claude memory instructions are context, not enforced configuration.",
+        "evidence": "Claude Code has two complementary memory systems. Both are loaded at the start of every conversation. Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead. The more specific and concise your instructions, the more consistently Claude follows them.",
+        "limitations": "Context order does not establish deterministic behavior; conflicting prose may still produce arbitrary choices."
+      },
+      {
+        "claim": "Claude concatenates discovered memory files rather than treating them as override-only configuration.",
+        "evidence": "All discovered files are concatenated into context rather than overriding each other. Across the directory tree, content is ordered from the filesystem root down to your working directory. For the foo/bar/ example, foo/CLAUDE.md appears in context before foo/bar/CLAUDE.md, so instructions closer to where you launched Claude are read last. Within each directory, CLAUDE.local.md is appended after CLAUDE.md, so your personal notes are the last thing Claude reads at that level.",
+        "limitations": "Context order does not establish deterministic behavior; conflicting prose may still produce arbitrary choices."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/05.txt",
+    "body_sha256": "b19869f25886f95f8d93cec941482cbf9472b507ab8d643b446b1450b915e0df",
+    "evidence_type": "primary source body"
+  },
+  {
+    "id": 6,
+    "title": "Claude Code hooks",
+    "url": "https://code.claude.com/docs/en/hooks",
+    "publisher": "Anthropic",
+    "retrieved_at": "2026-10-04T10:27:53.059984+00:00",
+    "claims": [
+      {
+        "claim": "Claude PreToolUse command/http/MCP hook timeout is not fail-closed.",
+        "evidence": "A timed-out command, http, or mcp_tool hook doesn’t block the tool call. The call continues through the normal permission flow, so don’t count on a stalled hook to act as a gate.",
+        "limitations": "Event and hook-family distinctions matter; no universal fail-closed promise. No hook was installed or tested here."
+      },
+      {
+        "claim": "A conventional exit code 1 alone does not reliably block most Claude hook events.",
+        "evidence": "For most hook events, exit code 2 is the only exit code that blocks through the code alone. Without valid JSON on stdout, Claude Code treats exit code 1 as a non-blocking error and proceeds with the action, even though 1 is the conventional Unix failure code. If your hook is meant to enforce a policy, use exit 2. The worktree events differ: any non-zero exit code from WorktreeCreate aborts worktree creation, and any non-zero exit code from WorktreeRemove makes worktree removal fail if the directory still exists afterward.",
+        "limitations": "Event and hook-family distinctions matter; no universal fail-closed promise. No hook was installed or tested here."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/06.txt",
+    "body_sha256": "ae1919a5b06aa6d4a213bfafcaab1d2473f0b89d53b9fcc35358a19ab9ca3e5d",
+    "evidence_type": "primary source body"
+  },
+  {
+    "id": 7,
+    "title": "Claude Code security",
+    "url": "https://code.claude.com/docs/en/security",
+    "publisher": "Anthropic",
+    "retrieved_at": "2026-10-04T10:27:52.953904+00:00",
+    "claims": [
+      {
+        "claim": "Claude working-directory approval is not OS-level containment.",
+        "evidence": "Working directory boundary: In Manual mode, Claude Code asks you before its file tools read or write outside the folder where it was started and its subfolders. The boundary is a permission prompt, so a Bash command you approve can still write anywhere your user account can",
+        "limitations": "Vendor capability is not evidence the sandbox is enabled; approved shell commands inherit actual OS authority."
+      },
+      {
+        "claim": "OS-level Bash restrictions require sandboxing.",
+        "evidence": "To restrict Bash commands at the operating system level, turn on sandboxing",
+        "limitations": "Vendor capability is not evidence the sandbox is enabled; approved shell commands inherit actual OS authority."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/07.txt",
+    "body_sha256": "a8a2ad7d077347f1d3ea43549b0be1070e03c7737647f73ef40035d5dafb5f40",
+    "evidence_type": "primary source body"
+  },
+  {
+    "id": 8,
+    "title": "Cline skills",
+    "url": "https://docs.cline.bot/customization/skills",
+    "publisher": "Cline",
+    "retrieved_at": "2026-10-04T10:27:53.250798+00:00",
+    "claims": [
+      {
+        "claim": "Cline global skill overrides same-name project skill.",
+        "evidence": "When a global skill and project skill have the same name, the global skill takes precedence. This lets you keep general-purpose skills globally while using project-specific skills in .cline/skills/ so the whole team can use them.",
+        "limitations": "Current docs disagree with Agent Skills guide generalization. Exact installed Cline version remains unknown."
+      },
+      {
+        "claim": "Discovered Cline skills have user-controlled enable/disable toggles.",
+        "evidence": "Every skill has a toggle to enable or disable it. This lets you control which skills are active without deleting the skill directory. Skills are enabled by default when discovered.",
+        "limitations": "Current docs disagree with Agent Skills guide generalization. Exact installed Cline version remains unknown."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/08.txt",
+    "body_sha256": "38e6af22c7e9f78e90e899a7bd285e6556bfd64197fbc3f7cf279cc9ff29d416",
+    "evidence_type": "primary source body"
+  },
+  {
+    "id": 9,
+    "title": "Cline rules",
+    "url": "https://docs.cline.bot/customization/cline-rules",
+    "publisher": "Cline",
+    "retrieved_at": "2026-10-04T10:27:53.308915+00:00",
+    "claims": [
+      {
+        "claim": "Cline workspace rules override conflicting global rules, unlike skill name precedence.",
+        "evidence": "When both workspace and global rules exist, Cline combines them. Workspace rules take precedence when they conflict with global rules. See Storage Locations for more guidance.",
+        "limitations": "Rule precedence is not skill precedence; both are guidance and can be toggled."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/09.txt",
+    "body_sha256": "c1a2353c024491a42961e5ea171c341c66bbed2647464d200bf90fdbaa8a48e3",
+    "evidence_type": "primary source body"
+  },
+  {
+    "id": 10,
+    "title": "Cline hooks",
+    "url": "https://docs.cline.bot/customization/hooks",
+    "publisher": "Cline",
+    "retrieved_at": "2026-10-04T10:27:53.370475+00:00",
+    "claims": [
+      {
+        "claim": "Cline hooks landing page delegates details to SDK plugins.",
+        "evidence": "See details under SDK Plugins page.",
+        "limitations": "Landing page alone proves no event schema or IDE compatibility. SDK page was followed separately."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/10.txt",
+    "body_sha256": "2ebd8cd1c0b11fec466a3b577971382d2c4ec1f9911679b10100029e9b3be095",
+    "evidence_type": "primary source body"
+  },
+  {
+    "id": 11,
+    "title": "Demystifying evals for AI agents",
+    "url": "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents",
+    "publisher": "Anthropic",
+    "retrieved_at": "2026-10-04T10:27:53.451618+00:00",
+    "claims": [
+      {
+        "claim": "Repeated trials are needed for variable agent outputs.",
+        "evidence": "Each attempt at a task is a trial. Because model outputs vary between runs, we run multiple trials to produce more consistent results.",
+        "limitations": "Vendor-authored methodology and examples, not independent proof of any skill gain or target threshold."
+      },
+      {
+        "claim": "Agent outcome evaluation must inspect environment state rather than trust claimed completion.",
+        "evidence": "The outcome is the final state in the environment at the end of the trial. A flight-booking agent might say “Your flight has been booked” at the end of the transcript, but the outcome is whether a reservation exists in the environment’s SQL database.",
+        "limitations": "Vendor-authored methodology and examples, not independent proof of any skill gain or target threshold."
+      },
+      {
+        "claim": "Agent evals combine code, model and human graders.",
+        "evidence": "Agent evaluations typically combine three types of graders: code-based, model-based, and human. Each grader evaluates some portion of either the transcript or the outcome. An essential component of effective evaluation design is to choose the right graders for the job.",
+        "limitations": "Vendor-authored methodology and examples, not independent proof of any skill gain or target threshold."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/11.txt",
+    "body_sha256": "7940a33d8e19ff68aac5e3c095e0fa771565a4b2416e8a781e9ed02d55668a12",
+    "evidence_type": "primary source body"
+  },
+  {
+    "id": 12,
+    "title": "DORA software delivery metrics",
+    "url": "https://dora.dev/guides/dora-metrics/",
+    "publisher": "DORA",
+    "retrieved_at": "2026-10-04T10:27:53.335018+00:00",
+    "claims": [
+      {
+        "claim": "DORA now documents five software-delivery performance metrics.",
+        "evidence": "These metrics have evolved alongside the technology landscape: shifting from the original four keys to the current five-metric model. To understand the research behind changes like the move from MTTR to Failed Deployment Recovery Time, read A history of DORA’s software delivery metrics.",
+        "limitations": "Service/team outcome measures, not causal AI-effect estimates or individual productivity scores."
+      },
+      {
+        "claim": "DORA change lead time runs from commit to production deployment.",
+        "evidence": "Change lead time: The amount of time it takes for a change to go from committed to version control to deployed in production.",
+        "limitations": "Service/team outcome measures, not causal AI-effect estimates or individual productivity scores."
+      },
+      {
+        "claim": "DORA deployment rework measures unplanned incident-driven deployments.",
+        "evidence": "Deployment rework rate: The ratio of deployments that are unplanned but happen as a result of an incident in production.",
+        "limitations": "Service/team outcome measures, not causal AI-effect estimates or individual productivity scores."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/12.txt",
+    "body_sha256": "0535efe22d238f38d1de5ec655efeb44a313e59f8a71085e902bde5c7a693cb9",
+    "evidence_type": "primary source body"
+  },
+  {
+    "id": 13,
+    "title": "NIST AI RMF",
+    "url": "https://www.nist.gov/itl/ai-risk-management-framework",
+    "publisher": "NIST",
+    "retrieved_at": "2026-10-04T10:27:53.731461+00:00",
+    "claims": [
+      {
+        "claim": "NIST AI RMF is voluntary guidance for trustworthiness across the AI lifecycle.",
+        "evidence": "Led by the Information Technology Laboratory (ITL) AI Program, and in collaboration with the private and public sectors, NIST has developed a framework to better manage risks to individuals, organizations, and society associated with artificial intelligence (AI). The NIST AI Risk Management Framework (AI RMF) is intended for voluntary use and to improve the ability to incorporate trustworthiness considerations into the design, development, use, and evaluation of AI products, services, and systems.",
+        "limitations": "Voluntary framework, not certification, legal advice, or evidence of Eldorado compliance."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/14.txt",
+    "body_sha256": "2fed4e9811f05579384a23b9c3b81600ddf0f011fc4cfe638352a817f91ed603",
+    "evidence_type": "primary source body"
+  },
+  {
+    "id": 14,
+    "title": "NIST Generative AI Profile",
+    "url": "https://www.nist.gov/publications/artificial-intelligence-risk-management-framework-generative-artificial-intelligence",
+    "publisher": "NIST",
+    "retrieved_at": "2026-10-04T10:27:53.743664+00:00",
+    "claims": [
+      {
+        "claim": "NIST GenAI profile is a cross-sectoral companion to AI RMF.",
+        "evidence": "This document is a cross-sectoral profile of and companion resource for the AI Risk Management Framework (AI RMF 1.0) for Generative AI, pursuant to President Biden's Executive Order (EO) 14110 on Safe, Secure, and Trustworthy Artificial Intelligence. The AI RMF was released in January 2023, and is intended for voluntary use and to improve the ability of organizations to incorporate trustworthiness considerations into the design, development, use, and evaluation of AI products, services, and systems.",
+        "limitations": "Publication landing-page abstract inspected; full PDF not read. Do not attribute detailed risk taxonomy to this excerpt."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/15.txt",
+    "body_sha256": "7998580f4dc83770568dc361ecae1d46e1d652a2df12a278263b88de6cbfb624",
+    "evidence_type": "primary source body"
+  },
+  {
+    "id": 15,
+    "title": "OWASP prompt injection",
+    "url": "https://genai.owasp.org/llmrisk/llm01-prompt-injection/",
+    "publisher": "OWASP",
+    "retrieved_at": "2026-10-04T10:27:53.529810+00:00",
+    "claims": [
+      {
+        "claim": "External sources can carry prompt injections.",
+        "evidence": "Indirect prompt injections occur when an LLM accepts input from external sources, such as websites or files. The content may have in the external content data that when interpreted by the model, alters the behavior of the model in unintended or unexpected ways. Like direct injections, indirect injections can be either intentional or unintentional.",
+        "limitations": "Mitigations reduce exposure; no guarantee that prompt injection is eliminated."
+      },
+      {
+        "claim": "OWASP recommends least privilege.",
+        "evidence": "Provide the application with its own API tokens for extensible functionality, and handle these functions in code rather than providing them to the model. Restrict the model’s access privileges to the minimum necessary for its intended operations.",
+        "limitations": "Mitigations reduce exposure; no guarantee that prompt injection is eliminated."
+      },
+      {
+        "claim": "OWASP recommends human approval for high-risk operations.",
+        "evidence": "Implement human-in-the-loop controls for privileged operations to prevent unauthorized actions.",
+        "limitations": "Mitigations reduce exposure; no guarantee that prompt injection is eliminated."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/16.txt",
+    "body_sha256": "5bfcc42a422165d0a6b25f28fbff144fc0dec5289f1a672a40203e1d64200c07",
+    "evidence_type": "primary source body"
+  },
+  {
+    "id": 16,
+    "title": "Experienced developer RCT",
+    "url": "https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/",
+    "publisher": "METR",
+    "retrieved_at": "2026-10-04T10:27:54.289507+00:00",
+    "claims": [
+      {
+        "claim": "METR early-2025 RCT found 19% longer task time in its setting.",
+        "evidence": "We conduct a randomized controlled trial (RCT) to understand how early-2025 AI tools affect the productivity of experienced open-source developers working on their own repositories. Surprisingly, we find that when developers use AI tools, they take 19% longer than without—AI makes them slower. We view this result as a snapshot of early-2025 AI capabilities in one relevant setting; as these systems continue to rapidly evolve, we plan on continuing to use this methodology to help estimate AI acceleration from AI R&D automation.",
+        "limitations": "Historical narrow setting, tools from early 2025; superseded as a current estimate by authors. No Eldorado forecast."
+      },
+      {
+        "claim": "Study involved 16 experienced developers and 246 issues on their repositories.",
+        "evidence": "To directly measure the real-world impact of AI tools on software development, we recruited 16 experienced developers from large open-source repositories (averaging 22k+ stars and 1M+ lines of code) that they’ve contributed to for multiple years. Developers provide lists of real issues (246 total) that would be valuable to the repository—bug fixes, features, and refactors that would normally be part of their regular work. Then, we randomly assign each issue to either allow or disallow use of AI while working on the issue. When AI is allowed, developers can use any tools they choose (primarily Cursor Pro with Claude 3.5/3.7 Sonnet—frontier models at the time of the study); when disallowed, they work without generative AI assistance. Developers complete these tasks (which average two hours each) while recording their screens, then self-report the total implementation time they needed. We pay developers $150/hr as compensation for their participation in the study.",
+        "limitations": "Historical narrow setting, tools from early 2025; superseded as a current estimate by authors. No Eldorado forecast."
+      },
+      {
+        "claim": "METR now explicitly marks those historical results as not current.",
+        "evidence": "We have released results that are current as of early 2026, in a continuation of this study. We believe these historical results no longer reflect the current impact of AI models on open-source developer productivity.",
+        "limitations": "Historical narrow setting, tools from early 2025; superseded as a current estimate by authors. No Eldorado forecast."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/17.txt",
+    "body_sha256": "f9abab8a3ad312279800d8327122ebae70c13804d9f91fda1788db1a466a178b",
+    "evidence_type": "primary source body"
+  },
+  {
+    "id": 17,
+    "title": "AI developer productivity experiment",
+    "url": "https://arxiv.org/abs/2302.06590",
+    "publisher": "Peng et al.",
+    "retrieved_at": "2026-10-04T10:27:53.477297+00:00",
+    "claims": [
+      {
+        "claim": "Peng et al. controlled HTTP-server task study reports 55.8% faster completion with Copilot.",
+        "evidence": "Abstract:Generative AI tools hold promise to increase human productivity. This paper presents results from a controlled experiment with GitHub Copilot, an AI pair programmer. Recruited software developers were asked to implement an HTTP server in JavaScript as quickly as possible. The treatment group, with access to the AI pair programmer, completed the task 55.8% faster than the control group. Observed heterogenous effects show promise for AI pair programmers to help people transition into software development careers.",
+        "limitations": "Primary paper abstract inspected, not full methods. Bounded JavaScript task; not whole-SDLC productivity."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/18.txt",
+    "body_sha256": "76c71ee9844c5066d184ec5006945c48959dfcd75854842463cd756f348a3140",
+    "evidence_type": "primary research abstract"
+  },
+  {
+    "id": 18,
+    "title": "How much does AI impact development speed? An enterprise-based randomized controlled trial",
+    "url": "https://arxiv.org/abs/2410.12944",
+    "publisher": "Paradis et al. / arXiv",
+    "retrieved_at": "2026-10-04T10:27:53.495104+00:00",
+    "claims": [
+      {
+        "claim": "Paradis et al. Google RCT abstract reports about 21% shorter task time with a large confidence interval, among 96 engineers.",
+        "evidence": "Abstract:How much does AI assistance impact developer productivity? To date, the software engineering literature has provided a range of answers, targeting a diversity of outcomes: from perceived productivity to speed on task and developer throughput. Our randomized controlled trial with 96 full-time Google software engineers contributes to this literature by sharing an estimate of the impact of three AI features on the time developers spent on a complex, enterprise-grade task. We found that AI significantly shortened the time developers spent on task. Our best estimate of the size of this effect, controlling for factors known to influence developer time on task, stands at about 21\\%, although our confidence interval is large. We also found an interesting effect whereby developers who spend more hours on code-related activities per day were faster with AI. Product and future research considerations are discussed. In particular, we invite further research that explores the impact of AI at the ecosystem level and across multiple suites of AI-enhanced tools, since we cannot assume that the effect size obtained in our lab study will necessarily apply more broadly, or that the effect of AI found using internal Google tooling in the summer of 2024 will translate across tools and over time.",
+        "limitations": "Primary paper abstract inspected, not full methods. Google-specific task/tool setting; no universal gain claim. Retrieval seed title was wrong and corrected from body."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/19.txt",
+    "body_sha256": "e3ac83e7a8c9a613ed67b179321599538d4132e0caf858c4d335452c924c6839",
+    "evidence_type": "primary research abstract"
+  },
+  {
+    "id": 19,
+    "title": "Copilot metrics concepts",
+    "url": "https://docs.github.com/en/copilot/concepts/billing-and-usage/copilot-usage-metrics/copilot-metrics",
+    "publisher": "GitHub",
+    "retrieved_at": "2026-10-04T10:27:54.384631+00:00",
+    "claims": [
+      {
+        "claim": "Copilot richest metrics depend on enabled client telemetry.",
+        "evidence": "Copilot usage metrics are derived from telemetry across multiple Copilot surfaces, including IDE, Copilot CLI, and agent apps activity. Most metrics come from client-side IDE telemetry, and end users need telemetry enabled in their IDE for the richest data in these metrics.",
+        "limitations": "No access to Eldorado subscription, settings, enabled exporters, reports or coverage. Adoption is not impact."
+      },
+      {
+        "claim": "Server-side active-user coverage does not ensure complete feature/LOC breakdowns.",
+        "evidence": "Users surfaced through server-side telemetry are fully counted toward your active user totals (such as daily active users, daily_active_users ). When available, they may also appear in totals_by_ide (including the most recently detected IDE and Copilot extension versions in per-user reports). However, other dimensional breakdowns—such as totals_by_feature and lines-of-code metrics—remain empty until richer telemetry is available for them. Top-level totals and breakdowns for users already captured by client telemetry are unchanged.",
+        "limitations": "No access to Eldorado subscription, settings, enabled exporters, reports or coverage. Adoption is not impact."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/20.txt",
+    "body_sha256": "556fe5be28952b3b7d980b86b8a1a15713f0cff8359a7a0e02e09af7d6916ace",
+    "evidence_type": "primary source body"
+  },
+  {
+    "id": 20,
+    "title": "Claude Code monitoring",
+    "url": "https://code.claude.com/docs/en/monitoring-usage",
+    "publisher": "Anthropic",
+    "retrieved_at": "2026-10-04T10:27:53.636289+00:00",
+    "claims": [
+      {
+        "claim": "Claude supports configured OTel usage/cost/tool telemetry.",
+        "evidence": "Track Claude Code usage, costs, and tool activity across your organization by exporting telemetry data through OpenTelemetry (OTel). Claude Code exports metrics as time series data via the standard metrics protocol, events via the logs/events protocol, and optionally distributed traces via the traces protocol.",
+        "limitations": "Capability depends on version/configuration. Tool/skill-name export may expose confidential identifiers; no observed Eldorado telemetry."
+      },
+      {
+        "claim": "Skill-name/tool detail collection has explicit opt-in and privacy implications.",
+        "evidence": "OTEL_LOG_TOOL_DETAILSEnable logging of tool parameters and input arguments in tool events and trace span attributes: Bash commands, MCP server and tool names, skill names, user-authored workflow names, and tool input. Also enables custom, plugin, and MCP command names on user_prompt events, and real agent, skill, plugin, and MCP server and tool names on the cost and token counters (default: disabled). For Claude Desktop’s built-in servers, in sessions Claude Desktop owns, mcp_server_name/mcp_tool_name emit on tool_decision/tool_result even with the flag off. The exception requires Claude Code v2.1.214 or later1 to enable",
+        "limitations": "Capability depends on version/configuration. Tool/skill-name export may expose confidential identifiers; no observed Eldorado telemetry."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/21.txt",
+    "body_sha256": "197b3be58cae62470e82ac24074ca81024b030701ab3e2729116067dac798b48",
+    "evidence_type": "primary source body"
+  },
+  {
+    "id": 21,
+    "title": "Agent Skills security",
+    "url": "https://agentskills.io/client-implementation/adding-skills-support",
+    "publisher": "Agent Skills",
+    "retrieved_at": "2026-10-04T10:27:53.937245+00:00",
+    "claims": [
+      {
+        "claim": "The implementation guide claims project-over-user skill precedence as universal.",
+        "evidence": "The universal convention across existing implementations: project-level skills override user-level skills.",
+        "limitations": "Implementation guidance rather than normative format; universal precedence claim contradicted by current Claude and Cline docs."
+      },
+      {
+        "claim": "Agent Skills format does not mandate discovery paths.",
+        "evidence": "The .agents/skills/ paths have emerged as a widely-adopted convention for cross-client skill sharing. While the Agent Skills specification does not mandate where skill directories live (it only defines what goes inside them), scanning .agents/skills/ means skills installed by other compliant clients are automatically visible to yours, and vice versa.",
+        "limitations": "Implementation guidance rather than normative format; universal precedence claim contradicted by current Claude and Cline docs."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/22.txt",
+    "body_sha256": "fb2909a93d445a4b18a7cab89c22a7e92502e99d2caa586cf785e8aa8ae7a77b",
+    "evidence_type": "primary source body"
+  },
+  {
+    "id": 22,
+    "title": "METR productivity update 2026",
+    "url": "https://metr.org/blog/2026-02-24-uplift-update/",
+    "publisher": "METR",
+    "retrieved_at": "2026-10-04T10:29:00.438454+00:00",
+    "claims": [
+      {
+        "claim": "METR 2026 follow-up calls its productivity signal unreliable because of selection and time-measurement issues.",
+        "evidence": "Unfortunately, given participant feedback and surveys, we believe that the data from our new experiment gives us an unreliable signal of the current productivity effect of AI tools. The primary reason is that we have observed a significant increase in developers choosing not to participate in the study because they do not wish to work without AI, which likely biases downwards our estimate of AI-assisted speedup. We additionally believe there have been selection effects due to a lower pay rate (we reduced the pay from $150/hr to $50/hr), and that our measurements of time-spent on each task are unreliable for the fraction of developers who use multiple AI agents concurrently.",
+        "limitations": "Authors explicitly warn selection and parallel-agent timing compromise causal magnitude. Neither raw estimate is an Eldorado baseline."
+      },
+      {
+        "claim": "2026 raw estimates suggest speedup, but intervals include no effect and selection limits generalization.",
+        "evidence": "Our raw results show some evidence for speedup. Our early 2025 study found the use of AI causes tasks to take 19% longer, with a confidence interval between +2% and +39%. For the subset of the original developers who participated in the later study, we now estimate a speedup of -18% with a confidence interval between -38% and +9%. Among newly-recruited developers the estimated speedup is -4%, with a confidence interval between -15% and +9%.",
+        "limitations": "Authors explicitly warn selection and parallel-agent timing compromise causal magnitude. Neither raw estimate is an Eldorado baseline."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/23.txt",
+    "body_sha256": "7a4ce4ac6ba1a7a2410e17982493ab0d905d5d6418f28dda7460ca2aa4068306",
+    "evidence_type": "primary source body"
+  },
+  {
+    "id": 23,
+    "title": "Cline SDK plugins",
+    "url": "https://docs.cline.bot/sdk/plugins",
+    "publisher": "Cline",
+    "retrieved_at": "2026-10-04T10:28:59.766735+00:00",
+    "claims": [
+      {
+        "claim": "Cline SDK plugins document fail_closed hook policy.",
+        "evidence": "Use fail_closed for policy-enforcement hooks where bypassing the hook is unsafe.",
+        "limitations": "SDK capability cannot be assumed identical in every Cline IDE/CLI build. Fail-closed behavior needs adapter conformance tests."
+      },
+      {
+        "claim": "Cline plugin installation accepts npm/git/file sources.",
+        "evidence": "Plugins can also be installed from file URLs, npm, git, or local paths using cline plugin install. See Plugins for install commands, the manifest format, and directory layout.",
+        "limitations": "SDK capability cannot be assumed identical in every Cline IDE/CLI build. Fail-closed behavior needs adapter conformance tests."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/24.txt",
+    "body_sha256": "445ba1089e4157e9eac938d1b7f1adf482769f3ae6d495d4bef5d666614fbd6a",
+    "evidence_type": "primary source body"
+  },
+  {
+    "id": 24,
+    "title": "SPACE research publication",
+    "url": "https://www.microsoft.com/en-us/research/publication/the-space-of-developer-productivity-theres-more-to-it-than-you-think/",
+    "publisher": "Microsoft Research",
+    "retrieved_at": "2026-10-04T10:29:02.189612+00:00",
+    "claims": [
+      {
+        "claim": "SPACE rejects productivity measurement with a single activity metric.",
+        "evidence": "Developer productivity is about more than an individual’s activity levels or the efficiency of the engineering systems relied on to ship software, and it cannot be measured by a single metric or dimension. The SPACE framework captures different dimensions of productivity, and here we demonstrate how this framework can be used to understand productivity in practice and why using it will help teams better understand developer productivity and create better measures to inform their work and teams.",
+        "limitations": "Author-hosted publication summary retrieved after ACM 403; supports multidimensional principle, not detailed instrument validity."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/25.txt",
+    "body_sha256": "1f8176ad5b14a5f4053162f670b95bdef81e191104f682c506b11099525b734e",
+    "evidence_type": "primary research abstract"
+  },
+  {
+    "id": 25,
+    "title": "NIST AI RMF Core",
+    "url": "https://airc.nist.gov/airmf-resources/airmf/5-sec-core/",
+    "publisher": "NIST",
+    "retrieved_at": "2026-10-04T10:29:00.075579+00:00",
+    "claims": [
+      {
+        "claim": "NIST RMF organizes risk activity into govern, map, measure, manage.",
+        "evidence": "highest level to govern, map, measure, and manage AI risks. Governance is designed to be a cross-cutting function",
+        "limitations": "Risk-framework recommendations are not proof controls are deployed or staffing exists."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/26.txt",
+    "body_sha256": "c80bf3d3d59511eb3932cfd285893aa2a329ca9d997939c7c8c7718d704f857b",
+    "evidence_type": "primary source body"
+  },
+  {
+    "id": 26,
+    "title": "Copilot adding skills",
+    "url": "https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/add-skills",
+    "publisher": "GitHub",
+    "retrieved_at": "2026-10-04T10:29:00.472587+00:00",
+    "claims": [
+      {
+        "claim": "gh skill --pin skips pinned skills during updates.",
+        "evidence": "To lock a skill to a specific version (or commit SHA) so it is skipped during updates, use --pin:",
+        "limitations": "gh skill is public preview, requires documented minimum CLI version; Gitea interoperability not verified. Pinning is not artifact safety."
+      },
+      {
+        "claim": "GitHub warns shared skills are unverified and may be malicious.",
+        "evidence": "Skills are not verified by GitHub and may contain prompt injections, hidden instructions, or malicious scripts. Always inspect the content of a skill before installation using gh skill preview.",
+        "limitations": "gh skill is public preview, requires documented minimum CLI version; Gitea interoperability not verified. Pinning is not artifact safety."
+      },
+      {
+        "claim": "gh skill records source ref and tree SHA in frontmatter.",
+        "evidence": "When you install a skill with gh skill, provenance metadata is written into the skill's SKILL.md frontmatter, including the source repository, ref, and tree SHA. The gh skill update command uses this metadata to check for upstream changes.",
+        "limitations": "gh skill is public preview, requires documented minimum CLI version; Gitea interoperability not verified. Pinning is not artifact safety."
+      }
+    ],
+    "evidence_file": "/opt/data/channels/eldorado-storm-v1/research/ai-adoption/bodies/27.txt",
+    "body_sha256": "7a5d8597f2ed72edb4610124e83f2abc282311739eabb561b3997ab6cbcbc46b",
+    "evidence_type": "primary source body"
+  }
+]

research/ai-adoption/strategy-blueprint.md

@@ -0,0 +1,190 @@
+# Eldorado AI adoption — strategy implementation blueprint
+
+Status: target operating model for review; not an approved rollout or an inventory of deployed controls. This handoff is documentation design only. It does not authorize installing agents, collecting employee telemetry, changing permissions or enabling autonomous delivery.
+
+## Implementation contract
+
+Create eight substantive pages in the independent Strategy navigation, in this order: `index`, `target-operating-model`, `skills-governance`, `skills-quality`, `skills-adoption`, `measurement`, `skills-maintenance`, `roadmap`. The structured companion is `strategy-model.json`; its KPI definitions and identifiers are authoritative for the measurement prototype. Preserve Organization Structure, Collaboration and SDLC and their exact department/team names. Cross-link rather than duplicate reporting charts. The existing organizational documentation is an operating model, not certification of staffing.
+
+Use the existing Archify JSON renderer and shared icon-only modal control. Diagram logical ID: `ai-adoption-target`; editable source: `diagrams/ai-adoption-target.architecture.json`. Do not expose downloadable JSON. Keep source mapping and open-decision material outside docs/static/search. Reader-facing prose below can be adapted into MDX without bibliography, evidence codes, recruitment commentary or repeated caveats. Use a visible **Target operating model** introduction and prospective verbs where status matters. Never present synthetic calculations as Eldorado results.
+
+## 1. Overview — index
+
+### Govern skills first, expand authority only with evidence
+
+Eldorado's target is to make AI-assisted work dependable across the organization: useful guidance, clear human ownership, controlled execution and measurable outcomes. The first investment is a governed skills system, not an autonomous replacement for the organization. A skill packages reusable working knowledge, prerequisites and verification steps. It helps an agent perform a task; it does not grant permission or guarantee that the work is correct.
+
+The target combines one logical SDLC coordinating agent with developer choice on local laptops. Copilot, Claude Code and Cline remain client options within a qualified support matrix. They receive the same reviewed portable skill content through client-specific adapters. Repository, CI and release services remain the enforcement points, independently of what any agent says or which local tool produced a change.
+
+The strategy describes the intended operating model and the evidence required to introduce it. It does not establish that these controls are installed, that every client is supported, or that AI has improved Eldorado's performance. The current reference is the documented six-department organization. Rollout begins by validating actual clients, responsibilities, data boundaries and available evidence.
+
+Success means accepted outcomes with maintained quality, controlled risk and understood total cost. Faster activity without reliable outcomes is not success. More skill invocations, generated lines or tool subscriptions are not productivity targets. People remain accountable for product, customer, financial and personnel decisions.
+
+## 2. Target operating model — target-operating-model
+
+### One coordination function, distributed contributions
+
+Data & AI owns the coordinating function, with the existing AI Architect function connecting it to Technology leadership. The logical coordinator maintains approved work records, dependencies, evidence requests, bounded retries and escalation. It can summarize, propose work and route decisions. It cannot declare its own work approved, change protected checks, authorize production release or replace the responsible human.
+
+One logical coordinator does not mean one fragile process. A durable task ledger, explicit state transitions, leases and idempotency keys allow recovery or multiple replicas without duplicate delivery. Inference outages stop new agent decisions, not the organization's ability to take over. People can resume work through the normal deterministic workflow. Evidence and authorization services fail closed for privileged actions; missing evidence never becomes permission.
+
+The delivery path is: an approved problem and acceptance criteria; an authorized task; local or isolated worker proposals; independently reviewed repository changes; exact-revision CI evidence; a human release decision; execution by the release service; then operational feedback. Product Management accepts the outcome hypothesis and business result. Product Design reviews experience and accessibility. Product Engineering owns the code and maintainability. Quality Engineering assesses quality independently. Architecture & Security assesses risk. Platform & IT operates the delivery boundary. No arrow from a laptop or coordinator goes directly to production authority.
+
+### Trust and authority boundaries
+
+People authenticate to the work system; the coordinator receives only the project context it needs. Untrusted issue text, repository content, web pages and tool output are task data, never an authorization source. Local clients operate under device controls and project-scoped access. Hard containment requires OS/container isolation, filesystem and network restrictions and separate short-lived identities; a skill folder, prompt or working directory is not a sandbox.
+
+The registry distributes reviewed immutable content and adapters, not ambient credentials. Executable scripts, plugins, MCP servers and dependencies are separately reviewed and pinned. Model-provider routing is allowlisted for the data classification, with approved retention and training-use terms before sensitive data crosses that boundary. Fallback to another provider must not silently change the data policy.
+
+Central controls verify protected-branch review, actual artifact identity, exact commit and policy revision, required checks and a scoped human approval. Candidate changes cannot edit their own authoritative gate or reuse approval for a different artifact. Deployment credentials belong to the release service, not the local agent. Approval expires or is invalidated by changed content. Emergency stop revokes mutation credentials and stops scheduling independently of the model, preserves evidence and enables human takeover.
+
+### Department contributions
+
+| Department / existing team | Contribution and retained human decision | First bounded workflow and evidence |
+| --- | --- | --- |
+| Product / Product Management | Own pilot priorities, acceptance criteria and outcome hypotheses; decide product value. | Draft acceptance criteria from sanitized discovery notes; independent completeness review and accepted-task success. |
+| Product / Product Design | Own design quality, accessibility and research handling. | Review a proposed flow against an accessibility checklist; verify findings against the interface. |
+| Technology / Product Engineering | Own skill authoring, code review and maintainability; remain accountable for generated code. | Test scaffolding and change summaries in a disposable branch; independent tests and escaped-quality follow-up. |
+| Technology / Platform & IT | Own supported client inventory, distribution, identity, isolation, CI/release integration, transport and emergency revocation. | Qualify a pinned bundle and exercise rollback; inventory and exact-revision gate evidence. |
+| Technology / Architecture & Security | Own risk classification, data boundaries, security review and bounded exceptions. | Review injected-input and unauthorized-tool cases; independent control evidence and policy-effect counts. |
+| Technology / Quality Engineering | Own regression/adversarial suites, rubric calibration and acceptance evidence. | Evaluate candidate versus approved skills on repeated representative tasks; retain all failures. |
+| Technology / Data & AI | Own catalog coordination, coordinator evaluation and measurement design, through existing AI enablement responsibilities. | Curate a small skill set and analyze a prospective pilot; no new AI department. |
+| Operations / Operations Squad | Own service acceptance, disputes, fraud, refunds and customer communications. | Draft an answer from sanitized resolved cases; Operational Quality workstream checks correctness before any send. No automated dispute/refund decision. |
+| Marketing / Marketing Squad | Own brand, factual claims, content rights, publication and spend approvals. | Draft a campaign brief against approved brand material; human claim/rights review before publication. |
+| Finance & Accounting / Finance & Accounting Squad | Own allocation of total costs, financial evidence and segregation of approvals. | Explain a sanitized reconciliation exception; no posting, payout or payment authority. |
+| HR & Administration / People & Administration Squad | Own coaching, acceptable use, feedback privacy and people decisions; partner with Platform & IT on access lifecycle. | Draft onboarding guidance from approved policy; human accuracy review. No hiring or performance decision automation. |
+
+Product keeps two teams; Technology keeps five; the other four departments keep one squad each. Coordination, skill ownership, approval and cover are assignments inside these teams, not new standing departments, roles or headcount. Department leaders retain accountability and designate real approvers before a pilot starts.
+
+## 3. Skills governance — skills-governance
+
+### A contract that travels, controls that stay authoritative
+
+Maintain one catalog entry per stable skill ID, with immutable revisions and a concise portable `SKILL.md` body. Required content includes when to use and when not to use the skill, prerequisites, bounded steps, expected artifacts, verification, failure handling and escalation. The companion model defines the complete metadata contract: owner and independent reviewer, risk tier, supported clients and versions, dependencies, digest, provenance and license, evaluations, approval, review date, deprecation and rollback.
+
+The release manifest pins the content, dependencies and adapter revisions by full immutable commit or digest. Names use an `eldorado-` prefix to reduce collisions. Friendly versions aid communication but never replace the digest. No arbitrary upstream automatic update is admitted into the approved bundle. Changes to scripts, resources or dependencies count as skill changes, not harmless documentation edits.
+
+Adapters place content in the qualified client's discovery paths and implement only verified client-specific behavior. Qualification records the host, exact build, OS, model configuration, discovery, explicit invocation, collisions, disabled skills, permission behavior, context compaction and reload behavior. A common file format is not common precedence or a portable hooks API. Claude and Cline skill-name precedence differs from rule/memory behavior; Copilot support varies by surface. Test the actual build, not the brand name.
+
+### Lifecycle and decision rights
+
+A proposal names the problem, owner, data scope and testable outcome. Experimental revisions run only in approved disposable environments. Promotion requires independent review, static and executable dependency checks, per-client behavioral evaluations and a bounded canary. Approval records bind the exact artifact and permitted uses. Deprecated revisions carry a migration path and deadline; retired revisions are unavailable for new work. Any active revision can be quarantined immediately.
+
+The author never supplies the only approval. Data & AI maintains catalog state; the owning team is accountable for content; Quality Engineering approves evaluation evidence; Architecture & Security approves higher-risk boundaries; Platform & IT verifies distribution and revocation. A business owner accepts workflow outcomes. These functions can be covered by existing staff, but incompatible author/approver duties must remain separate for the same release.
+
+An exception contains its ID, skill/client revision, scope, business reason, risk owner, compensating checks, approver, start and expiry, affected users/projects and rollback route. It does not disable protected release, payment or identity controls. Expired or unverifiable exceptions deny privileged actions. Repeated exceptions trigger a supported-design change rather than permanent informal bypass.
+
+### Distribution, stale clients and rollback
+
+Stage a verified bundle atomically, check its digest, load it through the qualified adapter and read back its effective revision. Test already-open sessions; changing files is not proof of reloading instructions. Record immutable last-known-good content and adapter dependencies. Canary upgrades precede wider distribution.
+
+A cached verified bundle may support explicitly permitted low-risk work if its model and tool dependencies are available. It does not make a cloud-backed client work offline. Stale or unsupported sessions cannot obtain centrally mediated privileged access. Reconnection revalidates support, revocation and policy before credentials are issued. Central artifact review protects delivery even when a laptop declaration is absent or false; a client report cannot prove which private prompt was actually followed.
+
+Rollback restores the approved manifest and dependencies, invalidates affected sessions, revokes unsafe revisions, runs a smoke test and verifies effective state. It cannot undo data disclosure or commands already executed. Those require incident response.
+
+## 4. Skills quality — skills-quality
+
+Quality has four separate questions: was the right skill selected, was the procedure executed safely, did the artifact pass independent checks, and did the workflow produce useful outcomes? A successful invocation answers none of the remaining questions by itself.
+
+The proposed qualification contract uses three tiers. R1 is read-only or drafting with nonsensitive approved material; R2 creates code or material with customer impact but no privileged external effect; R3 touches privileged, financial, sensitive-personal or production decisions. R3 remains human-authorized and out of the initial autonomous scope.
+
+Every tier requires all mandatory deterministic safety, schema, authorization and provenance checks to pass, with no observed critical unauthorized action. An observed critical effect blocks promotion. The model gives proposed pilot evaluation floors and success thresholds; these are design defaults for owner ratification, not externally validated guarantees or approved service levels. If sample coverage, acceptance criteria or responsible reviewers are missing, qualification remains incomplete. No aggregate score can trade off a failed mandatory safety check.
+
+Use sanitized, predeclared task sets containing positive triggers, near misses, negative cases and the normal workload mix. Compare no-skill, current-approved and candidate paths with the same starting artifacts; repeat stochastic trials and retain failed and abandoned attempts. Independently inspect output state. Deterministic tests grade checkable constraints; calibrated humans grade usefulness, maintainability and experience. A model judge is supplementary, versioned and checked against human disagreements, never the sole safety or promotion authority.
+
+Include adversarial repository text, malicious referenced code, wrong permissions, client toggles, name shadowing, unsupported versions, hook timeout/crash/malformed response, stale sessions, offline recovery and rollback. Run central checks against forged/missing client declarations. Hook presence is not fail-closed enforcement: failure semantics must be tested on each client, and central authorization remains independent.
+
+Report denominators, task mix, trial counts, per-client results and uncertainty. A passing benchmark is evidence within a tested envelope, not proof that all future tasks are safe. Material model, client, adapter or dependency changes trigger requalification.
+
+## 5. Adoption — skills-adoption
+
+Start with a small set of useful workflows chosen by the existing teams. Product Management and the departmental owner identify the outcome; Data & AI helps turn it into a skill; Quality Engineering establishes acceptance; Platform & IT qualifies the client path; Architecture & Security clears the data boundary. People & Administration Squad coordinates learning and accessible feedback.
+
+Onboarding should teach people to select the right skill, inspect the actual artifact, recognize untrusted instructions, use the exception and incident routes and recover without AI. A practice task ends with verified work and an explanation of limits, not just a logged invocation. Demonstrate the same portable skill on the supported local clients without promising identical agent behavior.
+
+Use short worked examples, peer pairing, office hours and a clear catalog search path. Gather reasons for non-use and rejected suggestions without penalizing them. Preserve a manual path. Training feedback improves the skill only through review, not automatic self-modification of the approved catalog. Departmental workflow outcomes matter more than uniform uptake.
+
+No developer rankings, individual productivity scores, minimum invocation quotas or inference of effort from token counts are part of this strategy. Report cohort-level evidence with privacy protection and balanced quality, flow, risk and cost. A participant may reasonably stop using a skill that creates more work or uncertainty.
+
+## 6. Measurement — measurement
+
+### Decide what counts before counting
+
+Use the machine-readable KPI catalog for exact definitions. Every report states its eligible population, observation window, numerator and denominator or distribution sample count, source coverage, exclusions and calculation version. Zero denominators return “not available.” Missing telemetry is unknown, not inactivity, compliance or success. Examples are explicitly synthetic and illustrative.
+
+Begin with task acceptance, repository, CI, deployment and incident systems because they can independently establish outcomes. Add catalog/version inventory and task-level declarations. Client telemetry is supplementary and version-dependent; enabling rich tool details may collect sensitive commands and identifiers. Do not enable it merely to count skills. A normalized adapter may report approved skill identifiers without forwarding raw arguments.
+
+Validated success uses all eligible initiated tasks whose predeclared observation window has matured. Failed and abandoned tasks remain nonsuccess. Unresolved or unobserved outcomes remain in the denominator, with known-outcome coverage shown alongside the conservative confirmed-success share. They are not relabeled as observed failure. A task cancelled before start is excluded; cancellation after start remains visible. Count a task once across retries and multiple skills. For timeliness, also show unfinished work and age; accepted-only lead-time distributions have survivorship limitations.
+
+Track all five service-level DORA measures: commit-to-production lead time, deployment frequency, change fail rate, failed deployment recovery time and deployment rework rate. Do not substitute PR-open-to-merge time or all-incident MTTR. Pair them with matured escaped-quality rates, policy effects, total cost per accepted outcome, support coverage, adoption, human experience and catalog maintenance. Keep customer/business outcomes linked to their departmental hypotheses; do not infer conversion, trust or revenue improvement from delivery telemetry.
+
+### Baseline and interpretation
+
+Before a pilot, freeze eligibility and acceptance rules and verify event joins. Collect prospective no-skill/current-practice evidence over a complete comparable workflow cycle and until the preregistered precision/sample requirement is met. Do not select a convenient end date after seeing results. Retain task class, service, skill, client/model configuration and concurrent changes. A matched or randomized comparison may be used when practical and ethical; label observational trends as descriptive and report confounding, selection and uncertainty.
+
+Elapsed time and human effort are different quantities. Parallel agents may reduce waiting while increasing review or compute. Include failed attempts and human review/rework in cost, do not multiply a multi-skill task's value across every invocation, and do not convert survey perceptions into proven time savings. Small or incomplete populations yield evidence limits, not an ROI percentage.
+
+### Event and privacy contract
+
+Use the event envelope and per-event required fields in the model. Source producer plus event ID deduplicates transport retries. Conflicting payloads under the same key are quarantined. Attempts have distinct IDs under one task. Domain IDs deduplicate deployments, defects and approvals even when multiple feeds describe them. Late arrivals produce versioned aggregate corrections; never silently overwrite a published result. Preserve occurrence and receipt times, reject impossible orderings and flag clock skew. Missing terminal events remain unresolved until the work owner reconciles them.
+
+Many-to-many task/attempt/skill/client associations preserve exact immutable versions. Unknown version stays null with a reason; never assign the latest revision retroactively. Client declarations, server facts and self-reports remain separately labeled. A skill-loaded event is evidence of loading only. The minimal prototype can operate without actor identity except where a lawful, necessary adoption denominator requires pseudonymous cohort membership.
+
+The privacy starting proposal is 30 days for raw structured analytics events and 12 months for aggregated trends, subject to the responsible owners' review. Keep the approved catalog/approval record for the supported revision's lifetime and its required audit period, which must be decided separately. Incident evidence uses a restricted, explicitly authorized hold and deletion schedule, not an indefinite analytics exception. Suppress reports below five people and prohibit drill-down or overlapping cohort slices that reconstruct identities. Five is a proposed minimum, not a guarantee against re-identification. No raw prompts, code, screens, customer cases or secrets are collected by default. Publish the purpose, lawful collection basis, access/deletion route and retention before collecting. Consent is not presumed to be an appropriate employment-law basis.
+
+## 7. Maintenance — skills-maintenance
+
+Every approved skill has an accountable owning team, independent reviewer, review due date, supported client matrix and rollback bundle. Review both usefulness and safety, not just metadata freshness. Proposed maximum review intervals are recorded by risk tier; incidents, dependency changes, model/client drift or repeated failures trigger earlier review.
+
+Data & AI reviews catalog health with the owning teams. Quality Engineering samples accepted outputs and adds confirmed failures to regression sets without exposing sensitive content. Platform & IT watches unsupported, deprecated and revoked revisions and tests distribution recovery. Architecture & Security reviews emerging misuse and exception expiry. Remove redundant or unused entries deliberately, after examining whether poor discoverability or fit explains non-use.
+
+A reported unsafe behavior opens an incident with artifact, policy and client versions. Architecture & Security coordinates containment; Platform & IT revokes authority, stops scheduling and quarantines affected revisions; the owning department handles customer or business consequences; Quality Engineering reproduces the failure; Data & AI coordinates catalog correction and trend analysis. Preserve minimal restricted evidence and involve People & Administration Squad for employee-data concerns and Finance & Accounting Squad for financial effects. Restart requires a reviewed fix, regression evidence, verified rollback/revocation and accountable human authorization. Closing the incident does not erase the historical failure from measurement.
+
+## 8. Roadmap — roadmap
+
+| Phase | Entry evidence | Work | Exit evidence and hold condition |
+| --- | --- | --- | --- |
+| Foundation | Strategy scope accepted for planning; existing teams identified. | Inventory actual client hosts/builds, provider/data terms, repositories, authority, owners and event availability; select low-risk workflows and metric definitions. | Named accountable people and independent reviewers, bounded pilot charter, forbidden actions, data/retention decision and reproducible baseline plan. Hold if accountability or lawful collection is unresolved. |
+| Governed skills pilot | Foundation evidence approved; no privileged autonomous effects. | Build a small registry, immutable contract, client adapters, evaluations, coaching and synthetic measurement verification. | Qualified client/skill tuples, mandatory safety checks, independent task acceptance, reconciled coverage and user feedback. Hold or narrow scope if quality or data coverage is inadequate. |
+| Reliable distribution | Pilot quality and usefulness support continuing. | Canary updates, effective-version readback, version locking, exception expiry, stale/offline handling and rollback. | Tested revocation and recovery, no bypass of central privileged gates, owners can support the catalog. Hold if effective versions or controls cannot be verified. |
+| Logical SDLC coordination | Distribution, authority and measurement evidence stable. | Observe and assemble evidence first, then propose and route work within scoped identities and budgets. | Exact-artifact approvals, idempotency, duplicate/outage recovery, separation of duties, audit and kill-switch drills pass; humans can take over. No authority expansion based on usage alone. |
+| Departmental expansion | Each department supplies a workflow owner, outcome, data boundary and capacity. | Add Operations, Marketing, Finance & Accounting and HR & Administration workflows with domain-specific review; Product and Technology continue quality improvement. | Departmental accepted outcomes, guardrails, total cost and experience justify continuation; sensitive decisions stay human. Stop or roll back workflows without adequate evidence. |
+
+There are no invented launch dates, budgets, staffing commitments or guaranteed gains. Phase gates permit narrowing or stopping. Re-evaluate earlier phases when the underlying client, provider, data scope or authority changes.
+
+## Internal architecture brief for implementer
+
+Use a small overview with six groups: (1) accountable people and approved work; (2) one logical coordinator and durable ledger; (3) governed registry plus qualified adapters; (4) local client contributors; (5) independent repository/CI/release boundary with separate human approval; (6) audit/measurement feedback. Put external model-provider access across a labeled data/egress boundary, with approved routing. Show registry-to-coordinator and registry-to-local-client distribution; coordinator-to-work proposals; clients-to-repository proposals; CI-to-human approval evidence; approval-to-release service; resulting evidence-to-audit and audit-to-people/coordinator feedback. Distinguish proposal/evidence arrows from authorization arrows. No coordinator-to-production or laptop-to-production edge. Diagram alt text must state target status, human accountability and lack of direct production authority. Keep full contract detail in prose, not tiny diagram boxes. Organization page links identify existing teams, not a new hierarchy.
+
+## Internal evidence mapping and open decisions
+
+Source IDs below refer to `research/ai-adoption/sources.json`. They support principles and documented capabilities, not local deployment or approval. Organization mapping was read from `repositories/documentation/docs/organization/{structure,collaboration,sdlc}.mdx` at `14ba1aa1ef66c91525135f743d15c77e32db78d3`.
+
+| Recommendation | Evidence | Design decision / limit |
+| --- | --- | --- |
+| Portable contract plus exact-client adapters | 1, 2, 4, 8, 9, 21, 26 | Content format is portable; precedence and enforcement are not. Vendored immutable distribution is the proposed default; no Gitea installer compatibility established. |
+| Independent gates, least privilege and human authority | 3, 5, 6, 7, 15, 23 | Central authorization and kill switch are target controls; local hooks are supplementary and may fail open. |
+| One logical coordinator, resilient task ledger and bounded authority | Task direction; 11, 15, 25 | Replica/idempotency/recovery topology is a design choice, not an observed installation or a vendor guarantee. |
+| Exact existing-team ownership | Three organization pages; findings section 5 | Assignments extend the documented model without asserting named staffing, capacity or approval. |
+| Immutable provenance, review, dependency checks and rollback | 1, 26, 15 | Approval digest and distribution manifest are proposed operational contracts. Pinning alone does not make content safe. |
+| Layered repeated evaluation and independent output checks | 11, 15 | Risk tiers, evaluation floors, review intervals and proposed percentages are local design defaults requiring ratification, not thresholds from the literature. |
+| Balanced KPIs and all five delivery measures | 12, 24 | Service/team evidence; no individual ranking or AI causal claim from activity. |
+| Comparative baseline, effort/elapsed distinction and no forecast ROI | 16, 17, 18, 22 | Studies vary by context; abstract-only evidence for 17/18 and known 2026 selection/timing limitations. Do not reproduce percentages as expected gains. |
+| Version-aware optional client telemetry | 19, 20, 23 | Actual licensing, settings and host coverage unknown; normalize only minimally necessary events. |
+| Lifecycle ownership, privacy and gates before expansion | 13, 14, 25; 20 | NIST voluntary framework is not certification; 14 inspected at landing-page level. Retention and cohort floor are proposals for review. |
+
+Open decisions (not blockers to writing target documentation; blockers to their corresponding rollout gates):
+
+1. Platform & IT with Architecture & Security: actual supported hosts/builds/OSs, identity boundaries, authoritative CI/release controls, protected-policy administration and stale-bundle access rule.
+2. Department leaders with Data & AI: named owner/reviewer/deputy coverage, pilot capacity and selected workflows; no new headcount is implied.
+3. Architecture & Security with People & Administration Squad and the relevant data owner: provider processing terms, data classification, lawful telemetry basis, retention, incident holds and access/deletion handling. Obtain specialist legal advice where needed; no new permanent legal role is invented.
+4. Quality Engineering with Data & AI and each workflow owner: ratify or replace the proposed risk-tier thresholds, task distributions, minimum samples, uncertainty criterion and quality follow-up windows before using them for promotion.
+5. Finance & Accounting Squad: cost allocation, currency normalization, treatment of shared licenses, effort sampling and confidence required for investment decisions.
+6. Product Management with departmental owners: business outcome hypotheses and whether a matched/randomized pilot is practical. No tool choice is coerced for an unreviewed experiment.
+7. Platform & IT: private registry distribution method, digest verification, revocation semantics, coordinator recovery and feasible minimal adapters. Do not assume vendor-preview installation or Cline SDK telemetry is already available.
+
+## Executable handoff and verification
+
+`build_strategy_model.py` writes the structured contract and illustrative values. `sample_calculations.py` is an executable reference/test plan using only labeled synthetic in-memory fixtures. The implementation child should port the same assertions into the documentation repository's established test tooling and add a CLI/fixture interface, rather than treating this reference as a production collector. Required cases are declared in the model. Do not ship research files or raw event fixtures into public static assets inadvertently.
+
+Acceptance for this synthesis: both requested files parse/exist; eight page IDs and all eleven existing teams are exact; every KPI has the full calculation/evidence/privacy contract; source IDs resolve; illustrative arithmetic is executed; synthetic edge-case tests pass; documentation repository remains unchanged. Publication, browser review, diagrams and production measurement infrastructure belong to the downstream implementation task, not this synthesis.

research/organization/README.md

@@ -0,0 +1,7 @@
+# Organization background research
+
+The source/excerpt ledger and `reconstruction-snapshot.mdx` preserve the original public-evidence investigation. They are background working material, outside the published docs and static assets.
+
+The reader-facing `docs/organization/structure.mdx` is an organizational operating model, not a research report or an employee roster. Per the user's presentation direction, it describes leadership, departments, teams and responsibilities directly without evidence markers, vacancies or citations. Internet research informs the model; this editorial change does not independently verify staffing, incumbent names or every reporting relationship.
+
+The original snapshot records which categories and relationships were evidenced, job-advertised or inferred. Retain that provenance for future maintenance, without importing it into the published page, diagram metadata or search index.

research/organization/reconstruction-snapshot.mdx

@@ -0,0 +1,102 @@
+---
+title: Structure
+description: Distinguish Eldorado’s publicly evidenced organization from advertised roles and planning assumptions.
+---
+
+import ArchifyDiagram from '@site/src/components/ArchifyDiagram';
+
+**Research snapshot: 2026-10-02.** This is a public-evidence reconstruction for AI strategy planning, **not a verified employee roster** or an internally approved organization chart.
+
+## What is known
+
+Eldorado names **Vladas Jurkevičius — co-founder and CEO** and **Lukas Deksnys — co-founder and COO** on its official About page.[1]
+
+Its official careers site uses seven hiring categories: **Management, Product, Technology, Operations, Marketing, Finance & Accounting, and HR & Administration**. Those labels are directly evidenced; treating them as six peer departments beneath Management is a planning arrangement, not a published reporting hierarchy.[4]
+
+### Evidence legend
+
+- **E — Publicly evidenced:** a named leader, team, function or careers category explicitly appears in an official source. This does not establish every reporting relationship.
+- **J — Job-advertised:** a vacancy describes a role, mandate or reporting line. The position may be unfilled or newly created.
+- **A — Assumed:** a proposed grouping or missing team boundary used for planning, not a claim about Eldorado’s current structure. Dashed connectors identify assumed placements.
+
+## Department overview
+
+<ArchifyDiagram name="organization-structure" title="Eldorado organization — evidence and assumptions" />
+
+**Text alternative:** Management is shown above Product, Technology, Operations, Marketing, Finance & Accounting, and HR & Administration. All six placements beneath Management are assumed. The department names come from the careers taxonomy; the notes in the viewer identify evidenced teams and proposed subdivisions. This view does not assign every function directly to the CEO or COO.
+
+## Departments and teams
+
+The following separates **named teams** from **roles, capabilities and domains**. A function mentioned in a vacancy is not automatically a separately staffed team.
+
+| Department / function | Publicly evidenced teams, roles or domains | Assumed completion for planning |
+| --- | --- | --- |
+| **Management** | **E:** CEO Vladas Jurkevičius and COO Lukas Deksnys. **J:** CTO and CMO are referenced as reporting managers.[1][8][12] CFO is advertised.[5] No incumbent names are inferred for those three roles. | **A:** a leadership coordination layer across the six functions. Exact executive reporting lines, Board membership and decision rights remain unverified. |
+| **Product** | **E:** Order/Orders team; Categories design team, with Boosting & Currency scope; Data Team appears in the ranking Data Scientist vacancy metadata. Data classification and product design evidence.[9][13][14] **J:** Sellers and Operations product-owner domain, including Seller Portal, integrations, onboarding, balances/withdrawals, invoicing and support tooling.[15] | **A:** treat Sellers & Operations as a cross-functional product squad for planning, not a proven standalone team. Do not duplicate Data as a separate peer department. |
+| **Technology** | **J:** Head of Engineering → Group Engineering Managers → Engineering Managers → engineers. AI Architect reports to CTO and starts solo. Technical Architect is named as an infrastructure/security partner; IT Engineer is advertised for identity, device management and internal SaaS.[6][8][10] | **A:** CTO → Head of Engineering. Proposed shared platform/reliability and security capability groups, with staffing and reporting unverified. Do not turn AI Architect into an established AI department. |
+| **Operations** | **E:** Customer Support, Trust & Resolution, Risk & Fraud. **J:** QA Specialist (Operations) reports directly to COO; separate support/resolution Team Lead mandates cover specialist teams.[11][17][18] | **A:** COO ownership of the wider Operations function and its team-lead escalation chain. Only the QA Specialist’s direct COO line is explicit in the reviewed sources. |
+| **Marketing** | **J:** Brand Team Lead reports to CMO. **E:** the wider Marketing team names Creative, SEO, PPC & Affiliate, Influencer, and CRM; brand scope includes organic social, community and brand partnerships.[12] | **A:** model these named disciplines as planning workstreams under Marketing. Separate team managers, headcounts and each discipline’s direct CMO line are not established. |
+| **Finance & Accounting** | **E:** Finance team / hiring category. **J:** CFO remit includes planning, reporting, cash/capital, tax, compliance, financial risk and payments; it describes partnership with CEO and Board, not an explicit reporting line.[5] | **A:** FP&A; Accounting/Tax/Controls; Treasury/Payment Operations as three capability groups. These are inferred subdivisions, not proven staffed teams. Financial risk is not the same thing as the Operations Risk & Fraud team. |
+| **HR & Administration** | **E:** Talent Acquisition team / role category. **J:** full-cycle IT and non-IT recruitment, partnering with hiring managers.[16] | **A:** People Operations and Office/Administration alongside Talent Acquisition. Separate teams and the HR leader’s reporting line remain unverified. |
+
+The Sellers and Operations posting establishes a **product domain**, not a named Sellers department. Its mandate crosses seller-facing features, operational tooling and marketplace infrastructure.[15]
+
+## Reporting lines supported by vacancies
+
+<ArchifyDiagram name="organization-reporting" title="Eldorado reporting lines — advertised and assumed" />
+
+**Read arrows as manager → role/team.** Solid **J** connectors are explicitly described in vacancies. The dashed **A** link between CTO and Head of Engineering is the only inferred link in this diagram. Separate rows are not connected because their upward reporting lines were not established.
+
+| Manager / leader | Role or team below it | Status and scope |
+| --- | --- | --- |
+| Head of Engineering | Group Engineering Manager | **J:** explicitly reports directly to Head of Engineering; the vacancy describes managing 4–5 Engineering Managers.[6] |
+| Group Engineering Manager | Engineering Manager | **J:** explicitly named manager in the Engineering Manager vacancy.[7] |
+| Engineering Manager | Software engineers | **J:** leads a team of around five engineers. This is the advertised span, not a count of all current engineering teams.[7] |
+| CTO | AI Architect | **J:** explicitly direct; a new individual-contributor role, starting solo with a possible future team.[8] |
+| COO | QA Specialist (Operations) | **J:** explicitly direct; independent quality work across Customer Support, Trust & Resolution, and Risk & Fraud.[11] |
+| CMO | Brand Team Lead | **J:** explicitly direct; brand, organic social, community and brand partnerships remit.[12] |
+| Customer Support / Trust & Resolution Team Leads | Their specialists | **J:** support/resolution leadership advert describes teams of 5–10 specialists; the resolution-specific advert also states 5–10. Their own upward manager is not stated.[17][18] |
+| CTO | Head of Engineering | **A:** plausible technology reporting arrangement, retained only as a planning assumption. |
+
+Product Owner, Tech Lead and Product Designer are described as collaborating on product direction. That is evidence of cross-functional work, **not** evidence that one line-manages the others.[13][14]
+
+## What this means for AI strategy
+
+**Research interpretation, not an approved roadmap:** use the evidenced organizational owners rather than inventing one central AI department.
+
+- **Engineering enablement:** the AI Architect vacancy focuses on engineering output, adoption, standards and security under the CTO—not ownership of every business AI initiative.[8]
+- **Marketplace intelligence:** Product/Data has an advertised ranking and recommendations remit, including experimentation and learning-to-rank.[9]
+- **Operations quality:** operational QA explicitly includes auditing AI-handled support and LLM-assisted scoring; customer support leadership includes AI-assisted support and automation.[11][17]
+- **Planning assumption:** coordinate these three areas with Product, Operations, Technology and Finance owners. Whether to create a cross-company AI steering group is a future decision, not a finding about current organization.
+
+## Limits and validation questions
+
+- **No complete internal chart was found in the reviewed public sources.** This is not a claim that none exists. Research prioritized official About, careers, vacancy and legal pages; it is not an exhaustive employee or vacancy census.
+- **Job postings are time-bound recruitment evidence.** A vacancy can describe a future role or team. Names, staffing, budgets and every executive reporting line still need company confirmation.
+- **No reliable total headcount is asserted.** The careers homepage itself contains both “150+” and “200+” descriptions; do not use either to derive department sizes.[2]
+- **Legal entities are not departments.** The Terms of Service names GWD Processing FZCO, Eldorado Sales LLC and Halfway House OÜ collectively as Eldorado. This establishes contracting language, not a parent/subsidiary hierarchy or the employing entity of each team.[3]
+- **Keep scope distinctions:** marketplace Risk & Fraud, financial risk, AI security, and corporate compliance may collaborate but should not be collapsed into one assumed reporting chain.
+
+Before using this as an operating model, confirm: **(1)** which advertised roles are filled, **(2)** executive and functional reporting lines, **(3)** product squad membership and engineering matrix, **(4)** ownership of Payments, Legal/Compliance and Data, and **(5)** the real team roster and capacity. Replace each **A** only when evidence is supplied.
+
+## Sources
+
+[1] https://www.eldorado.gg/about-us — Eldorado About us
+[2] https://careers.eldorado.gg — Eldorado Careers homepage
+[3] https://www.eldorado.gg/terms-of-service — Eldorado Terms of Service
+[4] https://careers.eldorado.gg/jobs — Eldorado Jobs — official hiring categories
+[5] https://careers.eldorado.gg/jobs/8394692-chief-financial-officer — Chief Financial Officer
+[6] https://careers.eldorado.gg/jobs/8376024-group-engineering-manager — Group Engineering Manager
+[7] https://careers.eldorado.gg/jobs/8290012-engineering-manager — Engineering Manager
+[8] https://careers.eldorado.gg/jobs/8175478-ai-architect — AI Architect
+[9] https://careers.eldorado.gg/jobs/8261309-data-scientist-offer-ranking-recommendations — Data Scientist (Offer Ranking & Recommendations)
+[10] https://careers.eldorado.gg/jobs/8363463-it-engineer — IT Engineer
+[11] https://careers.eldorado.gg/jobs/8358613-qa-specialist-operations — QA Specialist (Operations)
+[12] https://careers.eldorado.gg/jobs/8450323-brand-team-lead — Brand Team Lead
+[13] https://careers.eldorado.gg/jobs/8404928-product-designer-orders-team — Product Designer (Orders team)
+[14] https://careers.eldorado.gg/jobs/8253165-product-designer — Product Designer
+[15] https://careers.eldorado.gg/jobs/8389376-product-owner-sellers-and-operations — Product Owner (Sellers and Operations)
+[16] https://careers.eldorado.gg/jobs/8487069-talent-acquisition-partner-junior-mid — Talent Acquisition Partner (Junior - Mid)
+[17] https://careers.eldorado.gg/jobs/8381712-customer-support-team-lead — Customer Support Team Lead
+[18] https://careers.eldorado.gg/jobs/8483510-trust-resolution-team-lead — Trust & Resolution Team Lead
+

research/organization/sources.json

@@ -0,0 +1,261 @@
+{
+  "version": 1,
+  "sources": [
+    {
+      "id": 1,
+      "url": "https://www.eldorado.gg/about-us",
+      "title": "Eldorado About us",
+      "accessed": "2026-10-02",
+      "quotes": [
+        {
+          "text": "Eldorado.gg was founded by two Lithuanian co-founders, Vladas Jurkevičius (CEO) and Lukas Deksnys (COO).",
+          "added": "2026-10-02"
+        }
+      ]
+    },
+    {
+      "id": 2,
+      "url": "https://careers.eldorado.gg",
+      "title": "Eldorado Careers homepage",
+      "accessed": "2026-10-02",
+      "quotes": [
+        {
+          "text": "A global team of 150+ professionals shaping the future of in-game commerce at Eldorado.gg",
+          "added": "2026-10-02"
+        },
+        {
+          "text": "A team of 200+ professionals",
+          "added": "2026-10-02"
+        }
+      ]
+    },
+    {
+      "id": 3,
+      "url": "https://www.eldorado.gg/terms-of-service",
+      "title": "Eldorado Terms of Service",
+      "accessed": "2026-10-02",
+      "quotes": [
+        {
+          "text": "Together, GWD Processing FZCO, Eldorado Sales LLC and Halfway House OÜ are collectively referred to in this Agreement as “Eldorado,” unless otherwise specified.",
+          "added": "2026-10-02"
+        }
+      ]
+    },
+    {
+      "id": 4,
+      "url": "https://careers.eldorado.gg/jobs",
+      "title": "Eldorado Jobs — official hiring categories",
+      "accessed": "2026-10-02",
+      "quotes": [
+        {
+          "text": "Finance & Accounting (1)\nHR & Administration (1)\nMarketing (2)\nOperations (5)\nProduct (3)\nTechnology (9)\nManagement",
+          "added": "2026-10-02"
+        }
+      ]
+    },
+    {
+      "id": 5,
+      "url": "https://careers.eldorado.gg/jobs/8394692-chief-financial-officer",
+      "title": "Chief Financial Officer",
+      "accessed": "2026-10-02",
+      "quotes": [
+        {
+          "text": "This is a key executive role with a broad mandate across financial planning, reporting, cash and capital management, tax, compliance, risk, payments and the Finance team.",
+          "added": "2026-10-02"
+        }
+      ]
+    },
+    {
+      "id": 6,
+      "url": "https://careers.eldorado.gg/jobs/8376024-group-engineering-manager",
+      "title": "Group Engineering Manager",
+      "accessed": "2026-10-02",
+      "quotes": [
+        {
+          "text": "We're growing and looking for a Group Engineering Manager to lead an engineering group of several teams, manage 4-5 Engineering Managers, and report directly to Head of Engineering.",
+          "added": "2026-10-02"
+        }
+      ]
+    },
+    {
+      "id": 7,
+      "url": "https://careers.eldorado.gg/jobs/8290012-engineering-manager",
+      "title": "Engineering Manager",
+      "accessed": "2026-10-02",
+      "quotes": [
+        {
+          "text": "We’re growing and looking for an Engineering Manager to lead a team of around five software engineers and report to a Group Engineering Manager.",
+          "added": "2026-10-02"
+        }
+      ]
+    },
+    {
+      "id": 8,
+      "url": "https://careers.eldorado.gg/jobs/8175478-ai-architect",
+      "title": "AI Architect",
+      "accessed": "2026-10-02",
+      "quotes": [
+        {
+          "text": "We're creating a new role at Eldorado.gg: AI Architect, reporting directly to the CTO.",
+          "added": "2026-10-02"
+        },
+        {
+          "text": "You'll start solo: this is an individual-contributor role on paper, with outsized influence in practice. No direct reports required from day one, but a mandate that touches the whole organization.",
+          "added": "2026-10-02"
+        },
+        {
+          "text": "Own the security posture of AI usage across engineering, in partnership with Technical Architect on infra and security.",
+          "added": "2026-10-02"
+        }
+      ]
+    },
+    {
+      "id": 9,
+      "url": "https://careers.eldorado.gg/jobs/8261309-data-scientist-offer-ranking-recommendations",
+      "title": "Data Scientist (Offer Ranking & Recommendations)",
+      "accessed": "2026-10-02",
+      "quotes": [
+        {
+          "text": "Team\nProduct\nRole\nData Team",
+          "added": "2026-10-02"
+        }
+      ]
+    },
+    {
+      "id": 10,
+      "url": "https://careers.eldorado.gg/jobs/8363463-it-engineer",
+      "title": "IT Engineer",
+      "accessed": "2026-10-02",
+      "quotes": [
+        {
+          "text": "Own the joiner–mover–leaver process end to end;",
+          "added": "2026-10-02"
+        }
+      ]
+    },
+    {
+      "id": 11,
+      "url": "https://careers.eldorado.gg/jobs/8358613-qa-specialist-operations",
+      "title": "QA Specialist (Operations)",
+      "accessed": "2026-10-02",
+      "quotes": [
+        {
+          "text": "Our Operations teams - Customer Support, Trust & Resolution, and Risk & Fraud - are scaling fast, and each measures quality its own way.",
+          "added": "2026-10-02"
+        },
+        {
+          "text": "We're creating a new role at Eldorado.gg: QA Specialist (Operations), reporting directly to the COO.",
+          "added": "2026-10-02"
+        },
+        {
+          "text": "Audit AI-handled support conversations and root-cause failures into content, routing, or model issues;",
+          "added": "2026-10-02"
+        }
+      ]
+    },
+    {
+      "id": 12,
+      "url": "https://careers.eldorado.gg/jobs/8450323-brand-team-lead",
+      "title": "Brand Team Lead",
+      "accessed": "2026-10-02",
+      "quotes": [
+        {
+          "text": "You will manage a team of several people and report to our CMO.",
+          "added": "2026-10-02"
+        },
+        {
+          "text": "Lead and develop a high-performing team spanning brand, organic social, community and brand partnerships;",
+          "added": "2026-10-02"
+        },
+        {
+          "text": "Collaborate closely with the wider Marketing team (Creative, SEO, PPC & Affiliate, Influencer, CRM) as well as Product, Data, and other cross-functional stakeholders.",
+          "added": "2026-10-02"
+        }
+      ]
+    },
+    {
+      "id": 13,
+      "url": "https://careers.eldorado.gg/jobs/8404928-product-designer-orders-team",
+      "title": "Product Designer (Orders team)",
+      "accessed": "2026-10-02",
+      "quotes": [
+        {
+          "text": "We're growing and looking for a Product Designer to join our Order team.",
+          "added": "2026-10-02"
+        },
+        {
+          "text": "Shape product direction as an equal stakeholder alongside the Product Owner and Tech Lead, owning the end-to-end design process for the order page, dispute flows, and broader post-purchase delivery experience;",
+          "added": "2026-10-02"
+        }
+      ]
+    },
+    {
+      "id": 14,
+      "url": "https://careers.eldorado.gg/jobs/8253165-product-designer",
+      "title": "Product Designer",
+      "accessed": "2026-10-02",
+      "quotes": [
+        {
+          "text": "We’re growing and looking for a Product Designer to join our Categories design team.",
+          "added": "2026-10-02"
+        }
+      ]
+    },
+    {
+      "id": 15,
+      "url": "https://careers.eldorado.gg/jobs/8389376-product-owner-sellers-and-operations",
+      "title": "Product Owner (Sellers and Operations)",
+      "accessed": "2026-10-02",
+      "quotes": [
+        {
+          "text": "You’ll own the seller platform domain — the systems and tools that power how sellers operate on Eldorado.",
+          "added": "2026-10-02"
+        },
+        {
+          "text": "This includes Seller Portal and dashboards, direct seller integrations, onboarding and verification tools, balances and withdrawals, invoicing, and customer support tooling.",
+          "added": "2026-10-02"
+        }
+      ]
+    },
+    {
+      "id": 16,
+      "url": "https://careers.eldorado.gg/jobs/8487069-talent-acquisition-partner-junior-mid",
+      "title": "Talent Acquisition Partner (Junior - Mid)",
+      "accessed": "2026-10-02",
+      "quotes": [
+        {
+          "text": "Team\nHR & Administration\nRole\nTalent Acquisition",
+          "added": "2026-10-02"
+        }
+      ]
+    },
+    {
+      "id": 17,
+      "url": "https://careers.eldorado.gg/jobs/8381712-customer-support-team-lead",
+      "title": "Customer Support Team Lead",
+      "accessed": "2026-10-02",
+      "quotes": [
+        {
+          "text": "We’re growing our Customer Operations function and looking for two experienced Team Leads to join our Customer Support and Trust & Resolution teams.",
+          "added": "2026-10-02"
+        },
+        {
+          "text": "Explore AI-assisted support and automation opportunities;",
+          "added": "2026-10-02"
+        }
+      ]
+    },
+    {
+      "id": 18,
+      "url": "https://careers.eldorado.gg/jobs/8483510-trust-resolution-team-lead",
+      "title": "Trust & Resolution Team Lead",
+      "accessed": "2026-10-02",
+      "quotes": [
+        {
+          "text": "Lead, coach, and grow a team of 5-10 Trust & Resolution Specialists;",
+          "added": "2026-10-02"
+        }
+      ]
+    }
+  ]
+}

scripts/ai-kpi.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/** SYNTHETIC reference only. No collectors, network access or production authorization.
+ * Input is a deliberately simplified, reconciled fixture, NOT a production event schema.
+ * Conflicts fail closed (no output); reconciliation/quarantine storage is not implemented.
+ */
+import { readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+export const LABEL = 'SYNTHETIC — illustrative, not Eldorado observations';
+export const CALCULATION_VERSION = 'synthetic-1.0.0';
+export const ratio = (n, d, scale = 100) => d === 0 ? null : n / d * scale;
+export function time(value) {
+  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|\+00:00)$/.test(value)) throw new Error('UTC timestamp required');
+  const t = Date.parse(value);
+  if (!Number.isFinite(t) || new Date(t).toISOString().slice(0,19) !== value.slice(0,19)) throw new Error('Invalid timestamp');
+  return t;
+}
+const canonical = value => JSON.stringify(value, (_, v) => v && typeof v === 'object' && !Array.isArray(v) ? Object.fromEntries(Object.entries(v).sort(([a],[b]) => a.localeCompare(b))) : v);
+const without = (row, keys) => Object.fromEntries(Object.entries(row).filter(([k]) => !keys.includes(k)));
+export function dedup(events) {
+  const kept = new Map();
+  for (const e of events) {
+    if (!e.producer || !e.event_id) throw new Error('Missing transport identity');
+    if (time(e.received_at) < time(e.occurred_at)) throw new Error('Receipt before occurrence');
+    const key = canonical([e.producer, e.event_id]), prior = kept.get(key);
+    if (prior && canonical(without(prior,['received_at'])) !== canonical(without(e,['received_at']))) throw new Error('Conflicting duplicate requires quarantine');
+    if (!prior || time(e.received_at) < time(prior.received_at)) kept.set(key,e);
+  }
+  return [...kept.values()];
+}
+function result(n, d, as_of, {unit = '%', scale = 100, unknown = 0, exclusions = {}, ...extra} = {}) {
+  return {label:LABEL, as_of, calculation_version:CALCULATION_VERSION, numerator:n, denominator:d, unit, value_or_null:ratio(n,d,scale), unknown_count:unknown, exclusions, coverage:{known_percent:ratio(d-unknown,d)}, warnings:unknown ? ['Unknown records remain visible; this is not a failure/non-use rate.'] : [], ...extra};
+}
+function taskCohort(events, start, end, as_of) {
+  const lo=time(start), hi=time(end), cutoff=time(as_of);
+  if (lo >= hi) throw new Error('Invalid half-open window');
+  const starts=new Map(), terminal=new Map();
+  for (const e of dedup(events)) {
+    if (time(e.occurred_at)>cutoff || time(e.received_at)>cutoff) continue;
+    if (e.event_type.startsWith('task.') && !e.task_id) throw new Error('Missing task ID');
+    if (e.event_type==='task.started') {
+      if (!Number.isFinite(e.horizon_hours) || e.horizon_hours<0) throw new Error('Missing/invalid observation horizon');
+      const prior=starts.get(e.task_id);
+      if (prior && (time(prior.occurred_at)!==time(e.occurred_at) || prior.horizon_hours!==e.horizon_hours)) throw new Error('Conflicting semantic task start');
+      starts.set(e.task_id,e);
+    } else if (['task.accepted','task.failed','task.abandoned','task.cancelled'].includes(e.event_type)) {
+      if (e.event_type==='task.accepted' && e.independent_evidence!==true) continue;
+      const prior=terminal.get(e.task_id);
+      if (prior && prior.event_type!==e.event_type) throw new Error('Conflicting task terminal state');
+      if (!prior || time(e.occurred_at)<time(prior.occurred_at)) terminal.set(e.task_id,e);
+    }
+  }
+  for (const [id,e] of terminal) if (starts.has(id) && time(e.occurred_at)<time(starts.get(id).occurred_at)) throw new Error('Terminal before start');
+  const eligible = new Set([...starts].filter(([,e]) => time(e.occurred_at)>=lo && time(e.occurred_at)<hi && time(e.occurred_at)+e.horizon_hours*3600000<=cutoff).map(([id])=>id));
+  return {starts, terminal, eligible};
+}
+// Snapshot rows are pre-reconciled at fixture as_of. Optional receipt/occurrence
+// timestamps support late-record tests; missing timestamps are NOT inferred events.
+function unique(rows, fields=['id']) {
+  const map=new Map();
+  for (const r of rows) {
+    if (fields.some(k=>typeof r[k]!=='string' || !r[k])) throw new Error('Missing semantic identity');
+    const key=canonical(fields.map(k=>r[k])), payload=without(r,['producer','event_id','received_at']);
+    if (map.has(key) && canonical(without(map.get(key),['producer','event_id','received_at']))!==canonical(payload)) throw new Error('Semantic conflict requires reconciliation');
+    const prior=map.get(key);
+    if (!prior || (r.received_at && prior.received_at && time(r.received_at)<time(prior.received_at))) map.set(key,r);
+  }
+  return [...map.values()];
+}
+const visible = (r, as_of) => (!r.received_at || time(r.received_at)<=time(as_of)) && (!r.occurred_at || time(r.occurred_at)<=time(as_of));
+const within = (t,start,end) => time(t)>=time(start) && time(t)<time(end);
+function horizon(r) {
+  if (!Number.isFinite(r.followup_hours) || r.followup_hours<0) throw new Error('Missing/invalid followup horizon');
+  return r.followup_hours*3600000;
+}
+export function association(rows) {
+  const map=new Map();
+  for (const r of rows) {
+    const tuple={skill_id:r.skill_id,revision:r.revision ?? null,version_status:!Object.hasOwn(r,'revision') ? 'missing' : r.revision===null ? 'unknown' : 'known',client:r.client,missing_reason:r.missing_reason ?? null};
+    if (!map.has(r.task_id)) map.set(r.task_id,new Map());
+    map.get(r.task_id).set(canonical(tuple),tuple);
+  }
+  return Object.fromEntries([...map].map(([id, tuples])=>[id,[...tuples.values()].sort((a,b)=>canonical(a).localeCompare(canonical(b)))]));
+}
+export function deployments(rows) {
+  const effects=unique(rows,['service_id','deployment_id']).filter(r=>r.environment==='production' && r.production_effect===true);
+  return {effects:effects.length,successful:effects.filter(r=>r.succeeded===true).length,change_fail_rate:ratio(effects.filter(r=>r.intervention===true).length,effects.length),rework_rate:ratio(effects.filter(r=>r.planned===false && Boolean(r.incident_id)).length,effects.length)};
+}
+export function matureDefects(changes,defects,as_of,start='0001-01-01T00:00:00Z',end=as_of) {
+  const eligible=unique(changes).filter(c=>visible(c,as_of) && within(c.accepted_at,start,end) && time(c.accepted_at)+horizon(c)<=time(as_of));
+  const affected=new Set();
+  for (const d of unique(defects)) {
+    const c=eligible.find(c=>c.id===d.change_id);
+    if (c && d.confirmed===true && visible(d,as_of) && time(d.detected_at)>=time(c.accepted_at) && time(d.detected_at)<=time(c.accepted_at)+horizon(c)) affected.add(c.id);
+  }
+  return [affected.size,eligible.length];
+}
+export function survey(rows,invited,as_of) {
+  if (!Number.isInteger(invited) || invited<0) throw new Error('Invalid invitation count');
+  const all=unique(rows), valid=all.filter(r=>Number.isInteger(r.score) && r.score>=1 && r.score<=5);
+  if (all.length>invited) throw new Error('Responses exceed invitations');
+  const suppressed=valid.length<5;
+  return result(suppressed?null:valid.reduce((n,r)=>n+r.score,0),valid.length,as_of,{unit:'points (1–5)',scale:1,value_or_null:suppressed?null:ratio(valid.reduce((n,r)=>n+r.score,0),valid.length,1),suppressed,exclusions:{invalid_answers:all.length-valid.length},coverage:{response_percent:ratio(valid.length,invited)},distribution:suppressed?null:Object.fromEntries([1,2,3,4,5].map(s=>[s,valid.filter(r=>r.score===s).length])),warnings:suppressed?['People cohort below five suppressed.']:[]});
+}
+export function calculate(f) {
+  if (f.synthetic!==true || f.schema_version!=='1.0') throw new Error('Explicit synthetic schema 1.0 fixture required');
+  const {start,end,as_of}=f, kpis={};
+  kpis['validated-task-success']=success(f.events,start,end,as_of);
+  const trials=unique(f.selection).filter(r=>visible(r,as_of));
+  const scored=trials.filter(r=>typeof r.relevant==='boolean' && typeof r.activated==='boolean');
+  const tp=scored.filter(r=>r.relevant && r.activated).length;
+  for (const [id,den] of [['selection-precision',scored.filter(r=>r.activated).length],['selection-recall',scored.filter(r=>r.relevant).length]]) {
+    kpis[id]=result(tp,den,as_of,{unknown:trials.length-scored.length,coverage:{scorable_percent:ratio(scored.length,trials.length)},exclusions:{unscorable:trials.length-scored.length}});
+  }
+  const effects=unique(f.deployments,['service_id','deployment_id']).filter(r=>visible(r,as_of) && r.environment==='production' && r.production_effect===true && within(r.deployed_at,start,end));
+  const mature=effects.filter(r=>time(r.deployed_at)+horizon(r)<=time(as_of));
+  kpis['change-fail-rate']=result(mature.filter(r=>r.intervention===true).length,mature.length,as_of,{unknown:mature.filter(r=>typeof r.intervention!=='boolean').length,exclusions:{immature:effects.length-mature.length}});
+  kpis['deployment-rework-rate']=result(effects.filter(r=>r.planned===false && Boolean(r.incident_id)).length,effects.length,as_of,{unknown:effects.filter(r=>typeof r.planned!=='boolean' || (r.planned===false && !Object.hasOwn(r,'incident_id'))).length});
+  const [affected,accepted]=matureDefects(f.changes,f.defects,as_of,start,end);
+  const matureChanges=unique(f.changes).filter(r=>visible(r,as_of) && within(r.accepted_at,start,end) && time(r.accepted_at)+horizon(r)<=time(as_of));
+  kpis['escaped-quality-rate']=result(affected,accepted,as_of,{unknown:matureChanges.filter(r=>r.linkage_complete!==true).length,exclusions:{outside_window_immature_or_late:unique(f.changes).length-matureChanges.length},pending_triage_count:unique(f.defects).filter(r=>visible(r,as_of) && r.confirmed!==true).length});
+  const attempts=unique(f.attempts).filter(r=>visible(r,as_of));
+  kpis['policy-effects']=result(attempts.filter(r=>r.actual_effect===true).length,attempts.length,as_of,{unknown:attempts.filter(r=>typeof r.actual_effect!=='boolean').length,blocked_count:attempts.filter(r=>r.blocked===true).length});
+  const {eligible}=taskCohort(f.events,start,end,as_of);
+  const costs=unique(f.costs).filter(r=>visible(r,as_of) && (eligible.has(r.task_id) || r.task_id==='shared_pool'));
+  if (costs.some(r=>r.currency!==f.currency || !Number.isFinite(r.amount) || r.amount<0)) throw new Error('Invalid cost or mixed currency: approved conversion required');
+  const missing=f.expected_cost_buckets.filter(b=>!costs.some(r=>r.bucket===b));
+  kpis['cost-per-accepted-outcome']=result(costs.reduce((sum,r)=>sum+r.amount,0),kpis['validated-task-success'].numerator,as_of,{scale:1,unit:`${f.currency}/accepted outcome`,partial_estimate:missing.length>0,coverage:{missing_cost_buckets:missing},warnings:missing.length?['Partial estimate, not total cost; missing cost buckets.']:[]});
+  kpis['human-experience']=survey(f.survey.responses.filter(r=>visible(r,as_of)),f.survey.invited,as_of);
+  return {label:LABEL,as_of,calculation_version:CALCULATION_VERSION,window:{start,end},kpis,associations:association(f.associations),not_implemented:['supported-bundle-coverage','useful-adoption','change-lead-time','deployment-frequency','failed-deployment-recovery-time','maintenance-health','department-outcome'],limitations:['Synthetic simplified reconciled snapshots only; not the full production event envelope.','Snapshot rows without timestamps are assumed frozen at as_of, not missing-event evidence.','No causal attribution, uncertainty intervals, authorization or telemetry collection.','Survey implements primary item only; no cross-slice disclosure protection.','Defect severity strata and policy severity counts are not implemented.']};
+}
+if (process.argv[1] && import.meta.url===pathToFileURL(process.argv[1]).href) {
+  try {
+    if (process.argv.length>3) throw new Error('Usage: node scripts/ai-kpi.mjs [synthetic-fixture.json]');
+    const source=process.argv[2] ?? new URL('./fixtures/ai-kpi-synthetic.json',import.meta.url);
+    console.log(JSON.stringify(calculate(JSON.parse(readFileSync(source,'utf8'))),null,2));
+  } catch (error) { console.error(`Synthetic KPI calculation failed: ${error.message}`); process.exitCode=1; }
+}
+export function success(events,start,end,as_of) {
+  const {starts,terminal,eligible}=taskCohort(events,start,end,as_of);
+  const n=[...eligible].filter(id=>terminal.get(id)?.event_type==='task.accepted').length;
+  const unknown=[...eligible].filter(id=>!terminal.has(id)).length;
+  return result(n,eligible.size,as_of,{unknown, known_outcome_coverage:ratio(eligible.size-unknown,eligible.size), orphan_terminal_count:[...terminal.keys()].filter(id=>!starts.has(id)).length, excluded_start_count:starts.size-eligible.size, exclusions:{outside_window_or_immature:starts.size-eligible.size}});
+}

scripts/ai-kpi.test.mjs

@@ -0,0 +1,153 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, readFileSync } from 'node:fs';
+const moduleUrl = new URL('./ai-kpi.mjs', import.meta.url);
+import { spawnSync } from 'node:child_process';
+import * as api from './ai-kpi.mjs';
+const fixture = () => JSON.parse(readFileSync(new URL('./fixtures/ai-kpi-synthetic.json', import.meta.url)));
+test('semantic change duplicates preserve the complete quality report including exclusions', () => {
+  const original = fixture();
+  const repeated = fixture();
+  repeated.changes.push({...repeated.changes[0]});
+  assert.deepEqual(api.calculate(repeated).kpis['escaped-quality-rate'], api.calculate(original).kpis['escaped-quality-rate']);
+});
+test('CLI report exposes implemented KPI contracts and explicit omissions', async () => {
+  const m = await import(moduleUrl);
+  assert.equal(typeof m.calculate, 'function');
+  const r = m.calculate(fixture());
+  assert.equal(Object.keys(r.kpis).length, 9);
+  assert.equal(r.not_implemented.length, 7);
+  assert.equal(r.kpis['cost-per-accepted-outcome'].value_or_null, 60);
+  assert.equal(r.kpis['selection-precision'].value_or_null, 50);
+  assert.equal(r.kpis['selection-recall'].value_or_null, 50);
+  assert.equal(r.kpis['change-fail-rate'].value_or_null, 100);
+  assert.equal(r.kpis['deployment-rework-rate'].value_or_null, 100);
+  assert.equal(r.kpis['escaped-quality-rate'].value_or_null, 100);
+  assert.equal(r.kpis['policy-effects'].value_or_null, 50);
+  assert.equal(r.kpis['human-experience'].value_or_null, 4);
+});
+function event(id,task,kind,day=1,extra={}) {
+  const timestamp=`2026-01-${String(day).padStart(2,'0')}T00:00:00Z`;
+  return {producer:'synthetic',event_id:id,task_id:task,event_type:kind,occurred_at:timestamp,received_at:timestamp,...extra};
+}
+const run = (events,as_of=fixture().as_of) => api.success(events,fixture().start,fixture().end,as_of);
+test('transport duplicates and redelivery use earliest receipt in either order',()=>{
+  const f=fixture(), duplicate={...f.events[0],received_at:'2026-01-06T00:00:00Z'};
+  assert.deepEqual(run([...f.events,f.events[0]]),run(f.events));
+  assert.deepEqual(run([...f.events,duplicate]),run(f.events));
+  assert.deepEqual(run([duplicate,...f.events]),run(f.events));
+});
+test('transport conflicts fail closed',()=>assert.throws(()=>run([...fixture().events,{...fixture().events[0],task_id:'other'}]),/Conflicting duplicate/));
+test('retry and cross-feed semantic duplicate never add tasks',()=>{
+  const f=fixture();
+  assert.equal(run([...f.events,event('retry','accepted','attempt.started',2),event('retry-fail','accepted','attempt.failed',2),{...f.events[0],producer:'mirror',event_id:'mirror-start'}]).denominator,4);
+});
+test('immature task and half-open end excluded',()=>{
+  const r=run([...fixture().events,event('boundary','boundary','task.started',5,{horizon_hours:0})]);
+  assert.equal(r.excluded_start_count,2);
+  assert.equal(r.denominator,4);
+});
+test('all implemented zero denominator values are null',()=>{
+  const f=fixture();
+  for (const k of ['events','selection','deployments','changes','defects','attempts','costs','associations']) f[k]=[];
+  f.survey={invited:0,responses:[]};
+  for (const r of Object.values(api.calculate(f).kpis)) assert.equal(r.value_or_null,null);
+});
+test('orphan terminal does not increase accepted count',()=>{
+  const r=run([...fixture().events,event('orphan','absent','task.accepted',2,{independent_evidence:true})]);
+  assert.equal(r.orphan_terminal_count,1); assert.equal(r.numerator,1);
+});
+test('late arrival restates only when received',()=>{
+  const events=[...fixture().events,event('late','unknown','task.accepted',3,{independent_evidence:true,received_at:'2026-01-06T00:00:00Z'})];
+  assert.equal(run(events).numerator,1);
+  assert.equal(run(events,'2026-01-06T00:00:00Z').numerator,2);
+});
+test('unknown, absent and mixed versions retained without latest inference',()=>{
+  const rows=['a','b','a',null].map(revision=>({task_id:'t',skill_id:'s',revision,client:'Cline'}));
+  rows.push({task_id:'t',skill_id:'s',client:'Cline'});
+  const r=api.association(rows).t;
+  assert.equal(r.length,4);
+  assert.equal(r.filter(x=>x.version_status==='known').length,2);
+  assert.deepEqual(new Set(r.filter(x=>x.revision===null).map(x=>x.version_status)),new Set(['missing','unknown']));
+});
+test('invalid timestamps, UTC offsets, receipt order and terminal order rejected',()=>{
+  for(const t of ['no','2026-02-30T00:00:00Z','2026-01-01T00:00:00+01:00']) assert.throws(()=>api.time(t));
+  assert.throws(()=>run([event('s','t','task.started',2,{horizon_hours:24}),event('a','t','task.accepted',1,{independent_evidence:true})]),/Terminal before start/);
+  assert.throws(()=>api.dedup([event('s','t','task.started',2,{received_at:'2026-01-01T00:00:00Z'})]),/Receipt before/);
+});
+test('missing horizon is not silently mature',()=>assert.throws(()=>run([event('s','t','task.started')]),/horizon/));
+test('conflicting terminal and semantic start require reconciliation',()=>{
+  assert.throws(()=>run([...fixture().events,event('conflict','accepted','task.failed',3)]),/Conflicting task terminal/);
+  assert.throws(()=>run([...fixture().events,event('conflict','accepted','task.started',2,{horizon_hours:48})]),/semantic task start/);
+});
+test('no independent acceptance evidence means unknown, not accepted',()=>{
+  const r=run([event('s','t','task.started',1,{horizon_hours:24}),event('a','t','task.accepted',2)]);
+  assert.equal(r.numerator,0); assert.equal(r.unknown_count,1);
+});
+test('pre-start cancellation excluded; post-start cancellation remains denominator',()=>{
+  const r=run([event('pre','never','task.cancelled',1,{before_start:true}),event('s','started','task.started',1,{horizon_hours:24}),event('post','started','task.cancelled',2,{before_start:false})]);
+  assert.deepEqual([r.numerator,r.denominator,r.unknown_count],[0,1,0]);
+});
+test('deployment retries collapse; unknown rework not treated as planned',()=>{
+  const row=fixture().deployments[0];
+  assert.deepEqual(api.deployments([row,{...row,producer:'mirror',event_id:'2'}]),{effects:1,successful:1,change_fail_rate:100,rework_rate:100});
+  assert.equal(api.deployments([{...row,planned:null}]).rework_rate,0);
+  const f=fixture(); f.deployments[0].planned=null;
+  const r=api.calculate(f).kpis['deployment-rework-rate'];
+  assert.equal(r.denominator,1); assert.equal(r.unknown_count,1);
+  assert.throws(()=>api.deployments([row,{...row,planned:true}]),/Semantic conflict/);
+});
+test('mature deployment denominator retains unsuccessful production effects',()=>{
+  const f=fixture(); f.deployments[0].succeeded=false;
+  assert.equal(api.calculate(f).kpis['change-fail-rate'].denominator,1);
+  f.deployments[0].followup_hours=1000;
+  assert.equal(api.calculate(f).kpis['change-fail-rate'].denominator,0);
+});
+test('mature defect followup is linked, bounded and deduplicated',()=>{
+  const f=fixture();
+  f.changes.push({id:'new',accepted_at:'2026-01-04T00:00:00Z',followup_hours:48});
+  f.defects.push({...f.defects[0],id:'new-defect',change_id:'new'});
+  assert.deepEqual(api.matureDefects(f.changes,[...f.defects,f.defects[0]],f.as_of),[1,1]);
+  f.defects[0].detected_at='2026-01-04T00:00:00Z';
+  assert.deepEqual(api.matureDefects(f.changes,f.defects,f.as_of),[0,1]);
+});
+test('cost includes failed attempts, flags partial buckets and rejects mixed currencies',()=>{
+  const f=fixture(); let r=api.calculate(f).kpis['cost-per-accepted-outcome'];
+  assert.equal(r.numerator,60); assert.equal(r.partial_estimate,true);
+  f.costs.push({...f.costs[0]});
+  assert.equal(api.calculate(f).kpis['cost-per-accepted-outcome'].numerator,60);
+  f.costs.pop(); // Currency validation is separate from conflicting duplicate validation.
+  f.costs[0].currency='USD'; assert.throws(()=>api.calculate(f),/mixed currency/);
+});
+test('blocked attempts are not prohibited effects; unknown audits remain denominator',()=>{
+  const f=fixture(); f.attempts.push({id:'unknown'});
+  const r=api.calculate(f).kpis['policy-effects'];
+  assert.deepEqual([r.numerator,r.denominator,r.blocked_count,r.unknown_count],[1,3,1,1]);
+});
+test('survey suppresses small groups including sum and distribution',()=>{
+  const f=fixture(), r=api.survey(f.survey.responses.slice(0,4),10,f.as_of);
+  assert.equal(r.value_or_null,null); assert.equal(r.numerator,null); assert.equal(r.distribution,null);
+});
+test('required output fields accompany every implemented KPI',()=>{
+  const required=['label','as_of','calculation_version','numerator','denominator','unit','value_or_null','unknown_count','exclusions','coverage','warnings'];
+  for (const r of Object.values(api.calculate(fixture()).kpis)) for(const key of required) assert.ok(Object.hasOwn(r,key),key);
+});
+test('non-synthetic and unknown fixture schemas rejected',()=>{
+  assert.throws(()=>api.calculate({...fixture(),synthetic:false}),/synthetic/);
+  assert.throws(()=>api.calculate({...fixture(),schema_version:'future'}),/schema/);
+});
+test('CLI executes default and explicit fixture and fails visibly for missing input',()=>{
+  for(const args of [[],[new URL('./fixtures/ai-kpi-synthetic.json',import.meta.url).pathname]]) {
+    const r=spawnSync(process.execPath,[moduleUrl.pathname,...args],{encoding:'utf8'});
+    assert.equal(r.status,0,r.stderr); assert.equal(JSON.parse(r.stdout).kpis['validated-task-success'].value_or_null,25);
+  }
+  const r=spawnSync(process.execPath,[moduleUrl.pathname,'/nonexistent/synthetic-fixture.json'],{encoding:'utf8'});
+  assert.equal(r.status,1); assert.equal(r.stdout,''); assert.match(r.stderr,/failed/);
+});
+test('synthetic task calculator exists and retains failed, abandoned, unknown tasks', async () => {
+  assert.ok(existsSync(moduleUrl), 'calculator implementation is required');
+  const { success } = await import(moduleUrl);
+  const f = JSON.parse(readFileSync(new URL('./fixtures/ai-kpi-synthetic.json', import.meta.url)));
+  const r = success(f.events, f.start, f.end, f.as_of);
+  assert.deepEqual([r.numerator, r.denominator, r.unknown_count, r.value_or_null, r.known_outcome_coverage], [1,4,1,25,75]);
+});

scripts/browser/inline-controls.cjs

@@ -0,0 +1,142 @@
+const {chromium} = require('playwright');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+(async () => {
+  const base = process.argv[2] || 'http://127.0.0.1:4173';
+  const output = `.cache/inline-${process.argv[3] || 'local'}`;
+  fs.mkdirSync(output, {recursive: true});
+  const browser = await chromium.launch({headless: true, executablePath: process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE, args: ['--no-sandbox']});
+  const results = [];
+  try {
+    for (const width of [1440, 390, 320]) {
+      const context = await browser.newContext({viewport: {width, height: 1000}, colorScheme: 'light'});
+      const page = await context.newPage();
+      await page.goto(`${base}/eldorado-v1/documentation/strategy/`, {waitUntil: 'networkidle'});
+      const panel = page.locator('.archify-panel--story');
+      const iframe = panel.locator(width > 700 ? '.story-desktop' : '.story-mobile');
+      await iframe.scrollIntoViewIfNeeded();
+      const frame = await (await iframe.elementHandle()).contentFrame();
+      const theme = async value => {
+        await page.waitForFunction(t => document.documentElement.dataset.theme === t, value);
+        await frame.waitForFunction(t => document.documentElement.dataset.theme === t, value);
+      };
+      await theme('light');
+      for (const id of ['btn-theme', 'btn-preset', 'btn-export']) {
+        const box = await frame.locator(`#${id}`).boundingBox();
+        assert(box && box.width >= 40 && box.height >= 44, id);
+      }
+      const toolbar = await frame.locator('.toolbar').boundingBox();
+      const exportButton = await frame.locator('#btn-export').boundingBox();
+      const diagram = await frame.locator('.diagram-container > svg').boundingBox();
+      const rightGap = toolbar.x + toolbar.width - exportButton.x - exportButton.width;
+      assert(Math.abs(rightGap - 8) < 1, `toolbar right padding at ${width}: ${rightGap}`);
+      assert(diagram.y >= toolbar.y + toolbar.height, 'toolbar must stay above nodes');
+      const checkMenu = async selector => {
+        await frame.locator(selector).evaluate(n => Promise.all(n.getAnimations().map(a => a.finished)));
+        const menu = await frame.locator(selector).boundingBox();
+        const viewport = await iframe.boundingBox();
+        const currentToolbar = await frame.locator('.toolbar').boundingBox();
+        assert(menu && menu.x >= viewport.x - 1 && menu.y >= currentToolbar.y + currentToolbar.height - 1, selector);
+        assert(menu.x + menu.width <= viewport.x + viewport.width + 1, `${selector} clips horizontally`);
+        assert(menu.y + menu.height <= viewport.y + viewport.height + 1, `${selector} clips vertically`);
+      };
+      const light = await frame.locator('body').evaluate(n => getComputedStyle(n).backgroundColor);
+      await frame.locator('#btn-theme').click(); await theme('dark');
+      assert.notEqual(await frame.locator('body').evaluate(n => getComputedStyle(n).backgroundColor), light);
+      await frame.locator('#btn-theme').click(); await theme('light');
+      // Mobile portal theme control lives in the navigation drawer.
+      const portalTheme = async target => {
+        if (width <= 700) await page.getByRole('button', {name: 'Toggle navigation bar'}).click();
+        for (let attempt = 0; attempt < 3; attempt++) {
+          await page.getByRole('button', {name: /Switch between dark and light mode/}).filter({visible: true}).click();
+          if (await page.locator('html').getAttribute('data-theme') === target) break;
+        }
+        if (width <= 700) await page.getByRole('button', {name: 'Close navigation bar'}).click();
+      };
+      await portalTheme('dark'); await theme('dark');
+      await portalTheme('light'); await theme('light');
+      for (const preset of ['signal-flow', 'blueprint', 'editorial', 'classic']) {
+        await frame.locator('#btn-preset').click();
+        await checkMenu('.preset-menu');
+        await frame.locator(`[data-preset-value="${preset}"]`).click();
+        assert.equal(await frame.locator('html').getAttribute('data-preset'), preset);
+      }
+      // A theme change must not reload the iframe or lose the selected visual preset.
+      await frame.locator('#btn-preset').click();
+      await frame.locator('[data-preset-value="blueprint"]').click();
+      await portalTheme('dark'); await theme('dark');
+      assert.equal(await frame.locator('html').getAttribute('data-preset'), 'blueprint');
+      const exports = [];
+      for (const format of ['png', 'jpeg', 'webp', 'svg', 'svg-light', 'svg-dark', 'webm']) {
+        await frame.locator('#btn-export').click();
+        await checkMenu('.export-menu');
+        if (format === 'webm' && await frame.locator('[data-format="webm"]').isDisabled()) {
+          exports.push({format, unsupported: true});
+          await frame.locator('#btn-export').click();
+          continue;
+        }
+        console.log(`Export ${width} ${format}`);
+        const [download] = await Promise.all([
+          page.waitForEvent('download', {timeout: 60000}),
+          frame.locator(`[data-format="${format}"]`).click(),
+        ]);
+        assert.equal(await download.failure(), null);
+        const path = `${output}/${width}-${format}-${download.suggestedFilename()}`;
+        await download.saveAs(path);
+        const bytes = fs.readFileSync(path);
+        assert(bytes.length > 1000);
+        if (format.startsWith('svg')) {
+          const valid = await page.evaluate(xml => {
+            const doc = new DOMParser().parseFromString(xml, 'image/svg+xml');
+            if (doc.querySelector('[data-node-id="humans"], [data-edge-id="human-direction"]')) return false;
+            if (![...doc.querySelectorAll('[data-node-id="agent"] text')].some(n => n.textContent === 'Human Controlled')) return false;
+            if (doc.querySelectorAll('[data-node-id]').length !== 17 || doc.querySelectorAll('path[data-edge-id]').length !== 24) return false;
+            return !doc.querySelector('parsererror') && doc.documentElement.localName === 'svg' && doc.querySelectorAll('text').length > 0 && doc.querySelector('#eldorado-cycle-export')?.textContent.includes('stroke-dasharray: 3 9');
+          }, bytes.toString());
+          assert(valid, format);
+        } else {
+          const mime = {png:'image/png', jpeg:'image/jpeg', webp:'image/webp', webm:'video/webm'}[format];
+          const dimensions = await page.evaluate(async ({data, mime}) => {
+            const media = document.createElement(mime.startsWith('video') ? 'video' : 'img');
+            const loaded = new Promise((resolve, reject) => {media[mime.startsWith('video') ? 'onloadedmetadata' : 'onload'] = resolve; media.onerror = reject;});
+            media.src = `data:${mime};base64,${data}`; await loaded;
+            return [media.videoWidth || media.naturalWidth, media.videoHeight || media.naturalHeight];
+          }, {data: bytes.toString('base64'), mime});
+          assert(dimensions.every(n => n > 0), format);
+        }
+        exports.push({format, path, bytes:bytes.length});
+      }
+      const opener = panel.getByRole('button', {name:/^Expand /});
+      await opener.click();
+      let full = await (await panel.locator('dialog iframe').elementHandle()).contentFrame();
+      await full.waitForFunction(() => document.documentElement.dataset.theme === 'dark');
+      await full.locator('#btn-theme').click(); await theme('light');
+      const close = panel.getByRole('button', {name:'Close full-screen diagram'});
+      assert.equal(await close.innerText(), '×');
+      await close.click(); assert(await opener.evaluate(n => n === document.activeElement));
+      await opener.click();
+      full = await (await panel.locator('dialog iframe').elementHandle()).contentFrame();
+      await full.waitForFunction(() => document.documentElement.dataset.theme === 'light');
+      await close.focus(); await page.keyboard.press('Escape');
+      assert(await opener.evaluate(n => n === document.activeElement));
+      await iframe.scrollIntoViewIfNeeded();
+      await page.evaluate(() => scrollTo({top: 0, behavior: 'instant'}));
+      await page.evaluate(() => new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve))));
+      await page.screenshot({path:`${output}/${width}.png`, fullPage:true});
+      await frame.locator('#btn-theme').click(); await theme('dark');
+      // Exercise keyboard navigation without racing the portal's smooth scroll.
+      await page.locator('.strategy-content a[href$="/strategy/target-operating-model/"]').filter({visible:true}).focus();
+      await page.keyboard.press('Enter');
+      await page.waitForURL('**/strategy/target-operating-model/');
+      await page.getByRole('heading', {name:'Target operating model', exact:true, level:1}).waitFor();
+      const next = page.locator(`.archify-panel--story[data-diagram="strategy-target"] > .story-${width > 700 ? 'desktop' : 'mobile'}`);
+      await next.scrollIntoViewIfNeeded();
+      await (await (await next.elementHandle()).contentFrame()).waitForFunction(() => document.documentElement.dataset.theme === 'dark');
+      assert(!await page.evaluate(() => document.documentElement.scrollWidth > innerWidth));
+      results.push({width, toolbar, rightGap, dropdownsUnclipped:true, themeSync:true, presets:4, exports, fullscreen:true, routeTheme:true});
+      fs.writeFileSync(`${output}/results.json`, JSON.stringify(results,null,2));
+      await context.close();
+    }
+    console.log(`PASS ${results.length} viewports: bidirectional themes, 4 presets, all supported exports decoded, fullscreen and route persistence`);
+  } finally {await browser.close();}
+})().catch(error => {console.error(error); process.exitCode = 1;});

scripts/browser/sdlc-cycle.cjs

@@ -0,0 +1,77 @@
+const {chromium} = require('playwright');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+(async () => {
+  const base = process.argv[2] || 'http://127.0.0.1:4173';
+  const output = `.cache/cycle-${process.argv[3] || 'local'}`;
+  fs.mkdirSync(output, {recursive:true});
+  const browser = await chromium.launch({headless:true, executablePath:process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE, args:['--no-sandbox']});
+  const results = [];
+  try {
+    for (const width of [1440, 390, 320]) {
+      const context = await browser.newContext({viewport:{width,height:1000}, colorScheme:'light'});
+      const page = await context.newPage();
+      await page.goto(`${base}/eldorado-v1/documentation/`, {waitUntil:'networkidle'});
+      if (width < 700) await page.getByRole('button', {name:'Toggle navigation bar'}).click();
+      const nav = page.getByRole('link', {name:'Strategy', exact:true}).filter({visible:true});
+      assert((await nav.getAttribute('href')).endsWith('/strategy/target-operating-model/'));
+      await nav.click();
+      await page.waitForURL('**/strategy/target-operating-model/');
+      for (const route of ['target-operating-model/', '']) {
+        await page.goto(`${base}/eldorado-v1/documentation/strategy/${route}`, {waitUntil:'networkidle'});
+        if (width === 1440) assert.equal(await page.locator('.theme-doc-sidebar-menu .menu__link').first().innerText(), 'Target');
+        const iframe = page.locator(`.archify-panel--story > .story-${width > 700 ? 'desktop' : 'mobile'}`);
+        await iframe.scrollIntoViewIfNeeded();
+        const frame = await (await iframe.elementHandle()).contentFrame();
+        await frame.locator('svg[role="img"]').waitFor();
+        const metrics = await frame.evaluate(() => {
+          const svg = document.querySelector('svg[role="img"]');
+          const labels = [...svg.querySelectorAll('text[data-node-label]')].map(n => ({text:n.textContent,px:parseFloat(getComputedStyle(n).fontSize)*n.getScreenCTM().a}));
+          const edges = [...svg.querySelectorAll('path[data-edge-id^="stage-"]')].map(n => [n.dataset.edgeFrom,n.dataset.edgeTo,n.getAttribute('marker-end')]);
+          const overflow = [...svg.querySelectorAll('[data-node-id]')].flatMap(n => {
+            const box = n.querySelector('rect').getBoundingClientRect();
+            return [...n.querySelectorAll('text')].filter(t => {const b=t.getBoundingClientRect();return b.left<box.left||b.right>box.right||b.top<box.top||b.bottom>box.bottom;}).map(t=>t.textContent);
+          });
+          const relationships = [...svg.querySelectorAll('path[data-edge-id]')].map(n => ({id:n.dataset.edgeId,from:n.dataset.edgeFrom,to:n.dataset.edgeTo,dash:getComputedStyle(n).strokeDasharray,arrow:n.getAttribute('marker-end')}));
+          const nodes = [...svg.querySelectorAll('[data-node-id]')].map(n => {const r=n.querySelector('rect').getBoundingClientRect();return {id:n.dataset.nodeId,x:r.x+r.width/2,y:r.y+r.height/2};});
+          return {labels,edges,overflow,relationships,nodes};
+        });
+        const ids = ['scope','architecture','ui-ux','planning','delivery','uat','security','releases'];
+        assert.deepEqual(metrics.edges.map(e=>e.slice(0,2)), ids.map((id,i)=>[id,ids[(i+1)%ids.length]]));
+        assert(metrics.edges.every(e=>e[2]?.startsWith('url(')), 'all stages must have arrowheads');
+        assert.equal(metrics.nodes.length, 17);
+        assert(!metrics.nodes.some(n=>n.id==='humans'));
+        assert.equal(await frame.locator('[data-node-id="agent"] text').allTextContents().then(texts=>texts.includes('Human Controlled')), true);
+        assert.equal(metrics.relationships.length, 24);
+        const governs = metrics.relationships.filter(e=>e.id.startsWith('govern-'));
+        const contributions = metrics.relationships.filter(e=>e.id.startsWith('contribute-'));
+        assert.deepEqual(governs.map(e=>[e.from,e.to]), ids.map(id=>['agent',id]));
+        assert.deepEqual(contributions.map(e=>[e.from,e.to]), ids.map(id=>[`code-${id}`,id]));
+        assert(governs.every(e=>e.dash==='3px, 9px' && e.arrow?.startsWith('url(')));
+        assert(contributions.every(e=>e.dash==='12px, 8px' && e.arrow?.startsWith('url(')));
+        assert(!metrics.relationships.some(e=>e.id==='human-direction' || e.from==='humans' || e.to==='humans'));
+        if (width > 700) {
+          const agent = metrics.nodes.find(n=>n.id==='agent');
+          const phases = metrics.nodes.filter(n=>ids.includes(n.id));
+          for (const axis of ['x','y']) assert(Math.abs(agent[axis]-(Math.min(...phases.map(n=>n[axis]))+Math.max(...phases.map(n=>n[axis])))/2)<1);
+          for (const id of ids) {
+            const phase=phases.find(n=>n.id===id), code=metrics.nodes.find(n=>n.id===`code-${id}`);
+            assert(Math.hypot(code.x-agent.x,code.y-agent.y)>Math.hypot(phase.x-agent.x,phase.y-agent.y));
+          }
+        }
+        assert(metrics.labels.every(n=>n.px>=14), JSON.stringify(metrics.labels));
+        assert.deepEqual(metrics.overflow, []);
+        assert(!await page.evaluate(()=>document.documentElement.scrollWidth>innerWidth));
+        await page.evaluate(()=>scrollTo({top:0,behavior:'instant'}));
+        await page.waitForFunction(()=>scrollY===0);
+        await page.evaluate(()=>new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve))));
+        await page.screenshot({path:`${output}/${width}-${route ? 'target' : 'landing'}.png`,fullPage:true});
+        results.push({width,route,...metrics});
+        fs.writeFileSync(`${output}/results.json`,JSON.stringify(results,null,2));
+      }
+      await context.close();
+    }
+    assert.equal(results.length,6);
+    console.log('PASS 6 cycle routes/viewports: navigation, sidebar order, exact directed loop, arrowheads, >=14px labels, text bounds and no overflow');
+  } finally {await browser.close();}
+})().catch(error=>{console.error(error);process.exitCode=1;});

scripts/browser/strategy-story.cjs

@@ -0,0 +1,46 @@
+const {chromium}=require('playwright');
+const assert=require('node:assert/strict');
+const fs=require('node:fs');
+(async()=>{
+ const base=process.argv[2]||'http://127.0.0.1:4173';
+ const label=process.argv[3]||'accepted';
+ const browser=await chromium.launch({headless:true,executablePath:process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE,args:['--no-sandbox']});
+ const results=[];fs.mkdirSync(`.cache/story-${label}`,{recursive:true});
+ try{
+ for(const width of [1440,390]){
+  const context=await browser.newContext({viewport:{width,height:1000}});
+  const page=await context.newPage();
+  for(const id of ['index','target-operating-model','skills-governance','skills-quality','skills-adoption','measurement','skills-maintenance','roadmap']){
+   const response=await page.goto(`${base}/eldorado-v1/documentation/strategy/${id==='index'?'':id+'/'}`,{waitUntil:'networkidle'});assert.equal(response.status(),200);
+   const panel=page.locator('.archify-panel--story');
+   const iframe=panel.locator(width===390?'.story-mobile':'.story-desktop');await iframe.scrollIntoViewIfNeeded();
+   const frame=await (await iframe.elementHandle()).contentFrame();await frame.locator('svg[role="img"]').waitFor();
+   const geometry=await frame.locator('svg[role="img"]').evaluate(svg=>{
+    const nodes=[...svg.querySelectorAll('[data-node-id]')].map(n=>{const r=n.getBoundingClientRect();return {id:n.id,x:r.x,y:r.y,right:r.right,bottom:r.bottom};});
+    return {width:innerWidth,height:innerHeight,nodes,svg:svg.getBoundingClientRect().toJSON(),minLabel:Math.min(...[...svg.querySelectorAll('text[data-node-label]')].map(n=>parseFloat(getComputedStyle(n).fontSize)*n.getScreenCTM().a))};
+   });
+   assert(geometry.nodes.length>=5 && geometry.nodes.length<=(['index','target-operating-model'].includes(id)?18:7),id);
+   for(const n of geometry.nodes) assert(n.x>=0 && n.y>=0 && n.right<=geometry.width+1 && n.bottom<=geometry.height+1,`${id} ${width} clipped ${JSON.stringify(n)} / ${geometry.height}`);
+   const data=await page.locator('.strategy-content').evaluate(el=>({words:el.innerText.trim().split(/\s+/).length,overflow:document.documentElement.scrollWidth>innerWidth,openDetails:el.querySelectorAll('details[open]').length}));
+   assert(data.words<=200,id);assert(!data.overflow,id);assert.equal(data.openDetails,0,id);
+   await page.evaluate(()=>scrollTo({top:0,behavior:'instant'}));await page.screenshot({path:`.cache/story-${label}/${width}-${id}.png`,fullPage:true});
+   const opener=panel.getByRole('button',{name:/^Expand /});await opener.click();
+   const close=panel.getByRole('button',{name:'Close full-screen diagram',exact:true});await close.waitFor({state:'visible'});
+   assert.equal(await close.innerText(),'×');assert(await close.evaluate(n=>n===document.activeElement));
+   const box=await close.boundingBox();assert.equal(box.width,44);assert.equal(box.height,44);
+   await close.click();assert(await opener.evaluate(n=>n===document.activeElement));
+   await opener.click();await close.waitFor({state:'visible'});await page.keyboard.press('Escape');await page.waitForFunction(()=>!document.querySelector('.archify-panel--story dialog').open);assert(await opener.evaluate(n=>n===document.activeElement));
+   const summary=page.locator('.strategy-content > details > summary').first();
+   await summary.focus();await page.keyboard.press('Enter');
+   await page.waitForFunction(()=>document.querySelector('.strategy-content > details').open);
+   await page.keyboard.press('Enter');
+   results.push({id,width,...data,geometry,modalClick:true,modalEscape:true,focusRestored:true,details:true});fs.writeFileSync(`.cache/story-${label}/results.json`,JSON.stringify(results,null,2));
+  }
+  await page.goto(`${base}/eldorado-v1/documentation/strategy/measurement/#validated-task-success`,{waitUntil:'networkidle'});
+  const heading=page.locator('#validated-task-success');await heading.waitFor({state:'visible'});
+  assert(await heading.evaluate(n=>n.closest('details').open),'hash should open metric reference');
+  await context.close();
+ }
+ console.log(`PASS ${results.length} desktop/mobile cases, clipping, default word count, details, modal click/Escape/focus and KPI hash navigation`);
+ } finally {await browser.close();}
+})().catch(e=>{console.error(e);process.exitCode=1});

scripts/build-diagrams.mjs

@@ -0,0 +1,54 @@
+import {readdirSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, renameSync, rmSync} from 'node:fs';
+import {join} from 'node:path';
+import {execFileSync} from 'node:child_process';
+const cli = 'vendor/archify/bin/archify.mjs';
+const types = new Set(['architecture','workflow','sequence','dataflow','lifecycle']);
+const inlineStyles = readFileSync(new URL('./inline-viewer.css', import.meta.url), 'utf8');
+const cycleStyles = readFileSync(new URL('./cycle-viewer.css', import.meta.url), 'utf8');
+const themeBridge = readFileSync(new URL('./viewer-theme-bridge.js', import.meta.url), 'utf8');
+// This directory is generated-only and ignored by Git. Remove stale artifacts.
+rmSync('static/diagrams', {recursive: true, force: true});
+mkdirSync('static/diagrams', {recursive: true});
+mkdirSync('.cache/archify', {recursive: true});
+const names = new Set();
+for (const file of readdirSync('diagrams').sort()) {
+  const match = /^([a-z0-9]+(?:-[a-z0-9]+)*)\.([a-z]+)\.json$/.exec(file);
+  if (!match || !types.has(match[2])) throw new Error(`Unsupported diagram source: ${file}`);
+  const [,name,type] = match;
+  if (names.has(name)) throw new Error(`Duplicate diagram output: ${name}`);
+  names.add(name);
+  const input = join('diagrams',file);
+  const spec = JSON.parse(readFileSync(input,'utf8'));
+  const output = `static/diagrams/${name}/index.html`;
+  mkdirSync(`static/diagrams/${name}`, {recursive: true});
+  if (spec.diagram_type !== type || spec.meta.output !== output) throw new Error(`Diagram type/output mismatch: ${file}`);
+  const run = args => execFileSync(process.execPath,[cli,...args],{stdio:'inherit',env:{...process.env,ARCHIFY_UPDATE_CHECK_DISABLED:'1'}});
+  run(['validate',type,input,'--quality','showcase','--json']);
+  run(['deliver',type,input,output,'--quality','showcase','--json']);
+  run(['check',output,'--json','--require-provenance']);
+  // Verify the upstream artifact first, then add the scoped portal integration.
+  let viewer = readFileSync(output, 'utf8');
+  // Upstream intentionally disables preset selection in gallery embeds. Enable
+  // only those two guards; fail closed if a future vendor update changes them.
+  const start = viewer.indexOf('Archify.preset = (function () {');
+  const end = viewer.indexOf('Archify.theme = (function () {', start);
+  const preset = viewer.slice(start, end);
+  const guard = "if (html.getAttribute('data-embed') === 'true') return false;";
+  if (start < 0 || end < start || preset.split(guard).length !== 3) throw new Error('Archify preset integration drift');
+  viewer = viewer.slice(0, start) + preset.replaceAll(guard, '') + viewer.slice(end);
+  if (!viewer.includes('</head>') || !viewer.includes('</body>')) throw new Error(`Invalid viewer: ${output}`);
+  const storyStyles = ['strategy-target', 'strategy-target-mobile'].includes(name)
+    ? `${name === 'strategy-target' ? ':root {--cycle-label: 27px; --cycle-detail: 21px;}' : ':root {--cycle-label: 38px; --cycle-detail: 28px;}'}${cycleStyles}` : '';
+  if (storyStyles) {
+    // Keep typography and relationship styles inside exported standalone SVGs.
+    const diagramRoot = /<svg\b[^>]*role="img"[^>]*>/g;
+    if ([...viewer.matchAll(diagramRoot)].length !== 1) throw new Error('Cycle SVG integration drift');
+    const exportStyles = storyStyles.replaceAll(':root', 'svg[role="img"]').replaceAll('.diagram-container > svg', 'svg[role="img"]');
+    viewer = viewer.replace(diagramRoot, root => `${root}<style id="eldorado-cycle-export">${exportStyles}</style>`);
+  }
+  writeFileSync(output, viewer.replace('</head>', `<style id="eldorado-inline-controls">${inlineStyles}</style><style id="eldorado-cycle-labels">${storyStyles}</style></head>`)
+    .replace('</body>', `<script>${themeBridge}</script></body>`));
+  renameSync(`static/diagrams/${name}/index.delivery.json`, `.cache/archify/${name}.delivery.json`);
+}
+copyFileSync('vendor/archify/LICENSE','static/diagrams/ARCHIFY-LICENSE.txt');
+copyFileSync('vendor/archify/THIRD_PARTY_NOTICES.md','static/diagrams/THIRD-PARTY-NOTICES.md');

scripts/cycle-viewer.css

@@ -0,0 +1,19 @@
+/* Readable lifecycle story at inline scale, isolated from other diagrams. */
+.diagram-container > svg text {
+  font-family: Arial, sans-serif;
+  letter-spacing: 0;
+  font-size: 30px;
+}
+.diagram-container > svg text[data-node-label] {
+  font-size: var(--cycle-label);
+  transform: translateY(-6px);
+}
+.diagram-container > svg text[data-detail="context"] {
+  font-size: var(--cycle-detail);
+  transform: translateY(16px);
+}
+/* Edge semantics stay in SVG metadata; one page legend avoids repeated labels. */
+.diagram-container > svg g[data-edge-id] {display: none;}
+.diagram-container > svg path[data-edge-id^="stage-"] {stroke-width: 2.5;}
+.diagram-container > svg path[data-edge-id^="govern-"] {stroke-dasharray: 3 9; stroke-width: 3;}
+.diagram-container > svg path[data-edge-id^="contribute-"] {stroke-dasharray: 12 8; stroke-width: 3;}

scripts/fixtures/ai-kpi-synthetic.json

@@ -0,0 +1,37 @@
+{
+  "synthetic": true,
+  "label": "SYNTHETIC — illustrative, not Eldorado observations",
+  "schema_version": "1.0",
+  "start": "2026-01-01T00:00:00Z",
+  "end": "2026-01-05T00:00:00Z",
+  "as_of": "2026-01-05T00:00:00Z",
+  "events": [
+    {"producer":"synthetic","event_id":"sa","task_id":"accepted","event_type":"task.started","occurred_at":"2026-01-01T00:00:00Z","received_at":"2026-01-01T00:00:00Z","horizon_hours":48},
+    {"producer":"synthetic","event_id":"sf","task_id":"failed","event_type":"task.started","occurred_at":"2026-01-01T00:00:00Z","received_at":"2026-01-01T00:00:00Z","horizon_hours":48},
+    {"producer":"synthetic","event_id":"sb","task_id":"abandoned","event_type":"task.started","occurred_at":"2026-01-01T00:00:00Z","received_at":"2026-01-01T00:00:00Z","horizon_hours":48},
+    {"producer":"synthetic","event_id":"su","task_id":"unknown","event_type":"task.started","occurred_at":"2026-01-01T00:00:00Z","received_at":"2026-01-01T00:00:00Z","horizon_hours":48},
+    {"producer":"synthetic","event_id":"a","task_id":"accepted","event_type":"task.accepted","occurred_at":"2026-01-02T00:00:00Z","received_at":"2026-01-02T00:00:00Z","independent_evidence":true},
+    {"producer":"synthetic","event_id":"f","task_id":"failed","event_type":"task.failed","occurred_at":"2026-01-02T00:00:00Z","received_at":"2026-01-02T00:00:00Z"},
+    {"producer":"synthetic","event_id":"b","task_id":"abandoned","event_type":"task.abandoned","occurred_at":"2026-01-02T00:00:00Z","received_at":"2026-01-02T00:00:00Z"},
+    {"producer":"synthetic","event_id":"new","task_id":"immature","event_type":"task.started","occurred_at":"2026-01-04T00:00:00Z","received_at":"2026-01-04T00:00:00Z","horizon_hours":48}
+  ],
+  "selection": [
+    {"id":"trial-a","relevant":true,"activated":true},
+    {"id":"trial-b","relevant":false,"activated":true},
+    {"id":"trial-c","relevant":true,"activated":false},
+    {"id":"trial-d","relevant":null,"activated":null}
+  ],
+  "deployments": [{"service_id":"service-a","deployment_id":"deploy-a","environment":"production","production_effect":true,"succeeded":true,"intervention":true,"planned":false,"incident_id":"incident-a","deployed_at":"2026-01-02T00:00:00Z","followup_hours":24}],
+  "changes": [{"id":"change-a","accepted_at":"2026-01-01T00:00:00Z","followup_hours":48,"linkage_complete":true}],
+  "defects": [{"id":"defect-a","change_id":"change-a","confirmed":true,"detected_at":"2026-01-02T00:00:00Z"}],
+  "attempts": [{"id":"attempt-a","actual_effect":false,"blocked":true},{"id":"attempt-b","actual_effect":true,"blocked":false}],
+  "costs": [{"id":"cost-a","task_id":"accepted","amount":40,"currency":"EUR","bucket":"compute"},{"id":"cost-f","task_id":"failed","amount":20,"currency":"EUR","bucket":"compute"}],
+  "currency":"EUR",
+  "expected_cost_buckets":["compute","licenses","tooling","review","rework"],
+  "survey": {"invited":10,"responses":[{"id":"token-a","score":4},{"id":"token-b","score":5},{"id":"token-c","score":3},{"id":"token-d","score":4},{"id":"token-e","score":4}]},
+  "associations": [
+    {"task_id":"accepted","skill_id":"synthetic-skill","revision":"revision-a","client":"Cline"},
+    {"task_id":"accepted","skill_id":"synthetic-skill","revision":"revision-b","client":"Cline"},
+    {"task_id":"unknown","skill_id":"synthetic-skill","revision":null,"client":"Claude Code","missing_reason":"not_exposed"}
+  ]
+}

scripts/inline-viewer.css

@@ -0,0 +1,33 @@
+/* Portal integration only; keep the upstream renderer and export code pinned. */
+html[data-embed="true"] .toolbar {
+  display: flex !important;
+  position: relative;
+  inset: auto;
+  justify-content: flex-end;
+  height: 52px;
+  padding: 4px 8px;
+  box-sizing: border-box;
+  background: var(--bg);
+}
+html[data-embed="true"] #btn-present,
+html[data-embed="true"] #btn-motion { display: none !important; }
+html[data-embed="true"] .diagram-container > svg {
+  max-height: calc(100vh - 68px);
+}
+html[data-embed="true"] .toolbar .preset-menu,
+html[data-embed="true"] .toolbar .export-menu {
+  position: fixed;
+  top: 52px;
+  left: auto;
+  right: 0;
+  width: min(320px, 100vw);
+  max-width: 100vw;
+  max-height: calc(100vh - 52px);
+  overflow-y: auto;
+  box-sizing: border-box;
+}
+/* Keep the preset menu in the iframe viewport without moving its capsule. */
+html[data-embed="true"] .toolbar .export-wrap { position: static; }
+html[data-embed="true"] .toolbar .export-menu { position: absolute; top: 100%; }
+html[data-embed="true"] .toolbar .preset-menu button,
+html[data-embed="true"] .toolbar .export-menu button { min-height: 44px; }

scripts/inline-viewer.test.mjs

@@ -0,0 +1,51 @@
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {readFileSync} from 'node:fs';
+import {runInNewContext} from 'node:vm';
+const read = path => readFileSync(path, 'utf8');
+
+test('both story layouts permit downloads without weakening origin isolation', () => {
+  const wrapper = read('src/components/ArchifyDiagram/index.tsx');
+  for (const layout of ['desktop', 'mobile']) {
+    const iframe = wrapper.split(`<iframe className="story-${layout}"`)[1].split(' />')[0];
+    assert(iframe.includes('sandbox="allow-scripts allow-downloads"'));
+    assert(iframe.includes('?embed=1&theme=${initialTheme.current}'));
+  }
+  assert(!wrapper.includes('allow-same-origin'));
+});
+
+test('build adds maintained embed-only controls without changing pinned vendor', () => {
+  const build = read('scripts/build-diagrams.mjs');
+  assert(build.includes("new URL('./inline-viewer.css', import.meta.url)"));
+  assert(build.includes('eldorado-inline-controls'));
+  const css = read('scripts/inline-viewer.css');
+  assert(css.includes('html[data-embed="true"] .toolbar'));
+  assert(css.includes('display: flex !important'));
+  assert(css.includes('position: relative'));
+  assert(css.includes('max-height: calc(100vh - 52px)'));
+});
+
+test('theme bridge rejects unrelated senders/values and never echoes parent updates', () => {
+  const root = {dataset:{theme:'light'}};
+  let receive, observerCallback, mutations = 0;
+  const messages = [];
+  const parent = {postMessage: message => messages.push(message)};
+  const window = {parent, addEventListener: (type, callback) => {receive = callback;}};
+  const button = {click: () => {root.dataset.theme = root.dataset.theme === 'light' ? 'dark' : 'light'; mutations++;}};
+  class MutationObserver {
+    constructor(callback) {observerCallback = callback;}
+    observe() {}
+    takeRecords() {mutations = 0;}
+  }
+  runInNewContext(read('scripts/viewer-theme-bridge.js'), {window, document:{documentElement:root, getElementById: () => button}, MutationObserver});
+  const send = (source, theme) => receive({source, data:{type:'eldorado:set-theme', theme}});
+  send({}, 'dark'); send(parent, 'invalid');
+  assert.equal(root.dataset.theme, 'light');
+  send(parent, 'dark');
+  assert.equal(root.dataset.theme, 'dark');
+  assert.equal(mutations, 0);
+  assert.equal(messages.length, 0);
+  button.click(); observerCallback();
+  assert.equal(messages.length, 1);
+  assert.equal(messages[0].theme, 'light');
+});

scripts/portal.test.mjs

@@ -0,0 +1,153 @@
+import {test} from 'node:test';
+import {createHash} from 'node:crypto';
+import assert from 'node:assert/strict';
+import {readFileSync, existsSync, mkdtempSync, mkdirSync, writeFileSync, symlinkSync, unlinkSync, rmSync, readdirSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join, resolve} from 'node:path';
+import {spawnSync} from 'node:child_process';
+const read = p => readFileSync(p, 'utf8');
+test('real build removes stale diagrams, keeps receipts private and rejects collisions', () => {
+  const root = mkdtempSync(join(tmpdir(), 'eldorado-diagrams-'));
+  try {
+    mkdirSync(join(root,'diagrams'));
+    symlinkSync(resolve('vendor'),join(root,'vendor'),'dir');
+    const spec = JSON.parse(read('diagrams/organization-structure.architecture.json'));
+    const writeSpec = name => {
+      spec.meta.output = `static/diagrams/${name}/index.html`;
+      writeFileSync(join(root,`diagrams/${name}.architecture.json`),JSON.stringify(spec));
+    };
+    const build = () => spawnSync(process.execPath,[resolve('scripts/build-diagrams.mjs')],{cwd:root,encoding:'utf8'});
+    writeSpec('old');
+    let result = build(); assert.equal(result.status,0,result.stderr);
+    assert(existsSync(join(root,'static/diagrams/old/index.html')));
+    assert(!existsSync(join(root,'static/diagrams/old.json')));
+    assert(!readdirSync(join(root,'static/diagrams'),{recursive:true}).some(p=>p.endsWith('.delivery.json')));
+    unlinkSync(join(root,'diagrams/old.architecture.json'));
+    writeSpec('new');
+    result=build(); assert.equal(result.status,0,result.stderr);
+    assert(!existsSync(join(root,'static/diagrams/old')));
+    assert(!existsSync(join(root,'static/diagrams/old.json')));
+    writeFileSync(join(root,'diagrams/new.workflow.json'),JSON.stringify(spec));
+    result=build(); assert.notEqual(result.status,0);
+    assert(result.stderr.includes('Duplicate diagram output'));
+  } finally {rmSync(root,{recursive:true,force:true});}
+});
+test('vendored source matches the reviewed upstream snapshot', () => {
+  const checksums = JSON.parse(read('vendor/archify-checksums.json'));
+  for (const [path, hash] of Object.entries(checksums)) {
+    assert.equal(createHash('sha256').update(readFileSync(`vendor/archify/${path}`)).digest('hex'), hash, path);
+  }
+});
+test('three independent section menus and Structure first', () => {
+  const config = read('docusaurus.config.ts');
+  for (const section of ['Organization', 'Strategy', 'Contribution']) assert(config.includes(`label: '${section}'`));
+  assert(!config.includes("label: 'Documentation'"));
+  assert(!config.includes("label: 'Maintainer guide'"));
+  assert(read('sidebars/organization.ts').includes("organizationSidebar: ['structure', 'collaboration', 'sdlc']"));
+  for (const section of ['organization','strategy','contribution']) assert(config.includes(`id: '${section}'`));
+});
+test('Archify is pinned, licensed and rebuilt, not a remote embed', () => {
+  const provenance = JSON.parse(read('vendor/archify-provenance.json'));
+  assert.equal(provenance.commit, 'd5a1333d7447c866a765adac7d4d062f2f02e4d2');
+  assert(read('vendor/archify/LICENSE').includes('MIT License'));
+  const scripts = JSON.parse(read('package.json')).scripts;
+  assert(scripts.build.startsWith('pnpm diagrams:build'));
+  const wrapper = read('src/components/ArchifyDiagram/index.tsx');
+  assert(wrapper.includes('sandbox="allow-scripts allow-downloads"'));
+  assert(!wrapper.includes('allow-same-origin'));
+  assert(wrapper.includes('useBaseUrl'));
+  assert(wrapper.includes('showModal()') && wrapper.includes('onClose='));
+  assert(!wrapper.includes('target="_blank"'));
+  assert(wrapper.includes('Close full-screen diagram'));
+  assert(!wrapper.includes('JSON source') && !wrapper.includes('download>'));
+  assert(!wrapper.includes('Open full viewer'));
+  assert(wrapper.includes('aria-label={`Expand ${title}`}'));
+  assert(wrapper.includes('aria-hidden="true"'));
+  assert(read('src/css/custom.css').includes('justify-content: flex-end'));
+});
+test('full-screen close is cross-only with an accessible name and square touch target', () => {
+  const wrapper = read('src/components/ArchifyDiagram/index.tsx');
+  const button = wrapper.match(/<button[^>]*aria-label="Close full-screen diagram"[^>]*>(.*?)<\/button>/s);
+  assert(button, 'close button retains its accessible name');
+  assert.equal(button[1], '<span aria-hidden="true">×</span>');
+  assert(button[0].includes('autoFocus') && button[0].includes('onClick={close}'));
+  const styles = read('src/css/custom.css').match(/\.archify-modal-toolbar button \{([^}]+)\}/)[1];
+  assert(styles.includes('width: 44px') && styles.includes('height: 44px'));
+  assert(styles.includes('padding: 0') && styles.includes('flex-shrink: 0'));
+});
+test('Product owns two teams and Technology owns five separate teams', () => {
+  const spec = JSON.parse(read('diagrams/organization-structure.architecture.json'));
+  const page = read('docs/organization/structure.mdx');
+  assert(!/shared-delivery|squad-/i.test(JSON.stringify(spec)));
+  assert(!/shared squads|share a delivery structure|cross-functional teams/i.test(page));
+  for (const [dept, count, heading, next] of [['product',2,'Product','Technology'],['technology',5,'Technology','Operations']]) {
+    const teams = spec.components.filter(n => n.id.startsWith(`${dept}-team-`));
+    assert.equal(teams.length, count);
+    const section = page.split(`### ${heading}\n`)[1].split(`### ${next}\n`)[0];
+    const rows = section.split('\n').filter(l => l.startsWith('| ')).slice(2);
+    assert.equal(rows.length, count);
+    for (const team of teams) {
+      const parents = spec.connections.filter(e => e.to === team.id);
+      assert.deepEqual(parents.map(e => e.from), [dept]);
+      assert(rows.some(row => row.startsWith(`| ${team.label} |`)));
+    }
+  }
+});
+test('departments share one row and each has delivery teams below it', () => {
+  const spec = JSON.parse(read('diagrams/organization-structure.architecture.json'));
+  const page = read('docs/organization/structure.mdx');
+  const departments = ['product', 'technology', 'operations', 'marketing', 'finance', 'people'];
+  const nodes = new Map(spec.components.map(n => [n.id, n]));
+  assert.equal(new Set(departments.map(id => nodes.get(id).pos[1])).size, 1);
+  for (const [i, id] of departments.entries()) {
+    const department = nodes.get(id);
+    const teams = spec.connections.filter(e => e.from === id).map(e => nodes.get(e.to));
+    assert.equal(teams.length, i === 0 ? 2 : i === 1 ? 5 : 1);
+    for (const team of teams) {
+      assert(team.pos[1] > department.pos[1] + department.size[1]);
+      assert(team.size[0] < department.size[0]);
+      assert.equal(team.pos[0] + team.size[0], department.pos[0] + department.size[0]);
+      const edge = spec.connections.find(e => e.from === id && e.to === team.id);
+      assert.equal(edge.toSide, 'left');
+      assert.equal(edge.fromSide, 'bottom');
+      assert.equal(spec.connections.find(e => e.from === 'management' && e.to === id).toSide, 'top');
+      assert.deepEqual(spec.connections.filter(e => e.to === team.id).map(e => e.from), [id]);
+      assert(page.includes(team.label));
+    }
+  }
+  for (const [i, a] of spec.components.entries()) for (const b of spec.components.slice(i + 1)) {
+    assert(!(a.pos[0] < b.pos[0] + b.size[0] && a.pos[0] + a.size[0] > b.pos[0] && a.pos[1] < b.pos[1] + b.size[1] && a.pos[1] + a.size[1] > b.pos[1]), `${a.id} overlaps ${b.id}`);
+  }
+});
+test('organization content is split into linked focused pages', () => {
+  const structure = read('docs/organization/structure.mdx');
+  const collaboration = read('docs/organization/collaboration.mdx');
+  const sdlc = read('docs/organization/sdlc.mdx');
+  assert(!structure.includes('## How the departments work together'));
+  assert(!structure.includes('## Leadership and delivery structure'));
+  assert(!structure.includes('name="organization-reporting"'));
+  assert(collaboration.includes('## How the departments work together'));
+  for (const outcome of ['Better buyer experience', 'Stronger seller experience', 'Safe and trustworthy trading', 'Sustainable growth', 'AI-powered execution']) assert(collaboration.includes(outcome));
+  assert(sdlc.includes('title: SDLC — Software Delivery Life Cycle'));
+  assert(sdlc.includes('name="organization-reporting"'));
+  for (const role of ['Head of Engineering', 'AI Architect', 'Operational Quality', 'Brand Team Lead']) assert(sdlc.includes(role));
+  for (const [name, page] of [['structure',structure],['collaboration',collaboration],['sdlc',sdlc]]) {
+    for (const other of ['structure','collaboration','sdlc'].filter(n => n !== name)) assert(page.includes(`./${other}.mdx`));
+  }
+});
+test('organization page presents an operating model, not research notes', () => {
+  const page = read('docs/organization/structure.mdx');
+  assert(page.includes('operating model') && page.includes('## Departments and teams'));
+  const prohibited = /assum|job.advert|vacanc|publicly evidenced|research snapshot|## Sources|\[\d+\]|\b[EJA]:\s/i;
+  assert(!prohibited.test(page));
+  assert(page.includes('Vladas Jurkevičius') && page.includes('Lukas Deksnys'));
+  assert(existsSync('research/organization/reconstruction-snapshot.mdx'));
+  assert(JSON.parse(read('research/organization/sources.json')).sources.every(s => s.quotes?.length));
+  for (const name of ['organization-structure', 'organization-reporting']) {
+    const spec = JSON.parse(read(`diagrams/${name}.architecture.json`));
+    assert(!prohibited.test(JSON.stringify(spec)));
+    const ids = new Set(spec.components.map(n => n.id));
+    assert.equal(ids.size, spec.components.length);
+    for (const edge of spec.connections) assert(ids.has(edge.from) && ids.has(edge.to));
+  }
+});

scripts/sdlc-cycle.test.mjs

@@ -0,0 +1,61 @@
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {readFileSync} from 'node:fs';
+const read = p => readFileSync(p, 'utf8');
+const stages = ['Scope', 'Architecture', 'UI/UX', 'Planning', 'Delivery', 'UAT', 'Security', 'Releases'];
+
+test('Strategy opens at the autonomous lifecycle, with a matching direct landing story', () => {
+  assert.match(read('sidebars/strategy.ts'), /strategySidebar: \['target-operating-model', 'index'/);
+  assert.match(read('docs/strategy/target-operating-model.mdx'), /^sidebar_label: Target$/m);
+  for (const id of ['index', 'target-operating-model']) {
+    const page = read(`docs/strategy/${id}.mdx`);
+    const primary = page.split('<details>')[0];
+    assert(primary.includes('name="strategy-target"'));
+    assert(primary.includes('autonomous agent'));
+    assert(primary.includes('direct, guide and review'));
+    assert(primary.includes('Scope → Architecture → UI/UX → Planning → Delivery → UAT → Security → Releases → Scope'));
+    assert(primary.includes('human-controlled code agent'));
+    assert(primary.includes('TO-BE'));
+    assert(!/only routes|People authorize|independent gates protect release/.test(primary));
+  }
+});
+
+test('both target diagrams have eight stages, eight governed phases and eight human-controlled contributors', () => {
+  for (const suffix of ['', '-mobile']) {
+    const d = JSON.parse(read(`diagrams/strategy-target${suffix}.architecture.json`));
+    const ids = stages.map(label => d.components.find(n => n.label === label)?.id);
+    assert(ids.every(Boolean));
+    assert.equal(new Set(ids).size, 8);
+    const flow = d.connections.filter(e => ids.includes(e.from) && ids.includes(e.to));
+    assert.deepEqual(flow.map(e => [e.from, e.to]), ids.map((id, i) => [id, ids[(i + 1) % ids.length]]));
+    assert.match(flow.at(-1).label, /Repeat/);
+
+    assert(d.components.some(n => n.id === 'agent' && n.label === 'Autonomous agent' && n.sublabel === 'Human Controlled'));
+    assert(!d.components.some(n => n.id === 'humans' || n.label === 'Humans'));
+    assert(!d.connections.some(e => e.id === 'human-direction' || e.from === 'humans' || e.to === 'humans'));
+    assert.equal(d.connections.length, 24);
+    assert.deepEqual(d.connections.filter(e => e.from === 'agent').map(e => e.to), ids);
+    const contributors = d.components.filter(n => n.id.startsWith('code-'));
+    assert.equal(contributors.length, 8);
+    assert(contributors.every(n => n.label === 'Code agent' && n.sublabel === 'Human-controlled'));
+    for (const id of ids) {
+      assert(d.connections.some(e => e.from === `code-${id}` && e.to === id && e.variant === 'dashed'));
+      assert(d.connections.some(e => e.from === 'agent' && e.to === id && e.variant === 'security'));
+    }
+    assert.equal(d.components.length, 17);
+    if (!suffix) {
+      const center = n => n.pos.map((v, i) => v + n.size[i] / 2);
+      const agent = center(d.components.find(n => n.id === 'agent'));
+      const phaseCenters = ids.map(id => center(d.components.find(n => n.id === id)));
+      for (const axis of [0, 1]) {
+        const values = phaseCenters.map(c => c[axis]);
+        assert.equal(agent[axis], (Math.min(...values) + Math.max(...values)) / 2);
+      }
+      for (const code of contributors) {
+        const phase = d.components.find(n => n.id === code.id.slice(5));
+        const distance = n => Math.hypot(...center(n).map((v, i) => v - agent[i]));
+        assert(distance(code) > distance(phase), `${code.id} is exterior`);
+      }
+    }
+  }
+});

scripts/strategy-story.test.mjs

@@ -0,0 +1,48 @@
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {readFileSync} from 'node:fs';
+const read = p => readFileSync(p, 'utf8');
+const model = JSON.parse(read('research/ai-adoption/strategy-model.json'));
+
+test('every strategy page leads with a compact diagram story and closes its references', () => {
+  for (const {id} of model.pages) {
+    const page = read(`docs/strategy/${id}.mdx`);
+    const narrative = page.split('<div className="strategy-content">')[1].replace(/<details>[\s\S]*?<\/details>/g, '');
+    assert.equal((narrative.match(/<ArchifyDiagram /g) || []).length, 1, id);
+    assert(narrative.includes(' story />'), id);
+    assert(page.indexOf(' story />') < page.indexOf('<details>'), id);
+    assert(!/<details\s+open/.test(page), id);
+    assert.equal((page.match(/<details>/g) || []).length, (page.match(/<\/details>/g) || []).length, id);
+    assert.equal((narrative.match(/^## /gm) || []).length, 1, id);
+    assert((narrative.match(/^- /gm) || []).length <= 3, id);
+    assert(narrative.includes('**Next:**'), id);
+    assert(!narrative.includes('| ---'), id);
+    const words = narrative.replace(/<[^>]*>/g, '').trim().split(/\s+/).length;
+    assert(words <= 200, `${id}: ${words} default narrative words`);
+  }
+});
+
+test('mobile story diagrams preserve the same nodes and directed relationships', () => {
+  for (const {id} of model.pages) {
+    const page = read(`docs/strategy/${id}.mdx`);
+    const name = /<ArchifyDiagram name="([^"]+)"[^>]+ story/.exec(page)[1];
+    const desktop = JSON.parse(read(`diagrams/${name}.architecture.json`));
+    const mobile = JSON.parse(read(`diagrams/${name}-mobile.architecture.json`));
+    assert(desktop.components.length >= 5 && desktop.components.length <= (name === 'strategy-target' ? 18 : 7), name);
+    const semantic = d => ({nodes:d.components.map(({pos,size,...n})=>n),edges:d.connections.map(({fromSide,toSide,via,labelAt,...e})=>e)});
+    assert.deepEqual(semantic(desktop), semantic(mobile), name);
+    assert(desktop.connections.every(e => (e.label || e.id.startsWith('govern-')) && e.from !== e.to), name);
+    assert.equal(desktop.meta.legend.mode, 'hidden');
+  }
+});
+
+test('all sixteen exact KPI formulas remain reachable in the closed reference', () => {
+  const page = read('docs/strategy/measurement.mdx');
+  const contracts = page.split('<summary>All 16 KPI contracts')[1].split('</details>')[0];
+  assert.equal((contracts.match(/^### /gm) || []).length, 16);
+  for (const metric of model.kpis) {
+    const section = contracts.split(`### ${metric.name}\n`)[1]?.split('\n### ')[0];
+    assert(section, metric.name);
+    for (const label of ['Numerator','Denominator','Expression','Aggregation','Unit','Eligible population','Exclusions','Events and source','Owner / cadence','Missing evidence','Gaming and limits']) assert(section.includes(`| ${label} |`), `${metric.name}: ${label}`);
+  }
+});

scripts/strategy.test.mjs

@@ -0,0 +1,40 @@
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {readFileSync, readdirSync} from 'node:fs';
+const read = p => readFileSync(p, 'utf8');
+const model = JSON.parse(read('research/ai-adoption/strategy-model.json'));
+test('eight fixed strategy pages preserve target boundary and separate evidence', () => {
+  assert.equal(model.pages.length, 8);
+  assert.equal(readdirSync('docs/strategy').length, 8);
+  for (const {id} of model.pages) {
+    const page = read(`docs/strategy/${id}.mdx`);
+    assert(page.includes(`id: ${id}`));
+    assert(page.includes('Target operating model'));
+    assert(!/## Sources|\[\d+\]|Internal evidence mapping/.test(page));
+    assert(read('sidebars/strategy.ts').includes(`'${id}'`));
+  }
+  for (const teams of Object.values(model.organization)) for (const name of teams) {
+    assert(read('docs/organization/structure.mdx').includes(name));
+    assert(read('docs/strategy/target-operating-model.mdx').includes(name));
+  }
+});
+test('every metric has an actionable reader-facing contract', () => {
+  const page = read('docs/strategy/measurement.mdx');
+  assert.equal(model.kpis.length,16);
+  for (const k of model.kpis) {
+    const section=page.split(`### ${k.name}\n`)[1]?.split('\n### ')[0];
+    assert(section,k.name);
+    for (const field of ['Eligible population','Exclusions','Events and source','Owner / cadence','Missing evidence','Gaming and limits']) assert(section.includes(`| ${field} |`));
+    assert(section.includes(k.owner));
+  }
+  assert(page.includes('synthetic') && page.includes('not a production ingestion system'));
+});
+test('diagram preserves independent release approval and no agent production authority', () => {
+  const d=JSON.parse(read('diagrams/ai-adoption-target.architecture.json'));
+  assert(d.meta.title.startsWith('TO-BE'));
+  assert.equal(d.components.filter(n=>n.id==='coordinator').length,1);
+  assert.deepEqual(d.connections.filter(e=>e.to==='release').map(e=>e.from),['approval']);
+  for (const [from,to] of [['registry','coordinator'],['registry','clients'],['clients','gates'],['gates','approval'],['release','audit'],['audit','people']]) assert(d.connections.some(e=>e.from===from&&e.to===to));
+  assert(!d.connections.some(e=>['clients','coordinator'].includes(e.from)&&['release','approval'].includes(e.to)));
+  assert(d.boundaries.some(b=>b.wraps.includes('gates')&&b.wraps.includes('release')));
+});

scripts/verify.mjs

@@ -6,7 +6,7 @@ const config = read('docusaurus.config.ts');
 assert(config.includes("baseUrl: '/eldorado-v1/documentation/'"));
 assert(config.includes("onBrokenLinks: 'throw'"));
 assert(config.includes("hashed: 'filename'"));
-for (const file of readdirSync('docs')) {
+for (const file of readdirSync('docs', {recursive: true}).filter(f => /\.mdx?$/.test(f))) {
   const doc = read(join('docs', file));
   assert(/^---\n[\s\S]*?title: .+\n[\s\S]*?description: .+\n/.test(doc), `Missing metadata: ${file}`);
 }
@@ -16,9 +16,41 @@ const workflow = read('.gitea/workflows/pages.yml');
 assert(workflow.includes('mountpoint -q'));
 assert(workflow.includes("gitea.event_name == 'push' && gitea.ref == 'refs/heads/main'"));
 if (process.argv.includes('--build')) {
-  for (const route of ['index.html','docs/overview/index.html','docs/maintain/index.html','docs/reference/index.html','404.html']) {
+  const model = JSON.parse(read('research/ai-adoption/strategy-model.json'));
+  const indexes = readdirSync('build').filter(f => /^search-index.*\.json$/.test(f)).map(f => read(join('build',f))).join('\n');
+  for (const {id, title} of model.pages) {
+    const route = `strategy/${id === 'index' ? '' : `${id}/`}index.html`;
+    const page = read(join('build',route));
+    assert(page.includes(title) && page.includes('Target operating model'), route);
+    assert(indexes.includes(title), `Missing indexed Strategy page: ${id}`);
+    for (const match of page.matchAll(/href="(\/eldorado-v1\/documentation\/[^"?#]*)/g)) {
+      const local = decodeURIComponent(match[1].replace('/eldorado-v1/documentation/',''));
+      assert(existsSync(join('build', local.endsWith('/') ? `${local}index.html` : local)), `Broken built link: ${local}`);
+    }
+  }
+  assert(!existsSync('build/research'), 'Background research must remain private source');
+  assert(!readdirSync('build/diagrams', {recursive:true}).some(f => f.endsWith('.json')), 'No public diagram JSON');
+  assert(read('build/diagrams/ai-adoption-target/index.html').includes('TO-BE'));
+  for (const route of ['index.html','docs/overview/index.html','docs/maintain/index.html','docs/reference/index.html','404.html','organization/structure/index.html','organization/collaboration/index.html','organization/sdlc/index.html','strategy/index.html','contribution/index.html','contribution/diagrams/index.html','diagrams/organization-structure/index.html']) {
     assert(existsSync(join('build',route)), `Missing route: ${route}`);
   }
+  assert(!readdirSync('build/diagrams', {recursive: true}).some(f => f.endsWith('.delivery.json')), 'Private build receipts must not be published');
+  const diagram = read('build/diagrams/organization-structure/index.html');
+  assert(diagram.includes('node-product-team-2') && diagram.includes('node-technology-team-5'));
+  assert(!diagram.includes('shared-delivery'));
+  assert(!/A: placement|E: careers|J: advertised/.test(diagram));
+  assert(!diagram.includes('Example leadership'));
+  for (const [dept, count] of [['product', 2], ['technology', 5]]) {
+    for (let i = 1; i <= count; i++) assert(diagram.includes(`node-${dept}-team-${i}`));
+  }
+  const reporting = read('build/diagrams/organization-reporting/index.html');
+  assert(reporting.includes('AI Architect') && reporting.includes('Leads'));
+  assert(!/A: assumed|J: direct/.test(reporting));
+  const structure = read('build/organization/structure/index.html');
+  assert(structure.includes('Vladas Jurkevičius') && structure.includes('operating model'));
+  assert(!/Research snapshot|Job-advertised|careers\.eldorado\.gg|Assumed/.test(structure));
+  assert(!structure.includes('Illustrative integration example'));
+  assert(!diagram.includes('/opt/data/'), 'No build paths in published diagrams');
   const home = read('build/index.html');
   assert(/<title\b[^>]*>Eldorado Powered By AI<\/title>/.test(home));
   assert(home.includes('Powered By AI</span></h1>'));

scripts/viewer-theme-bridge.js

@@ -0,0 +1,21 @@
+// Sandboxed viewers have opaque origins: authenticate the sender by WindowProxy,
+// not origin. Only exchange a validated theme, never HTML, URLs or commands.
+(() => {
+  if (window.parent === window) return;
+  let connected = false;
+  window.addEventListener('message', event => {
+    if (event.source !== window.parent || event.data?.type !== 'eldorado:set-theme') return;
+    const theme = event.data.theme;
+    if (theme !== 'light' && theme !== 'dark') return;
+    connected = true;
+    if (document.documentElement.dataset.theme !== theme) {
+      document.getElementById('btn-theme').click();
+      // Parent updates are not new user choices; do not echo stale acknowledgements.
+      observer.takeRecords();
+    }
+  });
+  const observer = new MutationObserver(() => {
+    if (connected) window.parent.postMessage({type: 'eldorado:theme', theme: document.documentElement.dataset.theme}, '*');
+  });
+  observer.observe(document.documentElement, {attributes: true, attributeFilter: ['data-theme']});
+})();

sidebars/contribution.ts

@@ -0,0 +1,2 @@
+import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
+export default {contributionSidebar: ['contribute', 'diagrams']} satisfies SidebarsConfig;

sidebars/organization.ts

@@ -0,0 +1,2 @@
+import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
+export default {organizationSidebar: ['structure', 'collaboration', 'sdlc']} satisfies SidebarsConfig;

sidebars/strategy.ts

@@ -0,0 +1,2 @@
+import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
+export default {strategySidebar: ['target-operating-model', 'index', 'skills-governance', 'skills-quality', 'skills-adoption', 'measurement', 'skills-maintenance', 'roadmap']} satisfies SidebarsConfig;

src/components/ArchifyDiagram/index.tsx

@@ -0,0 +1,71 @@
+import React, {useEffect, useId, useRef, useState} from 'react';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import {useLocation} from '@docusaurus/router';
+import {useColorMode} from '@docusaurus/theme-common';
+
+export default function ArchifyDiagram({name, title, compact = false, story = false}: {name: string; title: string; compact?: boolean; story?: boolean}): React.ReactElement {
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) throw new Error('Invalid diagram name');
+  const source = useBaseUrl(`/diagrams/${name}/`);
+  const mobileSource = useBaseUrl(`/diagrams/${name}-mobile/`);
+  const dialog = useRef<HTMLDialogElement>(null);
+  const opener = useRef<HTMLButtonElement>(null);
+  const headingId = useId();
+  const [expanded, setExpanded] = useState(false);
+  const {colorMode, setColorMode} = useColorMode();
+  const initialTheme = useRef(colorMode);
+  const desktop = useRef<HTMLIFrameElement>(null);
+  const mobile = useRef<HTMLIFrameElement>(null);
+  const fullscreen = useRef<HTMLIFrameElement>(null);
+  const syncTheme = (frame: HTMLIFrameElement | null) => frame?.contentWindow?.postMessage({type: 'eldorado:set-theme', theme: colorMode}, '*');
+  useEffect(() => {
+    for (const frame of [desktop, mobile, fullscreen]) syncTheme(frame.current);
+    const receiveTheme = (event: MessageEvent) => {
+      if (!event.source || ![desktop, mobile, fullscreen].some(frame => frame.current?.contentWindow === event.source)) return;
+      if (event.data?.type !== 'eldorado:theme' || !['light', 'dark'].includes(event.data.theme)) return;
+      if (event.data.theme !== colorMode) setColorMode(event.data.theme);
+    };
+    window.addEventListener('message', receiveTheme);
+    return () => window.removeEventListener('message', receiveTheme);
+  }, [colorMode, setColorMode, expanded]);
+  const {pathname, hash} = useLocation();
+  useEffect(() => {
+    if (!story || !hash) return;
+    let id: string;
+    try {id = decodeURIComponent(hash.slice(1));} catch {return;}
+    const frame = requestAnimationFrame(() => {
+      const target = document.getElementById(id);
+      if (!target?.closest('.strategy-content')) return;
+      let detail = target.closest('details');
+      if (!detail) return;
+      while (detail) {
+        if (detail.dataset.collapsed === 'true') {
+          detail.querySelector<HTMLElement>(':scope > summary')?.click();
+        } else if (!detail.hasAttribute('data-collapsed')) {
+          detail.open = true;
+        }
+        detail = detail.parentElement?.closest('details') ?? null;
+      }
+      target.scrollIntoView();
+    });
+    return () => cancelAnimationFrame(frame);
+  }, [story, pathname, hash]);
+  useEffect(() => {
+    if (!expanded) return;
+    dialog.current?.showModal();
+    const previousOverflow = document.body.style.overflow;
+    document.body.style.overflow = 'hidden';
+    return () => {document.body.style.overflow = previousOverflow;};
+  }, [expanded]);
+  const close = () => {dialog.current?.close();};
+  return <section className={`archify-panel${compact ? ' archify-panel--compact' : ''}${story ? ' archify-panel--story' : ''}`} data-diagram={name} aria-label={title}>
+    <div className="archify-toolbar"><button ref={opener} type="button" className="archify-expand" aria-label={`Expand ${title}`} title="Expand diagram" onClick={() => setExpanded(true)}><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" aria-hidden="true"><path d="M8 3H3v5M16 3h5v5M21 16v5h-5M8 21H3v-5" /></svg></button></div>
+    {story ? <>
+      <iframe className="story-desktop" ref={desktop} onLoad={() => syncTheme(desktop.current)} src={`${source}?embed=1&theme=${initialTheme.current}`} title={title} sandbox="allow-scripts allow-downloads" loading="lazy" referrerPolicy="no-referrer" />
+      <iframe className="story-mobile" ref={mobile} onLoad={() => syncTheme(mobile.current)} src={`${mobileSource}?embed=1&theme=${initialTheme.current}`} title={`${title} — narrow layout`} sandbox="allow-scripts allow-downloads" loading="lazy" referrerPolicy="no-referrer" />
+    </> : <iframe ref={desktop} onLoad={() => syncTheme(desktop.current)} src={`${source}?theme=${initialTheme.current}`} title={title} sandbox="allow-scripts allow-downloads" loading="lazy" referrerPolicy="no-referrer" />}
+    <dialog ref={dialog} className="archify-modal" aria-labelledby={headingId} onClose={() => {setExpanded(false); opener.current?.focus();}}>
+      <div className="archify-modal-toolbar"><strong id={headingId}>{title}</strong><button type="button" onClick={close} autoFocus aria-label="Close full-screen diagram"><span aria-hidden="true">×</span></button></div>
+      {expanded && <iframe ref={fullscreen} onLoad={() => syncTheme(fullscreen.current)} src={`${source}?theme=${initialTheme.current}`} title={`${title} — expanded`} sandbox="allow-scripts allow-downloads" referrerPolicy="no-referrer" />}
+    </dialog>
+  </section>;
+}

src/css/custom.css

@@ -92,8 +92,46 @@
 .footer {background: #101014; color: #afadb9; font-size: .8rem; padding: 27px;}
 .theme-doc-markdown {max-width: 850px;}
 .theme-doc-markdown h1 {letter-spacing: -.035em;}
+.strategy-content table {display: table; width: 100%; table-layout: fixed;}
+.strategy-content th, .strategy-content td {overflow-wrap: anywhere; vertical-align: top;}
+.strategy-content th:first-child, .strategy-content td:first-child {width: 25%;}
+@media (max-width: 700px) {
+  .strategy-content th:first-child, .strategy-content td:first-child {width: 32%;}
+  .strategy-content th, .strategy-content td {padding: .65rem;}
+}
 .pagination-nav__link, .menu__link, .theme-admonition, pre {border-radius: 0;}
 a:focus-visible, button:focus-visible {outline: 3px solid #b88719; outline-offset: 4px;}
 @media (max-width: 996px) {.navbar {padding: 0 1rem;} .hero-inner {gap: 15px; padding: 55px 25px;} .hero-art {transform: scale(.85);} .start-section {padding: 35px 25px;} .start-card {padding: 20px;}}
 @media (max-width: 700px) {.hero-inner {grid-template-columns: 1fr; padding: 45px 24px;} .hero-art {display: none;} .hero-copy h1 {font-size: 3rem;} .start-grid {grid-template-columns: 1fr;} .section-heading {align-items: flex-start;} .foundation-badge {display: none;} .start-section {padding: 32px 20px;} .navbar__title {font-size: 1.45rem;} .navbar__logo {height: 31px;} .navbar input {max-width: 145px;} .button--lg {font-size: .95rem;} .button--primary span {padding-left: 10px;}}
+.archify-panel {border: 1px solid var(--line); margin: 1.5rem 0;}
+.archify-toolbar {display: flex; justify-content: flex-end; padding: 4px; background: var(--surface);}
+.archify-panel iframe {width: 100%; height: 720px; border: 0; display: block; background: #f6f6f6;}
+.archify-panel--compact > iframe {height: 500px;}
+.archify-panel--story {max-width: 740px;}
+.archify-panel--story > iframe {height: auto; aspect-ratio: 480 / 408;}
+.archify-panel--story > .story-mobile {display: none;}
+.archify-panel--story[data-diagram="strategy-target"] > iframe {aspect-ratio: 1620 / 1430;}
+.archify-panel--story[data-diagram="strategy-adoption"] > iframe {aspect-ratio: 545 / 408;}
+.archify-panel--story[data-diagram="strategy-maintenance"] > iframe {aspect-ratio: 524 / 408;}
+.strategy-content > details {margin: .65rem 0; border: 1px solid var(--line); padding: .8rem 1rem; background: var(--surface);}
+.strategy-content summary {cursor: pointer; font-weight: 700;}
+.strategy-content summary:focus-visible {outline: 3px solid #b88719; outline-offset: 4px;}
+.strategy-content > details[open] > summary {margin-bottom: 1rem;}
+@media (max-width: 700px) {.archify-panel iframe {height: 650px;}}
+@media (max-width: 700px) {
+  .archify-panel--story > .story-desktop {display: none;}
+  .archify-panel--story > .story-mobile {display: block; height: auto; aspect-ratio: 240 / 748;}
+  .archify-panel--story[data-diagram="strategy-roadmap"] > .story-mobile {aspect-ratio: 240 / 628;}
+  .archify-panel--story[data-diagram="strategy-adoption"] > .story-mobile {aspect-ratio: 305 / 748;}
+  .archify-panel--story[data-diagram="strategy-maintenance"] > .story-mobile {aspect-ratio: 284 / 748;}
+  .archify-panel--story[data-diagram="strategy-target"] > .story-mobile {aspect-ratio: 680 / 2340;}
+}
+.archify-expand {display: grid; place-items: center; width: 44px; height: 44px; border: 0; padding: 0; background: transparent; color: var(--ifm-link-color); cursor: pointer;}
+.archify-expand:hover {background: var(--ifm-hover-overlay);}
+.archify-modal {position: fixed; inset: 0; margin: 0; padding: 0; width: 100vw; height: 100dvh; max-width: none; max-height: none; border: 0; background: var(--surface); color: var(--ifm-color-content);}
+.archify-modal[open] {display: flex; flex-direction: column;}
+.archify-modal::backdrop {background: #000b;}
+.archify-modal-toolbar {display: flex; align-items: center; justify-content: space-between; gap: 16px; padding: 12px 20px; border-bottom: 1px solid var(--line);}
+.archify-modal-toolbar button {display: inline-flex; align-items: center; justify-content: center; flex-shrink: 0; width: 44px; height: 44px; padding: 0; background: var(--gold); color: #14131a; font: inherit; font-size: 24px; font-weight: 700; border: 0; cursor: pointer;}
+.archify-panel .archify-modal iframe {flex: 1; min-height: 0; height: 100%; width: 100%;}
 @media (prefers-reduced-motion: reduce) {.start-card {transition: none;} .start-card:hover {transform: none;}}

src/pages/index.tsx

@@ -11,7 +11,6 @@ export default function Home(): React.ReactElement {
             <p className="eyebrow">ELDORADO / AI STRATEGY</p>
             <h1>Eldorado<br/><span>Powered By AI</span></h1>
             <p className="hero-description">Strategy and direction for an AI-powered Eldorado.</p>
-            <Link className="button button--primary button--lg" to="/docs/overview/">Explore the documentation <span aria-hidden="true">→</span></Link>
             <p className="hero-note">A starting point for shaping the strategy.</p>
           </div>
           <div className="hero-art" aria-hidden="true">
@@ -25,9 +24,9 @@ export default function Home(): React.ReactElement {
       <section className="start-section container" aria-labelledby="start-title">
         <div className="section-heading"><div><p className="eyebrow">START HERE</p><h2 id="start-title">A clear place to begin.</h2></div><span className="foundation-badge">Foundation · v1</span></div>
         <div className="start-grid">
-          <Link className="start-card" to="/docs/overview/"><span className="card-number">01 / OVERVIEW</span><h3>What’s here</h3><p>Understand the starting point and what remains to be decided.</p><span className="card-action">Read the overview <span aria-hidden="true">↗</span></span></Link>
-          <Link className="start-card" to="/docs/maintain/"><span className="card-number">02 / MAINTENANCE</span><h3>Make it your own</h3><p>Add a page, preview a change, and publish through the existing pipeline.</p><span className="card-action">Open the guide <span aria-hidden="true">↗</span></span></Link>
-          <Link className="start-card" to="/docs/reference/"><span className="card-number">03 / REFERENCE</span><h3>Under the hood</h3><p>Find the repository layout, build commands, and publication details.</p><span className="card-action">View the reference <span aria-hidden="true">↗</span></span></Link>
+          <Link className="start-card" to="/organization/structure/"><span className="card-number">01 / ORGANIZATION</span><h3>Organization</h3><p>Explore the structure workspace and its first interactive diagram.</p><span className="card-action">Explore structure <span aria-hidden="true">↗</span></span></Link>
+          <Link className="start-card" to="/strategy/"><span className="card-number">02 / STRATEGY</span><h3>Strategy</h3><p>Shape the direction for an AI-powered Eldorado.</p><span className="card-action">View the direction <span aria-hidden="true">↗</span></span></Link>
+          <Link className="start-card" to="/contribution/"><span className="card-number">03 / CONTRIBUTION</span><h3>Contribution</h3><p>Contribute evidence, proposals, documentation, and diagrams.</p><span className="card-action">Start contributing <span aria-hidden="true">↗</span></span></Link>
         </div>
         <aside className="scope-note"><span className="scope-symbol" aria-hidden="true">✦</span><div><strong>Shaping the direction.</strong><p>This space is dedicated to AI strategy and direction for Eldorado. Specific initiatives, priorities, and the roadmap remain to be defined.</p></div></aside>
       </section>

vendor/archify-checksums.json

@@ -0,0 +1,110 @@
+{
+  "LICENSE": "b799ab081703e7821ae5096d2c1abdf14bbdc75e8ea1c4045998c36ed6db9706",
+  "SKILL.md": "66dfe99b35d7ceff95bcbdb00f138b8b3ec8094629acf69efba1eeda1013aaf3",
+  "THIRD_PARTY_NOTICES.md": "0b7fb59365dc21c93b0f62526d74ee913aeec9ae532c112bc76afa7edcd56e14",
+  "assets/JetBrainsMono-OFL.txt": "c1ab7c666206842a02b35b30770dac0d7a10156ed401c9defc3f02a754d89e90",
+  "assets/template.html": "b0b550d644b77cad401bbc4b21375919ef01db45d235122a0ee42b732cb34233",
+  "bin/archify.mjs": "97788086acaac4122aafc56c48acfe5fde1979d6aaa67db73aa1f4ab70b34390",
+  "bin/delivery-update.mjs": "d5ad7d6d7d949a8a8c37af4f80d79a8b4e057245e30ba11866efb40c6771dafa",
+  "bin/finalize.mjs": "c62710a0e80dc11b79e2c6a1a163fd9f6df46e13de141e3dd4d506554170d824",
+  "bin/open-artifact.mjs": "b0ab5f37c4f4556f76040dc862744afe9d4b65f319f35e1f9b505e0344b9c409",
+  "bin/preview.mjs": "2d01245850ab259500f0ff1782bef9f9c6f9caad0d13ad82061ef75a20fbaedb",
+  "bin/recover-output.mjs": "b3f7db21b3fc5341326207c1259aa787730120f42179eff50e481b0c6ad1e2d4",
+  "bin/visual-check.mjs": "93d07354e6b94725a8da354f90b7781f2739101f336afccd532ac6de9895a24c",
+  "brand-marks/README.md": "8b771a16322ce9ea47fdc00b9935e33adf0f3af608f2d735235443e15ef622e2",
+  "brand-marks/catalog.json": "e1a6c555cbf8ea36fb8100a4a25824e7ab87bebe9871e450ba05b6dea3b036d6",
+  "delta/architecture-delta.mjs": "94ad7ac625202759386e4ff06431902d0c198c32b62bc99ebf894616cb94deca",
+  "examples/agent-run.lifecycle.json": "230242a7557663877766c43a9fe7cffe8b4fb66e4866457dccd24c63175b4917",
+  "examples/agent-tool-call.workflow.json": "d67965d50872c97e4ff3476271e645bf19fab6b3ab44e111bdb44b063e3aa36f",
+  "examples/async-job-roundtrip.sequence.json": "b8c6c52f1763ede2933c77deb8da59b3e06917bc41d27e66df896136456b859a",
+  "examples/brand-aware-delivery.architecture.json": "211c126ebdc5f0124617b1067cecfb858143a1a18fd10621d01f5765c7de3b5d",
+  "examples/cache-miss-request.sequence.json": "f8486daa803fff6c295cecca4604c561fbbf9acb2e83326022b5a87639e8afe6",
+  "examples/checkout-platform.base.architecture.json": "81d55a2e86fc39f6473b32dfba986a12d3b7a705a95821844865b1dc831c9fe7",
+  "examples/checkout-platform.head.architecture.json": "eb4ae056035dd3316414a5d7f6599525107b5d1af7bedbd905460ade77daf5c6",
+  "examples/dataflow-product-analytics.html": "6d6790f1fa3631241dba4065e33ba2ce947a1da032cdd6d7d44c7190f85d3f5d",
+  "examples/deployment-release.lifecycle.json": "f565a8acfebdb21453e2bccd82d3760b4736e38fe194fb2f0804b57817eba813",
+  "examples/event-stream.dataflow.json": "3bdd77674282009c7c68d588cf8a3c495bc98a3be1b9c45327fd1801a6f83a23",
+  "examples/holiday-planning.workflow.json": "b98354f921ca45842fed235db09fd4f19d94adc16865876f438c0d699d05e1ea",
+  "examples/incident-response.workflow.json": "630be98449925d2716ecb8439f404b2bff5fe65ba905b0ad0baea6d96890c526",
+  "examples/lifecycle-agent-run.html": "0874c0723b10104ea03c566d1d63d958b6f93a6788c0075c1d1d162ccdb4054c",
+  "examples/locales/de.json": "d1cf160d3ada814676566b787f203c2aee99f8f5d5b51d2e3e0b3c03f55a33df",
+  "examples/locales/es.json": "1389068b7dddb5e72ed425d12084ca9104942bef933440a16113d60619f1daf3",
+  "examples/locales/fr.json": "805495b259b417ccc03744023e5bf803811752c0c4e8fc5be7433e2ac73e875d",
+  "examples/locales/fr.partial.json": "8958a8354ffccce2ce63ac21b3f8a0f131086f532832445a3fe7feff02200397",
+  "examples/locales/it.json": "76e45186196675e7a0e2e2281073da38c0971596e6ed6eae11ccc479ceda6eae",
+  "examples/locales/ja.json": "79418f8eb65dc6c4928a4cab54e4515b4bfffd867814323eda6c8aa3c96fac33",
+  "examples/locales/ko.json": "958db2030014f6835a0bf62813f58fb80ea66b48a13af6d2586805704709616f",
+  "examples/locales/pt.json": "efbae92eebc09636e2c3bbc6786a666a6336258bd8c2d451bd78b2921042ab67",
+  "examples/locales/ru.json": "3bd0eadf6cdfe65511e81a11f04b61bb33cc94e1b89044203d191e4296a3f40d",
+  "examples/product-analytics.dataflow.json": "8a635db9e51a5b1a8d2955b9d66f5b9a450e0a298432ce8f2e2f0be11f372e05",
+  "examples/production-deployment.architecture.json": "cb54bad2dfd0c2d02aa5b496bde6839789a0f07f23062343c4458b8d38806c13",
+  "examples/release-delivery.workflow.json": "dbd5c174af66296caec372e7214cf4df7158b50a563508e16826b95ab8d1cd6c",
+  "examples/sequence-cache-miss-request.html": "307951a168d2492eb0c41f318260d0a866f6e6057df5253d3528c32a23084ea3",
+  "examples/web-app-rendered.html": "8233f4f600c89559b64ac650ad11b66ee1423103e8b6c5e53f63740afc06f6da",
+  "examples/web-app.architecture.json": "95e051b27a9e4a3307e194c0f666fca4af51470be7e2228d400ff48aea5b353b",
+  "examples/workflow-agent-tool-call-rendered.html": "3edbb38a05430865ee2f620c35de49f8e78dfd8788be14840d9e134b5912230d",
+  "migrations/workflow-v2.mjs": "0eec02057b8490afca9b093de5ea6e636c7fad2361cd28a04cf2f3e4b6197434",
+  "package.json": "b609dc658a8e1a2097c304a7873ef039b9d6079832028980f60965d8d3ea886d",
+  "recipes/scenarios.mjs": "6c655f643dd198cc76a6cfd0f5b945dac1388eaed10bf00f195dcd9f077401b4",
+  "references/architecture-layout-repair.md": "6c90caa232c004fa43b8770c745b83672919deaf8909f2592a3ad5fcd4031953",
+  "references/authoring-contract.md": "b5d521401b6d38d2792b2feb18906ad2b9d50a1c265acd42be51b3d49f456eb8",
+  "references/authoring-defaults.md": "7277ebf440c568fac425af5ad085ff60976ec401fe694c0ea984efff192961b0",
+  "references/brand-marks.md": "304d48735e07673197715856271532cd2dfb7fbada184936a15dea3b40ec1f06",
+  "references/delivery-contract.md": "aa167fd1d2c5ab48cf7c53cd25dc9f49a8b52059e848d71d76b2489aa5b68780",
+  "references/repository-authoring.md": "da8fa6d2bbc4572e5253e53bbc2d08088568f4d5350e61aa4e2029b2a5d2beb1",
+  "references/update-awareness.md": "57750c5c730b1804b6b1ece3af972d47cfe4d06ef7920fba4418c5b09c842b41",
+  "references/viewer-runtime.md": "cabdf042069f0029f449755229335248d1568681542ec331e181fdc91efee14a",
+  "renderers/architecture/grid.mjs": "f6de99c32436feed3378b0ddef516bb4732ff27a89c543b50635d4d14a15a55a",
+  "renderers/architecture/labels.mjs": "7cf5bb20c3039f49683fe81a461110c42de0a006a58c867c47fdd3089a58bbbc",
+  "renderers/architecture/render-architecture.mjs": "3831899e2e12cedd2e8225285fc9e50e8cd032f036fac87264b0bd5ddc60fda6",
+  "renderers/architecture/routing.mjs": "b952b3ec0364827fa7fbff10a28e2a83f0ba11921c67f5ee224e5ef58c833cbb",
+  "renderers/dataflow/README.md": "5e380fa7fe32c93a2f978a2db5ad7d2e91afa5fc3cae62c4d27c4a2c81502873",
+  "renderers/dataflow/render-dataflow.mjs": "a8540e7b1a4794c6da6b64707ce17e970ca5e876544fd29554d2503c196f1dde",
+  "renderers/lifecycle/README.md": "2ce9bcd31529e97c176701a4dceb2f82f70f04a9483441779341eeeb79c54a9a",
+  "renderers/lifecycle/grid-routing.mjs": "81ae4d3a90aed30471f23dbc3083768d4979e96cf96544f9465713c2cd09e13f",
+  "renderers/lifecycle/render-lifecycle.mjs": "1ed2e359a5eab6a2bd9473c36c6184498d68748e9175cddf6894aa7b2ba3f670",
+  "renderers/sequence/README.md": "51d78bc944d10e06ded74ede3ca5b78f916db3e8e45ae099eabc204e4d316ef3",
+  "renderers/sequence/render-sequence.mjs": "46ed05a34655fbe6c421586366aa81480bca893233d61b9391e21afc667f15a1",
+  "renderers/shared/atomic-output.mjs": "f804d66d1801ac2dadc9d0a4c334645cfbb7a8cd1a7de112ddfb952c056a580b",
+  "renderers/shared/brand-marks.mjs": "5cfc3c517ca6fe7e867c208101059dd7747ca3de3c9934b17583d6cf20336620",
+  "renderers/shared/cli.mjs": "097f968a614008b07972f56de995e5b933c61ee0ba0d16d967c0a97c6d92e9d7",
+  "renderers/shared/desktop-readability.mjs": "de68f2ed92573ae714659d556f97eca01296f4e0063b94c429370efcc38f909a",
+  "renderers/shared/diagnostics.mjs": "d052a0e72eec2a2bf29c70dacdd3350100e2c76fc2627d14f79234077c571e3f",
+  "renderers/shared/engineering-profiles.mjs": "7e99f9d5423f66cc9ab6224da56dc2d5aa6c6faec29178034794e9db6b5b2889",
+  "renderers/shared/generated-brand-marks.mjs": "0f157d229c12df6f53763a3b88684baa5803a52484c49c4d34ec40b8743beea2",
+  "renderers/shared/generated-validators.mjs": "33697207b90a0eb0d0566a1c46eaf3cb58f85cef0f43caeec991017ade34c2b9",
+  "renderers/shared/geometry.mjs": "b25d849e6e256b1eef37fa3bb88712d0617d6eb646a2355a934505fcaa9be75d",
+  "renderers/shared/i18n.mjs": "03f5356110a08b2cf684a484af5502bb392482de1ef61123707c6da2724c5201",
+  "renderers/shared/layout-report.mjs": "4b5fa6e1af2b2efdd57d7fac16359089a059a745cc19ad1595ba42c3e483aec7",
+  "renderers/shared/legend.mjs": "1cc5033a188690fc5f5fef1bd7915a275e6c790bb3061c63c00a97b234625cbe",
+  "renderers/shared/output-path.mjs": "7422139101abd93493918898a97bed06f2212bfd411d3514cd229b6d57a3797e",
+  "renderers/shared/path-semantics.mjs": "4ef002af9061c06634a07de6d199fd7d13e6c50561c792fd018118bf3e065f52",
+  "renderers/shared/portable-path.mjs": "26130cbcdae9b9f082486aeb5feec9c5fe57905d2ed8e30c8081b9710e2e8ac3",
+  "renderers/shared/repository-evidence.mjs": "19c652af2afec5604e9ce23d356f3cc2c5d6146592531036da20e79f4db3ed1d",
+  "renderers/shared/repository-location.mjs": "9ee8294c39d1be40f5aca3334fdfc7527ef9b224d6c1e69ca57aefc6a8c77856",
+  "renderers/shared/route-quality.mjs": "0ae7e16210f8e00bb615da34d5323dee65efe52ceb11a40ea49fdd10b5257daa",
+  "renderers/shared/sidecar-path.mjs": "c23cac8bcc265a74e2920c58d0968d1ffa06c1328bdd9cfd07755d4df2f22974",
+  "renderers/shared/spatial-grid.mjs": "e728bf6a729972f95ae09e368ea370490d10ff94d49debe2fab2e9bac923ee1a",
+  "renderers/shared/text-fit.mjs": "ebd499072ef4fe31c9aabf45a01c204a9c2c142d45f087c3240673f90f477038",
+  "renderers/shared/utils.mjs": "422b66c6945de473b1f96e4f3641339b6a24c8ccef60795a38ca2386e10bc26b",
+  "renderers/shared/validator.mjs": "7460d7fcbcdf710649256c5e96142ae26d807a655d3296ee8caf7f5e158622cc",
+  "renderers/workflow/README.md": "c3ca0e258d3bba43390eda95f308d12388b1c778db972bbd936a5f5ad3344142",
+  "renderers/workflow/render-workflow.mjs": "df6cb1330231616dcb83592c3cc1dbf4b3e45567779836ae031ff57d2d517b89",
+  "renderers/workflow/workflow-compiler.mjs": "25646b0a7ee13d62ed7b21c915d40665608ffd57c69af263a8ec4250ceb9214e",
+  "renderers/workflow/workflow-migration-geometry.mjs": "ebfc5085dd008ae63802f500402fb7bf8ca0ae28460997d867f45e5493b8fbe6",
+  "schemas/README.md": "eeb4d75e4864128493939f277481ade4c5f023932ed5c0846cc539fdac9ae6aa",
+  "schemas/architecture.schema.json": "aef992b585a18a4016b8207254fe43a6227b0d45322a1ba95e0f69a80fc8f8c1",
+  "schemas/common.schema.json": "60912458e44224647a147a4dfccf0b40e0ea9c631767aabdeb5e82456f27c4e6",
+  "schemas/dataflow.schema.json": "f01b2faafa5fd6e300f6b5045eeca70f70226552411180442d6e528dd45172f1",
+  "schemas/lifecycle.schema.json": "6b310026a3bc5d4eb7f36a1ed862b8c95d88ce57246ce078ba3094e0d6ff3c90",
+  "schemas/sequence.schema.json": "411dcda121d7e95170a6850fb1cec51bec2e78222ce74b8465e11bcbd8e6e41a",
+  "schemas/workflow.schema.json": "e13a1ce3b841376c8c6f6b9cb8152f8c0c7d70a77a2960fecdfe9025de83dc25",
+  "scripts/check-render-output.mjs": "6ca0507cbbe442e5fa709477e7257b31a3fa929aa7f1a56ddbcbb3328df87a7d",
+  "scripts/check-update.mjs": "5a1add913beee623cdc9c009bad1980f4538bae1b9862bf92e41c83dd8a90666",
+  "scripts/delivery-update-child.mjs": "23b2cf0cb79935b90238558b511966bdf04c4158605c0651b1ccdc90b1736e5f",
+  "scripts/generate-brand-marks.mjs": "0434c31903b831382a91e85a329bcbcb39b32f29c656273a273f896b3b0a42e7",
+  "scripts/generate-validators.mjs": "fc8f003d7def53abaccac25148517cdccd390d975fc6fc745dee64a71425b9a2",
+  "scripts/render-examples.mjs": "a173a053fb26c0ac3cd72eb9b4e50411e67ca8c50bec57f05d4ca8ba79db2c0b",
+  "scripts/update-contract.mjs": "7c5d34c5fa2e08fcd0b42e33a0f3b4685fcecf3ac88f1ed820528df8fdc46cbc",
+  "skill-release.json": "93a31980e200d0749d887982eba8b6c3b33452a14e3a04d4e6969b9c42c7eacf"
+}

vendor/archify-provenance.json

@@ -0,0 +1,12 @@
+{
+  "repository": "https://github.com/tt-a1i/archify",
+  "commit": "d5a1333d7447c866a765adac7d4d062f2f02e4d2",
+  "version": "3.0.1",
+  "sourcePath": "archify/",
+  "license": "MIT",
+  "excluded": [
+    "test/",
+    "package-lock.json"
+  ],
+  "changes": "None to upstream source; portal integration is outside vendor/. No global skill installation."
+}

vendor/archify/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 tt-a1i (Archify)
+Copyright (c) 2025 Cocoon AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vendor/archify/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: archify
+description: Create polished, validated architecture, workflow, sequence, data-flow, and lifecycle/state diagrams as explorable standalone HTML with inline SVG, dark/light themes, optional trace motion, and PNG/JPEG/WebP/SVG/WebM export. Accept plain-language requirements or pasted Mermaid flowchart, sequenceDiagram, and stateDiagram input; inspect repository evidence when the diagram must reflect real code. Use when the user asks to visualize system architecture, infrastructure, cloud/security/network topology, technical workflows, API call sequences, request lifecycles, data pipelines, ETL/ELT, data lineage, state machines, or to convert/beautify Mermaid.
+license: MIT
+metadata:
+  version: "3.0"
+  author: tt-a1i
+  based_on: Cocoon-AI/architecture-diagram-generator (MIT, v1.0)
+---
+
+# Archify
+
+Create an interactive HTML diagram from typed JSON. Static output is the default; enable motion only when requested.
+
+Run commands from your working directory. Unless the user names another location, give each new diagram request its own folder `.archify/<type>-<slug>-<YYYYMMDD-HHMMSS>/` there (local time, chosen once when the request starts): keep `candidate.json` and `<slug>.html` in it, set `meta.output` to that relative HTML path, and reuse the folder for every repair rerun. A later request gets a new folder, so earlier versions stay intact. Replace `bin/archify.mjs` in the commands below with the installed package's absolute path, or its path relative to your working directory; input and output paths resolve from that working directory.
+
+For a real codebase, read [Repository authoring](references/repository-authoring.md) while tracing the requested behavior. A system description uses the steps below; an existing JSON uses the handoff path.
+
+## Existing candidate handoff
+
+When the user supplies a frozen candidate, run `finalize` first as one CLI invocation. Its passing receipt completes the automated gates; follow any visual review recommendation under Delivery before claiming visual quality. For repair, follow step 5.
+
+`finalize` includes a bounded update check in its delivery receipt; see Update awareness.
+
+## Fast authoring path
+
+Use this path for ordinary generation. Read branch references only when their stated trigger applies.
+
+1. Choose `architecture`, `workflow`, `sequence`, `dataflow`, or `lifecycle` from the question.
+2. Use the exact schema and example paths in the Type router without listing their directories. Read [Authoring defaults](references/authoring-defaults.md) and the mode's example in a bounded batch separate from project documents and complete schemas so neither is truncated; recover any missing section before writing. For Architecture, use the matching showcase example. For Sequence, Dataflow, and Lifecycle, also read the mode and common schemas. Read the relevant schema definition before choosing any new field, enum, or constrained text, especially boundary kinds. Examples teach shape, not facts. Use fresh IDs, wording, and layout. Go directly to the candidate without preliminary help, doctor, starter validation, temporary diagrams, or output-path listing. Query brands only for an explicitly requested mark; read [Brand marks](references/brand-marks.md) for an unknown mark with a user-provided URL.
+3. Once the requested scope and, for a real codebase, [source evidence](references/repository-authoring.md) are covered, write the complete candidate directly without planning coordinates in prose. Choose Architecture abstraction and connected placement using Authoring defaults before coordinates: show the main user journey and necessary branches, preserve control roles and behavior-changing conditions, and leave enough room for actual relationship labels. No node, relationship, source, view, card, or boundary count is a target or ceiling. Use automatic routes first; add explicit routing only for necessary branch, return, supplied geometry, or measured repair. Set `meta.quality_profile` to `"showcase"` unless the user requests dense `standard`.
+4. Once the complete first candidate is written, run `finalize` directly. Its first gate is showcase validation; successful first drafts need no separate pre-validation. Keep the candidate unchanged while the command runs:
+
+   ```bash
+   node bin/archify.mjs finalize <type> <candidate.json> <output.html> --quality showcase --json
+   ```
+
+   For a repository-backed candidate, include evidence on the first draft and use the complete first command: `node bin/archify.mjs finalize <type> <candidate.json> <output.html> --repo-root <repo-root> --quality showcase --json`.
+
+   A passing receipt proves the included `validate`, `deliver`, strict `check`, and real-browser `browser-check` gates passed. Use its compact summary; run standalone commands only for a separate request or focused failure diagnosis.
+
+5. A non-zero exit is never success. Read compact stdout or `evidence.summaryReceipt`, then [repair the failed gate](references/delivery-contract.md#failed-finalize-and-candidate-repair), including its repair limit. Preserve requested meaning and source evidence. For several tangled Architecture routes, read [Architecture layout repair](references/architecture-layout-repair.md); for measured field or geometry failures, read [Authoring contract](references/authoring-contract.md). Edit the connected neighborhood and rerun the complete `finalize` command from step 4.
+
+## Update awareness
+
+`finalize` and standalone `deliver` include `update` in their receipts. Do not run a separate check for the same delivery. If `update.noticeRequired` is true, read `references/update-awareness.md` and keep one update line in your final response to the user, even after a quality gate fails. For a task with several diagrams, mention the update once in the final response. Snooze or ignore a reminder only when the user explicitly asks; never install or update on your own initiative.
+
+Before the first candidate, use the authoring references and relevant repository source, not Archify implementation or tests. Inspect Archify implementation if diagnostics remain unactionable after focused repairs.
+
+## Type router
+
+| Type | Use for | Schema | Example |
+|---|---|---|---|
+| `architecture` | Components, services, cloud/security boundaries, infrastructure | `schemas/architecture.schema.json` | System descriptions, services, libraries, and CLI repos: `examples/web-app.architecture.json`; deployment repos: `examples/production-deployment.architecture.json` |
+| `workflow` | Processes, approval gates, tool calls, runbooks, CI/CD | `schemas/workflow.schema.json` | `examples/agent-tool-call.workflow.json` |
+| `sequence` | API call chains, request lifecycles, async traces, returns | `schemas/sequence.schema.json` | `examples/cache-miss-request.sequence.json` |
+| `dataflow` | Pipelines, ETL/ELT, lineage, governance, consumers | `schemas/dataflow.schema.json` | `examples/product-analytics.dataflow.json` |
+| `lifecycle` | State/status transitions, retries, waiting and terminal states | `schemas/lifecycle.schema.json` | `examples/deployment-release.lifecycle.json` |
+
+When ambiguous, run `node bin/archify.mjs guide "<scenario>" --json`. Scenario proof examples are structural references, not facts to copy.
+
+## Mermaid input
+
+Read Mermaid for topology and meaning, then author fresh Archify JSON; do not mechanically render Mermaid styling.
+
+- `flowchart` / `graph` → `workflow`, or `architecture` for a component map.
+- `sequenceDiagram` → `sequence`; participants become semantic participants and arrows become messages.
+- `stateDiagram` → `lifecycle`; states and transitions retain meaning, not Mermaid style.
+
+## Delivery
+
+Use the `finalize` command above for the first candidate and after a repair.
+
+`finalize` stops at the first non-passing gate. Its compact stdout and `<output-stem>.finalize-summary.json` are ordinary evidence. A passing run creates no screenshots and reports `visualReview: "not-requested"`.
+
+When a passing Architecture receipt reports `visualReviewRecommendation.signals.resolvedCrossovers`, copy the candidate aside and apply the hints in one edit that changes only node positions and sizes: every node, relationship (including its `from` and `to`), label, and source stays as it was. Rerun the complete `finalize` once with `--out-dir <folder>/review-2`, because the previous HTML already owns its browser evidence. If that run fails or reports more crossings, restore the copy and finalize it with `--out-dir <folder>/review-3`. Do not start a second placement round. Hints about extra bends alone are optional.
+
+When `layoutReviewRecommendation.action` is `inspect-sequence-width`, follow [Sequence width review](references/delivery-contract.md#sequence-width-review) before handing off a newly authored Sequence.
+
+Perceptual review is optional for ordinary generation, including a newly positioned Architecture. Use [Optional capture evidence](references/delivery-contract.md#optional-capture-evidence), with `--out-dir <folder>/visual-check`, when the user requests visual review, during development audits, or for a concrete route/browser concern. `visualReviewRecommendation` is advisory. Inspect captures before claiming visual quality; otherwise report automated checks only.
+
+Read [Delivery contract](references/delivery-contract.md) for failed gates, standalone commands, provenance/recovery, repeated delivery, exports, or opening. Recovery follows `deliver` → strict provenance `check` → `browser-check`; captures require strict provenance.
+
+For workflow viewport overflow, read [Workflow viewport repair](references/authoring-contract.md#workflow-viewport-repair) before the next layout edit.
+
+Report artifact checks, browser evidence, captures, and actual perceptual review as distinct results. For an explicitly requested immediate preview or active desktop loop, see [Optional opening](references/delivery-contract.md#optional-opening).
+
+## Optional viewer capabilities
+
+`meta.animation: "trace"` is opt-in.
+
+Read `references/viewer-runtime.md` only when the user explicitly asks for Share Cards, Route/Reach cards, motion, deep links, presentation, search/focus, or another Viewer Runtime feature.
+
+## Setup and fallback
+
+No install is required inside the skill package. For setup diagnosis, verify with:
+
+```bash
+node bin/archify.mjs doctor
+node bin/archify.mjs demo <output-directory>
+```
+
+When shell access is unavailable, hand-place architecture SVG into `assets/template.html`, use CSS semantic classes rather than inline colors, and follow the visual review contract in `references/delivery-contract.md`.
+
+## Output
+
+Return the checked HTML as an absolute path, diagram type, validation summary, specification/artifact receipt, browser-evidence status, and truthful visual-review status. Do not claim success for a non-zero command or claim visual inspection you did not perform.

vendor/archify/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,69 @@
+# Third-party notices
+
+Archify includes optional vector data for third-party brand marks. These marks
+are provided only to identify technologies and services in user-authored
+diagrams. Their inclusion does not imply sponsorship, endorsement, partnership,
+or affiliation with Archify.
+
+The Archify MIT license applies to Archify's own code and content. It does not
+replace the copyright licenses, trademark policies, or brand guidelines that
+apply to third-party marks. Users are responsible for confirming that their
+particular use is permitted.
+
+## Simple Icons
+
+Most of the built-in vector paths and their metadata were generated from
+[Simple Icons 16.28.0](https://github.com/simple-icons/simple-icons/tree/16.28.0).
+Simple Icons makes its collection work available under
+[CC0 1.0 Universal](https://github.com/simple-icons/simple-icons/blob/16.28.0/LICENSE.md).
+
+As Simple Icons explains in its
+[disclaimer](https://github.com/simple-icons/simple-icons/blob/16.28.0/DISCLAIMER.md),
+CC0 for the collection does not mean that every underlying icon is CC0. License
+and brand-guideline metadata may be incomplete or change over time. The absence
+of an individual license entry is not a grant of permission.
+
+Archify embeds the selected icons as vector-path data and may render them in a
+user-selected color. The following individual licenses were recorded in the
+pinned Simple Icons 16.28.0 metadata:
+
+| Mark | Recorded source | Recorded license | Archify treatment |
+|---|---|---|---|
+| Angular | [Angular press kit](https://angular.dev/press-kit) | [`CC-BY-4.0`](https://creativecommons.org/licenses/by/4.0/) | Embedded as vector-path data; color may be changed by the authored diagram. |
+| Apache Airflow | [Apache logos](https://apache.org/logos) | [`Apache-2.0`](https://www.apache.org/licenses/LICENSE-2.0) | Embedded as vector-path data; Apache trademarks remain subject to the [ASF trademark policy](https://www.apache.org/foundation/marks/). |
+| Apache Kafka | [Apache logos](https://apache.org/logos) | [`Apache-2.0`](https://www.apache.org/licenses/LICENSE-2.0) | Embedded as vector-path data; Apache trademarks remain subject to the [ASF trademark policy](https://www.apache.org/foundation/marks/). |
+| .NET | [.NET brand repository](https://github.com/dotnet/brand/blob/c7d0f51b8ec59531332d05fb27a5b758a7a3d689/logo/dotnet-logo.svg) | [`CC0-1.0`](https://creativecommons.org/publicdomain/zero/1.0/) | Embedded as vector-path data; color may be changed by the authored diagram. |
+| JavaScript | [JS community logo](https://github.com/voodootikigod/logo.js/blob/1544bdeed6d618a6cfe4f0650d04ab8d9cfa76d9/js.svg) | [`MIT`](https://github.com/voodootikigod/logo.js/blob/1544bdeed6d618a6cfe4f0650d04ab8d9cfa76d9/LICENSE) | Embedded as vector-path data; color may be changed by the authored diagram. |
+| Jenkins | [Jenkins artwork source](https://get.jenkins.io/art/) | [`CC-BY-SA-3.0`](https://creativecommons.org/licenses/by-sa/3.0/) | Embedded as vector-path data; color may be changed by the authored diagram. Jenkins retains its trademark rights. |
+| Rust | [Rust project](https://www.rust-lang.org) | [`CC-BY-SA-4.0`](https://creativecommons.org/licenses/by-sa/4.0/) | Embedded as vector-path data; color may be changed by the authored diagram. See the [Rust media guide](https://www.rust-lang.org/policies/media-guide). |
+| Vue.js | [Vue logo source](https://github.com/vuejs/art/blob/a1c78b74569b70a25300925b4eacfefcc143b8f6/logo.svg) | [`CC-BY-NC-SA-4.0`](https://creativecommons.org/licenses/by-nc-sa/4.0/) | Embedded as vector-path data; color may be changed by the authored diagram. The non-commercial and share-alike conditions remain applicable; see the [Vue artwork terms](https://github.com/vuejs/art/blob/a1c78b74569b70a25300925b4eacfefcc143b8f6/README.md). |
+
+The source, guideline, and known license fields for every packaged mark are
+preserved in `renderers/shared/generated-brand-marks.mjs`.
+
+## OpenAI mark
+
+The OpenAI vector path is recorded from the
+[OpenAI brand guidelines](https://openai.com/brand/), not from Simple Icons.
+Use remains subject to those current guidelines and any applicable trademark
+rights. Its inclusion does not state or imply endorsement by OpenAI.
+
+## JetBrains Mono
+
+Delivered Archify viewer artifacts embed the JetBrains Mono variable font
+subsets served by Google Fonts. For characters covered by these subsets, font
+selection does not depend on a network request or a locally installed copy.
+Uncovered characters (including CJK) still use the system fallback stack;
+browser and operating-system rasterization can differ.
+JetBrains Mono is maintained at
+[github.com/JetBrains/JetBrainsMono](https://github.com/JetBrains/JetBrainsMono)
+and is distributed under the SIL Open Font License 1.1. The complete license
+text is preserved in `assets/JetBrainsMono-OFL.txt` in the packaged Skill and
+in the font CSS carried by standalone HTML and SVG exports.
+
+## No additional rights granted
+
+Brand names, logos, and trademarks remain the property of their respective
+owners. This notice records provenance and known terms; it does not grant rights
+that Archify does not hold, and it does not state that every packaged mark has
+been cleared for every commercial, promotional, or redistributive use.

vendor/archify/assets/JetBrainsMono-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

vendor/archify/bin/delivery-update.mjs

@@ -0,0 +1,91 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const childPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'scripts', 'delivery-update-child.mjs');
+const DEADLINE_MS = 1_000;
+const MAX_OUTPUT_BYTES = 16 * 1_024;
+
+function unavailable(reason) {
+  return { status: 'unavailable', installedVersion: null, availableVersion: null,
+    releaseNotes: null, checkedAt: null, source: null, noticeRequired: false,
+    noticeText: null, reason };
+}
+
+function normalize(result) {
+  if (result?.status === 'current') return {
+    status: 'current', installedVersion: result.installedVersion,
+    availableVersion: result.availableVersion, releaseNotes: null,
+    checkedAt: result.checkedAt, source: result.source,
+    noticeRequired: false, noticeText: null,
+  };
+  if (result?.status !== 'update_available') {
+    return unavailable(result?.reason || (result?.status === 'silent' ? 'no-update' : 'invalid-result'));
+  }
+  const noticeRequired = result.noticeRequired !== false;
+  const cached = result.source === 'cache';
+  const noticeText = noticeRequired
+    ? `Archify ${result.severity === 'security' ? 'security update' : 'update'}: ${result.installedVersion} → ${result.latestVersion}. ${cached
+      ? `A previous check at ${result.checkedAt} found a newer release.`
+      : 'A newer release is available.'} Release notes: ${result.releaseNotes}. The installed Skill has not changed; ask to snooze or ignore this reminder.`
+    : null;
+  return {
+    status: 'update_available',
+    installedVersion: result.installedVersion,
+    availableVersion: result.latestVersion,
+    releaseNotes: result.releaseNotes,
+    severity: result.severity,
+    checkedAt: result.checkedAt,
+    source: result.source,
+    noticeRequired,
+    noticeText,
+    ...(result.eventKey ? { eventKey: result.eventKey } : {}),
+    ...(result.reason ? { reason: result.reason } : {}),
+    ...(result.suppressedUntil ? { suppressedUntil: result.suppressedUntil } : {}),
+  };
+}
+
+export function startDeliveryUpdateCheck({
+  env = process.env, deadlineMs = DEADLINE_MS, checkerPath = childPath,
+} = {}) {
+  if (env.ARCHIFY_UPDATE_CHECK_DISABLED === '1') return Promise.resolve(unavailable('disabled'));
+  return new Promise((resolve) => {
+    let child;
+    try {
+      const deadlineNs = process.hrtime.bigint() + BigInt(Math.floor(deadlineMs * 1_000_000));
+      child = spawn(process.execPath, [checkerPath, String(deadlineNs)], {
+        env,
+        stdio: ['ignore', 'pipe', 'ignore'],
+        windowsHide: true,
+      });
+    } catch {
+      resolve(unavailable('runtime-unavailable'));
+      return;
+    }
+    let output = '';
+    let timedOut = false;
+    let overflow = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGKILL');
+    }, deadlineMs);
+    child.stdout.on('data', (chunk) => {
+      if (Buffer.byteLength(output) + chunk.length > MAX_OUTPUT_BYTES) {
+        overflow = true;
+        child.kill('SIGKILL');
+      } else output += chunk.toString('utf8');
+    });
+    child.on('error', () => {});
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (overflow) return resolve(unavailable('invalid-result'));
+      // A synchronous renderer can delay both this callback and the parent's
+      // timer. A complete child result wins even if the timer fired meanwhile.
+      if (code === 0 && output.endsWith('\n')) {
+        try { return resolve(normalize(JSON.parse(output))); }
+        catch { return resolve(unavailable('invalid-result')); }
+      }
+      resolve(unavailable(timedOut || child.signalCode === 'SIGKILL' ? 'timeout' : 'check-failed'));
+    });
+  });
+}

vendor/archify/bin/finalize.mjs

@@ -0,0 +1,895 @@
+import { execFile } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { canonicalFuturePath, pathsAlias, resolveNativeOutputDirectory, resolveOutputPath } from '../renderers/shared/output-path.mjs';
+import { boundedSidecarStem } from '../renderers/shared/sidecar-path.mjs';
+import {
+  captureAtomicOutput, captureRegularFileBinding, publishRegularFileBinding,
+  releaseRegularFileBinding, removeOwnedRegularFile, verifyAtomicOutput,
+} from '../renderers/shared/atomic-output.mjs';
+import {
+  browserCheckSidecarPaths,
+  CAPTURE_VIEWPORTS,
+  ChromeVisualBrowser,
+  findChrome,
+  VISUAL_CHECK_VIEWPORTS,
+} from './visual-check.mjs';
+import { startDeliveryUpdateCheck } from './delivery-update.mjs';
+
+export const FINALIZE_STAGES = Object.freeze(['validate', 'deliver', 'check', 'browser-check']);
+const FINALIZE_UPDATE_DEADLINE_MS = 4_000;
+
+function sha256(buffer) {
+  return createHash('sha256').update(buffer).digest('hex');
+}
+
+function identity(file) {
+  try {
+    const bytes = fs.readFileSync(file);
+    return { path: path.resolve(file), sha256: sha256(bytes), bytes: bytes.byteLength };
+  } catch {
+    return { path: path.resolve(file) };
+  }
+}
+
+function durationMs(start) {
+  return Number((process.hrtime.bigint() - start) / 1000000n);
+}
+
+function receiptWriteError(file, state) {
+  const error = new Error(`Could not publish finalize evidence "${file}" safely (${state.reason?.code || state.status}).`);
+  error.finalizeCode = 'finalize/receipt-publication';
+  error.finalizeEvidence = { file, state };
+  return error;
+}
+
+function captureReceipt(file) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const capture = captureAtomicOutput(file, { requestedEntryPolicy: 'regular-or-absent' });
+  if (capture.status !== 'captured') throw receiptWriteError(file, capture);
+  return capture;
+}
+
+function writeJsonAtomic(file, value, capture, beforeCommit) {
+  const serialized = Buffer.from(`${JSON.stringify(value, null, 2)}\n`);
+  const temporary = path.join(path.dirname(capture.commitPath), `.archify-finalize-${randomUUID()}.json`);
+  let binding;
+  let stagedIdentity;
+  try {
+    fs.writeFileSync(temporary, serialized, { flag: 'wx' });
+    const metadata = fs.lstatSync(temporary, { bigint: true });
+    stagedIdentity = { device: metadata.dev, inode: metadata.ino };
+    if (capture.mode !== null) fs.chmodSync(temporary, capture.mode);
+    const staged = captureRegularFileBinding(temporary, {
+      subject: 'finalize-receipt', expectedIdentity: stagedIdentity,
+      expectedSha256: sha256(serialized), expectedBytes: serialized.byteLength,
+      ...(capture.mode === null ? {} : { expectedMode: capture.mode }),
+    });
+    if (staged.status !== 'captured') throw receiptWriteError(file, staged);
+    binding = staged.binding;
+    beforeCommit();
+    const publication = publishRegularFileBinding(binding, temporary, capture.snapshot, { subject: 'finalize-receipt' });
+    if (!['committed', 'committed-with-warning'].includes(publication.status)) throw receiptWriteError(file, publication);
+    // Preserve recovery evidence instead of reporting a clean completion when cleanup failed.
+    if (publication.status === 'committed-with-warning') throw receiptWriteError(file, publication);
+    const next = captureReceipt(file);
+    if (!pathsAlias(next.commitPath, capture.commitPath)) {
+      throw receiptWriteError(file, { status: 'different', reason: { code: 'receipt-slot-changed' } });
+    }
+    return next;
+  } finally {
+    if (binding) releaseRegularFileBinding(binding);
+    if (stagedIdentity) removeOwnedRegularFile(temporary, stagedIdentity, { subject: 'finalize-receipt' });
+  }
+}
+
+function parsedReceipt(stdout) {
+  const source = String(stdout || '').trim();
+  if (!source) return null;
+  try { return JSON.parse(source); } catch { return null; }
+}
+
+function isReceiptObject(receipt) {
+  return Boolean(receipt && typeof receipt === 'object' && !Array.isArray(receipt));
+}
+
+function validIdentity(value) {
+  return isReceiptObject(value)
+    && typeof value.sha256 === 'string'
+    && /^[0-9a-f]{64}$/.test(value.sha256)
+    && Number.isSafeInteger(value.bytes)
+    && value.bytes >= 0;
+}
+
+function identitiesMatch(left, right) {
+  return validIdentity(left)
+    && validIdentity(right)
+    && left.sha256 === right.sha256
+    && left.bytes === right.bytes;
+}
+
+function validReceiptId(value) {
+  return typeof value === 'string'
+    && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+
+function allChecksPassed(checks) {
+  return Array.isArray(checks) && checks.length > 0
+    && checks.every((check) => isReceiptObject(check) && check.ok === true);
+}
+
+function validCheckComposition(receipt, quality) {
+  const composition = receipt?.composition;
+  return isReceiptObject(composition)
+    && composition.schemaVersion === 1
+    && composition.profile === quality
+    && composition.status === 'pass'
+    && composition.summary?.errors === 0
+    && (quality !== 'showcase' || composition.summary?.warnings === 0);
+}
+
+function exactViewportCoverage(entries, viewports, predicate) {
+  if (!Array.isArray(entries) || entries.length !== viewports.length) return false;
+  return viewports.every((expected) => {
+    const matching = entries.filter((entry) => (
+      isReceiptObject(entry)
+        && entry.width === expected.width
+        && entry.height === expected.height
+        && (expected.theme === undefined || entry.requestedTheme === expected.theme)
+    ));
+    return matching.length === 1 && predicate(matching[0], expected);
+  });
+}
+
+function validBrowserEvidence(receipt) {
+  return exactViewportCoverage(receipt.containment?.viewports, VISUAL_CHECK_VIEWPORTS, (entry) => (
+    entry.theme === 'light' && entry.ok === true
+  ))
+    && exactViewportCoverage(receipt.readability?.viewports, VISUAL_CHECK_VIEWPORTS, (entry) => (
+      entry.theme === 'light' && entry.ok === true && entry.readabilityOk === true
+    ))
+    && exactViewportCoverage(receipt.viewerChrome?.viewports, VISUAL_CHECK_VIEWPORTS, (entry) => (
+      entry.theme === 'light' && entry.ok === true && entry.viewerChromeOk === true
+    ))
+    && exactViewportCoverage(receipt.themeStates?.viewports,
+      [...VISUAL_CHECK_VIEWPORTS.map((viewport) => ({ ...viewport, theme: 'light' })),
+        ...CAPTURE_VIEWPORTS.map((viewport) => ({ ...viewport, theme: 'dark' }))],
+      (entry, expected) => entry.ok === true
+        && entry.requestedTheme === expected.theme
+        && entry.resolvedTheme === expected.theme);
+}
+
+function validDeliveryValidation(receipt, quality, { allowShowcaseWarnings = false } = {}) {
+  const validation = receipt?.validation;
+  return isReceiptObject(validation)
+    && Number.isInteger(validation.checkCount)
+    && validation.checkCount > 0
+    && validation.checksPassed === validation.checkCount
+    && validation.compositionStatus === 'pass'
+    && validation.errors === 0
+    && validation.compositionProfile === quality
+    && (quality !== 'showcase' || allowShowcaseWarnings || validation.warnings === 0);
+}
+
+function validStageReceipt(stage, receipt, quality, options) {
+  if (!isReceiptObject(receipt) || receipt.ok !== true) return false;
+  if (receipt.status && receipt.status !== 'pass') return false;
+  if (stage === 'validate') return receipt.command === 'validate' && Array.isArray(receipt.checks);
+  if (stage === 'deliver') {
+    return receipt.command === 'deliver'
+      && receipt.schemaVersion === 1
+      && validReceiptId(receipt.receiptId)
+      && isReceiptObject(receipt.specification)
+      && validIdentity(receipt.specification)
+      && validIdentity(receipt.artifact)
+      && validDeliveryValidation(receipt, quality, options);
+  }
+  if (stage === 'check') {
+    return validIdentity(receipt.artifact)
+      && allChecksPassed(receipt.checks)
+      && receipt.provenance === 'current'
+      && validReceiptId(receipt.deliveryReceiptId)
+      && validCheckComposition(receipt, quality);
+  }
+  return receipt.command === 'browser-check'
+    && receipt.schemaVersion === 1
+    && receipt.status === 'pass'
+    && receipt.evidenceKind === 'automated-browser'
+    && validIdentity(receipt.artifact)
+    && receipt.provenance === 'current'
+    && validReceiptId(receipt.deliveryReceiptId)
+    && receipt.containment?.status === 'pass'
+    && receipt.themeStates?.status === 'pass'
+    && receipt.readability?.status === 'pass'
+    && receipt.viewerChrome?.status === 'pass'
+    && validBrowserEvidence(receipt);
+}
+
+function identityMismatchDiagnostic({ stage, expected, actual, expectedReceiptId, actualReceiptId, output }) {
+  return {
+    code: 'finalize/artifact-binding-mismatch',
+    severity: 'error',
+    message: `The ${stage} receipt does not prove the artifact delivered by this finalize run.`,
+    subject: { stage, artifact: output },
+    evidence: {
+      expectedArtifact: expected,
+      actualArtifact: actual,
+      ...(expectedReceiptId ? { expectedDeliveryReceiptId: expectedReceiptId } : {}),
+      ...(actualReceiptId ? { actualDeliveryReceiptId: actualReceiptId } : {}),
+    },
+    supportedFixes: ['finish other delivery attempts for this output, then rerun finalize from the frozen candidate'],
+  };
+}
+
+function showcaseWarningDiagnostics(receipt) {
+  const issues = receipt.validation.compositionIssues;
+  const warnings = receipt.validation.warnings;
+  if (!Array.isArray(issues) || issues.length !== warnings
+      || !issues.every((issue) => isReceiptObject(issue)
+        && issue.severity === 'warning'
+        && typeof issue.code === 'string'
+        && issue.code.startsWith('composition/')
+        && typeof issue.detail === 'string' && issue.detail.trim())) {
+    return [{
+      code: 'finalize/showcase-warnings', severity: 'error',
+      message: `Showcase delivery reported ${warnings} composition warning(s), but did not provide matching issue details.`,
+      subject: { stage: 'deliver', check: 'composition' },
+      evidence: { warnings, reportedIssues: Array.isArray(issues) ? issues.length : null },
+      supportedFixes: ['run validate on the frozen candidate to inspect the composition warnings, repair them, then rerun finalize'],
+    }];
+  }
+  return issues.map((issue) => {
+    const { code, severity, detail, ...evidence } = issue;
+    return {
+      code, severity: 'error',
+      message: `Showcase delivery reported ${code}; zero warnings are required.`,
+      subject: { stage: 'deliver', check: 'composition', ...(issue.nodeId ? { nodeId: issue.nodeId } : {}) },
+      evidence: { reportedSeverity: severity, ...evidence },
+      supportedFixes: [detail.replace(/^\[[^\]]+\]\s*/, '')],
+    };
+  });
+}
+
+function stageBindingDiagnostic({ stage, receipt, expectedArtifact, expectedReceiptId, output, specification, type, deliveryValidation }) {
+  if (stage === 'deliver') {
+    if (receipt.type !== type) {
+      return {
+        code: 'finalize/delivery-type-mismatch',
+        severity: 'error',
+        message: 'The delivery command reported a different diagram type than finalize requested.',
+        subject: { stage: 'deliver', artifact: output },
+        evidence: { expectedType: type, actualType: receipt.type },
+        supportedFixes: ['rerun finalize with a delivery command for the requested diagram type'],
+      };
+    }
+    if (!identitiesMatch(receipt.specification, specification)) {
+      return {
+        code: 'finalize/candidate-changed-during-delivery',
+        severity: 'error',
+        message: 'The delivery command froze a different candidate than finalize started with.',
+        subject: { stage: 'validate', candidate: specification.path },
+        evidence: {
+          expectedSha256: specification.sha256,
+          actualSha256: receipt.specification?.sha256,
+          expectedBytes: specification.bytes,
+          actualBytes: receipt.specification?.bytes,
+        },
+        supportedFixes: ['restore the frozen candidate and rerun finalize'],
+      };
+    }
+    if ((!receipt.output || !pathsAlias(receipt.output, output)) || !identitiesMatch(receipt.artifact, identity(output))) {
+      return identityMismatchDiagnostic({
+        stage,
+        expected: receipt.artifact,
+        actual: identity(output),
+        expectedReceiptId: receipt.receiptId,
+        output,
+      });
+    }
+    return null;
+  }
+  if (stage === 'check' && deliveryValidation?.checkCount !== receipt.checks.length) {
+    return {
+      code: 'finalize/delivery-validation-mismatch',
+      severity: 'error',
+      message: 'The delivery validation count does not match the complete checker receipt for the delivered artifact.',
+      subject: { stage: 'check', artifact: output },
+      evidence: {
+        deliveryCheckCount: deliveryValidation?.checkCount,
+        checkerCheckCount: receipt.checks.length,
+      },
+      supportedFixes: ['restore the complete delivery validation receipt and rerun finalize from the frozen candidate'],
+    };
+  }
+  const receiptArtifactPath = receipt.artifact?.path;
+  const receiptFile = receipt.file;
+  const pathMatchesOutput = stage === 'check'
+    ? typeof receiptFile === 'string' && pathsAlias(receiptFile, output)
+    : typeof receiptArtifactPath === 'string' && pathsAlias(receiptArtifactPath, output);
+  if (!pathMatchesOutput
+      || !identitiesMatch(receipt.artifact, expectedArtifact)
+      || receipt.deliveryReceiptId !== expectedReceiptId) {
+    return identityMismatchDiagnostic({
+      stage,
+      expected: expectedArtifact,
+      actual: receipt.artifact,
+      expectedReceiptId,
+      actualReceiptId: receipt.deliveryReceiptId,
+      output,
+    });
+  }
+  return null;
+}
+
+function finalArtifactDiagnostic({ output, expectedArtifact, expectedReceiptId, type, deliveryPath, inspectDelivery }) {
+  // Recheck dev's pending/lock, physical identity, and regular-file provenance barriers at handoff.
+  const provenance = inspectDelivery?.(output);
+  if (provenance && (!provenance.ok || provenance.receiptId !== expectedReceiptId)) {
+    return provenance.diagnostics?.[0] || identityMismatchDiagnostic({
+      stage: 'finalize', output, expected: expectedArtifact,
+      expectedReceiptId, actualReceiptId: provenance.receiptId,
+    });
+  }
+  const currentArtifact = identity(output);
+  let delivery;
+  try {
+    delivery = JSON.parse(fs.readFileSync(deliveryPath, 'utf8'));
+  } catch {
+    delivery = null;
+  }
+  if (identitiesMatch(currentArtifact, expectedArtifact)
+      && delivery?.schemaVersion === 1
+      && delivery.command === 'deliver'
+      && delivery.status === 'current'
+      && delivery.receiptId === expectedReceiptId
+      && delivery.type === type
+      && typeof delivery.output === 'string' && pathsAlias(delivery.output, output)
+      && identitiesMatch(delivery.artifact, expectedArtifact)) return null;
+  return {
+    code: 'finalize/final-artifact-mismatch',
+    severity: 'error',
+    message: 'The artifact or delivery receipt changed after the final gate completed.',
+    subject: { stage: 'finalize', artifact: output },
+    evidence: {
+      expectedArtifact,
+      currentArtifact,
+      expectedDeliveryReceiptId: expectedReceiptId,
+      expectedType: type,
+      ...(delivery?.receiptId ? { currentDeliveryReceiptId: delivery.receiptId } : {}),
+      ...(delivery?.type ? { currentType: delivery.type } : {}),
+      ...(delivery?.artifact ? { currentDeliveryArtifact: delivery.artifact } : {}),
+    },
+    supportedFixes: ['finish other delivery attempts for this output, then rerun finalize from the frozen candidate'],
+  };
+}
+
+function stageStatus(stage, exitCode, receipt, quality) {
+  if (exitCode === 2 || receipt?.status === 'skipped') return 'skipped';
+  return exitCode === 0 && validStageReceipt(stage, receipt, quality) ? 'pass' : 'fail';
+}
+
+function failureDiagnostics(stage, result, receipt, quality) {
+  if (Array.isArray(receipt?.diagnostics) && receipt.diagnostics.length) return receipt.diagnostics;
+  const invalidReceipt = (result.status ?? 1) === 0 && !validStageReceipt(stage, receipt, quality);
+  return [{
+    code: invalidReceipt ? 'finalize/invalid-stage-receipt' : 'finalize/stage-failure',
+    severity: 'error',
+    message: invalidReceipt
+      ? `The ${stage} stage exited successfully without a valid passing receipt.`
+      : `The ${stage} stage did not complete successfully.`,
+    subject: { stage },
+    evidence: {
+      exitCode: result.status ?? 1,
+      ...(result.signal ? { signal: result.signal } : {}),
+      ...(result.error?.message ? { reason: result.error.message } : {}),
+      ...(String(result.stdout || '').trim() ? { stdout: String(result.stdout).trim().slice(0, 2000) } : {}),
+      ...(String(result.stderr || '').trim() ? { stderr: String(result.stderr).trim().slice(0, 2000) } : {}),
+    },
+    supportedFixes: [invalidReceipt
+      ? `restore the ${stage} JSON receipt contract before retrying finalize`
+      : 'use the compact finalize summary to repair the named subject in place, then rerun finalize once'],
+  }];
+}
+
+function sidecarFile(directory, value) {
+  if (!value) return null;
+  return path.resolve(directory, value);
+}
+
+function browserEvidence(receipt, artifactPath) {
+  if (!receipt) return {};
+  const directory = receipt.sidecars?.directory
+    ? path.resolve(receipt.sidecars.directory)
+    : path.dirname(path.resolve(artifactPath));
+  return {
+    ...(receipt.sidecars?.receipt ? { browserCheckReceipt: sidecarFile(directory, receipt.sidecars.receipt) } : {}),
+  };
+}
+
+function defaultRunner({ cliPath, args, cwd, env }) {
+  return new Promise((resolve) => {
+    execFile(process.execPath, [cliPath, ...args], { cwd, env, encoding: 'utf8' }, (error, stdout, stderr) => {
+      resolve({
+        status: error ? (Number.isInteger(error.code) ? error.code : 1) : 0,
+        stdout,
+        stderr,
+        ...(error ? { error, signal: error.signal } : {}),
+      });
+    });
+  });
+}
+
+function stageArguments({ stage, type, input, output, quality, repoRoot, outDir }) {
+  const qualityArgs = ['--quality', quality];
+  const repoArgs = repoRoot ? ['--repo-root', repoRoot] : [];
+  if (stage === 'validate') return ['validate', type, input, ...qualityArgs, ...repoArgs, '--json'];
+  if (stage === 'deliver') return ['deliver', type, input, output, ...qualityArgs, ...repoArgs, '--json'];
+  if (stage === 'check') return ['check', output, '--require-provenance'];
+  return [
+    'browser-check', output, '--json', '--require-provenance',
+    ...(outDir ? ['--out-dir', outDir] : []),
+  ];
+}
+
+export function defaultFinalizeReceiptPath(output, { outDir } = {}) {
+  // Reuse the physical artifact and cross-directory namespace used by browser evidence.
+  const browserReceipt = browserCheckSidecarPaths(output, { outDir }).receipt;
+  const stem = path.basename(browserReceipt).slice(0, -'.browser-check.json'.length);
+  return path.join(path.dirname(browserReceipt), `${boundedSidecarStem(stem, ['.finalize.json', '.finalize-summary.json'])}.finalize.json`);
+}
+
+export function defaultFinalizeSummaryPath(receiptPath) {
+  const receipt = path.resolve(receiptPath);
+  const component = path.basename(receipt);
+  const isDefault = /\.finalize\.json$/i.test(component);
+  const stem = component.replace(isDefault ? /\.finalize\.json$/i : /\.json$/i, '');
+  const suffix = isDefault ? '.finalize-summary.json' : '-summary.json';
+  // Already bounded default stems share the receipt namespace; avoid hashing twice.
+  const summaryStem = Buffer.byteLength(`${stem}${suffix}`) <= 255 && `${stem}${suffix}`.length <= 255
+    ? stem : boundedSidecarStem(stem, [suffix]);
+  return path.join(path.dirname(receipt), `${summaryStem}${suffix}`);
+}
+
+function defaultDeliveryPaths(output) {
+  const artifact = canonicalFuturePath(output);
+  const delivery = artifact.replace(/\.html?$/i, '.delivery.json');
+  return {
+    provenance: delivery,
+    pending: delivery.replace(/\.json$/i, '-pending.json'),
+    lock: delivery.replace(/\.json$/i, '-lock.json'),
+    directoryLock: path.join(path.dirname(artifact), '.archify-delivery-lock.json'),
+  };
+}
+
+function reservedFinalizePaths({ input, output, outDir, deliveryPaths }) {
+  const browser = browserCheckSidecarPaths(output, { outDir });
+  return [path.resolve(input), path.resolve(output), ...Object.values(deliveryPaths(output)), browser.receipt];
+}
+
+// Node moves that remove the measured crossings and detours, most specific
+// first. Only positions and sizes change; every relationship keeps its endpoints.
+function placementHints({ crossings = [], detours = [], crowdedSides = [] }) {
+  const name = (relation) => `${relation.from} → ${relation.to}`;
+  const other = (relation, shared) => (relation.from === shared ? relation.to : relation.from);
+  const hints = [];
+  for (const side of crowdedSides) {
+    hints.push(`${side.node} has ${side.relationships} relationships facing its ${side.side} side, which fits ${Math.max(1, Math.floor((side.sidePx - 32) / 14) + 1)} ports: make that side at least ${side.neededPx}px, or move some of those neighbours so they face another side of ${side.node}.`);
+  }
+  for (const crossing of crossings) {
+    const shared = crossing.sharedNode;
+    hints.push(shared
+      ? `${name(crossing.left)} and ${name(crossing.right)} cross next to ${shared}: move node ${other(crossing.left, shared)} or ${other(crossing.right, shared)} so the two reach ${shared} from different sides (for example one level with it, one directly above or below it).`
+      : `${name(crossing.left)} crosses ${name(crossing.right)}: move the node of whichever is a branch, return, or second entrance to the other side of the main path, so that relationship runs through an empty corridor.`);
+  }
+  for (const detour of detours) {
+    if (detour.directCorridorBlockers?.length) continue;
+    hints.push(`${name(detour.relationship)} needs ${detour.bends} bends: move node ${detour.relationship.from} or ${detour.relationship.to} so they share a row or column with matching centers, or sit diagonally with a clear corner.`);
+  }
+  return [...new Set(hints)].slice(0, 8);
+}
+
+export function compactFinalizeReceipt(receipt) {
+  const gates = {};
+  for (const stage of FINALIZE_STAGES) gates[stage] = receipt.stages?.[stage]?.status || 'not-run';
+  const allDiagnostics = receipt.diagnostics || [];
+  const diagnosticLimit = 8;
+  const selectedDiagnostics = [];
+  const selectedIndexes = new Set();
+  const seenCodes = new Set();
+  const seenSubjects = new Set();
+  const subjectKey = (entry) => {
+    const subject = entry?.subject;
+    if (!subject) return null;
+    if (typeof subject === 'string') return subject;
+    if (typeof subject !== 'object' || Array.isArray(subject)) return JSON.stringify(subject);
+    for (const key of ['id', 'edge', 'connection', 'relationship', 'component', 'node', 'path', 'stage']) {
+      if (subject[key] !== undefined) return `${key}:${JSON.stringify(subject[key])}`;
+    }
+    return JSON.stringify(subject);
+  };
+  const addDiagnostic = (entry, index) => {
+    if (selectedDiagnostics.length >= diagnosticLimit || selectedIndexes.has(index)) return;
+    selectedIndexes.add(index);
+    selectedDiagnostics.push({
+      code: entry.code,
+      severity: entry.severity || 'error',
+      message: entry.message,
+      ...(entry.subject ? { subject: entry.subject } : {}),
+      ...(entry.evidence && Object.keys(entry.evidence).length ? { evidence: entry.evidence } : {}),
+      ...(Array.isArray(entry.supportedFixes) && entry.supportedFixes.length
+        ? { supportedFixes: entry.supportedFixes.slice(0, 2) } : {}),
+    });
+  };
+  for (const [index, entry] of allDiagnostics.entries()) {
+    if (seenCodes.has(entry.code)) continue;
+    seenCodes.add(entry.code);
+    addDiagnostic(entry, index);
+  }
+  for (const [index, entry] of allDiagnostics.entries()) {
+    const key = subjectKey(entry);
+    if (!key || seenSubjects.has(key)) continue;
+    seenSubjects.add(key);
+    addDiagnostic(entry, index);
+  }
+  for (const [index, entry] of allDiagnostics.entries()) addDiagnostic(entry, index);
+  const compact = {
+    schemaVersion: 1,
+    ok: receipt.ok,
+    command: 'finalize',
+    status: receipt.status,
+    type: receipt.type,
+    quality: receipt.quality,
+    specification: receipt.specification,
+    artifact: receipt.artifact,
+    gates,
+    ...(receipt.failedStage ? { failedStage: receipt.failedStage } : {}),
+    diagnostics: selectedDiagnostics,
+    diagnosticSummary: {
+      total: allDiagnostics.length,
+      shown: selectedDiagnostics.length,
+      truncated: allDiagnostics.length > selectedDiagnostics.length,
+    },
+    evidence: receipt.evidence,
+    ...(receipt.update ? { update: receipt.update } : {}),
+    visualReview: receipt.visualReview || 'not-requested',
+    durationMs: receipt.durationMs,
+  };
+  const metrics = receipt.stages?.check?.receipt?.composition?.metrics;
+  const reviewSignals = Object.fromEntries([
+    'resolvedCrossovers', 'routesOverSuggestedBends', 'routesOverSuggestedStretch',
+  ].filter((key) => Number.isFinite(metrics?.[key]) && metrics[key] > 0)
+    .map((key) => [key, metrics[key]]));
+  if (receipt.ok && Object.keys(reviewSignals).length) {
+    const routeReview = receipt.stages?.check?.receipt?.composition?.routeReview;
+    const hints = routeReview ? placementHints(routeReview) : [];
+    compact.visualReviewRecommendation = {
+      action: 'inspect-route-readability',
+      signals: reviewSignals,
+      reason: 'Automated gates passed, but crossings or detours still need perceptual review before claiming visual quality.',
+      ...(routeReview ? {
+        affectedRoutes: {
+          crossings: routeReview.crossings.slice(0, 8),
+          detours: routeReview.detours.slice(0, 8),
+          truncated: routeReview.crossings.length > 8 || routeReview.detours.length > 8,
+        },
+        ...(hints.length ? { hints } : {}),
+        repair: 'Trace these relationships at the desktop viewport. For Architecture, use references/architecture-layout-repair.md: reflow a blocked main path or tangled connected scene, and repair an isolated defect locally only when the surrounding composition is accepted. Preserve all semantic content and user-fixed geometry. Rerun finalize once after the edit.',
+      } : {}),
+    };
+  }
+  const leadingSpace = receipt.stages?.check?.receipt?.composition?.leadingSpace;
+  if (receipt.ok && leadingSpace?.reviewSuggested === true) {
+    compact.layoutReviewRecommendation = {
+      action: 'inspect-leading-space',
+      evidence: leadingSpace,
+      reason: 'Measured content, including routes and labels, leaves a large empty area above the diagram. This is a composition suggestion, not a failed gate.',
+      repair: 'Check whether that leading space is intentional. If not, reposition the connected scene nearer the canvas origin while retaining room for its actual boundaries, labels and return routes. Preserve all meaning and user-fixed geometry, then rerun finalize. No screenshot is required.',
+    };
+  }
+  const sequenceColumnSpace = receipt.stages?.check?.receipt?.composition?.sequenceColumnSpace;
+  if (receipt.ok && receipt.type === 'sequence' && sequenceColumnSpace?.reviewSuggested === true) {
+    compact.layoutReviewRecommendation = {
+      action: 'inspect-sequence-width',
+      evidence: sequenceColumnSpace,
+      reason: 'Fixed participant columns leave substantial unused space on the right, after accounting for message labels and notes. This is a layout suggestion, not a failed gate.',
+      repair: 'For a newly authored Sequence with omitted meta.column_fit and no user-fixed column geometry, set meta.column_fit to "spread" and rerun finalize once. Preserve participant order, every message, its y position, labels, notes and sources. Retain explicit fixed layouts and legacy inputs; report the suggestion instead of changing them automatically.',
+    };
+  }
+  if (!receipt.ok && receipt.status === 'fail' && receipt.failedStage === 'validate') {
+    compact.nextAction = {
+      action: 'edit-in-place',
+      candidate: receipt.specification?.path,
+      constraint: receipt.type === 'architecture'
+        ? 'Preserve all semantics and user-fixed geometry. Use references/architecture-layout-repair.md to choose a local repair or connected-scene reflow; edit the existing candidate.'
+        : 'Preserve unaffected semantics and geometry; do not replace the whole candidate.',
+      then: 'finalize-once',
+    };
+  }
+  return compact;
+}
+
+export async function runFinalize({
+  cliPath,
+  type,
+  input,
+  output,
+  quality = 'showcase',
+  repoRoot,
+  candidateSha256,
+  outDir,
+  receiptPath,
+  deliveryPaths = defaultDeliveryPaths,
+  inspectDelivery,
+  cwd = process.cwd(),
+  env = process.env,
+  runCommand = defaultRunner,
+  runBrowserCheck,
+  startUpdateCheck = startDeliveryUpdateCheck,
+  resolveChrome = findChrome,
+  createBrowser = (chromePath, options) => new ChromeVisualBrowser(chromePath, options),
+} = {}) {
+  if (!cliPath || !type || !input || !output) throw new Error('finalize requires cliPath, type, input, and output.');
+  const started = process.hrtime.bigint();
+  const startedAt = new Date().toISOString();
+  const resolvedInput = path.resolve(input);
+  const resolvedOutput = resolveOutputPath({ requestedOutput: output, inputPaths: [resolvedInput] }).outputPath;
+  const resolvedOutDir = outDir === undefined ? undefined : resolveNativeOutputDirectory(outDir);
+  const specification = identity(resolvedInput);
+  if (candidateSha256 && specification.sha256 !== candidateSha256) {
+    const error = new Error(`The candidate changed after validation: expected sha256 ${candidateSha256}, found ${specification.sha256 || 'unreadable'}.`);
+    error.finalizeCode = 'finalize/candidate-changed';
+    error.finalizeEvidence = {
+      candidate: resolvedInput,
+      expectedSha256: candidateSha256,
+      ...(specification.sha256 ? { actualSha256: specification.sha256 } : {}),
+    };
+    throw error;
+  }
+  // Validate raw native CLI paths before creating directories or normalizing them.
+  if (receiptPath !== undefined) resolveOutputPath({ requestedOutput: receiptPath, inputPaths: [resolvedInput], requiredExtension: '.json' });
+  fs.mkdirSync(path.dirname(canonicalFuturePath(resolvedOutput)), { recursive: true });
+  const resolvedReceipt = resolveOutputPath({
+    requestedOutput: receiptPath ?? defaultFinalizeReceiptPath(resolvedOutput, { outDir: resolvedOutDir }),
+    inputPaths: [resolvedInput], requiredExtension: '.json',
+  }).outputPath;
+  const resolvedSummary = resolveOutputPath({
+    requestedOutput: defaultFinalizeSummaryPath(resolvedReceipt), inputPaths: [resolvedInput], requiredExtension: '.json',
+  }).outputPath;
+  const assertReceiptPaths = () => {
+    const reserved = reservedFinalizePaths({ input: resolvedInput, output: resolvedOutput, outDir: resolvedOutDir, deliveryPaths });
+    const receiptCollision = reserved.find((file) => pathsAlias(resolvedReceipt, file));
+    if (receiptCollision) throw new Error(`The finalize receipt must be distinct from the specification, artifact, and gate sidecars: "${receiptCollision}".`);
+    const summaryCollision = [resolvedReceipt, ...reserved].find((file) => pathsAlias(resolvedSummary, file));
+    if (summaryCollision) throw new Error(`The finalize summary must be distinct from the full receipt, specification, artifact, and gate sidecars: "${summaryCollision}".`);
+  };
+  assertReceiptPaths();
+  // Capture both paths before changing either: an unsafe summary cannot leave a new full receipt behind.
+  let receiptCapture = captureReceipt(resolvedReceipt);
+  let summaryCapture = captureReceipt(resolvedSummary);
+
+  const receipt = {
+    schemaVersion: 1,
+    ok: false,
+    command: 'finalize',
+    status: 'running',
+    type,
+    quality,
+    startedAt,
+    specification,
+    artifact: { path: resolvedOutput },
+    stages: {},
+    diagnostics: [],
+    evidence: { receipt: resolvedReceipt, summaryReceipt: resolvedSummary },
+    visualReview: 'not-requested',
+  };
+  const persistReceipts = () => {
+    assertReceiptPaths();
+    for (const [file, capture] of [[resolvedReceipt, receiptCapture], [resolvedSummary, summaryCapture]]) {
+      const current = verifyAtomicOutput(capture.snapshot);
+      if (current.status !== 'match') throw receiptWriteError(file, current);
+    }
+    receiptCapture = writeJsonAtomic(resolvedReceipt, receipt, receiptCapture, assertReceiptPaths);
+    summaryCapture = writeJsonAtomic(resolvedSummary, compactFinalizeReceipt(receipt), summaryCapture, assertReceiptPaths);
+  };
+  persistReceipts();
+  // The gates below usually take seconds, so a slower network can finish the
+  // update check in parallel instead of timing out on every delivery.
+  const updateCheck = startUpdateCheck({ env, deadlineMs: FINALIZE_UPDATE_DEADLINE_MS });
+
+  // Only launch/attach the blank browser here. The normal browser gate still
+  // verifies current delivery provenance before it consumes this one-shot factory.
+  const chromePath = runBrowserCheck ? resolveChrome({ env }) : null;
+  let browser;
+  let browserStartupError;
+  let browserTransferred = false;
+  if (chromePath) {
+    try {
+      browser = createBrowser(chromePath, { env });
+      // Deliver/check may fail before inspect() awaits startup. Handle the
+      // rejection now while retaining the same promise for the browser gate.
+      browser.sessionPromise.catch(() => {});
+    } catch (error) {
+      browserStartupError = error;
+    }
+  }
+  const browserFactory = () => {
+    if (browserStartupError) throw browserStartupError;
+    if (browserTransferred || !browser) throw new Error('The finalize browser is unavailable or already consumed.');
+    browserTransferred = true;
+    return browser;
+  };
+
+  try {
+    let exitCode = 0;
+    for (const stage of ['deliver', 'check', 'browser-check']) {
+      const stageStarted = process.hrtime.bigint();
+      const args = stageArguments({
+        stage,
+        type,
+        input: resolvedInput,
+        output: resolvedOutput,
+        quality,
+        repoRoot,
+        outDir: resolvedOutDir,
+      });
+      const inProcess = stage === 'browser-check' && runBrowserCheck;
+      let result;
+      if (inProcess) {
+        const checked = await runBrowserCheck({
+          artifactPath: resolvedOutput,
+          outDir: resolvedOutDir,
+          chromePath,
+          resolveChrome: () => chromePath,
+          browserFactory,
+        });
+        result = { status: checked.exitCode, stdout: JSON.stringify(checked.receipt) };
+      } else {
+        result = await runCommand({ stage, cliPath, args, cwd,
+          env: stage === 'deliver' ? { ...env, ARCHIFY_UPDATE_CHECK_DISABLED: '1' } : env });
+      }
+      const stageReceipt = parsedReceipt(result.stdout);
+      const code = result.status ?? 1;
+      let status = stageStatus(stage, code, stageReceipt, quality);
+      let stageDiagnostics;
+      const command = [process.execPath, cliPath, ...args];
+      const elapsed = durationMs(stageStarted);
+      if (status === 'pass') {
+        const deliveryReceipt = stage === 'deliver' ? stageReceipt : receipt.stages.deliver?.receipt;
+        const bindingDiagnostic = stageBindingDiagnostic({
+          stage,
+          receipt: stageReceipt,
+          expectedArtifact: deliveryReceipt?.artifact,
+          expectedReceiptId: deliveryReceipt?.receiptId,
+          output: resolvedOutput,
+          specification,
+          type,
+          deliveryValidation: deliveryReceipt?.validation,
+        });
+        if (bindingDiagnostic) stageDiagnostics = [bindingDiagnostic];
+      } else if (stage === 'deliver' && code === 0 && quality === 'showcase'
+          && Number.isSafeInteger(stageReceipt?.validation?.warnings)
+          && stageReceipt.validation.warnings > 0
+          && validStageReceipt(stage, stageReceipt, quality, { allowShowcaseWarnings: true })) {
+        const bindingDiagnostic = stageBindingDiagnostic({
+          stage, receipt: stageReceipt, output: resolvedOutput, specification, type,
+        });
+        stageDiagnostics = bindingDiagnostic ? [bindingDiagnostic] : showcaseWarningDiagnostics(stageReceipt);
+      }
+      if (stageDiagnostics) {
+        status = 'fail';
+      }
+      const stageEntry = {
+        status,
+        exitCode: code,
+        durationMs: elapsed,
+        command,
+        ...(inProcess ? { execution: 'in-process' } : {}),
+        ...(stageReceipt ? { receipt: stageReceipt } : {}),
+        ...(!stageReceipt && String(result.stdout || '').trim() ? { stdout: String(result.stdout).trim() } : {}),
+        ...(String(result.stderr || '').trim() ? { stderr: String(result.stderr).trim() } : {}),
+        ...(result.signal ? { signal: result.signal } : {}),
+      };
+
+      if (stage === 'deliver' && status === 'pass') {
+        receipt.stages.validate = {
+          status: 'pass',
+          exitCode: 0,
+          durationMs: null,
+          execution: 'embedded-in-deliver',
+          command,
+          receipt: {
+            schemaVersion: 1,
+            ok: true,
+            command: 'validate',
+            specification: stageReceipt.specification,
+            validation: stageReceipt.validation,
+          },
+        };
+        receipt.stages.deliver = stageEntry;
+      } else if (stage === 'deliver') {
+        const validationFailed = stageDiagnostics?.some((diagnostic) => diagnostic.code === 'finalize/candidate-changed-during-delivery')
+          || ['input', 'render', 'check'].includes(stageReceipt?.stage);
+        receipt.stages.validate = validationFailed ? {
+          ...stageEntry,
+          status: 'fail',
+          durationMs: null,
+          execution: 'embedded-in-deliver',
+        } : { status: 'not-run', execution: 'embedded-in-deliver' };
+        receipt.stages.deliver = validationFailed
+          ? { status: 'not-run', execution: 'blocked-by-validate' }
+          : stageEntry;
+      } else {
+        receipt.stages[stage] = stageEntry;
+      }
+
+      if (stage === 'deliver' && stageReceipt?.artifact) receipt.artifact = {
+        path: resolvedOutput,
+        ...stageReceipt.artifact,
+      };
+      if (stage === 'browser-check') {
+        receipt.evidence = {
+          receipt: resolvedReceipt,
+          summaryReceipt: resolvedSummary,
+          ...browserEvidence(stageReceipt, resolvedOutput),
+        };
+      }
+
+      if (status !== 'pass') {
+        exitCode = status === 'skipped' ? 2 : (code || 1);
+        receipt.status = status;
+        receipt.diagnostics = stageDiagnostics || failureDiagnostics(stage, result, stageReceipt, quality);
+        receipt.failedStage = stage === 'deliver'
+          && receipt.stages.validate.status === 'fail' ? 'validate' : stage;
+        break;
+      }
+      persistReceipts();
+    }
+
+    receipt.ok = exitCode === 0;
+    receipt.status = receipt.ok ? 'pass' : receipt.status === 'running' ? 'fail' : receipt.status;
+    if (receipt.ok) {
+      const deliveryReceipt = receipt.stages.deliver?.receipt;
+      const diagnostic = finalArtifactDiagnostic({
+        output: resolvedOutput,
+        expectedArtifact: deliveryReceipt?.artifact,
+        expectedReceiptId: deliveryReceipt?.receiptId,
+        type,
+        deliveryPath: deliveryPaths(resolvedOutput).provenance,
+        inspectDelivery,
+      });
+      if (diagnostic) {
+        exitCode = 1;
+        receipt.ok = false;
+        receipt.status = 'fail';
+        receipt.failedStage = 'finalize';
+        receipt.diagnostics = [diagnostic];
+      }
+    }
+    if (receipt.ok && !identitiesMatch(specification, identity(resolvedInput))) {
+      exitCode = 1;
+      receipt.ok = false;
+      receipt.status = 'fail';
+      receipt.failedStage = 'finalize';
+      receipt.diagnostics = [{
+        code: 'finalize/candidate-changed', severity: 'error',
+        message: 'The frozen candidate changed before the final handoff.',
+        subject: { candidate: resolvedInput },
+        evidence: { expected: specification, actual: identity(resolvedInput) },
+        supportedFixes: ['restore the frozen candidate, or finalize the edited candidate as a new attempt'],
+      }];
+    }
+    receipt.artifact = receipt.ok
+      ? { path: resolvedOutput, ...receipt.stages.deliver.receipt.artifact }
+      : identity(resolvedOutput);
+    receipt.finishedAt = new Date().toISOString();
+    receipt.durationMs = durationMs(started);
+    receipt.update = await updateCheck;
+    persistReceipts();
+    return { exitCode, receipt, summary: compactFinalizeReceipt(receipt) };
+  } finally {
+    if (browser && !browserTransferred) await browser.close();
+    await updateCheck;
+  }
+}

vendor/archify/bin/open-artifact.mjs

@@ -0,0 +1,146 @@
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+const OPENERS = {
+  darwin: {
+    command: 'open',
+    method: 'open',
+    timeoutMs: 5000,
+    args: (target) => [target],
+  },
+  linux: {
+    command: 'xdg-open',
+    method: 'xdg-open',
+    timeoutMs: 5000,
+    args: (target) => [target],
+  },
+  win32: {
+    command: 'powershell.exe',
+    method: 'powershell',
+    // PowerShell cold starts can approach five seconds on hosted Windows
+    // runners. Keep the launch bounded without treating normal startup as a
+    // timeout.
+    timeoutMs: 15000,
+    // Keep the command constant and pass the target through a child-only
+    // environment variable. Paths are never interpolated into executable source.
+    args: () => [
+      '-NoProfile',
+      '-NonInteractive',
+      '-Command',
+      'Start-Process -FilePath $env:ARCHIFY_OPEN_TARGET',
+    ],
+  },
+};
+
+function failureDetails(result, opener, timeoutMs) {
+  const error = result?.error;
+  if (error?.code === 'ENOENT') {
+    return {
+      code: 'opener/unavailable',
+      reason: `Could not find ${opener.command}. Install or enable the platform opener, then open the target manually.`,
+      systemCode: 'ENOENT',
+    };
+  }
+  if (error?.code === 'ETIMEDOUT') {
+    return {
+      code: 'opener/timeout',
+      reason: `${opener.command} did not finish within ${timeoutMs}ms. Open the target manually or retry when the system is less busy.`,
+      systemCode: 'ETIMEDOUT',
+      timeoutMs,
+    };
+  }
+  if (error) {
+    return {
+      code: 'opener/spawn-failed',
+      reason: error.message || `${opener.command} could not be started. Open the target manually.`,
+      ...(error.code ? { systemCode: String(error.code) } : {}),
+    };
+  }
+  if (result?.signal) {
+    return {
+      code: 'opener/signaled',
+      reason: `${opener.command} was terminated by ${result.signal}. Open the target manually.`,
+      signal: result.signal,
+    };
+  }
+  if (result?.status !== 0) {
+    return {
+      code: 'opener/nonzero-exit',
+      reason: `${opener.command} exited with status ${result?.status ?? 'unknown'}. Open the target manually.`,
+      exitCode: result?.status ?? null,
+    };
+  }
+  return null;
+}
+
+function launchTimeout(value, fallback) {
+  return Number.isSafeInteger(value) && value > 0 ? value : fallback;
+}
+
+function launchTarget(target, options = {}) {
+  const platform = options.platform || process.platform;
+  const opener = OPENERS[platform];
+  if (!opener) {
+    return {
+      requested: true,
+      status: 'unsupported',
+      target,
+      method: null,
+    };
+  }
+
+  const spawn = options.spawn || spawnSync;
+  const timeoutMs = launchTimeout(options.timeoutMs, opener.timeoutMs);
+  let result;
+  try {
+    const spawnOptions = {
+      encoding: 'utf8',
+      shell: false,
+      stdio: 'ignore',
+      timeout: timeoutMs,
+      windowsHide: true,
+    };
+    if (platform === 'win32') {
+      spawnOptions.env = {
+        ...process.env,
+        ARCHIFY_OPEN_TARGET: target,
+      };
+    }
+    result = spawn(opener.command, opener.args(target), spawnOptions);
+  } catch (error) {
+    result = { error };
+  }
+
+  const failure = failureDetails(result, opener, timeoutMs);
+  let status = 'opened';
+  if (failure?.code === 'opener/unavailable') status = 'unsupported';
+  else if (failure) status = 'failed';
+
+  return {
+    requested: true,
+    status,
+    target,
+    method: opener.method,
+    ...(failure ? { failure } : {}),
+  };
+}
+
+export function openArtifact(target, options = {}) {
+  return launchTarget(path.resolve(target), options);
+}
+
+export function openLoopbackUrl(target, options = {}) {
+  let url;
+  try {
+    url = new URL(target);
+  } catch {
+    throw new TypeError('Preview URL must be a valid loopback HTTP URL.');
+  }
+  if (url.protocol !== 'http:' || url.hostname !== '127.0.0.1' || !url.port) {
+    throw new TypeError('Preview URL must be a loopback URL using http://127.0.0.1:<port>.');
+  }
+  if (url.username || url.password || url.pathname !== '/' || url.search || url.hash) {
+    throw new TypeError('Preview URL must target the loopback preview root.');
+  }
+  return launchTarget(url.href, options);
+}

vendor/archify/bin/preview.mjs

@@ -0,0 +1,969 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { openLoopbackUrl } from './open-artifact.mjs';
+import { resolveOutputPath } from '../renderers/shared/output-path.mjs';
+import { sameLocation } from '../renderers/shared/path-semantics.mjs';
+import {
+  captureAtomicOutput,
+  captureRegularFileBinding,
+  publishRegularFileBinding,
+  releaseRegularFileBinding,
+  removeEmptyDirectoryWithRetry,
+  removeOwnedRegularFile,
+  verifyAtomicOutput,
+} from '../renderers/shared/atomic-output.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const cliPath = path.join(here, 'archify.mjs');
+const loopbackHost = '127.0.0.1';
+const defaultDebounceMs = 400;
+const defaultPollMs = 800;
+const defaultStopGraceMs = 3000;
+const defaultStopKillMs = 750;
+const diagramTypes = new Set(['architecture', 'workflow', 'sequence', 'dataflow', 'lifecycle']);
+let previewCommitSequence = 0;
+
+function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function sourceDigest(inputPath) {
+  try {
+    const bytes = fs.readFileSync(inputPath);
+    return { hash: sha256(bytes), bytes, missing: false };
+  } catch (error) {
+    return { hash: `unreadable:${error.code || 'unknown'}`, bytes: null, missing: true };
+  }
+}
+
+function initialAuthoredOutput(inputPath) {
+  try {
+    const source = JSON.parse(fs.readFileSync(inputPath, 'utf8'));
+    if (typeof source?.meta?.output === 'string') {
+      return source.meta.output;
+    }
+  } catch {
+    // An invalid initial source still gets a status shell. Its output target is
+    // fixed to the same fallback that `deliver` would use after repair.
+  }
+  return undefined;
+}
+
+function previewPage() {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>Archify Live Preview</title>
+  <style>
+    :root { color-scheme: light dark; font-family: Inter, ui-sans-serif, system-ui, sans-serif; }
+    * { box-sizing: border-box; }
+    html, body { width: 100%; height: 100%; margin: 0; overflow: hidden; background: #0b111b; }
+    body { display: grid; grid-template-rows: auto minmax(0, 1fr); color: #e8edf5; }
+    header { position: relative; z-index: 2; display: flex; align-items: center; gap: 12px; min-height: 44px; padding: 7px 12px; border-bottom: 1px solid #253248; background: rgba(11, 17, 27, .96); box-shadow: 0 8px 22px rgba(0,0,0,.18); }
+    .brand { font-size: 12px; font-weight: 700; letter-spacing: .08em; text-transform: uppercase; color: #9cadc6; }
+    #status { margin-left: auto; display: inline-flex; align-items: center; gap: 8px; min-height: 30px; padding: 5px 10px; border: 1px solid #33435d; border-radius: 999px; background: #111b2a; font-size: 12px; white-space: nowrap; }
+    #status::before { content: ''; width: 8px; height: 8px; border-radius: 50%; background: #6f819d; }
+    body[data-state="checking"] #status::before { background: #f3b44b; box-shadow: 0 0 0 4px rgba(243,180,75,.12); }
+    body[data-state="verified"] #status::before { background: #45d6a8; box-shadow: 0 0 0 4px rgba(69,214,168,.12); }
+    body[data-state="needs-fix"] #status::before { background: #ff6f78; box-shadow: 0 0 0 4px rgba(255,111,120,.12); }
+    details { max-width: min(62vw, 760px); }
+    summary { cursor: pointer; color: #ffbdc2; font-size: 12px; }
+    .diagnostic { position: absolute; top: 38px; right: 12px; width: min(760px, calc(100vw - 24px)); max-height: min(44vh, 360px); overflow: auto; padding: 14px; border: 1px solid #6a3440; border-radius: 10px; background: #17131b; box-shadow: 0 14px 48px rgba(0,0,0,.42); }
+    pre { margin: 0 0 10px; white-space: pre-wrap; overflow-wrap: anywhere; font: 11px/1.55 ui-monospace, SFMono-Regular, Menlo, monospace; color: #f2dfe2; }
+    button { min-height: 32px; padding: 5px 10px; border: 1px solid #4a5d79; border-radius: 7px; background: #1a273a; color: #eef4ff; cursor: pointer; }
+    main { position: relative; min-height: 0; }
+    iframe { display: none; width: 100%; height: 100%; border: 0; background: #fff; }
+    body[data-has-artifact="true"] iframe { display: block; }
+    #empty { position: absolute; inset: 0; display: grid; place-items: center; padding: 32px; color: #91a2bc; text-align: center; background: radial-gradient(circle at 50% 38%, #15233a 0, #0b111b 55%); }
+    body[data-has-artifact="true"] #empty { display: none; }
+    @media (prefers-reduced-motion: reduce) { * { scroll-behavior: auto !important; } }
+  </style>
+</head>
+<body data-state="checking" data-has-artifact="false">
+  <header>
+    <span class="brand">Archify Preview</span>
+    <details id="failure" hidden>
+      <summary role="button" aria-controls="diagnostic-panel">View diagnostic</summary>
+      <div class="diagnostic" id="diagnostic-panel"><pre id="diagnostic"></pre><button id="copy" type="button">Copy diagnostic</button></div>
+    </details>
+    <span id="status" role="status" aria-live="polite">Checking · generation 1</span>
+  </header>
+  <main>
+    <div id="empty">Waiting for the first verified diagram. Invalid input will stay here with an exact diagnostic.</div>
+    <iframe id="artifact" title="Verified Archify diagram"></iframe>
+  </main>
+  <script>
+    (function () {
+      'use strict';
+      var body = document.body;
+      var status = document.getElementById('status');
+      var failure = document.getElementById('failure');
+      var diagnostic = document.getElementById('diagnostic');
+      var artifact = document.getElementById('artifact');
+      var lastRevision = 0;
+
+      function render(state) {
+        body.dataset.state = state.status;
+        if (state.status === 'verified') {
+          status.textContent = 'Verified · rev ' + state.revision;
+          failure.hidden = true;
+          failure.open = false;
+          if (state.revision !== lastRevision) {
+            lastRevision = state.revision;
+            artifact.src = '/artifact.html?revision=' + encodeURIComponent(state.revision) + '&sha=' + encodeURIComponent(state.lastVerified.sha256.slice(0, 12));
+            body.dataset.hasArtifact = 'true';
+          }
+        } else if (state.status === 'needs-fix') {
+          status.textContent = 'Needs fix · ' + (state.revision ? 'showing rev ' + state.revision : 'no verified revision');
+          diagnostic.textContent = 'Generation ' + state.generation + ' · ' + state.failure.stage + '\\n\\n' + state.failure.message;
+          failure.hidden = false;
+        } else {
+          status.textContent = 'Checking · generation ' + state.generation;
+          failure.hidden = true;
+        }
+      }
+
+      document.getElementById('copy').addEventListener('click', function () {
+        if (navigator.clipboard && navigator.clipboard.writeText) {
+          navigator.clipboard.writeText(diagnostic.textContent).catch(function () {});
+        }
+      });
+
+      var events = new EventSource('/events');
+      events.addEventListener('state', function (event) {
+        try { render(JSON.parse(event.data)); } catch (_) {}
+      });
+    }());
+  </script>
+</body>
+</html>`;
+}
+
+function compactMessage(value) {
+  let text = String(value || 'Preview build failed without a diagnostic.').trim();
+  const lines = text.split(/\r?\n/);
+  const errorLine = lines.findIndex((line) => /^Error:\s/.test(line));
+  if (errorLine > 0) text = lines.slice(errorLine).join('\n');
+  const relevant = text.split(/\r?\n/);
+  const stackLine = relevant.findIndex((line, index) => index > 0 && /^\s*at\s/.test(line));
+  if (stackLine > 0) text = relevant.slice(0, stackLine).join('\n');
+  return text.length > 6000 ? `${text.slice(0, 6000)}\n… diagnostic truncated` : text;
+}
+
+function redactDiagnostic(value, paths) {
+  let text = compactMessage(value);
+  for (const [absolutePath, replacement] of paths) {
+    if (!absolutePath) continue;
+    text = text.split(absolutePath).join(replacement);
+  }
+  return text;
+}
+
+function safeJson(value) {
+  return JSON.stringify(value).replace(/</g, '\\u003c');
+}
+
+function responseHeaders(contentType) {
+  return {
+    'Cache-Control': 'no-store',
+    'Content-Type': contentType,
+    'Cross-Origin-Resource-Policy': 'same-origin',
+    'Referrer-Policy': 'no-referrer',
+    'X-Content-Type-Options': 'nosniff',
+    'X-Frame-Options': 'SAMEORIGIN',
+  };
+}
+
+function parseReceipt(stdout) {
+  try {
+    return JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+}
+
+function atomicOutputFailure(result) {
+  const code = result?.reason?.code || 'unclassified';
+  let diagnosticCode = 'output/target-indeterminate';
+  let message;
+  if (code === 'target-hardlinked' || code === 'candidate-hardlinked') {
+    diagnosticCode = 'output/target-hardlinked';
+    message = code === 'candidate-hardlinked'
+      ? 'Preview commit candidate has multiple hard-link names and cannot be published safely.'
+      : 'Preview output has multiple hard-link names; atomic publication cannot update every name.';
+  } else if (code === 'target-not-regular-file' || code === 'candidate-not-regular-file') {
+    diagnosticCode = 'output/target-not-regular-file';
+    message = code === 'candidate-not-regular-file'
+      ? 'Preview commit candidate is no longer a regular file.'
+      : 'Preview output already exists and is not a regular file.';
+  } else if (result?.status === 'different') {
+    diagnosticCode = 'output/target-changed';
+    message = `Preview output changed while the verified candidate was being prepared (${code}).`;
+  } else {
+    message = `Preview output stability could not be determined safely (${code}).`;
+  }
+  return {
+    code: diagnosticCode,
+    message,
+    evidence: { relation: result?.reason || { code } },
+  };
+}
+
+function atomicOutputError(result) {
+  const failure = atomicOutputFailure(result);
+  return Object.assign(new Error(failure.message), { previewFailure: failure });
+}
+
+function stagePreviewCommit(commitPath, artifact, mode) {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    previewCommitSequence += 1;
+    const candidatePath = path.join(
+      path.dirname(commitPath),
+      `.archify-preview-commit-${process.pid}-${Date.now().toString(36)}-${previewCommitSequence}.tmp`,
+    );
+    let descriptor;
+    let identity;
+    try {
+      const noFollow = process.platform === 'win32' ? 0 : (fs.constants.O_NOFOLLOW || 0);
+      descriptor = fs.openSync(
+        candidatePath,
+        fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | noFollow,
+        mode ?? 0o666,
+      );
+      let metadata;
+      try {
+        metadata = fs.fstatSync(descriptor, { bigint: true });
+      } catch (error) {
+        try {
+          const retry = fs.fstatSync(descriptor, { bigint: true });
+          if (retry.isFile() && retry.ino !== 0n) {
+            identity = { device: retry.dev, inode: retry.ino };
+          }
+        } catch {}
+        throw error;
+      }
+      if (!metadata.isFile() || metadata.ino === 0n) {
+        throw new Error('Preview commit candidate identity could not be verified safely.');
+      }
+      identity = { device: metadata.dev, inode: metadata.ino };
+      fs.writeFileSync(descriptor, artifact);
+      if (mode !== null) fs.fchmodSync(descriptor, mode);
+      fs.closeSync(descriptor);
+      descriptor = undefined;
+      return { candidatePath, identity };
+    } catch (error) {
+      if (descriptor !== undefined) {
+        try { fs.closeSync(descriptor); } catch {}
+      }
+      if (error.code === 'EEXIST') continue;
+      if (identity) removeOwnedRegularFile(candidatePath, identity);
+      throw error;
+    }
+  }
+  throw Object.assign(new Error('Could not reserve a preview commit candidate beside the output.'), {
+    code: 'EEXIST',
+    errno: -17,
+    syscall: 'open',
+  });
+}
+
+function captureOwnedDirectory(directoryPath) {
+  const metadata = fs.lstatSync(directoryPath, { bigint: true });
+  if (!metadata.isDirectory() || metadata.ino === 0n) {
+    throw new Error('Preview staging directory identity could not be verified safely.');
+  }
+  return { device: metadata.dev, inode: metadata.ino };
+}
+
+function cleanupOwnedDirectory(directoryPath, identity) {
+  let current;
+  try {
+    current = fs.lstatSync(directoryPath, { bigint: true });
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return;
+    throw error;
+  }
+  // Preserve a replacement rather than recursively deleting a directory that
+  // this preview instance did not create.
+  if (!current.isDirectory()
+    || current.ino === 0n
+    || current.dev !== identity.device
+    || current.ino !== identity.inode) return;
+  try {
+    removeEmptyDirectoryWithRetry(directoryPath);
+  } catch (error) {
+    // An entry whose identity was never bound to this preview may be an
+    // external claimant. Preserve the private directory as recovery material
+    // instead of recursively deleting unknown contents.
+    if (error?.code !== 'ENOTEMPTY' && error?.code !== 'EEXIST') throw error;
+  }
+}
+
+function captureOwnedDeliverySidecars(candidatePath, snapshotPath, receipt) {
+  const suffixes = ['.delivery.json', '.delivery-pending.json'];
+  const capturedSidecars = [];
+  for (const suffix of suffixes) {
+    const sidecarPath = candidatePath.replace(/\.html$/iu, suffix);
+    const captured = captureRegularFileBinding(sidecarPath, {
+      subject: 'preview-delivery-sidecar',
+      expectedLinks: 1,
+      includeContent: true,
+    });
+    if (captured.status !== 'captured') continue;
+    try {
+      const sidecar = JSON.parse(captured.content.buffer.toString('utf8'));
+      const commonMatches = sidecar?.schemaVersion === 1
+        && sidecar.command === 'deliver'
+        && sameLocation(sidecar.output, candidatePath).status === 'match'
+        && (!receipt?.receiptId || sidecar.receiptId === receipt.receiptId);
+      const currentMatches = suffix === '.delivery.json'
+        && commonMatches
+        && sidecar.status === 'current'
+        && receipt?.artifact?.sha256
+        && sidecar.artifact?.sha256 === receipt.artifact.sha256;
+      const pendingMatches = suffix === '.delivery-pending.json'
+        && commonMatches
+        && sidecar.status === 'pending'
+        && sameLocation(sidecar.input, snapshotPath).status === 'match';
+      if (currentMatches || pendingMatches) {
+        capturedSidecars.push({ path: sidecarPath, identity: captured.identity });
+      }
+    } catch {
+      // Preserve malformed or claimant-controlled sidecars for recovery.
+    } finally {
+      releaseRegularFileBinding(captured.binding);
+    }
+  }
+  return capturedSidecars;
+}
+
+export async function startPreview(options) {
+  const type = options.type;
+  if (!diagramTypes.has(type)) throw new Error(`Unknown diagram type "${type}".`);
+  if (options.quality && !['standard', 'showcase'].includes(options.quality)) {
+    throw new Error(`Unknown quality profile "${options.quality}".`);
+  }
+  const inputPath = path.resolve(options.input);
+  const outputRequest = {
+    requestedOutput: options.output,
+    authoredOutput: initialAuthoredOutput(inputPath),
+    defaultOutput: `${type}.html`,
+    inputPaths: [inputPath],
+    inputDescription: 'its JSON input',
+    cwd: options.cwd || process.cwd(),
+  };
+  const { outputPath } = resolveOutputPath(outputRequest);
+  const outputDirectory = path.dirname(outputPath);
+  const debounceMs = Number.isFinite(options.debounceMs) ? options.debounceMs : defaultDebounceMs;
+  const pollMs = Number.isFinite(options.pollMs) ? options.pollMs : defaultPollMs;
+  const stopGraceMs = Number.isFinite(options.stopGraceMs) ? Math.max(0, options.stopGraceMs) : defaultStopGraceMs;
+  const stopKillMs = Number.isFinite(options.stopKillMs) ? Math.max(0, options.stopKillMs) : defaultStopKillMs;
+  const shouldOpen = options.open !== false;
+
+  fs.mkdirSync(outputDirectory, { recursive: true });
+  // Keep cleanup bound to the physical directory selected at startup. A
+  // symlink or junction in the requested output parent may be redirected while
+  // preview is running and must not redirect recursive cleanup to a claimant.
+  const physicalOutputDirectory = fs.realpathSync.native(outputDirectory);
+  const stagingDirectory = fs.mkdtempSync(path.toNamespacedPath(
+    path.join(physicalOutputDirectory, '.archify-preview-'),
+  ));
+  let stagingIdentity;
+  try {
+    stagingIdentity = captureOwnedDirectory(stagingDirectory);
+  } catch (error) {
+    try { fs.rmdirSync(stagingDirectory); } catch {}
+    throw error;
+  }
+
+  let port = 0;
+  let watcher;
+  let debounceTimer;
+  let pollTimer;
+  let stopGraceTimer;
+  let stopKillTimer;
+  let child;
+  let stopping = false;
+  let forceStopping = false;
+  let stopped = false;
+  let serverClosing = false;
+  let serverClosed = false;
+  let queuedHash = null;
+  let activeHash = null;
+  let lastGoodSourceHash = null;
+  let sourceEpoch = 0;
+  let activeEpoch = 0;
+  let pendingBuild = false;
+  let artifactBuffer = null;
+  const clients = new Set();
+  const sockets = new Set();
+  const state = {
+    schemaVersion: 1,
+    status: 'checking',
+    generation: 0,
+    revision: 0,
+    lastVerified: null,
+    failure: null,
+  };
+
+  let resolveClosed;
+  const closed = new Promise((resolve) => { resolveClosed = resolve; });
+
+  function publicState() {
+    return JSON.parse(JSON.stringify(state));
+  }
+
+  function sendState(res) {
+    res.write(`event: state\ndata: ${safeJson(publicState())}\n\n`);
+  }
+
+  function broadcast() {
+    for (const res of clients) sendState(res);
+  }
+
+  const page = Buffer.from(previewPage());
+  const server = http.createServer((req, res) => {
+    const expectedHost = `${loopbackHost}:${port}`;
+    if (req.headers.host !== expectedHost) {
+      res.writeHead(403, responseHeaders('text/plain; charset=utf-8'));
+      res.end('Forbidden host');
+      return;
+    }
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      res.writeHead(405, { ...responseHeaders('text/plain; charset=utf-8'), Allow: 'GET, HEAD' });
+      res.end('Method not allowed');
+      return;
+    }
+
+    let url;
+    try {
+      url = new URL(req.url, `http://${expectedHost}`);
+    } catch {
+      res.writeHead(400, responseHeaders('text/plain; charset=utf-8'));
+      res.end('Bad request');
+      return;
+    }
+
+    if (url.pathname === '/') {
+      res.writeHead(200, {
+        ...responseHeaders('text/html; charset=utf-8'),
+        'Content-Security-Policy': "default-src 'none'; frame-src 'self'; connect-src 'self'; script-src 'unsafe-inline'; style-src 'unsafe-inline'",
+        'Content-Length': page.byteLength,
+      });
+      if (req.method === 'HEAD') res.end();
+      else res.end(page);
+      return;
+    }
+    if (url.pathname === '/state') {
+      const body = Buffer.from(`${safeJson(publicState())}\n`);
+      res.writeHead(200, { ...responseHeaders('application/json; charset=utf-8'), 'Content-Length': body.byteLength });
+      if (req.method === 'HEAD') res.end();
+      else res.end(body);
+      return;
+    }
+    if (url.pathname === '/artifact.html') {
+      if (!artifactBuffer) {
+        res.writeHead(404, responseHeaders('text/plain; charset=utf-8'));
+        res.end('No verified artifact yet');
+        return;
+      }
+      res.writeHead(200, { ...responseHeaders('text/html; charset=utf-8'), 'Content-Length': artifactBuffer.byteLength });
+      if (req.method === 'HEAD') res.end();
+      else res.end(artifactBuffer);
+      return;
+    }
+    if (url.pathname === '/events' && req.method === 'GET') {
+      res.writeHead(200, {
+        ...responseHeaders('text/event-stream; charset=utf-8'),
+        Connection: 'keep-alive',
+      });
+      res.write('retry: 1000\n\n');
+      clients.add(res);
+      sendState(res);
+      req.on('close', () => clients.delete(res));
+      return;
+    }
+
+    res.writeHead(404, responseHeaders('text/plain; charset=utf-8'));
+    res.end('Not found');
+  });
+
+  server.on('connection', (socket) => {
+    sockets.add(socket);
+    socket.once('close', () => sockets.delete(socket));
+    // A connection event already queued when force-stop begins must not keep
+    // server.close() waiting after the current sockets have been destroyed.
+    if (forceStopping) socket.destroy();
+  });
+
+  try {
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(0, loopbackHost, () => {
+        server.off('error', reject);
+        port = server.address().port;
+        resolve();
+      });
+    });
+  } catch (error) {
+    try { server.close(); } catch {}
+    cleanupOwnedDirectory(stagingDirectory, stagingIdentity);
+    throw error;
+  }
+
+  const url = `http://${loopbackHost}:${port}/`;
+
+  function finishStop() {
+    if (stopped || child || !serverClosed) return;
+    stopped = true;
+    clearTimeout(debounceTimer);
+    clearInterval(pollTimer);
+    clearTimeout(stopGraceTimer);
+    clearTimeout(stopKillTimer);
+    try {
+      cleanupOwnedDirectory(stagingDirectory, stagingIdentity);
+    } finally {
+      resolveClosed();
+    }
+  }
+
+  function signalActiveChild(signal) {
+    if (!child || child.exitCode !== null || child.signalCode !== null) return;
+    try {
+      if (process.platform !== 'win32' && child.pid) process.kill(-child.pid, signal);
+      else child.kill(signal);
+    } catch (error) {
+      if (error.code === 'ESRCH') return;
+      try { child.kill(signal); } catch {}
+    }
+  }
+
+  function closeServer() {
+    if (serverClosing) return;
+    serverClosing = true;
+    for (const res of clients) res.end();
+    clients.clear();
+    server.close(() => {
+      serverClosed = true;
+      finishStop();
+    });
+    server.closeIdleConnections?.();
+  }
+
+  function startBoundedChildDrain() {
+    if (!child || stopGraceTimer || stopKillTimer) return;
+    stopGraceTimer = setTimeout(() => {
+      stopGraceTimer = undefined;
+      if (!child) return finishStop();
+      signalActiveChild('SIGTERM');
+      stopKillTimer = setTimeout(() => {
+        stopKillTimer = undefined;
+        signalActiveChild('SIGKILL');
+      }, stopKillMs);
+    }, stopGraceMs);
+  }
+
+  async function stop({ force = false } = {}) {
+    if (force) forceStopping = true;
+    if (!stopping) {
+      stopping = true;
+      clearTimeout(debounceTimer);
+      clearInterval(pollTimer);
+      watcher?.close();
+      closeServer();
+    }
+    if (forceStopping) {
+      for (const socket of sockets) socket.destroy();
+    }
+    if (child && force) {
+      clearTimeout(stopGraceTimer);
+      clearTimeout(stopKillTimer);
+      stopGraceTimer = undefined;
+      stopKillTimer = undefined;
+      signalActiveChild('SIGKILL');
+    } else if (child) {
+      startBoundedChildDrain();
+    } else {
+      finishStop();
+    }
+    return closed;
+  }
+
+  function publishFailure(receipt, stdout, stderr, candidatePath, snapshotPath) {
+    const repairDetails = receipt?.diagnostics
+      ?.slice(0, 12)
+      .map((entry) => {
+        const fix = entry.supportedFixes?.length ? `\nFix: ${entry.supportedFixes.join('; ')}` : '';
+        return `[${entry.code}] ${entry.message}${fix}`;
+      }) || [];
+    const checkerDetails = receipt?.checker?.checks
+      ?.filter((check) => !check.ok)
+      .flatMap((check) => check.details || [])
+      .filter(Boolean)
+      .slice(0, 12) || [];
+    const diagnostic = [
+      receipt?.error,
+      ...(repairDetails.length ? repairDetails : checkerDetails),
+    ].filter(Boolean).join('\n') || stderr || stdout;
+    state.status = 'needs-fix';
+    state.failure = {
+      stage: receipt?.stage || 'render',
+      ...(receipt?.code ? { code: receipt.code } : {}),
+      ...(receipt?.evidence ? { evidence: receipt.evidence } : {}),
+      message: redactDiagnostic(
+        diagnostic,
+        [
+          [inputPath, '<input.json>'],
+          [outputPath, '<output.html>'],
+          [snapshotPath, '<input.json>'],
+          [candidatePath, '<candidate.html>'],
+          [stagingDirectory, '<preview-staging>'],
+          [path.resolve(here, '..'), '<archify-skill>'],
+          [path.resolve(options.cwd || process.cwd()), '<working-directory>'],
+          ...(options.repoRoot ? [[path.resolve(options.repoRoot), '<repo-root>']] : []),
+        ],
+      ),
+    };
+    broadcast();
+  }
+
+  function commitCandidate(candidatePath, receipt, generationHash, outputCapture) {
+    let candidate;
+    let sourceCandidateBinding;
+    let sourceCandidateIdentity;
+    let commitCandidatePath;
+    let commitCandidateIdentity;
+    let commitCandidateBinding;
+    try {
+      const sourceCapture = captureRegularFileBinding(candidatePath, {
+        subject: 'candidate',
+        expectedSha256: receipt?.artifact?.sha256,
+        expectedBytes: receipt?.artifact?.bytes,
+        includeContent: true,
+      });
+      if (sourceCapture.status !== 'captured') throw atomicOutputError(sourceCapture);
+      sourceCandidateBinding = sourceCapture.binding;
+      sourceCandidateIdentity = sourceCapture.identity;
+      candidate = sourceCapture.content.buffer;
+      const digest = sourceCapture.content.sha256;
+      const releasedSource = releaseRegularFileBinding(sourceCandidateBinding);
+      sourceCandidateBinding = undefined;
+      if (releasedSource.status !== 'released') throw atomicOutputError(releasedSource);
+      resolveOutputPath(outputRequest);
+      const sameArtifact = state.lastVerified?.sha256 === digest;
+      const currentSource = sourceDigest(inputPath);
+      if (currentSource.hash !== generationHash) {
+        return {
+          committed: false,
+          supersededBy: currentSource,
+          candidateIdentity: sourceCandidateIdentity,
+        };
+      }
+      const beforeStage = verifyAtomicOutput(outputCapture.snapshot);
+      if (beforeStage.status !== 'match') throw atomicOutputError(beforeStage);
+      ({
+        candidatePath: commitCandidatePath,
+        identity: commitCandidateIdentity,
+      } = stagePreviewCommit(outputCapture.commitPath, candidate, outputCapture.mode));
+      const candidateCapture = captureRegularFileBinding(commitCandidatePath, {
+        subject: 'candidate',
+        expectedSha256: digest,
+        expectedBytes: candidate.byteLength,
+        expectedIdentity: commitCandidateIdentity,
+        ...(outputCapture.mode === null ? {} : { expectedMode: outputCapture.mode }),
+      });
+      if (candidateCapture.status !== 'captured') throw atomicOutputError(candidateCapture);
+      commitCandidateBinding = candidateCapture.binding;
+      const beforeCommit = verifyAtomicOutput(outputCapture.snapshot);
+      if (beforeCommit.status !== 'match') throw atomicOutputError(beforeCommit);
+      const publication = publishRegularFileBinding(
+        commitCandidateBinding,
+        commitCandidatePath,
+        outputCapture.snapshot,
+        { subject: 'candidate' },
+      );
+      if (!['committed', 'committed-with-warning'].includes(publication.status)) {
+        throw atomicOutputError(publication);
+      }
+      const releasedCandidate = releaseRegularFileBinding(commitCandidateBinding);
+      commitCandidateBinding = undefined;
+      if (releasedCandidate.status !== 'released') throw atomicOutputError(releasedCandidate);
+      commitCandidatePath = undefined;
+      commitCandidateIdentity = undefined;
+      artifactBuffer = candidate;
+      lastGoodSourceHash = generationHash;
+      state.status = 'verified';
+      if (!sameArtifact) {
+        state.revision += 1;
+        state.lastVerified = {
+          sha256: digest,
+          bytes: candidate.byteLength,
+          checksPassed: receipt.validation.checksPassed,
+          checkCount: receipt.validation.checkCount,
+          compositionProfile: receipt.validation.compositionProfile,
+          compositionStatus: receipt.validation.compositionStatus,
+        };
+      }
+      state.failure = null;
+      broadcast();
+      return { committed: true, supersededBy: null, candidateIdentity: sourceCandidateIdentity };
+    } catch (error) {
+      publishFailure({
+        stage: 'commit',
+        error: `Could not publish the verified preview: ${error.message}`,
+        ...(error.previewFailure || {}),
+      }, '', '', candidatePath);
+      return { committed: false, supersededBy: null, candidateIdentity: sourceCandidateIdentity };
+    } finally {
+      if (sourceCandidateBinding) releaseRegularFileBinding(sourceCandidateBinding);
+      if (commitCandidateBinding) releaseRegularFileBinding(commitCandidateBinding);
+      if (commitCandidatePath && commitCandidateIdentity) {
+        removeOwnedRegularFile(commitCandidatePath, commitCandidateIdentity);
+      }
+    }
+  }
+
+  function beginBuild(digest, epoch) {
+    if (stopping || child) return;
+    activeHash = digest.hash;
+    activeEpoch = epoch;
+    state.generation += 1;
+    state.status = 'checking';
+    state.failure = null;
+    broadcast();
+
+    const candidatePath = path.join(stagingDirectory, `generation-${state.generation}.html`);
+    const snapshotPath = path.join(stagingDirectory, `generation-${state.generation}.json`);
+    let snapshotIdentity;
+    const outputCapture = captureAtomicOutput(outputPath);
+    if (outputCapture.status !== 'captured') {
+      const failure = atomicOutputFailure(outputCapture);
+      publishFailure(
+        { stage: 'prepare', error: failure.message, ...failure },
+        '',
+        '',
+        candidatePath,
+        snapshotPath,
+      );
+      return;
+    }
+    const beforeBuild = verifyAtomicOutput(outputCapture.snapshot);
+    if (beforeBuild.status !== 'match') {
+      const failure = atomicOutputFailure(beforeBuild);
+      publishFailure(
+        { stage: 'prepare', error: failure.message, ...failure },
+        '',
+        '',
+        candidatePath,
+        snapshotPath,
+      );
+      return;
+    }
+    if (digest.bytes !== null) {
+      try {
+        fs.writeFileSync(snapshotPath, digest.bytes, { flag: 'wx', mode: 0o600 });
+        const metadata = fs.lstatSync(snapshotPath, { bigint: true });
+        if (metadata.isFile() && metadata.ino !== 0n) {
+          snapshotIdentity = { device: metadata.dev, inode: metadata.ino };
+        }
+      } catch (error) {
+        publishFailure(
+          { stage: 'prepare', error: `Could not snapshot the observed input: ${error.message}` },
+          '',
+          '',
+          candidatePath,
+          snapshotPath,
+        );
+        return;
+      }
+    }
+    const args = [options.deliveryCli || cliPath, 'deliver', type, snapshotPath, candidatePath, '--json'];
+    if (options.quality) args.push('--quality', options.quality);
+    if (options.repoRoot) args.push('--repo-root', path.resolve(options.repoRoot));
+    let stdout = '';
+    let stderr = '';
+    child = spawn(process.execPath, args, {
+      cwd: options.cwd || process.cwd(),
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: process.platform !== 'win32',
+    });
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('error', (error) => { stderr += error.message; });
+    child.on('close', (code) => {
+      const receipt = parseReceipt(stdout);
+      const generationEpoch = activeEpoch;
+      const generationHash = activeHash;
+      const stale = generationEpoch !== sourceEpoch;
+      let supersededBy = null;
+      let candidateIdentity;
+      const deliverySidecars = captureOwnedDeliverySidecars(
+        candidatePath,
+        snapshotPath,
+        receipt,
+      );
+      child = null;
+      clearTimeout(stopGraceTimer);
+      clearTimeout(stopKillTimer);
+      stopGraceTimer = undefined;
+      stopKillTimer = undefined;
+      if (!stopping && !stale && code === 0 && receipt?.ok) {
+        ({ supersededBy, candidateIdentity } = commitCandidate(
+          candidatePath,
+          receipt,
+          generationHash,
+          outputCapture,
+        ));
+      } else if (code === 0 && receipt?.ok) {
+        const abandonedCandidate = captureRegularFileBinding(candidatePath, {
+          subject: 'abandoned-preview-candidate',
+          expectedSha256: receipt.artifact?.sha256,
+          expectedBytes: receipt.artifact?.bytes,
+        });
+        if (abandonedCandidate.status === 'captured') {
+          candidateIdentity = abandonedCandidate.identity;
+          releaseRegularFileBinding(abandonedCandidate.binding);
+        }
+      } else if (!stopping && !stale) {
+        publishFailure(receipt, stdout, stderr, candidatePath, snapshotPath);
+      }
+      if (candidateIdentity) removeOwnedRegularFile(candidatePath, candidateIdentity);
+      if (snapshotIdentity) removeOwnedRegularFile(snapshotPath, snapshotIdentity, { subject: 'snapshot' });
+      for (const deliverySidecar of deliverySidecars) {
+        removeOwnedRegularFile(deliverySidecar.path, deliverySidecar.identity, {
+          subject: 'preview-delivery-sidecar',
+        });
+      }
+
+      if (stopping) {
+        finishStop();
+      } else if (pendingBuild || stale || supersededBy) {
+        pendingBuild = false;
+        if (supersededBy && sourceEpoch === generationEpoch) sourceEpoch += 1;
+        const digest = supersededBy || sourceDigest(inputPath);
+        queueStableBuild(digest.hash, true);
+      }
+    });
+  }
+
+  function queueStableBuild(hash, immediate = false) {
+    queuedHash = hash;
+    clearTimeout(debounceTimer);
+    const launch = () => {
+      if (stopping) return;
+      const digest = sourceDigest(inputPath);
+      if (digest.hash !== queuedHash) {
+        queueStableBuild(digest.hash);
+        return;
+      }
+      if (digest.hash === lastGoodSourceHash) {
+        if (state.status !== 'verified' && state.lastVerified) {
+          state.status = 'verified';
+          state.failure = null;
+          broadcast();
+        }
+        return;
+      }
+      if (child) {
+        pendingBuild = true;
+        return;
+      }
+      beginBuild(digest, sourceEpoch);
+    };
+    debounceTimer = setTimeout(launch, immediate ? 0 : debounceMs);
+  }
+
+  function observeSource({ immediate = false } = {}) {
+    const digest = sourceDigest(inputPath);
+    if (!immediate && digest.hash === queuedHash) return;
+    sourceEpoch += 1;
+    queueStableBuild(digest.hash, immediate);
+  }
+
+  if (options.watch !== false) {
+    try {
+      // `path.resolve` keeps Windows 8.3 names intact. Canonicalize short names
+      // and junctions before libuv opens the directory so its callback path has
+      // the same prefix as the watched path.
+      const watchedDirectory = fs.realpathSync.native(path.dirname(inputPath));
+      watcher = fs.watch(watchedDirectory, (event, filename) => {
+        // On Windows the watcher hands us just the basename; on POSIX it can be
+        // null. Resolve named events against the directory libuv actually opened
+        // so file-level case, 8.3, and hard-link aliases still identify the input.
+        if (
+          !filename
+          || sameLocation(path.join(watchedDirectory, filename.toString()), inputPath).status === 'match'
+        ) {
+          observeSource();
+        }
+      });
+      watcher.on('error', () => {
+        const failedWatcher = watcher;
+        watcher = undefined;
+        failedWatcher?.close();
+      });
+    } catch (error) {
+      await stop();
+      throw new Error(`Could not watch the input directory: ${error.message}`);
+    }
+  }
+  pollTimer = setInterval(() => observeSource(), pollMs);
+
+  let opener = null;
+  if (shouldOpen) {
+    try {
+      opener = openLoopbackUrl(url);
+    } catch {
+      opener = { requested: true, status: 'unsupported', target: url, method: null };
+    }
+  }
+
+  observeSource({ immediate: true });
+
+  return {
+    url,
+    input: inputPath,
+    output: outputPath,
+    opener,
+    state: publicState,
+    stop,
+    closed,
+  };
+}
+
+export async function runPreview(options) {
+  const preview = await startPreview(options);
+  console.log(`preview ${preview.url}`);
+  console.log(`watching ${preview.input}`);
+  console.log(`output ${preview.output}`);
+  if (preview.opener && preview.opener.status !== 'opened') {
+    console.error(`Could not open the preview (${preview.opener.status}). ${preview.opener.failure?.reason || 'Open it manually.'} Target: ${preview.url}`);
+  }
+
+  let signalCount = 0;
+  const stop = () => {
+    signalCount += 1;
+    if (signalCount === 1) {
+      console.log('\nstopping preview…');
+      preview.stop();
+    } else {
+      console.log('\nforcing preview shutdown…');
+      preview.stop({ force: true });
+    }
+  };
+  process.on('SIGINT', stop);
+  process.on('SIGTERM', stop);
+  await preview.closed;
+  process.off('SIGINT', stop);
+  process.off('SIGTERM', stop);
+}

vendor/archify/bin/recover-output.mjs

@@ -0,0 +1,41 @@
+import { recoverRetiredPublication } from '../renderers/shared/atomic-output.mjs';
+
+function usage(stream = process.stderr) {
+  stream.write('Usage: node bin/recover-output.mjs <private-recovery-directory> [--json]\n');
+}
+
+const args = process.argv.slice(2);
+if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
+  usage(process.stdout);
+} else {
+  let json = false;
+  let recoveryDirectory;
+  let invalid = false;
+  for (const argument of args) {
+    if (argument === '--json' && !json) {
+      json = true;
+    } else if (argument.startsWith('-') || recoveryDirectory !== undefined) {
+      invalid = true;
+    } else {
+      recoveryDirectory = argument;
+    }
+  }
+
+  if (invalid || recoveryDirectory === undefined) {
+    usage();
+    process.exitCode = 64;
+  } else {
+    const result = recoverRetiredPublication(recoveryDirectory);
+    if (json) {
+      process.stdout.write(`${JSON.stringify(result)}\n`);
+    } else {
+      const reason = result.reason?.code || 'publication-recovery-unknown';
+      process.stdout.write(`${result.status}: ${reason}\n`);
+    }
+    // A complete prior recovery is idempotent. A preserved target is a safe,
+    // deliberate non-action that needs the operator to inspect the claimant.
+    process.exitCode = ['recovered', 'absent'].includes(result.status)
+      ? 0
+      : result.status === 'preserved' ? 2 : 1;
+  }
+}

vendor/archify/brand-marks/README.md

@@ -0,0 +1,31 @@
+# Built-in brand marks
+
+Archify ships a bounded catalogue of 107 commonly used brands for architecture,
+workflow, sequence, data-flow, and lifecycle nodes. The mark is optional authored
+identity: it never replaces the node's semantic `type`, color, label, or
+relationships.
+
+Unknown sites are handled by an explicit two-stage workflow. Run
+`node bin/archify.mjs brands capture <url> --json`, then author the returned
+digest-pinned `brand` value. Normal render and validate commands do not perform
+an unpinned capture, and changed or unavailable content fails closed.
+
+Most vector paths and brand metadata are generated from Simple Icons 16.28.0.
+The OpenAI mark is traced to OpenAI's official brand guidelines. Every generated
+entry records its source and, when available upstream, its guidelines and license
+metadata in `renderers/shared/generated-brand-marks.mjs`.
+
+Brand names and logos may be trademarks of their respective owners. Simple
+Icons' CC0 license covers its collection work, not every underlying trademark or
+artwork. Contributors must review the recorded source, current brand guidelines,
+and intended referential use before adding or updating a mark. Archify does not
+imply sponsorship, endorsement, or partnership.
+
+Edit `catalog.json`, then regenerate the committed zero-runtime-dependency bundle:
+
+```bash
+npm run generate:brand-marks
+npm run check:brand-marks
+```
+
+Do not hand-edit `renderers/shared/generated-brand-marks.mjs`.

vendor/archify/brand-marks/catalog.json

@@ -0,0 +1,131 @@
+{
+  "schemaVersion": 1,
+  "marks": [
+    {
+      "id": "openai",
+      "title": "OpenAI",
+      "category": "ai",
+      "aliases": ["chatgpt", "gpt", "codex"],
+      "domains": ["openai.com", "chatgpt.com"],
+      "custom": {
+        "viewBox": 20,
+        "hex": "000000",
+        "path": "M11.248 18.25q-.825 0-1.568-.314a4.3 4.3 0 0 1-1.32-.874 4 4 0 0 1-1.304.214 4 4 0 0 1-2.046-.544 4.27 4.27 0 0 1-1.518-1.485 4 4 0 0 1-.56-2.095q0-.48.131-1.04A4.4 4.4 0 0 1 2.04 10.71a4.07 4.07 0 0 1 .017-3.4 4.2 4.2 0 0 1 1.056-1.418 3.8 3.8 0 0 1 1.6-.842 3.9 3.9 0 0 1 .76-1.683q.593-.759 1.451-1.188a4.04 4.04 0 0 1 1.832-.429q.825 0 1.567.313.742.314 1.32.875a4 4 0 0 1 1.304-.215q1.106 0 2.046.545a4.14 4.14 0 0 1 1.501 1.485q.578.941.578 2.095 0 .48-.132 1.04.66.61 1.023 1.419.363.792.363 1.666 0 .892-.38 1.717a4.3 4.3 0 0 1-1.072 1.435 3.8 3.8 0 0 1-1.584.825 3.8 3.8 0 0 1-.775 1.683 4.06 4.06 0 0 1-1.436 1.188 4.04 4.04 0 0 1-1.832.429m-4.076-2.062q.825 0 1.435-.347l3.103-1.782a.36.36 0 0 0 .164-.313v-1.42L7.881 14.62a.67.67 0 0 1-.726 0l-3.118-1.798a.5.5 0 0 1-.017.115v.198q0 .841.396 1.551.413.693 1.139 1.089a3.2 3.2 0 0 0 1.617.412m.165-2.69a.4.4 0 0 0 .181.05q.083 0 .165-.05l1.238-.71-3.977-2.31a.7.7 0 0 1-.363-.643v-3.58q-.825.362-1.32 1.122a2.9 2.9 0 0 0-.495 1.65q0 .809.413 1.55.412.743 1.072 1.123zm3.91 3.663q.875 0 1.585-.396a2.96 2.96 0 0 0 1.534-2.64v-3.564a.32.32 0 0 0-.165-.297l-1.254-.726v4.604a.7.7 0 0 1-.363.643l-3.119 1.799a3 3 0 0 0 1.783.577m.627-6.039V8.878L10.01 7.822 8.129 8.878v2.244l1.881 1.056zM7.057 5.859a.7.7 0 0 1 .363-.644l3.119-1.798a3 3 0 0 0-1.782-.578q-.874 0-1.584.396A2.96 2.96 0 0 0 6.05 4.324a3.07 3.07 0 0 0-.396 1.551v3.547q0 .199.165.314l1.237.726zm8.383 7.887q.825-.364 1.303-1.123.495-.758.495-1.65a3.15 3.15 0 0 0-.412-1.55q-.413-.743-1.073-1.123l-3.086-1.782q-.099-.065-.181-.049a.3.3 0 0 0-.165.05l-1.238.692 3.993 2.327a.6.6 0 0 1 .264.264.64.64 0 0 1 .1.363zm-3.317-8.382a.63.63 0 0 1 .726 0l3.135 1.831v-.297q0-.792-.396-1.501a2.86 2.86 0 0 0-1.105-1.155q-.71-.43-1.65-.43-.825 0-1.436.347L8.294 5.941a.36.36 0 0 0-.165.314v1.418z",
+        "source": "https://openai.com/brand/",
+        "guidelines": "https://openai.com/brand/"
+      }
+    },
+    { "id": "claude", "category": "ai", "simpleIcon": "claude", "aliases": ["claude-ai"], "domains": ["claude.ai"] },
+    { "id": "anthropic", "category": "ai", "simpleIcon": "anthropic", "domains": ["anthropic.com"] },
+    { "id": "google-gemini", "category": "ai", "simpleIcon": "googlegemini", "aliases": ["gemini"], "domains": ["gemini.google.com"] },
+    { "id": "deepseek", "category": "ai", "simpleIcon": "deepseek", "domains": ["deepseek.com"] },
+    { "id": "qwen", "category": "ai", "simpleIcon": "qwen", "domains": ["qwen.ai"] },
+    { "id": "meta", "category": "ai", "simpleIcon": "meta", "aliases": ["llama"], "domains": ["meta.com"] },
+    { "id": "mistral-ai", "category": "ai", "simpleIcon": "mistralai", "aliases": ["mistral"], "domains": ["mistral.ai"] },
+    { "id": "hugging-face", "category": "ai", "simpleIcon": "huggingface", "aliases": ["huggingface"], "domains": ["huggingface.co"] },
+    { "id": "ollama", "category": "ai", "simpleIcon": "ollama", "domains": ["ollama.com"] },
+    { "id": "openrouter", "category": "ai", "simpleIcon": "openrouter", "aliases": ["open-router"], "domains": ["openrouter.ai"] },
+    { "id": "perplexity", "category": "ai", "simpleIcon": "perplexity", "domains": ["perplexity.ai"] },
+    { "id": "replicate", "category": "ai", "simpleIcon": "replicate", "domains": ["replicate.com"] },
+
+    { "id": "google-cloud", "category": "cloud", "simpleIcon": "googlecloud", "aliases": ["gcp", "googlecloud"], "domains": ["cloud.google.com"] },
+    { "id": "cloudflare", "category": "cloud", "simpleIcon": "cloudflare", "domains": ["cloudflare.com"] },
+    { "id": "vercel", "category": "cloud", "simpleIcon": "vercel", "domains": ["vercel.com"] },
+    { "id": "netlify", "category": "cloud", "simpleIcon": "netlify", "domains": ["netlify.com"] },
+    { "id": "digitalocean", "category": "cloud", "simpleIcon": "digitalocean", "aliases": ["digital-ocean"], "domains": ["digitalocean.com"] },
+    { "id": "render", "category": "cloud", "simpleIcon": "render", "domains": ["render.com"] },
+    { "id": "railway", "category": "cloud", "simpleIcon": "railway", "domains": ["railway.com", "railway.app"] },
+    { "id": "fly-io", "category": "cloud", "simpleIcon": "flydotio", "aliases": ["fly.io"], "domains": ["fly.io"] },
+    { "id": "cloudinary", "category": "cloud", "simpleIcon": "cloudinary", "domains": ["cloudinary.com"] },
+    { "id": "alibaba-cloud", "category": "cloud", "simpleIcon": "alibabacloud", "aliases": ["aliyun"], "domains": ["alibabacloud.com", "aliyun.com"] },
+    { "id": "firebase", "category": "cloud", "simpleIcon": "firebase", "domains": ["firebase.google.com"] },
+    { "id": "supabase", "category": "cloud", "simpleIcon": "supabase", "domains": ["supabase.com"] },
+    { "id": "neon", "category": "cloud", "simpleIcon": "neon", "domains": ["neon.tech"] },
+
+    { "id": "github", "category": "engineering", "simpleIcon": "github", "domains": ["github.com"] },
+    { "id": "gitlab", "category": "engineering", "simpleIcon": "gitlab", "domains": ["gitlab.com"] },
+    { "id": "bitbucket", "category": "engineering", "simpleIcon": "bitbucket", "domains": ["bitbucket.org"] },
+    { "id": "docker", "category": "engineering", "simpleIcon": "docker", "domains": ["docker.com"] },
+    { "id": "kubernetes", "category": "engineering", "simpleIcon": "kubernetes", "aliases": ["k8s"], "domains": ["kubernetes.io"] },
+    { "id": "terraform", "category": "engineering", "simpleIcon": "terraform", "domains": ["terraform.io"] },
+    { "id": "pulumi", "category": "engineering", "simpleIcon": "pulumi", "domains": ["pulumi.com"] },
+    { "id": "ansible", "category": "engineering", "simpleIcon": "ansible", "domains": ["ansible.com"] },
+    { "id": "jenkins", "category": "engineering", "simpleIcon": "jenkins", "domains": ["jenkins.io"] },
+    { "id": "circleci", "category": "engineering", "simpleIcon": "circleci", "aliases": ["circle-ci"], "domains": ["circleci.com"] },
+    { "id": "github-actions", "category": "engineering", "simpleIcon": "githubactions" },
+    { "id": "argo", "category": "engineering", "simpleIcon": "argo", "aliases": ["argocd", "argo-cd"], "domains": ["argoproj.github.io"] },
+    { "id": "helm", "category": "engineering", "simpleIcon": "helm", "domains": ["helm.sh"] },
+    { "id": "grafana", "category": "engineering", "simpleIcon": "grafana", "domains": ["grafana.com"] },
+    { "id": "prometheus", "category": "engineering", "simpleIcon": "prometheus", "domains": ["prometheus.io"] },
+    { "id": "sentry", "category": "engineering", "simpleIcon": "sentry", "domains": ["sentry.io"] },
+    { "id": "datadog", "category": "engineering", "simpleIcon": "datadog", "domains": ["datadoghq.com"] },
+    { "id": "pagerduty", "category": "engineering", "simpleIcon": "pagerduty", "aliases": ["pager-duty"], "domains": ["pagerduty.com"] },
+
+    { "id": "postgresql", "category": "data", "simpleIcon": "postgresql", "aliases": ["postgres"], "domains": ["postgresql.org"] },
+    { "id": "mysql", "category": "data", "simpleIcon": "mysql", "domains": ["mysql.com"] },
+    { "id": "mongodb", "category": "data", "simpleIcon": "mongodb", "aliases": ["mongo"], "domains": ["mongodb.com"] },
+    { "id": "redis", "category": "data", "simpleIcon": "redis", "domains": ["redis.io"] },
+    { "id": "apache-kafka", "category": "data", "simpleIcon": "apachekafka", "aliases": ["kafka"], "domains": ["kafka.apache.org"] },
+    { "id": "rabbitmq", "category": "data", "simpleIcon": "rabbitmq", "aliases": ["rabbit-mq"], "domains": ["rabbitmq.com"] },
+    { "id": "clickhouse", "category": "data", "simpleIcon": "clickhouse", "domains": ["clickhouse.com"] },
+    { "id": "elasticsearch", "category": "data", "simpleIcon": "elasticsearch", "aliases": ["elastic"], "domains": ["elastic.co"] },
+    { "id": "opensearch", "category": "data", "simpleIcon": "opensearch", "aliases": ["open-search"], "domains": ["opensearch.org"] },
+    { "id": "snowflake", "category": "data", "simpleIcon": "snowflake", "domains": ["snowflake.com"] },
+    { "id": "databricks", "category": "data", "simpleIcon": "databricks", "domains": ["databricks.com"] },
+    { "id": "planetscale", "category": "data", "simpleIcon": "planetscale", "aliases": ["planet-scale"], "domains": ["planetscale.com"] },
+    { "id": "prisma", "category": "data", "simpleIcon": "prisma", "domains": ["prisma.io"] },
+    { "id": "sqlite", "category": "data", "simpleIcon": "sqlite", "domains": ["sqlite.org"] },
+    { "id": "mariadb", "category": "data", "simpleIcon": "mariadb", "aliases": ["maria-db"], "domains": ["mariadb.org"] },
+    { "id": "influxdb", "category": "data", "simpleIcon": "influxdb", "aliases": ["influx-db"], "domains": ["influxdata.com"] },
+    { "id": "apache-airflow", "category": "data", "simpleIcon": "apacheairflow", "aliases": ["airflow"], "domains": ["airflow.apache.org"] },
+
+    { "id": "notion", "category": "collaboration", "simpleIcon": "notion", "domains": ["notion.so"] },
+    { "id": "figma", "category": "collaboration", "simpleIcon": "figma", "domains": ["figma.com"] },
+    { "id": "jira", "category": "collaboration", "simpleIcon": "jira", "domains": ["atlassian.com"] },
+    { "id": "linear", "category": "collaboration", "simpleIcon": "linear", "domains": ["linear.app"] },
+    { "id": "discord", "category": "collaboration", "simpleIcon": "discord", "domains": ["discord.com"] },
+    { "id": "zoom", "category": "collaboration", "simpleIcon": "zoom", "domains": ["zoom.us"] },
+    { "id": "trello", "category": "collaboration", "simpleIcon": "trello", "domains": ["trello.com"] },
+    { "id": "asana", "category": "collaboration", "simpleIcon": "asana", "domains": ["asana.com"] },
+    { "id": "airtable", "category": "collaboration", "simpleIcon": "airtable", "domains": ["airtable.com"] },
+    { "id": "miro", "category": "collaboration", "simpleIcon": "miro", "domains": ["miro.com"] },
+    { "id": "stripe", "category": "business", "simpleIcon": "stripe", "domains": ["stripe.com"] },
+    { "id": "shopify", "category": "business", "simpleIcon": "shopify", "domains": ["shopify.com"] },
+    { "id": "hubspot", "category": "business", "simpleIcon": "hubspot", "domains": ["hubspot.com"] },
+    { "id": "paypal", "category": "business", "simpleIcon": "paypal", "domains": ["paypal.com"] },
+    { "id": "intercom", "category": "business", "simpleIcon": "intercom", "domains": ["intercom.com"] },
+    { "id": "zendesk", "category": "business", "simpleIcon": "zendesk", "domains": ["zendesk.com"] },
+    { "id": "wordpress", "category": "business", "simpleIcon": "wordpress", "domains": ["wordpress.org", "wordpress.com"] },
+    { "id": "woocommerce", "category": "business", "simpleIcon": "woocommerce", "aliases": ["woo-commerce"], "domains": ["woocommerce.com"] },
+
+    { "id": "wechat", "category": "channel", "simpleIcon": "wechat", "aliases": ["weixin", "微信"], "domains": ["weixin.qq.com"] },
+    { "id": "youtube", "category": "channel", "simpleIcon": "youtube", "domains": ["youtube.com", "youtu.be"] },
+    { "id": "tiktok", "category": "channel", "simpleIcon": "tiktok", "aliases": ["douyin", "抖音"], "domains": ["tiktok.com", "douyin.com"] },
+    { "id": "x", "category": "channel", "simpleIcon": "x", "aliases": ["twitter"], "domains": ["x.com", "twitter.com"] },
+    { "id": "instagram", "category": "channel", "simpleIcon": "instagram", "domains": ["instagram.com"] },
+    { "id": "facebook", "category": "channel", "simpleIcon": "facebook", "domains": ["facebook.com"] },
+    { "id": "reddit", "category": "channel", "simpleIcon": "reddit", "domains": ["reddit.com"] },
+    { "id": "telegram", "category": "channel", "simpleIcon": "telegram", "domains": ["telegram.org", "t.me"] },
+    { "id": "whatsapp", "category": "channel", "simpleIcon": "whatsapp", "domains": ["whatsapp.com"] },
+    { "id": "pinterest", "category": "channel", "simpleIcon": "pinterest", "domains": ["pinterest.com"] },
+
+    { "id": "python", "category": "language", "simpleIcon": "python", "domains": ["python.org"] },
+    { "id": "typescript", "category": "language", "simpleIcon": "typescript", "aliases": ["ts"], "domains": ["typescriptlang.org"] },
+    { "id": "javascript", "category": "language", "simpleIcon": "javascript", "aliases": ["js"] },
+    { "id": "go", "category": "language", "simpleIcon": "go", "aliases": ["golang"], "domains": ["go.dev"] },
+    { "id": "rust", "category": "language", "simpleIcon": "rust", "domains": ["rust-lang.org"] },
+    { "id": "node-js", "category": "framework", "simpleIcon": "nodedotjs", "aliases": ["node", "nodejs"], "domains": ["nodejs.org"] },
+    { "id": "react", "category": "framework", "simpleIcon": "react", "aliases": ["reactjs"], "domains": ["react.dev"] },
+    { "id": "vue", "category": "framework", "simpleIcon": "vuedotjs", "aliases": ["vuejs", "vue.js"], "domains": ["vuejs.org"] },
+    { "id": "next-js", "category": "framework", "simpleIcon": "nextdotjs", "aliases": ["nextjs", "next.js"], "domains": ["nextjs.org"] },
+    { "id": "pytorch", "category": "framework", "simpleIcon": "pytorch", "domains": ["pytorch.org"] },
+    { "id": "tensorflow", "category": "framework", "simpleIcon": "tensorflow", "domains": ["tensorflow.org"] },
+    { "id": "angular", "category": "framework", "simpleIcon": "angular", "domains": ["angular.dev"] },
+    { "id": "svelte", "category": "framework", "simpleIcon": "svelte", "domains": ["svelte.dev"] },
+    { "id": "django", "category": "framework", "simpleIcon": "django", "domains": ["djangoproject.com"] },
+    { "id": "flask", "category": "framework", "simpleIcon": "flask", "domains": ["palletsprojects.com"] },
+    { "id": "fastapi", "category": "framework", "simpleIcon": "fastapi", "domains": ["fastapi.tiangolo.com"] },
+    { "id": "spring", "category": "framework", "simpleIcon": "spring", "aliases": ["spring-boot"], "domains": ["spring.io"] },
+    { "id": "dotnet", "category": "framework", "simpleIcon": "dotnet", "aliases": [".net"], "domains": ["dotnet.microsoft.com"] }
+  ]
+}

vendor/archify/examples/agent-run.lifecycle.json

@@ -0,0 +1,55 @@
+{
+  "schema_version": 1,
+  "diagram_type": "lifecycle",
+  "meta": {
+    "title": "Agent Run Lifecycle",
+    "output": "examples/lifecycle-agent-run.html",
+    "viewBox": [1030, 630],
+    "animation": "trace",
+    "quality_profile": "showcase"
+  },
+  "lanes": [
+    { "id": "main", "label": "Lifecycle phases" },
+    { "id": "waiting", "label": "Interruptions" },
+    { "id": "exceptions", "label": "Recovery loop" },
+    { "id": "terminal", "label": "Terminal exits" }
+  ],
+  "states": [
+    { "id": "queued", "type": "start", "label": "Queued", "sublabel": "request accepted", "lane": "main", "col": 0, "step": "01", "tag": "entry" },
+    { "id": "planning", "type": "active", "label": "Planning", "sublabel": "build task graph", "lane": "main", "col": 1, "step": "02", "tag": "model" },
+    { "id": "executing", "type": "active", "label": "Executing", "sublabel": "tool calls", "lane": "main", "col": 2, "step": "03", "tag": "work" },
+    { "id": "reviewing", "type": "decision", "label": "Reviewing", "sublabel": "quality gate", "lane": "main", "col": 3, "step": "04", "tag": "check" },
+    { "id": "completed", "type": "success", "label": "Completed", "sublabel": "final response", "lane": "main", "col": 4, "step": "05", "tag": "done" },
+    { "id": "approval", "type": "waiting", "label": "Needs Approval", "sublabel": "human gate", "lane": "waiting", "col": 0, "tag": "pause" },
+    { "id": "blocked", "type": "waiting", "label": "Blocked", "sublabel": "missing input", "lane": "waiting", "col": 1, "tag": "wait" },
+    { "id": "failed", "type": "failure", "label": "Failed", "sublabel": "recoverable error", "lane": "exceptions", "col": 0, "yOffset": 78, "tag": "retryable" },
+    { "id": "cancelled", "type": "failure", "label": "Cancelled", "sublabel": "user stopped", "lane": "terminal", "col": 0, "tag": "terminal" },
+    { "id": "expired", "type": "failure", "label": "Expired", "sublabel": "timeout", "lane": "terminal", "col": 1, "tag": "terminal" }
+  ],
+  "transitions": [
+    { "id": "approval-needed", "from": "executing", "to": "approval", "variant": "security", "fromSide": "bottom", "toSide": "top", "route": "straight" },
+    { "id": "review-blocked", "from": "reviewing", "to": "blocked", "variant": "default", "route": "drop" },
+    { "id": "execution-failed", "from": "executing", "to": "failed", "variant": "security", "fromSide": "left", "toSide": "left", "via": [[320, 157], [320, 385]] },
+    { "id": "failed-retry", "from": "failed", "to": "executing", "variant": "emphasis", "fromSide": "left", "toSide": "top", "via": [[20, 385], [20, 80], [402, 80]] },
+    { "id": "block-expired", "from": "blocked", "to": "expired", "variant": "security", "fromSide": "bottom", "toSide": "top", "route": "straight" },
+    { "id": "approval-cancelled", "from": "approval", "to": "cancelled", "variant": "security", "fromSide": "bottom", "toSide": "top", "via": [[480, 336], [480, 432], [402, 432]] }
+  ],
+  "cards": [
+    {
+      "dot": "emerald",
+      "title": "Main Path + Waits",
+      "items": [
+        "The run has five ordered phases from queue to completion",
+        "Approval and missing input pause the run without ending it"
+      ]
+    },
+    {
+      "dot": "rose",
+      "title": "Recovery + Terminal Exits",
+      "items": [
+        "Failed loops back while retry budget remains",
+        "Cancelled and Expired are terminal exits with no return path"
+      ]
+    }
+  ]
+}

vendor/archify/examples/agent-tool-call.workflow.json

@@ -0,0 +1,74 @@
+{
+  "schema_version": 2,
+  "diagram_type": "workflow",
+  "meta": {
+    "title": "Agent Tool Call Workflow",
+    "animation": "trace",
+    "visual_preset": "signal-flow",
+    "quality_profile": "showcase",
+    "output": "examples/workflow-agent-tool-call-rendered.html"
+  },
+  "lanes": [
+    { "id": "ui", "label": "User Interface" },
+    { "id": "agent", "label": "Agent Runtime" },
+    { "id": "policy", "label": "Policy & Recovery", "variant": "exception" },
+    { "id": "tools", "label": "Tool Execution & Evidence" }
+  ],
+  "phases": [
+    { "id": "intake", "label": "Intake", "fromCol": 0, "toCol": 1 },
+    { "id": "reasoning", "label": "Plan + route", "fromCol": 2, "toCol": 3, "variant": "emphasis" },
+    { "id": "execution", "label": "Execute + report", "fromCol": 4, "toCol": 5, "variant": "dashed" }
+  ],
+  "groups": [
+    { "id": "agent_loop", "label": "Planning loop", "lane": "agent", "fromCol": 2, "toCol": 3, "variant": "emphasis" },
+    { "id": "exception_path", "label": "Human or policy stop", "lane": "policy", "fromCol": 3, "toCol": 5, "variant": "security" },
+    { "id": "evidence_path", "label": "Evidence path", "lane": "tools", "fromCol": 1, "toCol": 2, "variant": "dashed" },
+    { "id": "tool_work", "label": "Tool work", "lane": "tools", "fromCol": 4, "toCol": 5, "variant": "dashed" }
+  ],
+  "mainPath": ["user", "chat", "planner", "router", "approval", "tool", "external", "final"],
+  "nodes": [
+    { "id": "user", "lane": "ui", "col": 0, "type": "external", "label": "User", "sublabel": "asks for work", "width": 132 },
+    { "id": "chat", "lane": "ui", "col": 1, "type": "frontend", "label": "Chat Surface", "sublabel": "thread + files", "width": 132 },
+    { "id": "final", "lane": "ui", "col": 5, "type": "backend", "label": "Final Reply", "sublabel": "answer + changes", "width": 132 },
+    { "id": "planner", "lane": "agent", "col": 2, "type": "backend", "label": "Agent Planner", "sublabel": "plan next step", "tag": "context aware", "width": 132 },
+    { "id": "router", "lane": "agent", "col": 3, "type": "backend", "label": "Tool Router", "sublabel": "choose capability", "width": 132 },
+    { "id": "approval", "lane": "policy", "col": 3, "type": "security", "label": "Approval Gate", "sublabel": "scope + consent", "tag": "block risky ops", "width": 132 },
+    { "id": "blocked", "lane": "policy", "col": 4, "type": "security", "label": "Blocked", "sublabel": "wait or reject", "width": 132 },
+    { "id": "retry", "lane": "policy", "col": 5, "type": "messagebus", "label": "Retry Path", "sublabel": "revise request", "width": 132 },
+    { "id": "tool", "lane": "tools", "col": 4, "type": "messagebus", "label": "Tool Call", "sublabel": "shell / browser / MCP", "tag": "structured result", "width": 132 },
+    { "id": "external", "lane": "tools", "col": 5, "type": "cloud", "label": "External API", "sublabel": "network service", "width": 132 },
+    { "id": "store", "lane": "tools", "col": 1, "type": "database", "label": "Context Store", "sublabel": "repo + memory", "width": 132 },
+    { "id": "trace", "lane": "tools", "col": 2, "type": "database", "label": "Trace Log", "sublabel": "events + output", "width": 132 }
+  ],
+  "edges": [
+    { "id": "request-chat", "from": "user", "to": "chat", "variant": "default" },
+    { "id": "plan-request", "from": "chat", "to": "planner", "label": "plan", "variant": "emphasis" },
+    { "id": "planner-route", "from": "planner", "to": "router", "variant": "default" },
+    { "id": "approval-check", "from": "router", "to": "approval", "label": "needs approval?", "variant": "security" },
+    { "id": "approved-tool", "from": "approval", "to": "tool", "variant": "emphasis" },
+    { "id": "approval-denied", "from": "approval", "to": "blocked", "label": "denied", "variant": "security", "role": "error" },
+    { "id": "retry-request", "from": "blocked", "to": "retry", "variant": "dashed", "role": "branch" },
+    { "id": "tool-external-call", "from": "tool", "to": "external", "variant": "default" },
+    { "id": "external-reply", "from": "external", "to": "final", "variant": "emphasis", "role": "return", "fromSide": "right", "toSide": "right", "route": "outside-right", "width": 1.2 },
+    { "id": "record-result", "from": "external", "to": "trace", "label": "record result", "variant": "dashed", "fromSide": "bottom", "toSide": "bottom", "route": "bottom-channel", "labelSegment": 1 },
+    { "id": "write-trace-memory", "from": "store", "to": "trace", "label": "trace + memory", "variant": "dashed" }
+  ],
+  "cards": [
+    {
+      "dot": "cyan",
+      "title": "Compiler Contract",
+      "items": [
+        "Lanes and columns determine node placement",
+        "Labels reserve clearance; routes stay orthogonal"
+      ]
+    },
+    {
+      "dot": "rose",
+      "title": "Runtime Semantics",
+      "items": [
+        "Approval gates risky work before tool execution",
+        "Evidence returns through isolated trace and memory"
+      ]
+    }
+  ]
+}

vendor/archify/examples/async-job-roundtrip.sequence.json

@@ -0,0 +1,56 @@
+{
+  "schema_version": 1,
+  "diagram_type": "sequence",
+  "meta": {
+    "title": "Async Job Roundtrip",
+    "output": "examples/async-job-roundtrip.html",
+    "viewBox": [820, 920],
+    "animation": "trace",
+    "visual_preset": "signal-flow",
+    "quality_profile": "showcase"
+  },
+  "participants": [
+    { "id": "client", "type": "external", "label": "Client", "sublabel": "mobile app" },
+    { "id": "api", "type": "backend", "label": "Jobs API", "sublabel": "request edge" },
+    { "id": "queue", "type": "messagebus", "label": "Queue", "sublabel": "durable work" },
+    { "id": "worker", "type": "backend", "label": "Worker", "sublabel": "background" },
+    { "id": "provider", "type": "cloud", "label": "Provider", "sublabel": "external API" },
+    { "id": "store", "type": "database", "label": "Job Store", "sublabel": "source of truth" },
+    { "id": "notify", "type": "messagebus", "label": "Notifier", "sublabel": "webhook" }
+  ],
+  "segments": [
+    { "from": 150, "to": 288, "label": "Accept" },
+    { "from": 306, "to": 538, "label": "Background work" },
+    { "from": 554, "to": 800, "label": "Notify + reconcile" }
+  ],
+  "messages": [
+    { "from": "client", "to": "api", "y": 180, "label": "POST /jobs", "variant": "emphasis" },
+    { "from": "api", "to": "queue", "y": 222, "label": "enqueue job", "variant": "emphasis" },
+    { "from": "api", "to": "client", "y": 264, "label": "202 + job id", "variant": "return" },
+    { "from": "queue", "to": "worker", "y": 326, "label": "deliver", "variant": "emphasis" },
+    { "from": "worker", "to": "provider", "y": 368, "label": "perform work", "variant": "default" },
+    { "from": "provider", "to": "worker", "y": 410, "label": "result / timeout", "variant": "return" },
+    { "from": "worker", "to": "queue", "y": 452, "label": "retry if timeout", "variant": "dashed" },
+    { "from": "worker", "to": "store", "y": 494, "label": "persist final state", "variant": "emphasis" },
+    { "from": "worker", "to": "notify", "y": 566, "label": "job.completed", "variant": "dashed" },
+    { "from": "notify", "to": "client", "y": 608, "label": "signed webhook", "variant": "dashed" },
+    { "from": "client", "to": "api", "y": 650, "label": "GET /jobs/:id", "variant": "default" },
+    { "from": "api", "to": "store", "y": 692, "label": "read status", "variant": "default" },
+    { "from": "store", "to": "api", "y": 734, "label": "completed", "variant": "return" },
+    { "from": "api", "to": "client", "y": 776, "label": "200 final result", "variant": "return" }
+  ],
+  "activations": [
+    { "participant": "api", "from": 174, "to": 272, "type": "backend" },
+    { "participant": "queue", "from": 216, "to": 334, "type": "messagebus" },
+    { "participant": "worker", "from": 320, "to": 574, "type": "backend" },
+    { "participant": "provider", "from": 362, "to": 416, "type": "cloud" },
+    { "participant": "store", "from": 488, "to": 742, "type": "database" },
+    { "participant": "notify", "from": 560, "to": 616, "type": "messagebus" },
+    { "participant": "api", "from": 644, "to": 784, "type": "backend" }
+  ],
+  "cards": [
+    { "dot": "cyan", "title": "Fast Acknowledgement", "items": ["The caller receives a durable job id before work begins", "Queue ownership is visible in the acceptance contract", "The original connection does not wait for provider latency"] },
+    { "dot": "orange", "title": "Bounded Recovery", "items": ["Timeouts re-enter the queue with a retry policy", "Final state is persisted before notification", "The job store remains the source of truth"] },
+    { "dot": "emerald", "title": "Two Observation Paths", "items": ["A signed webhook announces completion", "Status polling is a fallback, not a second workflow", "Both paths converge on the same final state"] }
+  ]
+}

vendor/archify/examples/brand-aware-delivery.architecture.json

@@ -0,0 +1,34 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "Brand-aware AI delivery",
+    "output": "brand-aware-delivery.html",
+    "quality_profile": "showcase",
+    "viewBox": [1120, 640]
+  },
+  "components": [
+    { "id": "request", "type": "external", "label": "Product request", "sublabel": "Owner brief", "pos": [38, 260], "size": [138, 68] },
+    { "id": "claude", "type": "frontend", "label": "Claude", "sublabel": "Plan and author", "brand": "claude", "pos": [220, 260], "size": [138, 68] },
+    { "id": "github", "type": "messagebus", "label": "GitHub", "sublabel": "Review and merge", "brand": "github", "pos": [402, 260], "size": [138, 68] },
+    { "id": "container", "type": "backend", "label": "Docker service", "sublabel": "Build and run", "brand": "docker", "pos": [584, 260], "size": [138, 68] },
+    { "id": "edge", "type": "cloud", "label": "Cloudflare", "sublabel": "Global delivery", "brand": "cloudflare", "pos": [766, 260], "size": [138, 68] },
+    { "id": "customer", "type": "external", "label": "Customers", "sublabel": "Web and mobile", "pos": [948, 260], "size": [138, 68] },
+    { "id": "database", "type": "database", "label": "PostgreSQL", "sublabel": "Durable state", "brand": "postgresql", "pos": [584, 420], "size": [138, 68] },
+    { "id": "billing", "type": "external", "label": "Stripe", "sublabel": "Billing events", "brand": "stripe", "pos": [766, 420], "size": [138, 68] }
+  ],
+  "connections": [
+    { "id": "brief-to-claude", "from": "request", "to": "claude", "label": "brief", "variant": "emphasis" },
+    { "id": "claude-to-github", "from": "claude", "to": "github", "label": "change set", "labelDy": -28 },
+    { "id": "github-to-container", "from": "github", "to": "container", "label": "approved build", "labelDy": -28 },
+    { "id": "container-to-edge", "from": "container", "to": "edge", "label": "deploy" },
+    { "id": "edge-to-customer", "from": "edge", "to": "customer", "label": "HTTPS", "variant": "emphasis" },
+    { "id": "container-to-database", "from": "container", "to": "database", "label": "SQL", "fromSide": "bottom", "toSide": "top", "labelAt": [625, 370] },
+    { "id": "container-to-billing", "from": "container", "to": "billing", "label": "create charge", "variant": "dashed", "fromSide": "bottom", "toSide": "top", "via": [[653, 374], [835, 374]] },
+    { "id": "billing-to-database", "from": "billing", "to": "database", "label": "webhook", "variant": "dashed" }
+  ],
+  "cards": [
+    { "dot": "cyan", "title": "Identity at a glance", "items": ["Semantic color still explains technical role", "Brand badges identify the actual products"] },
+    { "dot": "amber", "title": "Portable by default", "items": ["Preset marks ship inside Archify", "Every visual export keeps the same badge"] }
+  ]
+}

vendor/archify/examples/cache-miss-request.sequence.json

@@ -0,0 +1,77 @@
+{
+  "schema_version": 1,
+  "diagram_type": "sequence",
+  "meta": {
+    "title": "Cache Miss Request Sequence",
+    "output": "examples/sequence-cache-miss-request.html",
+    "viewBox": [1080, 580],
+    "column_fit": "spread",
+    "animation": "trace",
+    "quality_profile": "showcase"
+  },
+  "participants": [
+    { "id": "user", "type": "external", "label": "User", "sublabel": "browser session" },
+    { "id": "web", "type": "frontend", "label": "Web App", "sublabel": "React UI" },
+    { "id": "api", "type": "backend", "label": "API", "sublabel": "request handler" },
+    { "id": "auth", "type": "security", "label": "Auth", "sublabel": "JWT verify" },
+    { "id": "redis", "type": "database", "label": "Redis", "sublabel": "cache" },
+    { "id": "db", "type": "database", "label": "Postgres", "sublabel": "source of truth" },
+    { "id": "trace", "type": "messagebus", "label": "Trace", "sublabel": "async event" }
+  ],
+  "segments": [
+    { "from": 150, "to": 250, "label": "Request" },
+    { "from": 260, "to": 370, "label": "Fallback" },
+    { "from": 380, "to": 480, "label": "Response + trace" }
+  ],
+  "messages": [
+    { "id": "open-page", "from": "user", "to": "web", "y": 160, "label": "open page", "variant": "default" },
+    { "id": "dashboard-request", "from": "web", "to": "api", "y": 185, "label": "GET /dashboard", "variant": "emphasis" },
+    { "id": "verify-jwt", "from": "api", "to": "auth", "y": 210, "label": "verify JWT", "variant": "security" },
+    { "id": "auth-claims", "from": "auth", "to": "api", "y": 238, "label": "claims ok", "variant": "return" },
+    { "id": "cache-read", "from": "api", "to": "redis", "y": 270, "label": "read cache", "variant": "default" },
+    { "id": "cache-miss", "from": "redis", "to": "api", "y": 298, "label": "miss", "variant": "return" },
+    { "id": "profile-query", "from": "api", "to": "db", "y": 330, "label": "query profile + metrics", "variant": "emphasis" },
+    { "id": "profile-rows", "from": "db", "to": "api", "y": 358, "label": "rows", "variant": "return" },
+    { "id": "cache-write", "from": "api", "to": "redis", "y": 390, "label": "set cache", "variant": "dashed" },
+    { "id": "trace-emit", "from": "api", "to": "trace", "y": 418, "label": "emit trace", "variant": "dashed" },
+    { "id": "dashboard-response", "from": "api", "to": "web", "y": 443, "label": "200 JSON", "variant": "return" },
+    { "id": "page-render", "from": "web", "to": "user", "y": 468, "label": "render", "variant": "return" }
+  ],
+  "activations": [
+    { "participant": "web", "from": 180, "to": 474, "type": "frontend" },
+    { "participant": "api", "from": 185, "to": 450, "type": "backend" },
+    { "participant": "auth", "from": 205, "to": 244, "type": "security" },
+    { "participant": "redis", "from": 265, "to": 304, "type": "database" },
+    { "participant": "db", "from": 325, "to": 364, "type": "database" },
+    { "participant": "trace", "from": 413, "to": 449, "type": "messagebus" }
+  ],
+  "cards": [
+    {
+      "dot": "emerald",
+      "title": "Happy Path",
+      "items": [
+        "The main request is Web App -> API -> data source -> response",
+        "Return messages are quieter than forward calls",
+        "Activation bars make ownership duration visible"
+      ]
+    },
+    {
+      "dot": "rose",
+      "title": "Policy + Fallback",
+      "items": [
+        "JWT verification is colored as a security interaction",
+        "Cache miss is visible without overpowering the main path",
+        "Database access only appears after cache fallback"
+      ]
+    },
+    {
+      "dot": "orange",
+      "title": "Async Trace",
+      "items": [
+        "Trace emission is dashed and secondary",
+        "It does not block the response path",
+        "The diagram separates user-facing latency from observability"
+      ]
+    }
+  ]
+}

vendor/archify/examples/checkout-platform.base.architecture.json

@@ -0,0 +1,32 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "Checkout Platform — Baseline",
+    "output": "checkout-platform.base.html",
+    "visual_preset": "signal-flow"
+  },
+  "components": [
+    { "id": "buyers", "type": "external", "label": "Buyers", "sublabel": "Web + mobile", "pos": [40, 250], "size": [120, 60] },
+    { "id": "edge", "type": "cloud", "label": "Edge Gateway", "sublabel": "TLS + routing", "pos": [220, 250], "size": [130, 60] },
+    { "id": "checkout", "type": "backend", "label": "Checkout API", "sublabel": "v1 service", "pos": [430, 250], "size": [130, 60] },
+    { "id": "cache", "type": "database", "label": "Session Cache", "sublabel": "Redis", "pos": [430, 100], "size": [130, 60] },
+    { "id": "orders", "type": "database", "label": "Orders", "sublabel": "PostgreSQL", "pos": [640, 250], "size": [130, 60] },
+    { "id": "queue", "type": "messagebus", "label": "Order Events", "sublabel": "durable queue", "pos": [430, 400], "size": [130, 60] },
+    { "id": "worker", "type": "backend", "label": "Fulfilment", "sublabel": "async worker", "pos": [640, 400], "size": [130, 60] },
+    { "id": "payments", "type": "external", "label": "Payment Rail", "sublabel": "external", "pos": [850, 250], "size": [130, 60] }
+  ],
+  "boundaries": [
+    { "kind": "region", "label": "Production region", "wraps": ["edge", "checkout", "cache", "orders", "queue", "worker"] },
+    { "kind": "security-group", "label": "Checkout trust zone", "wraps": ["checkout", "orders"] }
+  ],
+  "connections": [
+    { "id": "buyer-request", "from": "buyers", "to": "edge", "label": "HTTPS", "variant": "emphasis" },
+    { "id": "edge-checkout", "from": "edge", "to": "checkout" },
+    { "id": "session-read", "from": "checkout", "to": "cache", "label": "session", "fromSide": "top", "toSide": "bottom", "labelDy": -66 },
+    { "id": "persist-order", "from": "checkout", "to": "orders", "label": "SQL" },
+    { "id": "publish-order", "from": "checkout", "to": "queue", "label": "accepted", "variant": "dashed", "fromSide": "bottom", "toSide": "top", "labelDy": 66 },
+    { "id": "consume-order", "from": "queue", "to": "worker" },
+    { "id": "authorize-payment", "from": "orders", "to": "payments", "label": "authorize", "variant": "security" }
+  ]
+}

vendor/archify/examples/checkout-platform.head.architecture.json

@@ -0,0 +1,32 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "Checkout Platform — Fraud Gate",
+    "output": "checkout-platform.head.html",
+    "visual_preset": "signal-flow"
+  },
+  "components": [
+    { "id": "buyers", "type": "external", "label": "Buyers", "sublabel": "Web + mobile", "pos": [40, 250], "size": [120, 60] },
+    { "id": "edge", "type": "cloud", "label": "Edge Gateway", "sublabel": "TLS + routing", "pos": [220, 250], "size": [130, 60] },
+    { "id": "checkout", "type": "backend", "label": "Checkout API", "sublabel": "v2 idempotent", "pos": [430, 250], "size": [130, 60] },
+    { "id": "fraud", "type": "security", "label": "Fraud Gate", "sublabel": "policy scoring", "pos": [640, 100], "size": [130, 60], "tag": "new owner" },
+    { "id": "orders", "type": "database", "label": "Orders", "sublabel": "PostgreSQL", "pos": [640, 250], "size": [130, 60] },
+    { "id": "queue", "type": "messagebus", "label": "Order Events", "sublabel": "durable queue", "pos": [430, 420], "size": [130, 60] },
+    { "id": "worker", "type": "backend", "label": "Fulfilment", "sublabel": "async worker", "pos": [640, 400], "size": [130, 60] },
+    { "id": "payments", "type": "external", "label": "Payment Rail", "sublabel": "external", "pos": [850, 250], "size": [130, 60] }
+  ],
+  "boundaries": [
+    { "kind": "region", "label": "Production region", "wraps": ["edge", "checkout", "fraud", "orders", "queue", "worker"] },
+    { "kind": "security-group", "label": "Checkout trust zone", "wraps": ["checkout", "fraud", "orders"] }
+  ],
+  "connections": [
+    { "id": "buyer-request", "from": "buyers", "to": "edge", "label": "HTTPS", "variant": "emphasis" },
+    { "id": "edge-checkout", "from": "edge", "to": "checkout" },
+    { "id": "fraud-check", "from": "checkout", "to": "fraud", "label": "screen", "variant": "security", "fromSide": "top", "toSide": "bottom", "labelDy": -66 },
+    { "id": "persist-order", "from": "checkout", "to": "orders", "label": "SQL tx" },
+    { "id": "publish-order", "from": "checkout", "to": "queue", "label": "accepted", "variant": "dashed", "fromSide": "bottom", "toSide": "top", "labelDy": 76 },
+    { "id": "consume-order", "from": "queue", "to": "worker" },
+    { "id": "authorize-payment", "from": "fraud", "to": "payments", "label": "authorize", "variant": "security", "fromSide": "right", "toSide": "top", "via": [[820, 130], [915, 130]] }
+  ]
+}

vendor/archify/examples/deployment-release.lifecycle.json

@@ -0,0 +1,48 @@
+{
+  "schema_version": 2,
+  "diagram_type": "lifecycle",
+  "meta": {
+    "title": "Deployment Release Lifecycle",
+    "output": "examples/deployment-release.html",
+    "animation": "trace",
+    "visual_preset": "signal-flow",
+    "quality_profile": "showcase"
+  },
+  "lanes": [
+    { "id": "main", "label": "Release phases" },
+    { "id": "waiting", "label": "Approval + health wait" },
+    { "id": "recovery", "label": "Rollback controller" },
+    { "id": "terminal", "label": "Terminal exits" }
+  ],
+  "states": [
+    { "id": "queued", "type": "start", "label": "Queued", "sublabel": "change accepted", "lane": "main", "col": 0, "step": "01", "tag": "pending" },
+    { "id": "building", "type": "active", "label": "Building", "sublabel": "immutable image", "lane": "main", "col": 1, "step": "02", "tag": "running" },
+    { "id": "verifying", "type": "decision", "label": "Verifying", "sublabel": "tests + policy", "lane": "main", "col": 2, "step": "03", "tag": "gate" },
+    { "id": "ready", "type": "waiting", "label": "Ready", "sublabel": "promotion pending", "lane": "main", "col": 3, "step": "04", "tag": "approved" },
+    { "id": "live", "type": "success", "label": "Live", "sublabel": "production healthy", "lane": "main", "col": 4, "step": "05", "tag": "success" },
+    { "id": "approval", "type": "waiting", "label": "Needs Approval", "sublabel": "release owner", "lane": "waiting", "col": 2, "tag": "pause" },
+    { "id": "rollback", "type": "active", "label": "Rolling Back", "sublabel": "last good image", "lane": "recovery", "col": 3, "tag": "automatic" },
+    { "id": "paused", "type": "waiting", "label": "Health Paused", "sublabel": "SLO regression", "lane": "waiting", "col": 4, "tag": "observe" },
+    { "id": "cancelled", "type": "failure", "label": "Cancelled", "sublabel": "approval denied", "lane": "terminal", "col": 2, "tag": "terminal" },
+    { "id": "failed", "type": "failure", "label": "Failed", "sublabel": "rollback failed", "lane": "terminal", "col": 3, "tag": "terminal" },
+    { "id": "rolled_back", "type": "success", "label": "Rolled Back", "sublabel": "service restored", "lane": "terminal", "col": 4, "tag": "terminal" }
+  ],
+  "transitions": [
+    { "from": "queued", "to": "building" },
+    { "from": "building", "to": "verifying" },
+    { "from": "verifying", "to": "ready" },
+    { "from": "ready", "to": "live" },
+    { "from": "verifying", "to": "approval", "variant": "security", "label": "needs sign-off" },
+    { "from": "approval", "to": "ready", "label": "approved" },
+    { "from": "approval", "to": "cancelled", "variant": "security" },
+    { "from": "ready", "to": "rollback", "variant": "security" },
+    { "from": "rollback", "to": "failed", "variant": "security" },
+    { "from": "live", "to": "paused", "variant": "dashed" },
+    { "from": "paused", "to": "rolled_back", "variant": "emphasis" }
+  ],
+  "cards": [
+    { "dot": "cyan", "title": "Promotion Rail", "items": ["The release object moves through five ordered phases", "Verification and approval remain distinct states", "Live means production health is currently proven"] },
+    { "dot": "amber", "title": "Wait States", "items": ["Human approval can pause without consuming a worker", "A health regression pauses further rollout", "Every wait exposes the event required to continue"] },
+    { "dot": "rose", "title": "Explicit Endings", "items": ["Denied approval ends as Cancelled", "Rollback controller failure ends as Failed", "Successful rollback is a terminal restored outcome"] }
+  ]
+}

vendor/archify/examples/event-stream.dataflow.json

@@ -0,0 +1,52 @@
+{
+  "schema_version": 1,
+  "diagram_type": "dataflow",
+  "meta": {
+    "title": "Order Event-stream Topology",
+    "output": "examples/event-stream.html",
+    "viewBox": [1080, 780],
+    "animation": "trace",
+    "visual_preset": "signal-flow",
+    "quality_profile": "showcase"
+  },
+  "stages": [
+    { "label": "Producers" },
+    { "label": "Transit" },
+    { "label": "Processors" },
+    { "label": "State + recovery" },
+    { "label": "Consumers" }
+  ],
+  "nodes": [
+    { "id": "checkout", "type": "frontend", "label": "Checkout API", "sublabel": "order producer", "stage": 0, "row": 0, "tag": "team commerce" },
+    { "id": "billing", "type": "backend", "label": "Billing API", "sublabel": "payment producer", "stage": 0, "row": 2, "tag": "team money" },
+    { "id": "orders", "type": "messagebus", "label": "orders.v1", "sublabel": "12 partitions", "stage": 1, "row": 0, "tag": "key: order_id" },
+    { "id": "payments", "type": "messagebus", "label": "payments.v2", "sublabel": "8 partitions", "stage": 1, "row": 2, "tag": "key: order_id" },
+    { "id": "validate", "type": "backend", "label": "Order Validate", "sublabel": "group fulfillment", "stage": 2, "row": 0, "tag": "ordered" },
+    { "id": "enrich", "type": "backend", "label": "Payment Enrich", "sublabel": "group analytics", "stage": 2, "row": 2, "tag": "at-least-once" },
+    { "id": "state", "type": "database", "label": "Order State", "sublabel": "materialized view", "stage": 3, "row": 1, "tag": "idempotent" },
+    { "id": "dlq", "type": "messagebus", "label": "events.dlq", "sublabel": "poison events", "stage": 3, "row": 4, "tag": "7-day retention" },
+    { "id": "fulfillment", "type": "backend", "label": "Fulfillment", "sublabel": "shipping workflow", "stage": 4, "row": 0, "tag": "consumer" },
+    { "id": "analytics", "type": "database", "label": "Analytics", "sublabel": "streaming facts", "stage": 4, "row": 2, "tag": "consumer" },
+    { "id": "replay", "type": "security", "label": "Replay Tool", "sublabel": "approved batch", "stage": 4, "row": 4, "tag": "operator gate" },
+    { "id": "ops", "type": "external", "label": "On-call", "sublabel": "DLQ owner", "stage": 4, "row": 3, "yOffset": -18, "tag": "SRE" }
+  ],
+  "flows": [
+    { "from": "checkout", "to": "orders", "label": "OrderPlaced", "classification": "schema v1", "variant": "emphasis", "route": "straight" },
+    { "from": "billing", "to": "payments", "label": "PaymentCaptured", "classification": "schema v2", "variant": "emphasis", "route": "straight" },
+    { "from": "orders", "to": "validate", "label": "ordered orders", "classification": "consumer group", "variant": "emphasis", "route": "straight" },
+    { "from": "payments", "to": "enrich", "label": "payment facts", "classification": "at-least-once", "variant": "emphasis", "route": "straight" },
+    { "from": "validate", "to": "state", "label": "valid order", "classification": "idempotent", "variant": "emphasis", "route": "vertical-channel" },
+    { "from": "enrich", "to": "state", "label": "enriched payment", "classification": "idempotent", "variant": "default", "route": "vertical-channel" },
+    { "from": "state", "to": "fulfillment", "label": "ready orders", "classification": "read model", "variant": "emphasis", "route": "vertical-channel" },
+    { "from": "state", "to": "analytics", "label": "order facts", "classification": "non-PII", "variant": "default", "route": "vertical-channel" },
+    { "from": "validate", "to": "dlq", "label": "invalid event", "classification": "dead letter", "variant": "security", "fromSide": "top", "toSide": "top", "via": [[530, 80], [20, 80], [20, 550], [745, 550]], "labelAt": [300, 550] },
+    { "from": "enrich", "to": "dlq", "label": "poison event", "classification": "dead letter", "variant": "security", "route": "bottom-channel", "labelDy": 30 },
+    { "from": "dlq", "to": "ops", "label": "failure sample", "classification": "restricted", "variant": "security", "route": "vertical-channel" },
+    { "from": "dlq", "to": "replay", "label": "approved replay", "classification": "audited batch", "variant": "dashed", "route": "straight", "labelDy": 30 }
+  ],
+  "cards": [
+    { "dot": "amber", "title": "Transit Contract", "items": ["Every event and topic is named", "Partition keys preserve per-order ordering", "Consumer groups expose processing ownership"] },
+    { "dot": "emerald", "title": "State + Delivery", "items": ["Processors write an idempotent materialized view", "Fulfillment and analytics consume distinct assets", "At-least-once delivery never implies duplicate business effects"] },
+    { "dot": "rose", "title": "Failure Ownership", "items": ["Poison events land in a retained dead-letter topic", "On-call inspects samples before replay", "Replay is gated, batched, and auditable"] }
+  ]
+}

vendor/archify/examples/holiday-planning.workflow.json

@@ -0,0 +1,143 @@
+{
+  "schema_version": 2,
+  "diagram_type": "workflow",
+  "meta": {
+    "title": "2026年剩余假期安排",
+    "locale": "zh-CN",
+    "quality_profile": "showcase",
+    "legend": {
+      "entries": {
+        "backend": {
+          "label": "假期"
+        },
+        "security": {
+          "label": "补班"
+        },
+        "external": {
+          "label": "时间节点"
+        }
+      }
+    },
+    "output": "holiday-planning.html"
+  },
+  "lanes": [
+    {
+      "id": "calendar",
+      "label": "时间线"
+    },
+    {
+      "id": "makeup",
+      "label": "调休"
+    }
+  ],
+  "mainPath": [
+    "today",
+    "mid_autumn",
+    "national_day",
+    "year_end"
+  ],
+  "nodes": [
+    {
+      "id": "today",
+      "lane": "calendar",
+      "col": 0,
+      "type": "external",
+      "label": "今天 9月22日",
+      "sublabel": "周二 · 距中秋3天",
+      "icon": "clock"
+    },
+    {
+      "id": "mid_autumn",
+      "lane": "calendar",
+      "col": 1,
+      "type": "backend",
+      "label": "中秋节",
+      "sublabel": "9月25日–27日 · 3天",
+      "tag": "无需调休",
+      "icon": "moon"
+    },
+    {
+      "id": "national_day",
+      "lane": "calendar",
+      "col": 3,
+      "type": "backend",
+      "label": "国庆节",
+      "sublabel": "10月1日–7日 · 7天",
+      "tag": "连休",
+      "icon": "calendar"
+    },
+    {
+      "id": "year_end",
+      "lane": "calendar",
+      "col": 5,
+      "type": "external",
+      "label": "此后至年底",
+      "sublabel": "无法定节假日",
+      "icon": "flag"
+    },
+    {
+      "id": "makeup_work",
+      "lane": "makeup",
+      "col": 3,
+      "type": "security",
+      "label": "调休上班",
+      "sublabel": "10月10日（周六）",
+      "tag": "补班",
+      "icon": "briefcase"
+    }
+  ],
+  "edges": [
+    {
+      "id": "to_mid_autumn",
+      "from": "today",
+      "to": "mid_autumn",
+      "label": "3天后连休"
+    },
+    {
+      "id": "mid_to_national",
+      "from": "mid_autumn",
+      "to": "national_day",
+      "label": "节后上班3天"
+    },
+    {
+      "id": "to_year_end",
+      "from": "national_day",
+      "to": "year_end",
+      "label": "假期结束"
+    },
+    {
+      "id": "makeup_branch",
+      "from": "national_day",
+      "to": "makeup_work",
+      "label": "国庆调休",
+      "role": "branch",
+      "variant": "security"
+    }
+  ],
+  "cards": [
+    {
+      "dot": "emerald",
+      "title": "中秋节",
+      "items": [
+        "9月25日（周五）至27日（周日）放假，共3天",
+        "与周末自然相连，无需额外调休上班"
+      ]
+    },
+    {
+      "dot": "amber",
+      "title": "国庆节",
+      "items": [
+        "10月1日（周四）至7日（周三）放假调休，共7天",
+        "9月20日（周日）上班日已过",
+        "10月10日（周六）需补班"
+      ]
+    },
+    {
+      "dot": "slate",
+      "title": "年底前",
+      "items": [
+        "国庆假期结束后，到2026年底不再有法定节假日安排"
+      ]
+    }
+  ]
+}

vendor/archify/examples/incident-response.workflow.json

@@ -0,0 +1,59 @@
+{
+  "schema_version": 1,
+  "diagram_type": "workflow",
+  "meta": {
+    "title": "Incident Response Runbook",
+    "output": "examples/incident-response.html",
+    "animation": "trace",
+    "visual_preset": "signal-flow",
+    "quality_profile": "showcase"
+  },
+  "lanes": [
+    { "id": "signals", "label": "Signals" },
+    { "id": "responders", "label": "Incident Command" },
+    { "id": "mitigation", "label": "Service Mitigation" },
+    { "id": "recovery", "label": "Recovery Evidence" },
+    { "id": "communication", "label": "Stakeholder Communication" },
+    { "id": "exceptions", "label": "Escalation + Rollback", "variant": "exception" }
+  ],
+  "phases": [
+    { "id": "detect", "label": "Detect", "fromCol": 0, "toCol": 1 },
+    { "id": "respond", "label": "Triage + mitigate", "fromCol": 2, "toCol": 3, "variant": "emphasis" },
+    { "id": "recover", "label": "Verify + close", "fromCol": 4, "toCol": 5, "variant": "dashed" }
+  ],
+  "groups": [
+    { "id": "command", "label": "Incident command", "lane": "responders", "fromCol": 1, "toCol": 3, "variant": "emphasis" },
+    { "id": "exception_actions", "label": "If impact persists", "lane": "exceptions", "fromCol": 3, "toCol": 5, "variant": "security" }
+  ],
+  "mainPath": ["alert", "page", "triage", "contain", "recover", "verify", "close"],
+  "nodes": [
+    { "id": "alert", "lane": "signals", "col": 0, "type": "messagebus", "label": "SLO Alert", "sublabel": "burn rate" },
+    { "id": "page", "lane": "responders", "col": 1, "width": 76, "type": "external", "label": "Page On-call", "sublabel": "acknowledge" },
+    { "id": "triage", "lane": "responders", "col": 2, "width": 64, "type": "backend", "label": "Triage", "sublabel": "scope impact" },
+    { "id": "declare", "lane": "responders", "col": 3, "type": "security", "label": "Declare", "sublabel": "assign commander", "tag": "SEV-1/2" },
+    { "id": "contain", "lane": "mitigation", "col": 3, "width": 72, "type": "backend", "label": "Contain", "sublabel": "stop growth" },
+    { "id": "recover", "lane": "mitigation", "col": 4, "width": 52, "type": "cloud", "label": "Recover", "sublabel": "restore" },
+    { "id": "verify", "lane": "recovery", "col": 5, "type": "database", "label": "Verify", "sublabel": "SLO + traces", "tag": "15 min stable" },
+    { "id": "close", "lane": "communication", "col": 5, "type": "external", "label": "Resolve", "sublabel": "final update" },
+    { "id": "update", "lane": "communication", "col": 3, "type": "frontend", "label": "Status Update", "sublabel": "impact + ETA" },
+    { "id": "escalate", "lane": "exceptions", "col": 3, "width": 72, "type": "security", "label": "Escalate", "sublabel": "specialist" },
+    { "id": "rollback", "lane": "exceptions", "col": 5, "type": "messagebus", "label": "Rollback", "sublabel": "last good" }
+  ],
+  "edges": [
+    { "from": "alert", "to": "page", "label": "page", "variant": "emphasis", "route": "drop", "fromSide": "bottom", "toSide": "top" },
+    { "from": "page", "to": "triage", "route": "bottom-channel", "fromSide": "bottom", "toSide": "bottom" },
+    { "from": "triage", "to": "contain", "variant": "emphasis", "route": "drop", "fromSide": "bottom", "toSide": "top" },
+    { "from": "contain", "to": "recover", "route": "bottom-channel", "fromSide": "bottom", "toSide": "bottom" },
+    { "from": "recover", "to": "verify", "variant": "emphasis", "route": "drop", "fromSide": "bottom", "toSide": "top" },
+    { "from": "verify", "to": "close", "variant": "emphasis", "route": "drop", "fromSide": "bottom", "toSide": "top" },
+    { "from": "triage", "to": "declare", "variant": "security" },
+    { "from": "declare", "to": "update", "variant": "dashed", "fromSide": "top", "toSide": "left", "via": [[430, 16], [20, 16], [20, 615]] },
+    { "from": "update", "to": "escalate", "variant": "security", "route": "drop", "fromSide": "bottom", "toSide": "top" },
+    { "from": "verify", "to": "rollback", "variant": "security", "role": "error", "route": "outside-right", "fromSide": "right", "toSide": "right" }
+  ],
+  "cards": [
+    { "dot": "rose", "title": "Ownership First", "items": ["A page is not an incident until someone owns command", "Severity and scope are explicit before mitigation spreads", "Escalation names the missing expertise"] },
+    { "dot": "emerald", "title": "Recovery Is Evidence", "items": ["Mitigation can reduce impact without proving recovery", "SLOs and traces must stay healthy for a fixed window", "The final update follows verification, not optimism"] },
+    { "dot": "cyan", "title": "Communication Contract", "items": ["Stakeholders receive impact, action, and next update time", "Rollback remains visible as a deliberate response", "Every branch has an owner and observable exit"] }
+  ]
+}