@jterrats/open-orchestra 1.0.2 → 1.0.3

package/docs/diagrams/experiments/roadmap/experiment.md

@@ -0,0 +1,44 @@
+# Technology Roadmap Diagram Experiment
+
+Task: DIAGRAM-ROADMAP-EXPERIMENT
+
+## Source Inventory
+
+- `roadmap-technology-component.pdf`: one-page technology component roadmap with a title band, legend, month columns, a left-side product lane, and rounded initiative cards positioned by time span.
+
+## Element Contract
+
+- Audience: delivery leads and technical stakeholders planning releases and dependencies.
+- Reading flow: month grid left to right; cards occupy the months where work happens.
+- Layout: single product lane with month columns January through June.
+- Nodes: initiative cards with title, start/end date, dependency note, and component icons.
+- Visual constraints: cards must align to month columns, legend must stay separate from the schedule, and card shadows should not imply grouping.
+
+## Prompt Used
+
+Create a technology component roadmap diagram as SVG.
+
+Use a title block on the upper left, a compact legend on the upper right, and a
+timeline grid below. The grid has a left lane label and six monthly columns:
+January, February, March, April, May, June. Use rounded initiative cards placed
+inside the grid by rough date span. Include these initiatives:
+
+- Environment Set-Up, January 15 to February 1, dependency Environment.
+- Account and Contact Management, February 5 to March 15, dependency Environment.
+- Custom Lead Conversion Process, February 15 to April 10, dependency Leads.
+- Opportunity and Quote Management, March 15 to April 15, dependency Accounts, Contacts, Leads.
+- CPQ Integration, March 20 to April 25, dependency Environment.
+- Forecasting, April 20 to May 15, dependency Accounts, Contacts, Leads.
+- Territory Management, April 15 to May 10, dependency Accounts, Contacts, Leads.
+
+Use icon dots inside each card to show component categories. Align every card to
+the relevant month region. Re-evaluate text fit, timeline alignment, overlap,
+and legend spacing after rendering.
+
+## Evaluation Findings
+
+- Roadmaps need column-grid fidelity more than connector fidelity; small card shifts can change perceived timing.
+- Card density becomes a problem when initiatives overlap in the same months; vertical staggering must be part of the prompt.
+- Icons work as metadata, but they need a legend and consistent spacing.
+- A future master rule should require roadmap card start/end alignment checks against the declared time axis.
+

package/docs/diagrams/experiments/sfdc-implementation/diagram.mmd

@@ -0,0 +1,54 @@
+flowchart TB
+  subgraph app["Application, Service, Orchestration and Agentic Layer"]
+    WS["Collaboration Workspace"]
+    EO["Employee Org"]
+    SO["Service Org"]
+    SA["Sales Org"]
+    PO["Partner Org"]
+    CS["Customer Success Org"]
+    WS --> EO
+    WS --> SO
+    WS --> SA
+    WS --> PO
+    WS --> CS
+  end
+
+  subgraph bi["Business Intelligence and Reporting Layer"]
+    AC["Analytics Cloud"]
+  end
+
+  subgraph data["Data Platform and Unification Layer"]
+    DP2["Data Platform Instance 2\nEmployee, IT, Security, Legal"]
+    DP1["Data Platform Instance 1\nSales, Knowledge, CS, M&A, Marketing"]
+    DP2 <--> DP1
+  end
+
+  subgraph external["External Data and Federation Layer"]
+    FED["Query and Federation Layer"]
+    EDW["EDW"]
+    MA["M&A EDW"]
+    TL["Telemetry Lake"]
+    FED --> EDW
+    FED --> MA
+    FED --> TL
+  end
+
+  subgraph source["Source Layer"]
+    SRC1["1P and 3P Data"]
+    SRC2["Structured Data"]
+    SRC3["Enterprise Systems"]
+    SRC4["Marketing Systems"]
+    SRC5["App Logs and Telemetry"]
+  end
+
+  EO --> DP2
+  SO --> AC
+  SA --> AC
+  PO --> DP1
+  CS --> DP1
+  AC --> DP1
+  DP1 --> FED
+  DP2 --> SRC2
+  EDW --> SRC3
+  MA --> SRC4
+  TL --> SRC5

package/docs/diagrams/experiments/sfdc-implementation/diagram.svg

@@ -0,0 +1,72 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1380" height="980" viewBox="0 0 1380 980" role="img" aria-labelledby="title desc">
+  <title id="title">Layered implementation architecture experiment</title>
+  <desc id="desc">Five-layer enterprise implementation architecture with application orgs, reporting, data platforms, external data, and source systems.</desc>
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0 0 L10 5 L0 10 z" fill="#7b8497"/>
+    </marker>
+    <style>
+      .font{font-family:Arial,Helvetica,sans-serif}.title{fill:#2f3747;font-size:22px;font-weight:700}.sub{fill:#3f4858;font-size:11px}.layerLabel{fill:#fff;font-size:14px;font-weight:700}.band{fill:#f0f1fc}.rail{fill:#6155f6}.card{fill:#fff;stroke:#7a8394;stroke-width:1.4}.bar{fill:#fff;stroke:#7a8394;stroke-width:1.4}.cardTitle{fill:#243044;font-size:13px;font-weight:700}.small{fill:#374151;font-size:10px}.chip{fill:#e8fff8;stroke:#bde9db}.chip2{fill:#fff3f3;stroke:#f0c7c7}.edge{fill:none;stroke:#8d96a8;stroke-width:1.5;marker-end:url(#arrow)}.edgeSoft{fill:none;stroke:#8d96a8;stroke-width:1.2}.badgeText{fill:#fff;font-size:9px;font-weight:700}
+    </style>
+  </defs>
+  <rect width="1380" height="980" fill="#fff"/>
+  <g class="font">
+    <text class="title" x="82" y="78">Customer Zero Implementation Architecture</text>
+    <text class="sub" x="82" y="104">Layered view of service, reporting, data platform, external data, and source system relationships.</text>
+    <path d="M760 42 C800 78 800 118 760 154 H1320 V42 Z" fill="#e5e7eb"/>
+    <rect x="930" y="58" width="320" height="80" rx="8" fill="#fff"/>
+    <circle cx="960" cy="82" r="10" fill="#f97316"/><text class="small" x="978" y="86">Cloud service</text>
+    <circle cx="1080" cy="82" r="10" fill="#4285f4"/><text class="small" x="1098" y="86">Ads / media</text>
+    <circle cx="960" cy="114" r="10" fill="#2563eb"/><text class="small" x="978" y="118">Data platform</text>
+    <circle cx="1080" cy="114" r="10" fill="#4b5563"/><text class="small" x="1098" y="118">External app</text>
+    <g>
+      <rect class="rail" x="70" y="178" width="160" height="238" rx="8"/><text class="layerLabel" x="150" y="274" text-anchor="middle">Application</text><text class="layerLabel" x="150" y="294" text-anchor="middle">Service</text><text class="layerLabel" x="150" y="314" text-anchor="middle">Orchestration</text><text class="layerLabel" x="150" y="334" text-anchor="middle">Agentic Layer</text>
+      <rect class="rail" x="70" y="424" width="160" height="118" rx="8"/><text class="layerLabel" x="150" y="466" text-anchor="middle">Business</text><text class="layerLabel" x="150" y="486" text-anchor="middle">Intelligence and</text><text class="layerLabel" x="150" y="506" text-anchor="middle">Reporting Layer</text>
+      <rect class="rail" x="70" y="550" width="160" height="154" rx="8"/><text class="layerLabel" x="150" y="610" text-anchor="middle">Data Platform</text><text class="layerLabel" x="150" y="630" text-anchor="middle">and Unification</text><text class="layerLabel" x="150" y="650" text-anchor="middle">Layer</text>
+      <rect class="rail" x="70" y="712" width="160" height="150" rx="8"/><text class="layerLabel" x="150" y="770" text-anchor="middle">External Data</text><text class="layerLabel" x="150" y="790" text-anchor="middle">and Federation</text><text class="layerLabel" x="150" y="810" text-anchor="middle">Layer</text>
+      <rect class="rail" x="70" y="870" width="160" height="82" rx="8"/><text class="layerLabel" x="150" y="906" text-anchor="middle">Source Layer</text>
+    </g>
+    <rect class="band" x="245" y="178" width="1070" height="238" rx="10"/>
+    <rect class="band" x="245" y="424" width="1070" height="118" rx="10"/>
+    <rect class="band" x="245" y="550" width="1070" height="154" rx="10"/>
+    <rect class="band" x="245" y="712" width="1070" height="150" rx="10"/>
+    <rect class="band" x="245" y="870" width="1070" height="82" rx="10"/>
+    <rect class="bar" x="280" y="192" width="820" height="54" rx="8"/><text class="cardTitle" x="300" y="225">Collaboration Workspace</text>
+    <g>
+      <rect class="card" x="290" y="280" width="160" height="106" rx="8"/><text class="cardTitle" x="310" y="310">Employee Org</text><text class="small" x="310" y="334">Employee agents</text><text class="small" x="310" y="352">HR support</text>
+      <rect class="card" x="478" y="280" width="160" height="106" rx="8"/><text class="cardTitle" x="498" y="310">Service Org</text><text class="small" x="498" y="334">Service agents</text><text class="small" x="498" y="352">Support workflows</text>
+      <rect class="card" x="666" y="280" width="160" height="106" rx="8"/><text class="cardTitle" x="686" y="310">Sales Org</text><text class="small" x="686" y="334">Sales agents</text><text class="small" x="686" y="352">Revenue workflows</text>
+      <rect class="card" x="854" y="280" width="160" height="106" rx="8"/><text class="cardTitle" x="874" y="310">Partner Org</text><text class="small" x="874" y="334">Partner learning</text><text class="small" x="874" y="352">Lead routing</text>
+      <rect class="card" x="1042" y="280" width="160" height="106" rx="8"/><text class="cardTitle" x="1062" y="310">Customer Success</text><text class="small" x="1062" y="334">Incident response</text><text class="small" x="1062" y="352">Success metrics</text>
+    </g>
+    <rect class="card" x="660" y="454" width="190" height="64" rx="8"/><text class="cardTitle" x="682" y="482">Analytics Cloud</text><text class="small" x="682" y="500">Data intelligence and reporting</text>
+    <rect class="card" x="340" y="578" width="310" height="98" rx="8"/><text class="cardTitle" x="362" y="606">Data Platform Instance 2</text><rect class="chip" x="362" y="628" width="66" height="24" rx="5"/><text class="small" x="374" y="644">Employee</text><rect class="chip" x="436" y="628" width="56" height="24" rx="5"/><text class="small" x="451" y="644">IT</text><rect class="chip2" x="362" y="658" width="66" height="24" rx="5"/><text class="small" x="380" y="674">Security</text><rect class="chip2" x="436" y="658" width="56" height="24" rx="5"/><text class="small" x="452" y="674">Legal</text>
+    <rect class="card" x="880" y="578" width="310" height="98" rx="8"/><text class="cardTitle" x="902" y="606">Data Platform Instance 1</text><rect class="chip" x="902" y="628" width="58" height="24" rx="5"/><text class="small" x="918" y="644">Sales</text><rect class="chip" x="968" y="628" width="98" height="24" rx="5"/><text class="small" x="982" y="644">Unified Knowledge</text><rect class="chip2" x="902" y="658" width="58" height="24" rx="5"/><text class="small" x="920" y="674">CS</text><rect class="chip2" x="968" y="658" width="58" height="24" rx="5"/><text class="small" x="986" y="674">M&amp;A</text><rect class="chip2" x="1034" y="658" width="72" height="24" rx="5"/><text class="small" x="1048" y="674">Marketing</text>
+    <rect class="bar" x="736" y="692" width="280" height="24" rx="6"/><text class="small" x="876" y="708" text-anchor="middle">Data sharing between platform instances</text>
+    <rect class="bar" x="742" y="726" width="380" height="26" rx="6"/><text class="small" x="932" y="744" text-anchor="middle">Query and federation layer</text>
+    <g>
+      <rect class="card" x="690" y="772" width="150" height="58" rx="8"/><text class="cardTitle" x="710" y="804">EDW</text>
+      <rect class="card" x="860" y="772" width="150" height="58" rx="8"/><text class="cardTitle" x="880" y="804">M&amp;A EDW</text>
+      <rect class="card" x="1030" y="772" width="150" height="58" rx="8"/><text class="cardTitle" x="1050" y="804">Telemetry Lake</text>
+    </g>
+    <g>
+      <rect class="card" x="270" y="890" width="130" height="42" rx="7"/><text class="small" x="335" y="916" text-anchor="middle">1P and 3P Data</text>
+      <rect class="card" x="430" y="890" width="150" height="42" rx="7"/><text class="small" x="505" y="916" text-anchor="middle">Structured Data</text>
+      <rect class="card" x="610" y="890" width="170" height="42" rx="7"/><text class="small" x="695" y="916" text-anchor="middle">Enterprise Systems</text>
+      <rect class="card" x="810" y="890" width="160" height="42" rx="7"/><text class="small" x="890" y="916" text-anchor="middle">Marketing Systems</text>
+      <rect class="card" x="1000" y="890" width="180" height="42" rx="7"/><text class="small" x="1090" y="916" text-anchor="middle">App Logs and Telemetry</text>
+    </g>
+    <path class="edge" d="M370 386V578"/>
+    <path class="edge" d="M558 386V454"/>
+    <path class="edge" d="M746 386V454"/>
+    <path class="edge" d="M934 386V578"/>
+    <path class="edge" d="M1122 386V578"/>
+    <path class="edge" d="M755 518V578"/>
+    <path class="edgeSoft" d="M650 628H880"/>
+    <path class="edge" d="M495 676V890"/>
+    <path class="edge" d="M1035 676V772"/>
+    <path class="edge" d="M765 830V890"/>
+    <path class="edge" d="M935 830V890"/>
+    <path class="edge" d="M1105 830V890"/>
+  </g>
+</svg>

package/docs/diagrams/experiments/sfdc-implementation/experiment.md

@@ -0,0 +1,41 @@
+# Implementation Architecture Diagram Experiment
+
+Task: DIAGRAM-SFDC-IMPLEMENTATION-EXPERIMENT
+
+## Source Inventory
+
+- `sfdc_customer_zero_implementation.pdf`: one-page layered enterprise implementation architecture. It uses a title/legend band, horizontal layer bands, a left-side layer label rail, system cards, internal subcards, many vertical integration lines, and external/source systems at the bottom.
+
+## Element Contract
+
+- Audience: architecture reviewer evaluating system boundaries and data movement.
+- Reading flow: top application layer down to source systems, with lateral data sharing between platform instances.
+- Layers: Application/Service/Agentic, BI/Reporting, Data Platform, External Data, Source.
+- Nodes: workspace cards, platform cards, external system cards, and integration bars.
+- Connectors: mostly vertical, orthogonal, and labeled only for cross-layer meaning.
+- Visual constraints: layer labels must align with bands, connectors must not hide system names, and dense icons should be abstracted into compact badges.
+
+## Prompt Used
+
+Create a layered implementation architecture diagram as SVG.
+
+Use a top title band and compact legend. Build five horizontal layers with a
+purple label rail on the left. In the top layer, place five organization cards
+under a collaboration bar. In the reporting layer, place a central analytics
+card. In the data platform layer, place two platform instance cards with data
+space chips and feature blocks. In the external data layer, place a shared query
+and federation bar plus three data platform cards. In the source layer, place
+five source system cards.
+
+Use vertical orthogonal connectors between layers and one horizontal connector
+between platform instances. Abstract vendor icons as small colored badges. Keep
+all text inside cards, avoid connector overlap with labels, and re-evaluate
+layer heights after rendering.
+
+## Evaluation Findings
+
+- Dense enterprise diagrams need abstraction rules; copying every icon and micro-label from a reference makes the output unreadable.
+- Layer bands are the primary structure; connectors should be secondary and lower contrast.
+- The prompt must declare which labels are essential versus optional because source diagrams contain many small badges.
+- Future master rules should add a density budget for architecture recreations: max cards per layer, max badges per card, and required zoom/screenshot review.
+

package/docs/diagrams/experiments/swimlane/diagram.mmd

@@ -0,0 +1,40 @@
+flowchart LR
+  subgraph client["Client"]
+    direction TB
+    C1(["Client submits PO"])
+  end
+
+  subgraph sales["Sales"]
+    direction TB
+    S1["Sales reviews costing"]
+  end
+
+  subgraph contracts["Contracts"]
+    direction TB
+    K1["Contracts review"]
+    K2{"Contract okay?"}
+    K3["Set mobilization date"]
+    K4["Complete requirements"]
+    K5["Completion date delayed"]
+  end
+
+  subgraph construction["Construction"]
+    direction TB
+    B1["Construction starts"]
+    B2{"Terms accepted?"}
+    B3["Return files to contractor"]
+  end
+
+  subgraph handover["Handover"]
+    direction TB
+    H1["Construction finished"]
+    H2(["Project handed over"])
+  end
+
+  C1 --> S1 --> K1 --> K2
+  K2 -- Yes --> K3 --> B1 --> B2
+  K2 -- No --> K4
+  K4 --> K3
+  B2 -- Yes --> H1 --> H2
+  B2 -- No --> B3 --> K5
+

package/docs/diagrams/experiments/swimlane/diagram.svg

@@ -0,0 +1,70 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1180" height="760" viewBox="0 0 1180 760" role="img" aria-labelledby="title desc">
+  <title id="title">Swimlane workflow experiment</title>
+  <desc id="desc">Five-lane process flow with department ownership, decisions, and handoff arrows.</desc>
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#7384b7"/>
+    </marker>
+    <style>
+      .font{font-family:Arial,Helvetica,sans-serif}.h{fill:#fff;font-size:24px;font-weight:700}.icon{fill:#fff;font-size:32px;font-weight:700}.laneText{fill:#17213a;font-size:14px}.node{fill:#fff;stroke:#8ea0d4;stroke-width:2}.start{fill:#28208b;stroke:#8ea0d4;stroke-width:2}.process{fill:#6876e8;stroke:#8ea0d4;stroke-width:2}.process2{fill:#5b9df0;stroke:#8ea0d4;stroke-width:2}.end{fill:#0966d8;stroke:#7fb3ff;stroke-width:2}.txt{fill:#fff;font-size:14px}.small{fill:#2b3556;font-size:12px}.edge{fill:none;stroke:#9aabd8;stroke-width:2;marker-end:url(#arrow)}.lbl{fill:#8c9ccb;font-size:16px}
+    </style>
+  </defs>
+  <rect x="34" y="34" width="1112" height="650" fill="#eaf0fb"/>
+  <g class="font">
+    <g>
+      <rect x="34" y="34" width="222" height="126" fill="#28208b"/>
+      <rect x="256" y="34" width="222" height="126" fill="#3e45bd"/>
+      <rect x="478" y="34" width="222" height="126" fill="#787ee8"/>
+      <rect x="700" y="34" width="222" height="126" fill="#62a2ef"/>
+      <rect x="922" y="34" width="224" height="126" fill="#0966d8"/>
+      <path d="M256 34V684M478 34V684M700 34V684M922 34V684" stroke="#fff" stroke-width="3"/>
+      <text class="icon" x="120" y="83" text-anchor="middle">+</text><text class="h" x="145" y="124" text-anchor="middle">Client</text>
+      <text class="icon" x="367" y="83" text-anchor="middle">$</text><text class="h" x="367" y="124" text-anchor="middle">Sales</text>
+      <text class="icon" x="589" y="83" text-anchor="middle">#</text><text class="h" x="589" y="124" text-anchor="middle">Contracts</text>
+      <text class="icon" x="811" y="83" text-anchor="middle">*</text><text class="h" x="811" y="124" text-anchor="middle">Construction</text>
+      <text class="icon" x="1034" y="83" text-anchor="middle">✓</text><text class="h" x="1034" y="124" text-anchor="middle">Handover</text>
+    </g>
+    <g>
+      <rect class="start" x="72" y="184" width="142" height="68" rx="28"/>
+      <text class="txt" x="143" y="213" text-anchor="middle">Client</text><text class="txt" x="143" y="231" text-anchor="middle">submits PO</text>
+      <rect class="process" x="294" y="184" width="148" height="68"/>
+      <text class="txt" x="368" y="209" text-anchor="middle">Sales reviews</text><text class="txt" x="368" y="227" text-anchor="middle">costing</text>
+      <rect class="process" x="516" y="184" width="148" height="68"/>
+      <text class="txt" x="590" y="209" text-anchor="middle">Contracts</text><text class="txt" x="590" y="227" text-anchor="middle">review</text>
+      <path class="process" d="M590 288 L662 328 L590 368 L518 328 z"/>
+      <text class="txt" x="590" y="324" text-anchor="middle">Contract</text><text class="txt" x="590" y="342" text-anchor="middle">okay?</text>
+      <rect class="process" x="516" y="414" width="148" height="68"/>
+      <text class="txt" x="590" y="441" text-anchor="middle">Set mobilization</text><text class="txt" x="590" y="459" text-anchor="middle">date</text>
+      <rect class="process2" x="738" y="414" width="148" height="68"/>
+      <text class="txt" x="812" y="441" text-anchor="middle">Construction</text><text class="txt" x="812" y="459" text-anchor="middle">starts</text>
+      <path class="process2" d="M812 526 L884 566 L812 606 L740 566 z"/>
+      <text class="txt" x="812" y="562" text-anchor="middle">Terms</text><text class="txt" x="812" y="580" text-anchor="middle">accepted?</text>
+      <rect class="process2" x="738" y="636" width="148" height="68"/>
+      <text class="txt" x="812" y="663" text-anchor="middle">Return files to</text><text class="txt" x="812" y="681" text-anchor="middle">contractor</text>
+      <rect class="process" x="516" y="636" width="148" height="68"/>
+      <text class="txt" x="590" y="663" text-anchor="middle">Completion date</text><text class="txt" x="590" y="681" text-anchor="middle">delayed</text>
+      <rect class="process" x="516" y="526" width="148" height="68"/>
+      <text class="txt" x="590" y="553" text-anchor="middle">Complete</text><text class="txt" x="590" y="571" text-anchor="middle">requirements</text>
+      <rect class="process2" x="960" y="414" width="148" height="68"/>
+      <text class="txt" x="1034" y="441" text-anchor="middle">Construction</text><text class="txt" x="1034" y="459" text-anchor="middle">finished</text>
+      <rect class="end" x="960" y="540" width="148" height="68" rx="28"/>
+      <text class="txt" x="1034" y="567" text-anchor="middle">Project handed</text><text class="txt" x="1034" y="585" text-anchor="middle">over</text>
+    </g>
+    <path class="edge" d="M214 218H294"/>
+    <path class="edge" d="M442 218H516"/>
+    <path class="edge" d="M590 252V288"/>
+    <path class="edge" d="M590 368V414"/>
+    <text class="lbl" x="606" y="393">Yes</text>
+    <path class="edge" d="M518 328H494V560H516"/>
+    <text class="lbl" x="486" y="394">No</text>
+    <path class="edge" d="M664 448H738"/>
+    <path class="edge" d="M812 482V526"/>
+    <path class="edge" d="M884 566H922V670H886"/>
+    <text class="lbl" x="902" y="618">No</text>
+    <path class="edge" d="M740 566H664"/>
+    <path class="edge" d="M738 670H664"/>
+    <path class="edge" d="M886 448H960"/>
+    <path class="edge" d="M1034 482V540"/>
+    <text class="small" x="70" y="730" font-size="22" font-weight="700">Swimlane Activity Diagram</text>
+  </g>
+</svg>

package/docs/diagrams/experiments/swimlane/experiment.md

@@ -0,0 +1,50 @@
+# Swimlane Diagram Experiment
+
+Task: DIAGRAM-SWIMLANE-EXPERIMENT
+
+## Source Inventory
+
+- `swimline-1.png`: five vertical lanes with colored headers, role icons, light lane backgrounds, process rectangles, decision diamonds, start/end rounded nodes, and orthogonal arrows across lanes.
+- `Swimlane diagram - definitions, uses, examples.pdf`: long-form reference with swimlane illustrations; the useful visual pattern is a role-owned process flow with handoffs and decisions.
+- `Swimlane Diagrams for Presentations.pdf`: presentation-oriented variants for layout and spacing reference.
+
+## Element Contract
+
+- Audience: product/operations reviewer validating process ownership and handoffs.
+- Reading flow: left to right across departments, with retry paths returning to earlier lanes.
+- Lanes: Client, Sales, Contracts, Construction, Handover.
+- Nodes: start/end rounded pills, process rectangles, decision diamonds.
+- Connectors: orthogonal arrows, lane-crossing handoffs, labels only when they disambiguate decision branches.
+- Visual constraints: headers remain compact, lane bodies keep equal widths, arrows land on target edges, and decision branches avoid covering text.
+
+## Prompt Used
+
+Create an editable swimlane workflow diagram as SVG.
+
+Use five vertical lanes: Client, Sales, Contracts, Construction, and Handover.
+Each lane has a saturated blue/purple header with a simple white role icon and a
+light blue body. Place nodes on a clear left-to-right process path:
+
+1. Client submits PO.
+2. Sales reviews costing.
+3. Contracts reviews contract.
+4. Decision: Contract okay?
+5. If yes, set mobilization date, then Construction starts.
+6. Decision: Terms accepted?
+7. If yes, Construction finished, then Project handed over.
+8. If no, Construction returns files to contractor and Completion date delayed.
+9. If contract is not okay, complete requirements and return into the same review path.
+
+Use rounded start/end nodes, rectangular process nodes, and diamond decisions.
+Use orthogonal connectors only. Avoid diagonal connectors. Route arrows outside
+node interiors. Add branch labels with at least 10px clearance from lines and
+containers. After rendering, re-evaluate lane width, node text fit, connector
+landing points, and unused whitespace.
+
+## Evaluation Findings
+
+- Swimlane references need explicit lane ownership and equal lane sizing; otherwise the flow becomes a generic process diagram.
+- Decision labels are the highest-risk element because they can collide with vertical handoff lines.
+- Icons are decorative but useful as first-scan lane identifiers; they should not drive layout.
+- The generated SVG is readable, but a future high-fidelity pass should add a legend only when shape meaning is not obvious.
+

package/docs/diagrams/experiments/timeline/diagram.mmd

@@ -0,0 +1,9 @@
+timeline
+  title Business Process Timeline
+  Discover : Collect goals and current-state pain
+  Map : Identify actors, systems, and flow
+  Design : Define target experience
+  Build : Implement the approved slice
+  Validate : Test against acceptance criteria
+  Launch : Release and monitor adoption
+

package/docs/diagrams/experiments/timeline/diagram.svg

@@ -0,0 +1,29 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1180" height="620" viewBox="0 0 1180 620" role="img" aria-labelledby="title desc">
+  <title id="title">Timeline infographic experiment</title>
+  <desc id="desc">Six-step alternating process timeline with numbered circular milestones.</desc>
+  <defs>
+    <style>
+      .font{font-family:Arial,Helvetica,sans-serif}.title{fill:#263238;font-size:30px;font-weight:700;letter-spacing:0}.sub{fill:#607d8b;font-size:14px}.line{stroke:#8fa1b5;stroke-width:5;stroke-linecap:round}.stem{stroke:#b6c1ce;stroke-width:2}.card{fill:#fff;stroke:#d5dde8;stroke-width:1.5}.cardTitle{fill:#253044;font-size:16px;font-weight:700}.body{fill:#526174;font-size:12px}.num{fill:#fff;font-size:18px;font-weight:700}.icon{fill:#fff;font-size:22px;font-weight:700}
+    </style>
+  </defs>
+  <rect width="1180" height="620" fill="#fbfcfe"/>
+  <g class="font">
+    <text class="title" x="590" y="64" text-anchor="middle">Business Process Timeline</text>
+    <text class="sub" x="590" y="92" text-anchor="middle">Six staged milestones with alternating annotations and balanced spacing.</text>
+    <path class="line" d="M110 316H1070"/>
+    <g>
+      <path class="stem" d="M130 316V172"/><rect class="card" x="60" y="112" width="140" height="96" rx="8"/><text class="cardTitle" x="130" y="142" text-anchor="middle">Discover</text><text class="body" x="130" y="166" text-anchor="middle">Collect goals and</text><text class="body" x="130" y="184" text-anchor="middle">current-state pain.</text>
+      <circle cx="130" cy="316" r="34" fill="#ff6d00"/><text class="num" x="130" y="323" text-anchor="middle">01</text>
+      <path class="stem" d="M314 316V458"/><rect class="card" x="244" y="414" width="140" height="96" rx="8"/><text class="cardTitle" x="314" y="444" text-anchor="middle">Map</text><text class="body" x="314" y="468" text-anchor="middle">Identify actors,</text><text class="body" x="314" y="486" text-anchor="middle">systems, and flow.</text>
+      <circle cx="314" cy="316" r="34" fill="#00a6a6"/><text class="num" x="314" y="323" text-anchor="middle">02</text>
+      <path class="stem" d="M498 316V172"/><rect class="card" x="428" y="112" width="140" height="96" rx="8"/><text class="cardTitle" x="498" y="142" text-anchor="middle">Design</text><text class="body" x="498" y="166" text-anchor="middle">Define target</text><text class="body" x="498" y="184" text-anchor="middle">experience.</text>
+      <circle cx="498" cy="316" r="34" fill="#2f80ed"/><text class="num" x="498" y="323" text-anchor="middle">03</text>
+      <path class="stem" d="M682 316V458"/><rect class="card" x="612" y="414" width="140" height="96" rx="8"/><text class="cardTitle" x="682" y="444" text-anchor="middle">Build</text><text class="body" x="682" y="468" text-anchor="middle">Implement the</text><text class="body" x="682" y="486" text-anchor="middle">approved slice.</text>
+      <circle cx="682" cy="316" r="34" fill="#172b4d"/><text class="num" x="682" y="323" text-anchor="middle">04</text>
+      <path class="stem" d="M866 316V172"/><rect class="card" x="796" y="112" width="140" height="96" rx="8"/><text class="cardTitle" x="866" y="142" text-anchor="middle">Validate</text><text class="body" x="866" y="166" text-anchor="middle">Test against</text><text class="body" x="866" y="184" text-anchor="middle">acceptance criteria.</text>
+      <circle cx="866" cy="316" r="34" fill="#2e7d32"/><text class="num" x="866" y="323" text-anchor="middle">05</text>
+      <path class="stem" d="M1050 316V458"/><rect class="card" x="980" y="414" width="140" height="96" rx="8"/><text class="cardTitle" x="1050" y="444" text-anchor="middle">Launch</text><text class="body" x="1050" y="468" text-anchor="middle">Release and</text><text class="body" x="1050" y="486" text-anchor="middle">monitor adoption.</text>
+      <circle cx="1050" cy="316" r="34" fill="#6a1b9a"/><text class="num" x="1050" y="323" text-anchor="middle">06</text>
+    </g>
+  </g>
+</svg>

package/docs/diagrams/experiments/timeline/experiment.md

@@ -0,0 +1,34 @@
+# Timeline Infographic Diagram Experiment
+
+Task: DIAGRAM-TIMELINE-EXPERIMENT
+
+## Source Inventory
+
+- Three downloaded timeline/process infographic PDFs from Vecteezy. The converted pages mostly include site chrome, but the visible previews show horizontal timeline patterns, circular milestones, icon markers, and alternating annotation blocks.
+
+## Element Contract
+
+- Audience: business presentation reviewer scanning a staged process.
+- Reading flow: left to right along a single horizontal spine.
+- Nodes: six milestones with numbered circular markers.
+- Annotations: alternating above and below the spine to reduce crowding.
+- Visual constraints: milestone labels must not sit on the line, icons must be centered, and connector stems must be vertical.
+
+## Prompt Used
+
+Create a clean six-step process timeline infographic as SVG.
+
+Use a horizontal spine across the center with six evenly spaced circular markers.
+Alternate annotation cards above and below the line. Each marker has a number,
+short title, icon placeholder, and two-line description. Use a mixed palette
+instead of one hue: orange, teal, blue, navy, green, and violet. Keep all text
+inside cards. Re-evaluate marker spacing, card text fit, and stem clearance
+after rendering.
+
+## Evaluation Findings
+
+- Timeline references often include website chrome in downloaded PDFs; the prompt must identify the actual diagram region before copying page structure.
+- Alternating cards reduce vertical whitespace but require strict stem alignment.
+- Numbered circles and icons should be separated; otherwise the marker becomes visually noisy.
+- For future rules, add a source-region extraction step before diagram generation when the PDF is a web download rather than a direct asset.
+

package/docs/diagrams/final-artifact-hygiene.md

@@ -0,0 +1,40 @@
+# Diagram Final Artifact Hygiene
+
+Use this checklist before handing off a diagram as final.
+
+## Keep In Final Delivery
+
+- Accepted editable source: `.drawio`, `.mmd`, source `.svg`, or equivalent.
+- Accepted rendered output: `.svg`, `.png`, `.pdf`, or the format requested by
+  the user.
+- Prompt master or final prompt when it adds reusable traceability.
+- Final QA evidence: rendered screenshot, source comparison report for
+  recreations, lint output, or visual review checklist.
+- Short handoff note with accepted artifact paths and known residual risks.
+
+## Archive Or Exclude
+
+- Preview iterations such as `preview-v1.png`, `preview-v2.png`, failed renders,
+  temporary exported images, and superseded SVGs.
+- Incremental prompts that were consolidated into a prompt master.
+- One-off visual correction notes that are not reusable rules.
+- Source-specific PDF/page text that should not enter the reusable prompt bank.
+
+## Archive Rules
+
+- Keep audit-relevant iterations in workflow evidence, an explicit archive
+  folder, or an ignored output path.
+- Do not package or present archived iterations as final deliverables.
+- If the user asks for traceability, link to the archive/evidence from the
+  handoff instead of mixing intermediate artifacts into the final folder.
+- If a prompt delta becomes reusable, rewrite it as a source-free rule before
+  promoting it to the prompt bank.
+
+## QA Checklist
+
+- Final source and final render are geometrically equivalent.
+- Final render passes whole-canvas visual review.
+- Intermediate artifacts are removed from the final delivery path or clearly
+  archived.
+- Prompt bank candidates are source-free, reusable, and validated.
+- Handoff lists only accepted artifact paths plus evidence paths.

package/docs/diagrams/mermaid-target-strategy.md

@@ -0,0 +1,106 @@
+# Mermaid Target Strategy
+
+Task: DIAGRAM-MERMAID-TARGET-STRATEGY
+Date: 2026-05-16
+
+## Position
+
+Mermaid should be supported as the default semantic diagram target for docs,
+architecture notes, pull requests, and offline agent evidence. It is not the
+right target for high-fidelity recreation of PDF, Lucid, or presentation assets
+where exact geometry, icon placement, connector routing, line jumps, or manual
+label positioning matter.
+
+When the user asks for a recreation, the acceptance target is pixel-perfect
+source fidelity unless they explicitly accept an approximation. In that mode,
+Mermaid can be used only as a semantic companion artifact; it is not the
+authoritative recreation target.
+
+Use this target order:
+
+1. Mermaid first when the goal is explainability, reviewability, markdown-native
+   documentation, or fast validation.
+2. draw.io XML when the goal is editable high-fidelity layout, controlled
+   connector anchors, bend points, line jumps, rotated labels, and SVG parity.
+3. Lucid/Lucidspark when the goal is collaborative editing, stakeholder review,
+   live boards, or use of a visual tool already owned by the team.
+
+## Decision Matrix
+
+| Diagram family | Mermaid fit | Recommended Mermaid type | Escalate to draw.io/Lucid when |
+| --- | --- | --- | --- |
+| Swimlane workflow | Medium | `flowchart` with subgraphs | Equal lane sizing, exact header styling, lane icons, or complex retry routing are required. |
+| Technology roadmap | Medium | `gantt` | Cards must be staggered freely, include component icon legends, or align to a branded roadmap template. |
+| Timeline infographic | Medium-high | `timeline` or `flowchart` | The visual is a presentation infographic with alternating cards, decorative icons, or precise spacing. |
+| Layered enterprise architecture | Medium | `flowchart` with subgraphs | The diagram has many system cards, badges, layer rails, dense integration lines, or needs pixel-level readability. |
+| UML state machine | High for semantics, low for recreation | `stateDiagram-v2` | The task is to recreate a reference diagram with exact arrows, labels, internal actions, history markers, or line crossings. |
+| Sequence/integration | High | `sequenceDiagram` | Stakeholder-facing visual branding or custom swimlanes are required. |
+| Data model | High | `erDiagram` | Crow's-foot styling, domain colors, or physical layout are part of the deliverable. |
+
+## Mermaid Implementation Rules
+
+- Classify the work before authoring:
+  - `semantic`: explain the idea; Mermaid is usually enough.
+  - `inspired-by-reference`: borrow structure/style; Mermaid may be enough if
+    visual fidelity is not acceptance criteria.
+  - `recreation`: reproduce the source; use draw.io/Lucid as the authoritative
+    target and validate pixel-perfect gaps.
+- Start from a diagram contract: purpose, audience, required elements, grouping,
+  relationships, reading flow, and validation criteria.
+- Preserve semantics over visual fidelity. If Mermaid cannot express exact
+  placement, document the approximation.
+- Prefer native Mermaid types:
+  - `flowchart` for workflows, swimlanes, layered architecture, component maps.
+  - `gantt` for roadmaps with actual dates.
+  - `timeline` for milestone narratives.
+  - `stateDiagram-v2` for lifecycle/state logic.
+  - `sequenceDiagram` for integration order.
+  - `erDiagram` for entity relationships.
+- Keep labels short. Mermaid text wrapping is renderer-dependent.
+- Avoid depending on exact connector paths. Mermaid owns layout.
+- Use subgraphs as semantic groups, not as guaranteed layout containers.
+- Run Mermaid lint/render validation before publishing.
+- Capture residual gaps in the experiment or evidence file.
+
+## Escalation Rules
+
+Escalate from Mermaid to draw.io/Lucid when any of these are acceptance criteria:
+
+- source-reference fidelity, near-pixel recreation, or pixel-perfect recreation.
+- exact lane sizes, timeline card positions, or layer rails.
+- explicit connector anchors, bend counts, line jumps, or no-line-over-label guarantees.
+- rotated labels or non-horizontal text.
+- branded icon libraries, dense badges, or presentation-quality visual hierarchy.
+- manual stakeholder editing in a visual canvas.
+- rendering must match screenshots across tools, not only describe the architecture.
+
+## Validation Strategy
+
+For Mermaid:
+
+- validate syntax with `orchestra diagrams lint --file <diagram.mmd>`.
+- render to SVG where local Mermaid tooling is available.
+- visually inspect the rendered output for nonblank content, readable labels, and
+  grouping semantics.
+- document known loss versus the source SVG/draw.io/Lucid output.
+
+For draw.io/Lucid:
+
+- for recreation, compare source and output as a pixel-perfect review, not only
+  as a semantic review.
+- keep editable source and rendered SVG equivalent.
+- run post-render visual QA for text fit, connector endpoints, z-order, line
+  overlaps, and label clearance.
+- capture screenshots as evidence.
+
+## Experiment Mapping
+
+The recent SVG experiments now have Mermaid semantic counterparts:
+
+- `docs/diagrams/experiments/swimlane/diagram.mmd`
+- `docs/diagrams/experiments/roadmap/diagram.mmd`
+- `docs/diagrams/experiments/timeline/diagram.mmd`
+- `docs/diagrams/experiments/sfdc-implementation/diagram.mmd`
+
+These Mermaid files should be reviewed as semantic approximations, not visual
+replacements for the SVG experiments.