@jterrats/open-orchestra 1.0.1 → 1.0.3

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.

package/docs/diagrams/payment-gateway/architecture.md

@@ -0,0 +1,57 @@
+# Payment Gateway Architecture
+
+Task: ARCH-PAYMENT-GATEWAY-DIAGRAM
+
+## Source Mode
+
+`source-free`
+
+No visual source reference was provided. This diagram is validated against its
+own architecture contract and the current diagram quality rules.
+
+## Architecture Contract
+
+- Audience: architect, security, developer, QA, and release reviewers.
+- Required systems:
+  - Web interface for merchants, admins, and customers.
+  - APIs / middleware layer for payment orchestration.
+  - Payment gateway core service.
+  - Transaction database.
+  - Security layer.
+- Added supporting elements:
+  - Identity provider for authentication.
+  - WAF / API gateway for edge protection.
+  - Token vault / KMS for card tokenization and key management.
+  - Fraud/risk engine for transaction scoring.
+  - Audit log / monitoring for compliance and operations.
+  - External payment processor / card network.
+- Required relationships:
+  - Users access the web interface through edge security.
+  - Web interface calls APIs through the API gateway.
+  - Middleware orchestrates payment requests and routes them to the payment
+    gateway core.
+  - Gateway core stores transaction state in the database.
+  - Gateway core tokenizes sensitive payment data through token vault / KMS.
+  - Gateway core requests fraud/risk scoring before authorization.
+  - Gateway core sends authorization/capture/refund messages to the external
+    processor.
+  - Middleware and gateway core emit audit and operational events.
+- Visual requirements:
+  - Security controls are visually distinct and readable.
+  - API/middleware and core payment responsibilities are separated.
+  - Connectors are orthogonal, visibly attached, and do not cover text.
+  - Parent containers leave visible padding around child nodes.
+  - Empty whitespace is intentional and supports scan order.
+
+## Validation Notes
+
+- All requested systems are present.
+- The security layer is shown as a distinct trust/control band.
+- Connector labels sit in whitespace or on readable label backgrounds.
+- The first render was reviewed and adjusted for label lanes and connector
+  endpoint clarity before acceptance.
+- Preview `output/diagram-experiments/payment-gateway/preview-v6.png` is the
+  current visual candidate for review after applying prompt v14. The pass moved
+  competing labels into separate lanes, split and repositioned the long
+  application note, terminated `user traffic` at the Security Edge boundary, and
+  resized Security Controls so Audit / Monitoring remains fully contained.

package/docs/diagrams/payment-gateway/architecture.mmd

@@ -0,0 +1,39 @@
+flowchart LR
+  users["Users\nMerchants / Admins / Customers"]
+
+  subgraph edge["Security Edge"]
+    waf["WAF / API Gateway\nTLS, throttling, threat rules"]
+    idp["Identity Provider\nOIDC / MFA / service auth"]
+  end
+
+  subgraph app["Application Layer"]
+    web["Web Interface\ncheckout, admin, merchant portal"]
+    middleware["APIs / Middleware\norchestration, idempotency, routing"]
+    core["Payment Gateway Core\nauthorize, capture, refund"]
+  end
+
+  subgraph security["Security Controls"]
+    vault["Token Vault / KMS\ntokenization, keys, secrets"]
+    fraud["Fraud / Risk Engine\nscoring, rules, velocity checks"]
+    audit["Audit Log / Monitoring\nPCI evidence, traces, alerts"]
+  end
+
+  subgraph data["Data Layer"]
+    db["Transaction Database\norders, payments, ledger state"]
+  end
+
+  processor["External Processor / Card Network\nauthorization, settlement"]
+
+  users -->|"browser / API traffic"| waf
+  waf -->|"validated traffic"| web
+  waf -->|"API requests"| middleware
+  idp -->|"tokens / claims"| waf
+  web -->|"checkout + admin calls"| middleware
+  middleware -->|"payment commands"| core
+  core <-->|"transaction state"| db
+  core <-->|"tokenize / detokenize"| vault
+  core -->|"risk scoring"| fraud
+  fraud -->|"score + decision"| core
+  core <-->|"auth / capture / refund"| processor
+  middleware -->|"events + metrics"| audit
+  core -->|"payment events"| audit

package/docs/diagrams/payment-gateway/architecture.svg

@@ -0,0 +1,171 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1440" height="900" viewBox="0 0 1440 900" role="img" aria-labelledby="title desc">
+  <title id="title">Payment gateway architecture</title>
+  <desc id="desc">Architecture diagram showing users, security edge, web interface, APIs and middleware, payment gateway core, database, token vault, fraud engine, audit monitoring, and external processor.</desc>
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto">
+      <path d="M0 0 L10 5 L0 10 z" fill="#475569"/>
+    </marker>
+    <marker id="arrow-start" viewBox="0 0 10 10" refX="1" refY="5" markerWidth="8" markerHeight="8" orient="auto">
+      <path d="M10 0 L0 5 L10 10 z" fill="#475569"/>
+    </marker>
+    <style>
+      .font{font-family:Arial,Helvetica,sans-serif}
+      .title{font-size:28px;font-weight:700;fill:#172033}
+      .subtitle{font-size:13px;fill:#4b596c}
+      .boundary{fill:#f7fafc;stroke:#94a3b8;stroke-width:1.5}
+      .edgeBoundary{fill:#f3f8ff;stroke:#89a9d8;stroke-width:1.5}
+      .appBoundary{fill:#f8fbf7;stroke:#93bd9b;stroke-width:1.5}
+      .securityBoundary{fill:#fff7ed;stroke:#e7b274;stroke-width:1.5}
+      .dataBoundary{fill:#f8f5ff;stroke:#b7a5e8;stroke-width:1.5}
+      .externalBoundary{fill:#fff8f8;stroke:#dda2a2;stroke-width:1.5}
+      .label{font-size:13px;font-weight:700;fill:#526174;text-transform:uppercase}
+      .card{fill:#fff;stroke:#64748b;stroke-width:1.5}
+      .cardTitle{font-size:17px;font-weight:700;fill:#1f2a3d}
+      .cardSub{font-size:12px;fill:#445267}
+      .badge{font-size:11px;font-weight:700;fill:#fff}
+      .edge{fill:none;stroke:#475569;stroke-width:2;marker-end:url(#arrow)}
+      .edgeBoth{fill:none;stroke:#475569;stroke-width:2;marker-start:url(#arrow-start);marker-end:url(#arrow)}
+      .labelBg{fill:#fff;stroke:#d8dee8;stroke-width:1}
+      .edgeLabel{font-size:12px;fill:#263445}
+      .note{font-size:12px;fill:#506074}
+    </style>
+  </defs>
+  <rect width="1440" height="900" fill="#ffffff"/>
+  <g class="font">
+    <text class="title" x="56" y="58">Payment Gateway Architecture</text>
+    <text class="subtitle" x="56" y="82">Source-free architecture candidate generated for visual validation.</text>
+
+    <rect class="card" x="56" y="362" width="166" height="100" rx="12"/>
+    <circle cx="88" cy="396" r="17" fill="#334155"/>
+    <text class="badge" x="88" y="400" text-anchor="middle">U</text>
+    <text class="cardTitle" x="118" y="392">Users</text>
+    <text class="cardSub" x="78" y="424">Merchants / admins</text>
+    <text class="cardSub" x="78" y="444">customers</text>
+
+    <rect class="edgeBoundary" x="274" y="170" width="254" height="484" rx="18"/>
+    <text class="label" x="304" y="204">Security Edge</text>
+    <rect class="card" x="314" y="256" width="174" height="104" rx="12"/>
+    <circle cx="346" cy="290" r="17" fill="#2563eb"/>
+    <text class="badge" x="346" y="294" text-anchor="middle">GW</text>
+    <text class="cardTitle" x="374" y="286">WAF / API</text>
+    <text class="cardTitle" x="374" y="306">Gateway</text>
+    <text class="cardSub" x="336" y="334">TLS, throttling</text>
+    <text class="cardSub" x="336" y="352">threat rules</text>
+
+    <rect class="card" x="314" y="456" width="174" height="104" rx="12"/>
+    <circle cx="346" cy="490" r="17" fill="#4f46e5"/>
+    <text class="badge" x="346" y="494" text-anchor="middle">ID</text>
+    <text class="cardTitle" x="374" y="486">Identity</text>
+    <text class="cardTitle" x="374" y="506">Provider</text>
+    <text class="cardSub" x="336" y="534">OIDC / MFA</text>
+    <text class="cardSub" x="336" y="552">service auth</text>
+
+    <rect class="appBoundary" x="584" y="118" width="404" height="620" rx="18"/>
+    <text class="label" x="616" y="152">Application Layer</text>
+    <rect class="card" x="632" y="214" width="206" height="112" rx="12"/>
+    <circle cx="664" cy="248" r="17" fill="#059669"/>
+    <text class="badge" x="664" y="252" text-anchor="middle">WEB</text>
+    <text class="cardTitle" x="696" y="244">Web Interface</text>
+    <text class="cardSub" x="658" y="278">checkout, admin</text>
+    <text class="cardSub" x="658" y="298">merchant portal</text>
+
+    <rect class="card" x="632" y="394" width="206" height="118" rx="12"/>
+    <circle cx="664" cy="428" r="17" fill="#0f766e"/>
+    <text class="badge" x="664" y="432" text-anchor="middle">API</text>
+    <text class="cardTitle" x="696" y="424">APIs / Middleware</text>
+    <text class="cardSub" x="658" y="460">orchestration</text>
+    <text class="cardSub" x="658" y="480">idempotency + routing</text>
+
+    <rect class="card" x="632" y="586" width="206" height="112" rx="12"/>
+    <circle cx="664" cy="620" r="17" fill="#0ea5e9"/>
+    <text class="badge" x="664" y="624" text-anchor="middle">PAY</text>
+    <text class="cardTitle" x="696" y="616">Gateway Core</text>
+    <text class="cardSub" x="658" y="650">authorize, capture</text>
+    <text class="cardSub" x="658" y="670">refund</text>
+
+    <rect class="securityBoundary" x="1038" y="118" width="326" height="482" rx="18"/>
+    <text class="label" x="1070" y="152">Security Controls</text>
+    <rect class="card" x="1086" y="210" width="228" height="92" rx="12"/>
+    <circle cx="1118" cy="242" r="17" fill="#d97706"/>
+    <text class="badge" x="1118" y="246" text-anchor="middle">KMS</text>
+    <text class="cardTitle" x="1150" y="238">Token Vault / KMS</text>
+    <text class="cardSub" x="1110" y="272">tokenization, keys</text>
+    <text class="cardSub" x="1110" y="290">secrets</text>
+
+    <rect class="card" x="1086" y="348" width="228" height="92" rx="12"/>
+    <circle cx="1118" cy="380" r="17" fill="#dc2626"/>
+    <text class="badge" x="1118" y="384" text-anchor="middle">FR</text>
+    <text class="cardTitle" x="1150" y="376">Fraud / Risk</text>
+    <text class="cardTitle" x="1150" y="396">Engine</text>
+    <text class="cardSub" x="1110" y="424">scoring + rules</text>
+
+    <rect class="card" x="1086" y="486" width="228" height="92" rx="12"/>
+    <circle cx="1118" cy="518" r="17" fill="#7c3aed"/>
+    <text class="badge" x="1118" y="522" text-anchor="middle">AUD</text>
+    <text class="cardTitle" x="1150" y="514">Audit / Monitoring</text>
+    <text class="cardSub" x="1110" y="548">PCI evidence</text>
+    <text class="cardSub" x="1110" y="566">traces + alerts</text>
+
+    <rect class="dataBoundary" x="1038" y="620" width="326" height="160" rx="18"/>
+    <text class="label" x="1070" y="654">Data Layer</text>
+    <rect class="card" x="1086" y="680" width="228" height="78" rx="12"/>
+    <circle cx="1118" cy="712" r="17" fill="#6d28d9"/>
+    <text class="badge" x="1118" y="716" text-anchor="middle">DB</text>
+    <text class="cardTitle" x="1150" y="708">Transaction DB</text>
+    <text class="cardSub" x="1110" y="738">orders, payments, ledger</text>
+
+    <rect class="externalBoundary" x="1020" y="812" width="360" height="60" rx="18"/>
+    <text class="label" x="1048" y="848">External Processor / Card Network</text>
+
+    <path class="edge" d="M222 412 H274"/>
+    <rect class="labelBg" x="224" y="388" width="86" height="20" rx="4"/>
+    <text class="edgeLabel" x="232" y="402">user traffic</text>
+
+    <path class="edge" d="M488 308 H632"/>
+    <rect class="labelBg" x="518" y="284" width="106" height="20" rx="4"/>
+    <text class="edgeLabel" x="526" y="298">validated UI</text>
+
+    <path class="edge" d="M488 326 H560 Q584 326 584 453 H632"/>
+    <rect class="labelBg" x="510" y="350" width="86" height="20" rx="4"/>
+    <text class="edgeLabel" x="518" y="364">API calls</text>
+
+    <path class="edge" d="M401 456 V360"/>
+    <rect class="labelBg" x="414" y="400" width="90" height="20" rx="4"/>
+    <text class="edgeLabel" x="422" y="414">auth claims</text>
+
+    <path class="edge" d="M735 326 V394"/>
+    <rect class="labelBg" x="752" y="350" width="116" height="20" rx="4"/>
+    <text class="edgeLabel" x="760" y="364">checkout calls</text>
+
+    <path class="edge" d="M735 512 V586"/>
+    <rect class="labelBg" x="752" y="540" width="136" height="20" rx="4"/>
+    <text class="edgeLabel" x="760" y="554">payment command</text>
+
+    <path class="edgeBoth" d="M838 686 H960 Q1000 686 1000 718 H1086"/>
+    <rect class="labelBg" x="906" y="706" width="126" height="20" rx="4"/>
+    <text class="edgeLabel" x="914" y="720">transaction state</text>
+
+    <path class="edgeBoth" d="M838 620 H930 Q958 620 958 256 H1086"/>
+    <rect class="labelBg" x="850" y="586" width="130" height="20" rx="4"/>
+    <text class="edgeLabel" x="858" y="600">token operations</text>
+
+    <path class="edge" d="M838 648 H966 Q1000 648 1000 394 H1086"/>
+    <rect class="labelBg" x="908" y="366" width="88" height="20" rx="4"/>
+    <text class="edgeLabel" x="916" y="380">risk score</text>
+
+    <path class="edge" d="M838 666 H944 Q982 666 982 532 H1086"/>
+    <rect class="labelBg" x="986" y="556" width="110" height="20" rx="4"/>
+    <text class="edgeLabel" x="994" y="570">payment events</text>
+
+    <path class="edge" d="M838 453 H1010 Q1038 453 1038 532 H1086"/>
+    <rect class="labelBg" x="852" y="460" width="104" height="20" rx="4"/>
+    <text class="edgeLabel" x="860" y="474">API metrics</text>
+
+    <path class="edgeBoth" d="M735 698 V838 H1020"/>
+    <rect class="labelBg" x="782" y="816" width="168" height="20" rx="4"/>
+    <text class="edgeLabel" x="790" y="830">auth / capture / refund</text>
+
+    <text class="note" x="752" y="754">Application responsibilities are separated</text>
+    <text class="note" x="752" y="772">from security controls and persistent state.</text>
+  </g>
+</svg>

package/docs/diagrams/prompt-bank.md

@@ -0,0 +1,48 @@
+# Diagram Prompt Bank
+
+Use this index to decide which diagram-generation prompt assets should feed the
+master prompt and which should remain only as experiment history.
+
+## Keep In Prompt Bank
+
+- `diagram-master-prompt.md`: canonical source-free prompt for diagram
+  generation, target selection, layout reflow, connector routing, validation,
+  evidence, and final artifact hygiene.
+- `mermaid-target-strategy.md`: target-selection guidance for when Mermaid is
+  acceptable and when draw.io/Lucid-style editable geometry is needed.
+- `v14-stress-test/README.md` and `v14-stress-test/stress-test.svg`: source-free
+  validation fixture for checking whether the prompt rules catch bounded text,
+  label lanes, containment, and connector route problems.
+
+## Keep As Visual Examples, Not Prompt Rules
+
+- `enterprise-set/*.svg`: source-free diagram candidates useful for visual QA
+  practice. Do not copy their business labels into the master prompt.
+- `payment-gateway/*`: architecture example useful for visual regression checks.
+  Do not promote payment-domain wording into the master prompt.
+- `salesforce-integration/*`: architecture example useful for target-format
+  comparison. Do not promote platform-specific wording into the master prompt.
+
+## Keep As Experiment Archive Only
+
+- `state-uml-recreated.prompt.md` through `state-uml-recreated.prompt.v11.md`:
+  historical deltas from a specific recreation exercise. Extract only generic
+  rules already represented in v12/v14.
+- `state-uml-recreated.prompt.v12.md` and `state-uml-recreated.prompt.v14.md`:
+  reusable deltas that have been consolidated into `diagram-master-prompt.md`.
+  Keep them only as provenance until the master prompt is accepted.
+- `experiments/**/experiment.md` and `source-fidelity-review.md`: these contain
+  downloaded-source observations and PDF/page-specific analysis. Keep them for
+  traceability, but exclude their source text from the prompt bank.
+- `experiments/**/*.mmd` and `experiments/**/*.svg`: rendered experiment outputs.
+  Useful for manual comparison, not for master-prompt wording.
+
+## Promotion Criteria
+
+- Promote only rules that are domain-agnostic and apply to any diagram type.
+- Exclude source text, platform names, business labels, PDF wording, and
+  one-off coordinates from reusable prompt guidance.
+- A prompt-bank candidate must include a validation rule, not only a drawing
+  instruction.
+- If two regenerated versions preserve the same visual error, the rule is not
+  strong enough. Add a geometry-change requirement before keeping it.