ptxiagram 0.1.0 → 0.2.0

package/README.md

@@ -2,39 +2,63 @@
 
 **Generate architecture and workflow diagrams as native, editable PowerPoint shapes — not an embedded image.**
 
+> Built with [Claude Code](https://claude.com/claude-code) — from the initial prototype through the pptxgenjs/Hancom Office compatibility investigation, the JSON schema design, the layout validator, and this package's release automation. See the [commit history](https://github.com/hiio420official/ptxiagram/commits/main) for the build process.
+
 ptxiagram is an agent skill for Claude (and a standalone CLI/library) that turns a plain-English description of a system or process into a `.pptx` slide built from real PowerPoint shapes: rectangles, cylinders, clouds, connectors, text boxes. Anyone can open the result in PowerPoint — or Hancom 한쇼 — and click a box to change its color, text, or position, because it *is* a box, not a picture of one.
 
 - **Native shapes, not a picture** — every box and arrow is a real PPTX shape, editable after generation
-- **Two diagram types today** — `workflow` (swimlanes, happy-path flows) and `architecture` (free-placed components, trust boundaries, hub-and-spoke)
+- **Three diagram types today** — `workflow` (swimlanes, happy-path flows), `architecture` (free-placed components, trust boundaries, hub-and-spoke), and `sequence` (participants + lifelines, API call chains)
 - **A validator that catches real layout bugs before rendering** — node overlap, labels wider than their shape, and connectors that cut through an unrelated node all fail loudly with a specific fix, instead of shipping a broken-looking slide
 - **Ships a Hancom Office compatibility fix** — every generated file is post-processed to strip a documented PptxGenJS defect that PowerPoint silently repairs but Hancom's 한쇼 flags as a corrupted document (see below)
 - **Route presets instead of hand-computed coordinates** — `straight`, `drop`, `elbow-right`, `arc-over-top` cover swimlane transitions, hub-and-spoke fan-out, and routing around a boundary box
 
-## Install
+## Use it in an agent (Claude Code, Codex, Cursor, ...)
 
-As a Claude Skill:
+Install with the [`skills` CLI](https://github.com/vercel-labs/skills) — it detects every supported agent on your machine and wires the skill into each one:
 
 ```bash
 npx skills add hiio420official/ptxiagram -g
 ```
 
-As a CLI / library:
+Then just ask in chat:
 
-```bash
-npm install -g ptxiagram
-ptxiagram doctor
+```text
+Use ptxiagram to draw an architecture diagram for this repo's runtime,
+as a PPTX I can drop into a slide deck.
 ```
 
-## Quick start
+```text
+Use ptxiagram to make a workflow diagram of our incident response process,
+with a lane per team, so I can paste it into the postmortem deck.
+```
+
+The agent reads `SKILL.md`, writes a small JSON file describing your nodes and
+edges, and runs the CLI to produce a `.pptx` with real, editable shapes.
+
+**Per-agent notes:**
+- **Claude Code**: works out of the box after `npx skills add`.
+- **Codex CLI / opencode**: install with an explicit `--agent` flag if you don't want it installed everywhere, e.g. `npx skills use hiio420official/ptxiagram@ptxiagram --agent codex`.
+- **Any other `skills`-supported agent** (Cursor, Windsurf, Continue, Antigravity, Gemini CLI, ...): the same `npx skills add` command installs to whichever of these are detected on your machine.
+
+## Use it standalone (CLI / library)
 
 ```bash
+npm install -g ptxiagram
+ptxiagram doctor
 ptxiagram render workflow examples/onboarding.workflow.json out.pptx
 ptxiagram check out.pptx
 ```
 
+Or as a library:
+
+```js
+import { renderWorkflow } from "ptxiagram";
+await renderWorkflow("my-diagram.workflow.json", "out.pptx");
+```
+
 `render` validates the input (schema + layout) before writing anything, and always repairs the output for Hancom Office compatibility. `check` confirms the repair took, dumps every embedded text run for a spelling/content spot-check, and — if LibreOffice is installed — writes a PNG preview for a quick visual check.
 
-See [`ptxiagram/SKILL.md`](ptxiagram/SKILL.md) for the full JSON shape of both diagram types, the node-type → shape/color mapping, and the route presets.
+See [`SKILL.md`](SKILL.md) for the full JSON shape of both diagram types, the node-type → shape/color mapping, and the route presets.
 
 ## Why every file gets repaired
 

package/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: ptxiagram
-description: Create architecture and workflow diagrams as native, editable PowerPoint shapes (real rectangles, connectors, and text boxes a user can click and restyle in PowerPoint or Hancom 한쇼) instead of an embedded image. Accepts a plain-language description, turns it into a small JSON file, and renders it with pptxgenjs. Use when the user asks for a diagram, architecture drawing, or process flow that needs to end up inside a .pptx deck or a Korean-office-suite-compatible presentation - not when they just want a standalone image or an HTML/web diagram (use an SVG-based diagram tool for that instead).
+description: Create architecture, workflow, and sequence diagrams as native, editable PowerPoint shapes (real rectangles, connectors, and text boxes a user can click and restyle in PowerPoint or Hancom 한쇼) instead of an embedded image. Accepts a plain-language description, turns it into a small JSON file, and renders it with pptxgenjs. Use when the user asks for a diagram, architecture drawing, process flow, or API call sequence that needs to end up inside a .pptx deck or a Korean-office-suite-compatible presentation - not when they just want a standalone image or an HTML/web diagram (use an SVG-based diagram tool for that instead).
 license: MIT
 metadata:
-  version: "0.1.0"
+  version: "0.2.0"
   status: prototype
   based_on: "gitbrent/PptxGenJS (MIT)"
 ---
@@ -51,6 +51,7 @@ validation and the embedded-text dump, just no rendered preview image).
 |------|---------|--------|
 | `workflow` | Cross-team processes, approval chains, anything with swimlanes and a happy path | `schemas/workflow.schema.json` |
 | `architecture` | System components, services, datastores, trust boundaries, hub-and-spoke integrations | `schemas/architecture.schema.json` |
+| `sequence` | API call chains, request/response traces, cache-fallback flows — up to 6 participants, up to 9 messages | `schemas/sequence.schema.json` |
 
 ## The loop
 
@@ -58,6 +59,7 @@ validation and the embedded-text dump, just no rendered preview image).
    shape, don't guess the field names:
    - `examples/onboarding.workflow.json`
    - `examples/order-processing.architecture.json`
+   - `examples/cache-miss.sequence.json`
 2. Write `<name>.<type>.json`.
 3. Render:
    ```bash
@@ -127,6 +129,30 @@ order. Default node size is 1.8×0.95in.
 `boundaries[].wraps` takes component ids, not coordinates — the renderer
 computes a padded frame around them, so never hand-compute a boundary box.
 
+## Sequence JSON shape
+
+```json
+{
+  "schema_version": 1,
+  "diagram_type": "sequence",
+  "meta": { "title": "...", "output": "out.pptx" },
+  "participants": [
+    { "id": "api", "type": "backend", "label": "API", "sublabel": "handler" }
+  ],
+  "messages": [
+    { "from": "client", "to": "api", "label": "GET /orders/123", "variant": "emphasis" }
+  ],
+  "cards": []
+}
+```
+
+**Layout budget**: up to 6 participants in a row (auto-spaced, 2.2in apart),
+each with a vertical dashed lifeline. Messages are drawn in JSON array order
+at auto-incrementing y positions (0.55in apart) — order matters, there's no
+explicit `y` field. Up to 9 messages without `cards`, ~6 with (cards need
+room at the bottom, so the lifeline gets shorter). Self-messages (same
+`from`/`to`) aren't supported yet.
+
 ## Node types
 
 `client` `frontend` `neutral` `backend` `database` `cache` `queue`
@@ -169,7 +195,8 @@ this automatically; `check` verifies it actually happened. Source:
 
 ## What's not built yet
 
-- `sequence`, `dataflow`, `lifecycle` diagram types (only `workflow` and
-  `architecture` exist so far)
+- `dataflow`, `lifecycle` diagram types (`workflow`, `architecture`, and
+  `sequence` exist so far)
 - No CJK exact-metrics font measurement — the label-width check is a
   conservative estimate, not real glyph widths
+- Sequence self-messages (a participant messaging itself)

package/bin/cli.mjs

@@ -7,11 +7,12 @@ import { promisify } from "node:util";
 import JSZip from "jszip";
 import { renderWorkflow } from "../renderers/workflow/render-workflow.mjs";
 import { renderArchitecture } from "../renderers/architecture/render-architecture.mjs";
+import { renderSequence } from "../renderers/sequence/render-sequence.mjs";
 import { validateAll } from "../lib/validate.mjs";
 
 const execFileAsync = promisify(execFile);
 
-const RENDERERS = { workflow: renderWorkflow, architecture: renderArchitecture };
+const RENDERERS = { workflow: renderWorkflow, architecture: renderArchitecture, sequence: renderSequence };
 
 function usage() {
   console.log(`Usage:
@@ -20,7 +21,7 @@ function usage() {
   cli check <output.pptx>
   cli doctor
 
-Types: workflow, architecture`);
+Types: workflow, architecture, sequence`);
 }
 
 async function cmdRender(type, inputPath, outputPath) {

package/examples/cache-miss.sequence.json

@@ -0,0 +1,23 @@
+{
+  "schema_version": 1,
+  "diagram_type": "sequence",
+  "meta": {
+    "title": "캐시 미스 요청 흐름",
+    "subtitle": "Client → API → Cache → DB",
+    "output": "test/output/cache-miss.schema-driven.pptx"
+  },
+  "participants": [
+    { "id": "client", "type": "client", "label": "Client", "sublabel": "브라우저" },
+    { "id": "api", "type": "backend", "label": "API", "sublabel": "handler" },
+    { "id": "cache", "type": "cache", "label": "Cache", "sublabel": "Redis" },
+    { "id": "db", "type": "database", "label": "DB", "sublabel": "PostgreSQL" }
+  ],
+  "messages": [
+    { "from": "client", "to": "api", "label": "GET /orders/123", "variant": "emphasis" },
+    { "from": "api", "to": "cache", "label": "조회", "variant": "default" },
+    { "from": "cache", "to": "api", "label": "캐시 미스", "variant": "dashed" },
+    { "from": "api", "to": "db", "label": "쿼리 실행", "variant": "emphasis" },
+    { "from": "db", "to": "api", "label": "결과 반환", "variant": "dashed" },
+    { "from": "api", "to": "client", "label": "200 OK", "variant": "emphasis" }
+  ]
+}

package/index.mjs

@@ -1,4 +1,11 @@
 export { renderWorkflow } from "./renderers/workflow/render-workflow.mjs";
 export { renderArchitecture } from "./renderers/architecture/render-architecture.mjs";
-export { validateAll, validateSchema, validateWorkflowLayout, validateArchitectureLayout } from "./lib/validate.mjs";
+export { renderSequence } from "./renderers/sequence/render-sequence.mjs";
+export {
+  validateAll,
+  validateSchema,
+  validateWorkflowLayout,
+  validateArchitectureLayout,
+  validateSequenceLayout,
+} from "./lib/validate.mjs";
 export { repairPptx } from "./lib/repair-pptx.mjs";

package/lib/layout.mjs

@@ -47,6 +47,29 @@ export function computeWorkflowLayout(raw) {
   return { laneBoxes, nodeBoxes, nodeMeta, cardsY };
 }
 
+export const SEQUENCE_LAYOUT = {
+  X0: 0.7, GAP: 2.2, BOX_W: 1.5, BOX_H: 0.7,
+  TOP_Y: 1.1, LIFELINE_BOTTOM: 7.0,
+  MSG_START_Y: 2.3, MSG_STEP: 0.55,
+};
+
+export function computeSequenceLayout(raw) {
+  const L = SEQUENCE_LAYOUT;
+  const participantBoxes = {};
+  const centerX = {};
+  raw.participants.forEach((p, i) => {
+    const x = L.X0 + i * L.GAP;
+    participantBoxes[p.id] = { x, y: L.TOP_Y, w: L.BOX_W, h: L.BOX_H };
+    centerX[p.id] = x + L.BOX_W / 2;
+  });
+  const messageYs = raw.messages.map((_, i) => L.MSG_START_Y + i * L.MSG_STEP);
+  // cards need ~1.75in of vertical room, so diagrams that use them get a
+  // shorter lifeline (fewer messages fit) instead of overflowing the slide
+  const lifelineBottom = raw.cards && raw.cards.length ? 5.3 : L.LIFELINE_BOTTOM;
+  const cardsY = lifelineBottom + 0.15;
+  return { participantBoxes, centerX, messageYs, lifelineBottom, cardsY };
+}
+
 const BOUNDARY_PAD = 0.3;
 
 export function computeArchitectureLayout(raw) {

package/lib/routes.mjs

@@ -110,3 +110,19 @@ export function connector(slide, from, to, opts = {}) {
     });
   }
 }
+
+/** Draws a single point-to-point arrow at an explicit y (sequence
+ * messages, self-loops) instead of anchoring to node box sides. Direction
+ * matters: the arrowhead lands at (x2,y). opts: { color, dashed, label } */
+export function drawArrow(slide, { x1, x2, y, color = "94A3B8", dashed = false, label }) {
+  slide.addShape("line", {
+    x: Math.min(x1, x2), y, w: Math.abs(x2 - x1), h: 0,
+    line: { color, width: 2, dashType: dashed ? "dash" : "solid", endArrowType: "triangle" },
+  });
+  if (label) {
+    slide.addText(label, {
+      x: Math.min(x1, x2), y: y - 0.26, w: Math.abs(x2 - x1), h: 0.24,
+      align: "center", fontFace: FONT, fontSize: 8.5, color: "475569",
+    });
+  }
+}

package/lib/shapes.mjs

@@ -92,6 +92,15 @@ export function drawCards(slide, cards, y) {
   });
 }
 
+// Draws a participant's vertical lifeline (a sequence-diagram convention:
+// a thin dashed reference line a participant's messages attach to).
+export function drawLifeline(slide, { x, fromY, toY }) {
+  slide.addShape("line", {
+    x, y: fromY, w: 0, h: toY - fromY,
+    line: { color: "CBD5E1", width: 1, dashType: "dash" },
+  });
+}
+
 // Draws a swimlane frame with a title strip. Returns the lane's box.
 export function drawLane(slide, { x, y, w, h, label }) {
   slide.addShape("rect", {

package/lib/validate.mjs

@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import Ajv2020 from "ajv/dist/2020.js";
-import { computeWorkflowLayout, computeArchitectureLayout, SLIDE_W, SLIDE_H } from "./layout.mjs";
+import { computeWorkflowLayout, computeArchitectureLayout, computeSequenceLayout, SLIDE_W, SLIDE_H } from "./layout.mjs";
 import { computeSegments } from "./routes.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -133,11 +133,50 @@ export function validateArchitectureLayout(raw) {
   });
 }
 
+export function validateSequenceLayout(raw) {
+  const problems = [];
+  const { participantBoxes, messageYs, lifelineBottom } = computeSequenceLayout(raw);
+  const ids = Object.keys(participantBoxes);
+
+  for (const p of raw.participants) {
+    const box = participantBoxes[p.id];
+    const w = estimateTextWidth(p.label, 12.5);
+    if (w > box.w - 0.1) {
+      problems.push(`Participant "${p.id}" label "${p.label}" (~${w.toFixed(2)}in) is wider than its shape (${box.w.toFixed(2)}in) — shorten the label or move detail to sublabel.`);
+    }
+    if (offSlide(box)) {
+      problems.push(`Participant "${p.id}" is off-slide (slide is ${SLIDE_W}x${SLIDE_H}in).`);
+    }
+  }
+
+  for (let i = 0; i < ids.length; i++) {
+    for (let j = i + 1; j < ids.length; j++) {
+      if (rectsOverlap(participantBoxes[ids[i]], participantBoxes[ids[j]])) {
+        problems.push(`Participants "${ids[i]}" and "${ids[j]}" overlap.`);
+      }
+    }
+  }
+
+  raw.messages.forEach((m, i) => {
+    if (m.from === m.to) {
+      problems.push(`Message ${i} ("${m.label}") has the same participant "${m.from}" as from and to — self-messages aren't supported yet.`);
+    }
+    if (!participantBoxes[m.from]) problems.push(`Message ${i} references unknown participant "${m.from}".`);
+    if (!participantBoxes[m.to]) problems.push(`Message ${i} references unknown participant "${m.to}".`);
+    if (messageYs[i] > lifelineBottom - 0.3) {
+      problems.push(`Message ${i} ("${m.label}") falls below the lifeline (too many messages for the available space) — split into fewer messages or drop the cards to free up room.`);
+    }
+  });
+
+  return problems;
+}
+
 /** Runs schema validation, then layout collision checks. Returns the list
  * of layout problems (empty = clean); throws if schema validation fails. */
 export async function validateAll(type, raw) {
   await validateSchema(type, raw);
   if (type === "workflow") return validateWorkflowLayout(raw);
   if (type === "architecture") return validateArchitectureLayout(raw);
+  if (type === "sequence") return validateSequenceLayout(raw);
   throw new Error(`Unknown diagram type: ${type}`);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ptxiagram",
-  "version": "0.1.0",
-  "description": "Generate native, editable PowerPoint (PPTX) architecture and workflow diagrams from a small JSON file — real shapes and connectors, not an embedded image. Ships with a Claude Skill (SKILL.md) and a CLI.",
+  "version": "0.2.0",
+  "description": "Generate native, editable PowerPoint (PPTX) architecture, workflow, and sequence diagrams from a small JSON file — real shapes and connectors, not an embedded image. Ships with a Claude Skill (SKILL.md) and a CLI.",
   "type": "module",
   "main": "index.mjs",
   "bin": {
@@ -18,7 +18,7 @@
   ],
   "scripts": {
     "doctor": "node bin/cli.mjs doctor",
-    "test": "node test/render-workflow.test.mjs && node test/render-architecture.test.mjs && node test/validate.test.mjs && node test/workflow-lib-smoke.test.mjs"
+    "test": "node test/render-workflow.test.mjs && node test/render-architecture.test.mjs && node test/render-sequence.test.mjs && node test/validate.test.mjs && node test/workflow-lib-smoke.test.mjs"
   },
   "keywords": [
     "pptx",
@@ -27,6 +27,7 @@
     "claude-skill",
     "architecture-diagram",
     "workflow-diagram",
+    "sequence-diagram",
     "hancom",
     "hanshow",
     "office-automation"

package/renderers/architecture/render-architecture.mjs

@@ -1,5 +1,6 @@
 import pptxgen from "pptxgenjs";
 import fs from "node:fs/promises";
+import path from "node:path";
 import { drawNode, drawBoundary, drawCards, FONT, EDGE_VARIANTS } from "../../lib/shapes.mjs";
 import { connector } from "../../lib/routes.mjs";
 import { repairPptx } from "../../lib/repair-pptx.mjs";
@@ -62,6 +63,7 @@ export async function renderArchitecture(inputPath, outputPath) {
   });
 
   const outFile = outputPath || raw.meta.output || "output.pptx";
+  await fs.mkdir(path.dirname(outFile), { recursive: true });
   await pptx.writeFile({ fileName: outFile });
   await repairPptx(outFile);
   return outFile;

package/renderers/sequence/render-sequence.mjs

@@ -0,0 +1,67 @@
+import pptxgen from "pptxgenjs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { drawNode, drawLifeline, drawCards, FONT, EDGE_VARIANTS } from "../../lib/shapes.mjs";
+import { drawArrow } from "../../lib/routes.mjs";
+import { repairPptx } from "../../lib/repair-pptx.mjs";
+import { validateSchema, validateSequenceLayout } from "../../lib/validate.mjs";
+import { computeSequenceLayout } from "../../lib/layout.mjs";
+
+export async function renderSequence(inputPath, outputPath) {
+  const raw = JSON.parse(await fs.readFile(inputPath, "utf8"));
+  await validateSchema("sequence", raw);
+
+  const { participantBoxes, centerX, messageYs, lifelineBottom, cardsY } = computeSequenceLayout(raw);
+  const problems = validateSequenceLayout(raw);
+  if (problems.length) {
+    throw new Error(`Sequence layout validation failed:\n- ${problems.join("\n- ")}`);
+  }
+
+  const pptx = new pptxgen();
+  pptx.defineLayout({ name: "WIDE", width: 13.33, height: 7.5 });
+  pptx.layout = "WIDE";
+  const slide = pptx.addSlide();
+
+  slide.addText(raw.meta.title, {
+    x: 0.4, y: 0.2, w: 12.5, h: 0.5,
+    fontFace: FONT, fontSize: 20, bold: true, color: "0F172A",
+  });
+  if (raw.meta.subtitle) {
+    slide.addText(raw.meta.subtitle, {
+      x: 0.4, y: 0.65, w: 12.5, h: 0.3,
+      fontFace: FONT, fontSize: 11, color: "64748B",
+    });
+  }
+
+  for (const p of raw.participants) {
+    drawNode(slide, { ...participantBoxes[p.id], label: p.label, sublabel: p.sublabel, type: p.type });
+    drawLifeline(slide, {
+      x: centerX[p.id],
+      fromY: participantBoxes[p.id].y + participantBoxes[p.id].h,
+      toY: lifelineBottom,
+    });
+  }
+
+  raw.messages.forEach((m, i) => {
+    const variant = EDGE_VARIANTS[m.variant || "default"];
+    drawArrow(slide, {
+      x1: centerX[m.from], x2: centerX[m.to], y: messageYs[i],
+      color: variant.color, dashed: variant.dashed, label: m.label,
+    });
+  });
+
+  if (raw.cards && raw.cards.length) {
+    drawCards(slide, raw.cards, cardsY);
+  }
+
+  slide.addText("Made with a Claude Skill · native PPTX shapes, editable in PowerPoint", {
+    x: 0.4, y: 7.15, w: 12.5, h: 0.3,
+    fontFace: FONT, fontSize: 8, color: "94A3B8", italic: true,
+  });
+
+  const outFile = outputPath || raw.meta.output || "output.pptx";
+  await fs.mkdir(path.dirname(outFile), { recursive: true });
+  await pptx.writeFile({ fileName: outFile });
+  await repairPptx(outFile);
+  return outFile;
+}

package/renderers/workflow/render-workflow.mjs

@@ -1,5 +1,6 @@
 import pptxgen from "pptxgenjs";
 import fs from "node:fs/promises";
+import path from "node:path";
 import { drawNode, drawLane, drawCards, FONT, EDGE_VARIANTS } from "../../lib/shapes.mjs";
 import { connector } from "../../lib/routes.mjs";
 import { repairPptx } from "../../lib/repair-pptx.mjs";
@@ -61,6 +62,7 @@ export async function renderWorkflow(inputPath, outputPath) {
   });
 
   const outFile = outputPath || raw.meta.output || "output.pptx";
+  await fs.mkdir(path.dirname(outFile), { recursive: true });
   await pptx.writeFile({ fileName: outFile });
   await repairPptx(outFile);
   return outFile;

package/schemas/sequence.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://claude-skills/pptx-diagram/schemas/sequence.schema.json",
+  "title": "Native PPTX Sequence Diagram",
+  "description": "Participants sit in a row (max 6, auto-spaced) with a vertical lifeline; messages are drawn in JSON order at auto-incrementing y positions. See renderers/sequence for the layout budget.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "diagram_type", "meta", "participants", "messages"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "diagram_type": { "const": "sequence" },
+    "meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["title"],
+      "properties": {
+        "title": { "type": "string", "minLength": 1 },
+        "subtitle": { "type": "string" },
+        "output": { "type": "string" }
+      }
+    },
+    "participants": {
+      "type": "array",
+      "minItems": 2,
+      "maxItems": 6,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "type", "label"],
+        "properties": {
+          "id": { "$ref": "common.schema.json#/$defs/id" },
+          "type": { "$ref": "common.schema.json#/$defs/nodeType" },
+          "label": { "type": "string", "minLength": 1 },
+          "sublabel": { "type": "string" }
+        }
+      }
+    },
+    "messages": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 9,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["from", "to", "label"],
+        "properties": {
+          "from": { "$ref": "common.schema.json#/$defs/id" },
+          "to": { "$ref": "common.schema.json#/$defs/id" },
+          "label": { "type": "string", "minLength": 1 },
+          "variant": { "enum": ["default", "emphasis", "security", "dashed"] }
+        }
+      }
+    },
+    "cards": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["title", "items"],
+        "properties": {
+          "title": { "type": "string", "minLength": 1 },
+          "color": { "$ref": "common.schema.json#/$defs/hexColor" },
+          "items": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    }
+  }
+}