@stacksjs/defaults 0.74.40 → 0.74.42

package/ai/skills/stacks-technical-diagrams/examples/agent-run.lifecycle.json

@@ -3,9 +3,15 @@
   "diagram_type": "lifecycle",
   "meta": {
     "title": "Agent Run Lifecycle",
-    "subtitle": "State machine for planning, tool execution, human approval, retries, and terminal outcomes",
     "output": "examples/lifecycle-agent-run.html",
-    "viewBox": [980, 660]
+    "viewBox": [1030, 630],
+    "animation": "trace",
+    "quality_profile": "showcase",
+    "views": [
+      { "id": "main-lifecycle", "label": "Main lifecycle", "focus": ["queued", "planning", "executing", "reviewing", "completed"], "note": "Follow the ordered phases from accepted request to completed response." },
+      { "id": "human-waits", "label": "Human and input waits", "focus": ["executing", "approval", "reviewing", "blocked"], "note": "See where the run pauses without becoming terminal." },
+      { "id": "recovery-and-exits", "label": "Recovery and terminal exits", "focus": ["executing", "failed", "blocked", "cancelled", "expired"], "note": "Separate retryable failure from cancellation and expiry." }
+    ]
   },
   "lanes": [
     { "id": "main", "label": "Lifecycle phases" },
@@ -26,38 +32,28 @@
     { "id": "expired", "type": "failure", "label": "Expired", "sublabel": "timeout", "lane": "terminal", "col": 1, "tag": "terminal" }
   ],
   "transitions": [
-    { "from": "executing", "to": "approval", "variant": "security", "fromSide": "bottom", "toSide": "top", "route": "straight" },
-    { "from": "reviewing", "to": "blocked", "variant": "default", "route": "drop" },
-    { "from": "executing", "to": "failed", "variant": "security", "fromSide": "left", "toSide": "top", "via": [[340, 342], [402, 342]] },
-    { "from": "blocked", "to": "expired", "variant": "security", "fromSide": "bottom", "toSide": "top", "route": "straight" },
-    { "from": "approval", "to": "cancelled", "variant": "security", "fromSide": "bottom", "toSide": "top", "route": "straight" }
+    { "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",
+      "title": "Main Path + Waits",
       "items": [
         "The run has five ordered phases from queue to completion",
-        "The primary lifecycle is carried by one horizontal rail",
-        "Completion is a phase, not a detached side box"
-      ]
-    },
-    {
-      "dot": "amber",
-      "title": "Human + Input Gates",
-      "items": [
-        "Approval pauses execution without ending the run",
-        "Blocked waits for missing user input",
-        "Wait states can resume back into planning or execution"
+        "Approval and missing input pause the run without ending it"
       ]
     },
     {
       "dot": "rose",
-      "title": "Terminal + Recovery",
+      "title": "Recovery + Terminal Exits",
       "items": [
         "Failed loops back while retry budget remains",
-        "Cancelled and Expired are exits from the lifecycle",
-        "Terminal exits do not point back into active execution"
+        "Cancelled and Expired are terminal exits with no return path"
       ]
     }
   ]

package/ai/skills/stacks-technical-diagrams/examples/agent-tool-call.workflow.json

@@ -1,19 +1,38 @@
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "diagram_type": "workflow",
   "meta": {
     "title": "Agent Tool Call Workflow",
-    "subtitle": "Renderer-driven workflow prototype with lanes, anchored nodes, and orthogonal edges",
-    "output": "examples/workflow-agent-tool-call-rendered.html",
-    "viewBox": [720, 900]
+    "animation": "trace",
+    "visual_preset": "signal-flow",
+    "quality_profile": "showcase",
+    "views": [
+      {
+        "id": "happy-path",
+        "label": "Request to result",
+        "focus": ["user", "chat", "planner", "router", "approval", "tool", "external", "final"],
+        "note": "Follow the successful request from user intent to the final reply."
+      },
+      {
+        "id": "safety-gate",
+        "label": "Policy and recovery",
+        "focus": ["router", "approval", "blocked", "retry"],
+        "note": "See where risky work stops, waits for consent, or returns for revision."
+      },
+      {
+        "id": "evidence-loop",
+        "label": "Evidence and memory",
+        "focus": ["external", "store", "trace"],
+        "note": "Isolate the durable trace and context path behind the visible answer."
+      }
+    ],
+    "output": "examples/workflow-agent-tool-call-rendered.html"
   },
   "lanes": [
     { "id": "ui", "label": "User Interface" },
     { "id": "agent", "label": "Agent Runtime" },
-    { "id": "policy", "label": "Policy Boundary" },
-    { "id": "exceptions", "label": "Exception Handling", "variant": "exception" },
-    { "id": "tools", "label": "Tool Execution" },
-    { "id": "trace", "label": "Observability" }
+    { "id": "policy", "label": "Policy & Recovery", "variant": "exception" },
+    { "id": "tools", "label": "Tool Execution & Evidence" }
   ],
   "phases": [
     { "id": "intake", "label": "Intake", "fromCol": 0, "toCol": 1 },
@@ -22,66 +41,53 @@
   ],
   "groups": [
     { "id": "agent_loop", "label": "Planning loop", "lane": "agent", "fromCol": 2, "toCol": 3, "variant": "emphasis" },
-    { "id": "tool_work", "label": "Tool work", "lane": "tools", "fromCol": 4, "toCol": 5, "variant": "dashed" },
-    { "id": "exception_path", "label": "Human or policy stop", "lane": "exceptions", "fromCol": 3, "toCol": 5, "variant": "security" }
+    { "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" },
-    { "id": "chat", "lane": "ui", "col": 1, "type": "frontend", "label": "Chat Surface", "sublabel": "thread + files" },
-    { "id": "final", "lane": "ui", "col": 5, "type": "backend", "label": "Final Reply", "sublabel": "answer + changes" },
-    { "id": "planner", "lane": "agent", "col": 2, "type": "backend", "label": "Agent Planner", "sublabel": "plan next step", "tag": "context aware" },
-    { "id": "router", "lane": "agent", "col": 3, "type": "backend", "label": "Tool Router", "sublabel": "choose capability" },
-    { "id": "approval", "lane": "policy", "col": 3, "type": "security", "label": "Approval Gate", "sublabel": "scope + consent", "tag": "block risky ops" },
-    { "id": "blocked", "lane": "exceptions", "col": 4, "type": "security", "label": "Blocked", "sublabel": "wait or reject" },
-    { "id": "retry", "lane": "exceptions", "col": 5, "type": "messagebus", "label": "Retry Path", "sublabel": "revise request" },
-    { "id": "tool", "lane": "tools", "col": 4, "type": "messagebus", "label": "Tool Call", "sublabel": "shell / browser / MCP", "tag": "structured result" },
-    { "id": "external", "lane": "tools", "col": 5, "type": "cloud", "label": "External API", "sublabel": "network service" },
-    { "id": "store", "lane": "trace", "col": 1, "type": "database", "label": "Context Store", "sublabel": "repo + memory" },
-    { "id": "trace", "lane": "trace", "col": 4, "type": "database", "label": "Trace Log", "sublabel": "events + output" }
+    { "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": [
-    { "from": "user", "to": "chat", "variant": "default" },
-    { "from": "chat", "to": "planner", "label": "plan", "variant": "emphasis", "fromSide": "bottom", "toSide": "top", "route": "drop", "labelSegment": 1 },
-    { "from": "planner", "to": "router", "variant": "default" },
-    { "from": "router", "to": "approval", "label": "needs approval?", "variant": "security", "fromSide": "bottom", "toSide": "top", "route": "drop", "labelSegment": 0, "labelDx": 34, "labelDy": 18 },
-    { "from": "approval", "to": "tool", "variant": "emphasis", "fromSide": "left", "toSide": "left", "route": "return-left" },
-    { "from": "approval", "to": "blocked", "label": "denied", "variant": "security", "role": "error", "fromSide": "bottom", "toSide": "top", "route": "drop", "labelSegment": 1, "labelDy": 12 },
-    { "from": "blocked", "to": "retry", "variant": "dashed", "role": "branch" },
-    { "from": "tool", "to": "external", "variant": "default" },
-    { "from": "external", "to": "final", "variant": "emphasis", "role": "return", "fromSide": "right", "toSide": "right", "route": "outside-right", "width": 1.2 },
-    { "from": "external", "to": "trace", "label": "record result", "variant": "dashed", "fromSide": "bottom", "toSide": "bottom", "route": "bottom-channel", "labelSegment": 1 },
-    { "from": "store", "to": "trace", "label": "trace + memory", "variant": "dashed", "labelAt": [365, 735] }
+    { "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": "Renderer Rules",
+      "title": "Compiler Contract",
       "items": [
         "Lanes and columns determine node placement",
-        "Edges attach to explicit node anchors",
-        "Cross-lane paths use orthogonal routing",
-        "Short adjacent links stay unlabeled"
+        "Labels reserve clearance; routes stay orthogonal"
       ]
     },
     {
       "dot": "rose",
-      "title": "Workflow Semantics",
+      "title": "Runtime Semantics",
       "items": [
-        "Approval is a first-class policy step",
-        "Consent gates are visible in the main path",
-        "External calls stay inside the tool lane",
-        "Trace writes are separate from the hot path"
-      ]
-    },
-    {
-      "dot": "emerald",
-      "title": "Why It Matters",
-      "items": [
-        "This is closer to a diagram_type renderer",
-        "The graph can be edited without SVG surgery",
-        "Layout rules can be tested and improved",
-        "A future IR can reuse this shape directly"
+        "Approval gates risky work before tool execution",
+        "Evidence returns through isolated trace and memory"
       ]
     }
   ]

package/ai/skills/stacks-technical-diagrams/examples/async-job-roundtrip.sequence.json

@@ -0,0 +1,61 @@
+{
+  "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",
+    "views": [
+      { "id": "accept-and-enqueue", "label": "Accept without blocking", "focus": ["client", "api", "queue"], "note": "The API acknowledges quickly after durable enqueue." },
+      { "id": "work-and-retry", "label": "Background work and retry", "focus": ["queue", "worker", "provider"], "note": "Timeouts re-enter the queue instead of holding the original request open." },
+      { "id": "observe-final-state", "label": "Observe final consistency", "focus": ["worker", "store", "notify", "client", "api"], "note": "Webhook delivery is primary; polling remains a bounded fallback." }
+    ]
+  },
+  "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"] }
+  ]
+}

package/ai/skills/stacks-technical-diagrams/examples/brand-aware-delivery.architecture.json

@@ -0,0 +1,47 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "Brand-aware AI delivery",
+    "quality_profile": "showcase",
+    "viewBox": [1120, 640],
+    "views": [
+      {
+        "id": "delivery-path",
+        "label": "Delivery path",
+        "focus": ["request", "claude", "github", "container", "edge", "customer"],
+        "note": "Follow one delivery from the request through the model, repository, container, and edge."
+      },
+      {
+        "id": "business-data",
+        "label": "Business and data",
+        "focus": ["container", "database", "billing"],
+        "note": "Inspect durable state and billing without losing the main delivery path."
+      }
+    ]
+  },
+  "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 the skill", "Every visual export keeps the same badge"] }
+  ]
+}

package/ai/skills/stacks-technical-diagrams/examples/cache-miss-request.sequence.json

@@ -3,9 +3,16 @@
   "diagram_type": "sequence",
   "meta": {
     "title": "Cache Miss Request Sequence",
-    "subtitle": "Frontend request path with auth, cache fallback, persistence, and async trace",
     "output": "examples/sequence-cache-miss-request.html",
-    "viewBox": [820, 760]
+    "viewBox": [1080, 560],
+    "column_fit": "spread",
+    "animation": "trace",
+    "quality_profile": "showcase",
+    "views": [
+      { "id": "request-and-auth", "label": "Request and identity", "focus": ["user", "web", "api", "auth"], "note": "Follow the user request through the authentication check." },
+      { "id": "cache-fallback", "label": "Cache fallback", "focus": ["api", "redis", "db"], "note": "See the cache miss and the source-of-truth query it triggers." },
+      { "id": "return-and-trace", "label": "Return and trace", "focus": ["db", "api", "redis", "trace", "web", "user"], "note": "Separate response latency from the non-blocking observability write." }
+    ]
   },
   "participants": [
     { "id": "user", "type": "external", "label": "User", "sublabel": "browser session" },
@@ -17,31 +24,31 @@
     { "id": "trace", "type": "messagebus", "label": "Trace", "sublabel": "async event" }
   ],
   "segments": [
-    { "from": 150, "to": 295, "label": "Request" },
-    { "from": 315, "to": 505, "label": "Fallback" },
-    { "from": 525, "to": 665, "label": "Response + trace" }
+    { "from": 150, "to": 250, "label": "Request" },
+    { "from": 260, "to": 370, "label": "Fallback" },
+    { "from": 380, "to": 480, "label": "Response + trace" }
   ],
   "messages": [
-    { "from": "user", "to": "web", "y": 185, "label": "open page", "variant": "default" },
-    { "from": "web", "to": "api", "y": 228, "label": "GET /dashboard", "variant": "emphasis" },
-    { "from": "api", "to": "auth", "y": 270, "label": "verify JWT", "variant": "security" },
-    { "from": "auth", "to": "api", "y": 305, "label": "claims ok", "variant": "return" },
-    { "from": "api", "to": "redis", "y": 354, "label": "read cache", "variant": "default" },
-    { "from": "redis", "to": "api", "y": 391, "label": "miss", "variant": "return" },
-    { "from": "api", "to": "db", "y": 443, "label": "query profile + metrics", "variant": "emphasis" },
-    { "from": "db", "to": "api", "y": 489, "label": "rows", "variant": "return" },
-    { "from": "api", "to": "redis", "y": 536, "label": "set cache", "variant": "dashed" },
-    { "from": "api", "to": "trace", "y": 580, "label": "emit trace", "variant": "dashed" },
-    { "from": "api", "to": "web", "y": 625, "label": "200 JSON", "variant": "return" },
-    { "from": "web", "to": "user", "y": 662, "label": "render", "variant": "return" }
+    { "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": 220, "to": 668, "type": "frontend" },
-    { "participant": "api", "from": 228, "to": 632, "type": "backend" },
-    { "participant": "auth", "from": 265, "to": 310, "type": "security" },
-    { "participant": "redis", "from": 349, "to": 398, "type": "database" },
-    { "participant": "db", "from": 438, "to": 496, "type": "database" },
-    { "participant": "trace", "from": 575, "to": 630, "type": "messagebus" }
+    { "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": [
     {

package/ai/skills/stacks-technical-diagrams/examples/checkout-platform.base.architecture.json

@@ -0,0 +1,31 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "Checkout Platform - Baseline",
+    "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" }
+  ]
+}

package/ai/skills/stacks-technical-diagrams/examples/checkout-platform.head.architecture.json

@@ -0,0 +1,31 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "Checkout Platform - Fraud Gate",
+    "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]] }
+  ]
+}

package/ai/skills/stacks-technical-diagrams/examples/deployment-release.lifecycle.json

@@ -0,0 +1,49 @@
+{
+  "schema_version": 1,
+  "diagram_type": "lifecycle",
+  "meta": {
+    "title": "Deployment Release Lifecycle",
+    "output": "examples/deployment-release.html",
+    "viewBox": [980, 680],
+    "animation": "trace",
+    "visual_preset": "signal-flow",
+    "quality_profile": "showcase",
+    "views": [
+      { "id": "promotion-rail", "label": "Promotion rail", "focus": ["queued", "building", "verifying", "ready", "live"], "note": "Follow the deployment object from accepted change to healthy production." },
+      { "id": "approval-gate", "label": "Approval gate", "focus": ["verifying", "approval", "cancelled", "ready"], "note": "Approval pauses promotion and can terminate the release cleanly." },
+      { "id": "rollback-outcomes", "label": "Rollback outcomes", "focus": ["ready", "rollback", "failed", "live", "paused", "rolled_back"], "note": "Separate pre-promotion failure from post-promotion health regression." }
+    ]
+  },
+  "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": 0, "tag": "pause" },
+    { "id": "rollback", "type": "active", "label": "Rolling Back", "sublabel": "last good image", "lane": "recovery", "col": 1, "tag": "automatic" },
+    { "id": "paused", "type": "waiting", "label": "Health Paused", "sublabel": "SLO regression", "lane": "waiting", "col": 2, "tag": "observe" },
+    { "id": "cancelled", "type": "failure", "label": "Cancelled", "sublabel": "approval denied", "lane": "terminal", "col": 0, "tag": "terminal" },
+    { "id": "failed", "type": "failure", "label": "Failed", "sublabel": "rollback failed", "lane": "terminal", "col": 1, "tag": "terminal" },
+    { "id": "rolled_back", "type": "success", "label": "Rolled Back", "sublabel": "service restored", "lane": "terminal", "col": 2, "tag": "terminal" }
+  ],
+  "transitions": [
+    { "from": "verifying", "to": "approval", "variant": "security", "route": "straight", "fromSide": "bottom", "toSide": "top" },
+    { "from": "approval", "to": "cancelled", "variant": "security", "route": "straight", "fromSide": "bottom", "toSide": "top" },
+    { "from": "ready", "to": "rollback", "variant": "security", "route": "straight", "fromSide": "bottom", "toSide": "top" },
+    { "from": "rollback", "to": "failed", "variant": "security", "route": "straight", "fromSide": "bottom", "toSide": "top" },
+    { "from": "live", "to": "paused", "variant": "dashed", "route": "straight", "fromSide": "bottom", "toSide": "top" },
+    { "from": "paused", "to": "rolled_back", "variant": "emphasis", "route": "straight", "fromSide": "bottom", "toSide": "top" }
+  ],
+  "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"] }
+  ]
+}