wotann 0.5.0 → 0.5.39

package/skills/scientific/markdown-mermaid-writing/references/diagrams/quadrant.md

@@ -0,0 +1,66 @@
+<!-- Source: https://github.com/SuperiorByteWorks-LLC/agent-project | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
+
+# Quadrant Chart
+
+> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
+
+**Syntax keyword:** `quadrantChart`
+**Best for:** Prioritization matrices, risk assessment, two-axis comparisons, effort/impact analysis
+**When NOT to use:** Time-based data (use [Gantt](gantt.md) or [XY Chart](xy_chart.md)), simple rankings (use a table)
+
+> ⚠️ **Accessibility:** Quadrant charts do **not** support `accTitle`/`accDescr`. Always place a descriptive _italic_ Markdown paragraph directly above the code block.
+
+---
+
+## Exemplar Diagram
+
+_Priority matrix plotting engineering initiatives by effort required versus business impact, helping teams decide what to build next:_
+
+```mermaid
+quadrantChart
+    title 🎯 Engineering Priority Matrix
+    x-axis Low Effort --> High Effort
+    y-axis Low Impact --> High Impact
+    quadrant-1 Do First
+    quadrant-2 Plan Carefully
+    quadrant-3 Reconsider
+    quadrant-4 Quick Wins
+    Upgrade auth library: [0.3, 0.9]
+    Migrate to new DB: [0.9, 0.8]
+    Fix typos in docs: [0.1, 0.2]
+    Add dark mode: [0.4, 0.6]
+    Rewrite legacy API: [0.95, 0.95]
+    Update CI cache: [0.15, 0.5]
+    Add unit tests: [0.5, 0.7]
+```
+
+---
+
+## Tips
+
+- Label axes with `Low X --> High X` format
+- Name all four quadrants with **actionable** labels
+- Plot items as `Name: [x, y]` with values 0.0–1.0
+- Limit to **5–10 items** — more becomes cluttered
+- Quadrant numbering: 1=top-right, 2=top-left, 3=bottom-left, 4=bottom-right
+- **Always** pair with a Markdown text description above for screen readers
+
+---
+
+## Template
+
+_Description of the two axes and what the quadrant placement means:_
+
+```mermaid
+quadrantChart
+    title 🎯 Your Matrix Title
+    x-axis Low X Axis --> High X Axis
+    y-axis Low Y Axis --> High Y Axis
+    quadrant-1 High Both
+    quadrant-2 High Y Only
+    quadrant-3 Low Both
+    quadrant-4 High X Only
+    Item A: [0.3, 0.8]
+    Item B: [0.7, 0.6]
+    Item C: [0.2, 0.3]
+```

package/skills/scientific/markdown-mermaid-writing/references/diagrams/radar.md

@@ -0,0 +1,59 @@
+<!-- Source: https://github.com/SuperiorByteWorks-LLC/agent-project | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
+
+# Radar Chart
+
+> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
+
+**Syntax keyword:** `radar-beta`
+**Mermaid version:** v11.6.0+
+**Best for:** Multi-dimensional comparisons, skill assessments, performance profiles, competitive analysis
+**When NOT to use:** Time series data (use [XY Chart](xy_chart.md)), simple proportions (use [Pie](pie.md))
+
+> ⚠️ **Accessibility:** Radar charts do **not** support `accTitle`/`accDescr`. Always place a descriptive _italic_ Markdown paragraph directly above the code block.
+
+---
+
+## Exemplar Diagram
+
+_Radar chart comparing two engineering candidates across six core competency areas, showing complementary strengths:_
+
+```mermaid
+radar-beta
+    title Team Skill Assessment
+    axis sys["System Design"], algo["Algorithms"], comms["Communication"], team["Teamwork"], ops["DevOps"], acq["Domain Knowledge"]
+    curve candidate_a["Candidate A"]{4, 3, 5, 5, 2, 3}
+    curve candidate_b["Candidate B"]{2, 5, 3, 3, 5, 4}
+    max 5
+    graticule polygon
+    ticks 5
+    showLegend true
+```
+
+---
+
+## Tips
+
+- Define axes with `axis id["Label"]` — use short labels (1–2 words)
+- Define curves with `curve id["Label"]{val1, val2, ...}` matching axis order
+- Set `max` to normalize all values to the same scale
+- `graticule` options: `circle` (default) or `polygon`
+- `ticks` controls the number of concentric rings (default 5)
+- `showLegend true` adds a legend for multiple curves
+- Keep to **5–8 axes** and **2–4 curves** for readability
+- **Always** pair with a Markdown text description above for screen readers
+
+---
+
+## Template
+
+_Description of what dimensions are being compared across which entities:_
+
+```mermaid
+radar-beta
+    title Your Radar Title
+    axis dim1["Dimension 1"], dim2["Dimension 2"], dim3["Dimension 3"], dim4["Dimension 4"], dim5["Dimension 5"]
+    curve series_a["Series A"]{3, 4, 2, 5, 3}
+    curve series_b["Series B"]{5, 2, 4, 3, 4}
+    max 5
+    showLegend true
+```

package/skills/scientific/markdown-mermaid-writing/references/diagrams/requirement.md

@@ -0,0 +1,88 @@
+<!-- Source: https://github.com/SuperiorByteWorks-LLC/agent-project | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
+
+# Requirement Diagram
+
+> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
+
+**Syntax keyword:** `requirementDiagram`
+**Best for:** System requirements traceability, compliance mapping, formal requirements engineering
+**When NOT to use:** Informal task tracking (use [Kanban](kanban.md)), general relationships (use [ER](er.md))
+
+---
+
+## Exemplar Diagram
+
+```mermaid
+requirementDiagram
+
+    requirement high_availability {
+        id: 1
+        text: System shall maintain 99.9 percent uptime
+        risk: high
+        verifymethod: test
+    }
+
+    requirement data_encryption {
+        id: 2
+        text: All data at rest shall be AES-256 encrypted
+        risk: medium
+        verifymethod: inspection
+    }
+
+    requirement session_timeout {
+        id: 3
+        text: Sessions expire after 30 minutes idle
+        risk: low
+        verifymethod: test
+    }
+
+    element auth_service {
+        type: service
+        docref: auth-service-v2
+    }
+
+    element crypto_module {
+        type: module
+        docref: crypto-lib-v3
+    }
+
+    auth_service - satisfies -> high_availability
+    auth_service - satisfies -> session_timeout
+    crypto_module - satisfies -> data_encryption
+```
+
+---
+
+## Tips
+
+- Each requirement needs: `id`, `text`, `risk`, `verifymethod`
+- **`id` must be numeric** — use `id: 1`, `id: 2`, etc. (dashes like `REQ-001` can cause parse errors)
+- Risk levels: `low`, `medium`, `high` (all lowercase)
+- Verify methods: `analysis`, `inspection`, `test`, `demonstration` (all lowercase)
+- Use `element` for design components that satisfy requirements
+- Relationship types: `- satisfies ->`, `- traces ->`, `- contains ->`, `- derives ->`, `- refines ->`, `- copies ->`
+- Keep to **3–5 requirements** per diagram
+- Avoid special characters in text fields — spell out symbols (e.g., "99.9 percent" not "99.9%")
+- Use 4-space indentation inside `{ }` blocks
+
+---
+
+## Template
+
+```mermaid
+requirementDiagram
+
+    requirement your_requirement {
+        id: 1
+        text: The requirement statement here
+        risk: medium
+        verifymethod: test
+    }
+
+    element your_component {
+        type: service
+        docref: component-ref
+    }
+
+    your_component - satisfies -> your_requirement
+```

package/skills/scientific/markdown-mermaid-writing/references/diagrams/sankey.md

@@ -0,0 +1,71 @@
+<!-- Source: https://github.com/SuperiorByteWorks-LLC/agent-project | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
+
+# Sankey Diagram
+
+> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
+
+**Syntax keyword:** `sankey-beta`
+**Best for:** Flow magnitude visualization, resource distribution, budget allocation, traffic routing
+**When NOT to use:** Simple proportions (use [Pie](pie.md)), process steps (use [Flowchart](flowchart.md))
+
+> ⚠️ **Accessibility:** Sankey diagrams do **not** support `accTitle`/`accDescr`. Always place a descriptive _italic_ Markdown paragraph directly above the code block.
+
+---
+
+## Exemplar Diagram
+
+_Sankey diagram showing how a $100K monthly cloud budget flows from the total allocation through service categories (compute, storage, networking, observability) to specific AWS services, with band widths proportional to cost:_
+
+```mermaid
+sankey-beta
+
+Cloud Budget,Compute,45000
+Cloud Budget,Storage,25000
+Cloud Budget,Networking,15000
+Cloud Budget,Observability,10000
+Cloud Budget,Security,5000
+
+Compute,EC2 Instances,30000
+Compute,Lambda Functions,10000
+Compute,ECS Containers,5000
+
+Storage,S3 Buckets,15000
+Storage,RDS Databases,10000
+
+Networking,CloudFront CDN,8000
+Networking,API Gateway,7000
+
+Observability,CloudWatch,6000
+Observability,Datadog,4000
+```
+
+---
+
+## Tips
+
+- Format: `Source,Target,Value` — one flow per line
+- Values determine the width of each flow band
+- Keep to **3 levels** maximum (source → category → destination)
+- Blank lines between groups improve source readability
+- Good for answering "where does the 💰 go?" questions
+- No emoji in node names (parser limitation) — use descriptive text
+- **Always** pair with a Markdown text description above for screen readers
+
+---
+
+## Template
+
+_Description of what flows from where to where and what the magnitudes represent:_
+
+```mermaid
+sankey-beta
+
+Source,Category A,500
+Source,Category B,300
+Source,Category C,200
+
+Category A,Destination 1,300
+Category A,Destination 2,200
+
+Category B,Destination 3,300
+```

package/skills/scientific/markdown-mermaid-writing/references/diagrams/sequence.md

@@ -0,0 +1,174 @@
+<!-- Source: https://github.com/SuperiorByteWorks-LLC/agent-project | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
+
+# Sequence Diagram
+
+> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
+
+**Syntax keyword:** `sequenceDiagram`
+**Best for:** API interactions, temporal flows, multi-actor communication, request/response patterns
+**When NOT to use:** Simple linear processes (use [Flowchart](flowchart.md)), static relationships (use [Class](class.md) or [ER](er.md))
+
+---
+
+## Exemplar Diagram
+
+```mermaid
+sequenceDiagram
+    accTitle: OAuth 2.0 Authorization Code Flow
+    accDescr: Step-by-step OAuth flow between user browser, app server, and identity provider showing the token exchange and error path
+
+    participant U as 👤 User Browser
+    participant A as 🖥️ App Server
+    participant I as 🔐 Identity Provider
+
+    U->>A: Click Sign in
+    A-->>U: Redirect to IdP
+
+    U->>I: Enter credentials
+    I->>I: 🔍 Validate credentials
+
+    alt ✅ Valid credentials
+        I-->>U: Redirect with auth code
+        U->>A: Send auth code
+        A->>I: Exchange code for token
+        I-->>A: 🔐 Access + refresh token
+        A-->>U: ✅ Set session cookie
+        Note over U,A: 🔒 User is now authenticated
+    else ❌ Invalid credentials
+        I-->>U: ⚠️ Show error message
+    end
+```
+
+---
+
+## Tips
+
+- Limit to **4–5 participants** — more becomes unreadable
+- Solid arrows (`->>`) for requests, dashed (`-->>`) for responses
+- Use `alt/else/end` for conditional branches
+- Use `Note over X,Y:` for contextual annotations with emoji
+- Use `par/end` for parallel operations
+- Use `loop/end` for repeated interactions
+- Emoji in **message text** works great for status clarity (✅, ❌, ⚠️, 🔐)
+
+## Common Patterns
+
+**Parallel calls:**
+
+```
+par 📥 Fetch user
+    A->>B: GET /user
+and 📥 Fetch orders
+    A->>C: GET /orders
+end
+```
+
+**Loops:**
+
+```
+loop ⏰ Every 30 seconds
+    A->>B: Health check
+    B-->>A: ✅ 200 OK
+end
+```
+
+---
+
+## Template
+
+```mermaid
+sequenceDiagram
+    accTitle: Your Title Here
+    accDescr: Describe the interaction between participants and what the sequence demonstrates
+
+    participant A as 👤 Actor
+    participant B as 🖥️ System
+    participant C as 💾 Database
+
+    A->>B: 📤 Request action
+    B->>C: 🔍 Query data
+    C-->>B: 📥 Return results
+    B-->>A: ✅ Deliver response
+```
+
+---
+
+## Complex Example
+
+A microservices checkout flow with 6 participants grouped in `box` regions. Shows parallel calls, conditional branching, error handling with `break`, retry logic, and contextual notes — the full toolkit for complex sequences.
+
+```mermaid
+sequenceDiagram
+    accTitle: Microservices Checkout Flow
+    accDescr: Multi-service checkout sequence showing parallel inventory and payment processing, error recovery with retries, and async notification dispatch across client, gateway, and backend service layers
+
+    box rgb(237,233,254) 🌐 Client Layer
+        participant browser as 👤 Browser
+    end
+
+    box rgb(219,234,254) 🖥️ API Layer
+        participant gw as 🌐 API Gateway
+        participant order as 📋 Order Service
+    end
+
+    box rgb(220,252,231) ⚙️ Backend Services
+        participant inventory as 📦 Inventory
+        participant payment as 💰 Payment
+        participant notify as 📤 Notifications
+    end
+
+    browser->>gw: 🛒 Submit checkout
+    gw->>gw: 🔐 Validate JWT token
+    gw->>order: 📋 Create order
+
+    Note over order: 📊 Order status: PENDING
+
+    par ⚡ Parallel validation
+        order->>inventory: 📦 Reserve items
+        inventory-->>order: ✅ Items reserved
+    and
+        order->>payment: 💰 Authorize card
+        payment-->>order: ✅ Payment authorized
+    end
+
+    alt ✅ Both succeeded
+        order->>payment: 💰 Capture payment
+        payment-->>order: ✅ Payment captured
+        order->>inventory: 📦 Confirm reservation
+
+        Note over order: 📊 Order status: CONFIRMED
+
+        par 📤 Async notifications
+            order->>notify: 📧 Send confirmation email
+        and
+            order->>notify: 📱 Send push notification
+        end
+
+        order-->>gw: ✅ Order confirmed
+        gw-->>browser: ✅ Show confirmation page
+
+    else ❌ Inventory unavailable
+        order->>payment: 🔄 Void authorization
+        order-->>gw: ⚠️ Items out of stock
+        gw-->>browser: ⚠️ Show stock error
+
+    else ❌ Payment declined
+        order->>inventory: 🔄 Release reservation
+
+        loop 🔄 Retry up to 2 times
+            order->>payment: 💰 Retry authorization
+            payment-->>order: ❌ Still declined
+        end
+
+        order-->>gw: ❌ Payment failed
+        gw-->>browser: ❌ Show payment error
+    end
+```
+
+### Why this works
+
+- **`box` grouping** clusters participants by architectural layer — readers instantly see which services are client-facing vs backend
+- **`par` blocks** show parallel inventory + payment checks happening simultaneously, which is how real checkout systems work for performance
+- **Nested `alt`/`else`** covers the happy path AND two distinct failure modes, each with proper cleanup (void auth, release reservation)
+- **`loop` for retry logic** shows the payment retry pattern without cluttering the happy path
+- **Emoji in messages** makes scanning fast — 📦 for inventory, 💰 for payment, ✅/❌ for outcomes

package/skills/scientific/markdown-mermaid-writing/references/diagrams/state.md

@@ -0,0 +1,150 @@
+<!-- Source: https://github.com/SuperiorByteWorks-LLC/agent-project | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
+
+# State Diagram
+
+> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
+
+**Syntax keyword:** `stateDiagram-v2`
+**Best for:** State machines, lifecycle flows, status transitions, object lifecycles
+**When NOT to use:** Sequential processes with many steps (use [Flowchart](flowchart.md)), timing-critical interactions (use [Sequence](sequence.md))
+
+---
+
+## Exemplar Diagram
+
+```mermaid
+stateDiagram-v2
+    accTitle: Order Fulfillment Lifecycle
+    accDescr: State machine for an e-commerce order from placement through payment, fulfillment, and delivery with cancellation paths
+
+    [*] --> Placed: 📋 Customer submits
+
+    Placed --> PaymentPending: 💰 Initiate payment
+    PaymentPending --> PaymentFailed: ❌ Declined
+    PaymentPending --> Confirmed: ✅ Payment received
+
+    PaymentFailed --> Placed: 🔄 Retry payment
+    PaymentFailed --> Cancelled: 🚫 Customer cancels
+
+    Confirmed --> Picking: 📦 Warehouse picks
+    Picking --> Shipped: 🚚 Carrier collected
+    Shipped --> Delivered: ✅ Proof of delivery
+    Delivered --> [*]: 🏁 Complete
+
+    Cancelled --> [*]: 🏁 Closed
+
+    note right of Confirmed
+        📋 Inventory reserved
+        💰 Invoice generated
+    end note
+```
+
+---
+
+## Tips
+
+- Always start with `[*]` (initial state) and end with `[*]` (terminal)
+- Label transitions with **emoji + action** for visual clarity
+- Use `note right of` / `note left of` for contextual details
+- State names: `CamelCase` (Mermaid convention for state diagrams)
+- Use nested states sparingly: `state "name" as s1 { ... }`
+- Keep to **8–10 states** maximum
+
+---
+
+## Template
+
+```mermaid
+stateDiagram-v2
+    accTitle: Your Title Here
+    accDescr: Describe the entity lifecycle and key transitions between states
+
+    [*] --> InitialState: ⚡ Trigger event
+
+    InitialState --> ActiveState: ▶️ Action taken
+    ActiveState --> CompleteState: ✅ Success
+    ActiveState --> FailedState: ❌ Error
+
+    CompleteState --> [*]: 🏁 Done
+    FailedState --> [*]: 🏁 Closed
+```
+
+---
+
+## Complex Example
+
+A CI/CD pipeline modeled as a state machine with 3 composite (nested) states, each containing internal substates. Shows how source changes flow through build, test, and deploy phases with failure recovery and rollback transitions.
+
+```mermaid
+stateDiagram-v2
+    accTitle: CI/CD Pipeline State Machine
+    accDescr: Composite state diagram for a CI/CD pipeline showing source detection, build and test phases with parallel scanning, and a three-stage deployment with approval gate and rollback path
+
+    [*] --> Source: ⚡ Commit pushed
+
+    state "📥 Source" as Source {
+        [*] --> Idle
+        Idle --> Fetching: 🔄 Poll detected change
+        Fetching --> Validating: 📋 Checkout complete
+        Validating --> [*]: ✅ Config valid
+    }
+
+    Source --> Build: ⚙️ Pipeline triggered
+
+    state "🔧 Build & Test" as Build {
+        [*] --> Compiling
+        Compiling --> UnitTests: ✅ Build artifact ready
+        UnitTests --> IntegrationTests: ✅ Unit tests pass
+        IntegrationTests --> SecurityScan: ✅ Integration pass
+        SecurityScan --> [*]: ✅ No vulnerabilities
+
+        note right of Compiling
+            📦 Docker image built
+            🏷️ Tagged with commit SHA
+        end note
+    }
+
+    Build --> Deploy: 📦 Artifact published
+    Build --> Failed: ❌ Build or test failure
+
+    state "🚀 Deployment" as Deploy {
+        [*] --> Staging
+        Staging --> WaitApproval: ✅ Staging healthy
+        WaitApproval --> Production: ✅ Approved
+        WaitApproval --> Cancelled: 🚫 Rejected
+        Production --> Monitoring: 🚀 Deployed
+        Monitoring --> [*]: ✅ Stable 30 min
+
+        note right of WaitApproval
+            👤 Requires team lead approval
+            ⏰ Auto-reject after 24h
+        end note
+    }
+
+    Deploy --> Rollback: ❌ Health check failed
+    Rollback --> Deploy: 🔄 Revert to previous
+    Deploy --> Complete: 🏁 Pipeline finished
+    Failed --> Source: 🔧 Fix pushed
+    Cancelled --> [*]: 🏁 Pipeline aborted
+    Complete --> [*]: 🏁 Done
+
+    state Failed {
+        [*] --> AnalyzeFailure
+        AnalyzeFailure --> NotifyTeam: 📤 Alert sent
+        NotifyTeam --> [*]
+    }
+
+    state Rollback {
+        [*] --> RevertArtifact
+        RevertArtifact --> RestorePrevious: 🔄 Previous version
+        RestorePrevious --> VerifyRollback: 🔍 Health check
+        VerifyRollback --> [*]
+    }
+```
+
+### Why this works
+
+- **Composite states group pipeline phases** — Source, Build & Test, and Deployment each contain their internal flow, readable in isolation or as part of the whole
+- **Failure and rollback are first-class states** — not just transition labels. The Failed and Rollback states have their own internal substates showing what actually happens during recovery
+- **Notes on key states** add operational context — the approval gate has timeout rules, the compile step documents the artifact format. This is the kind of detail operators need.
+- **Transitions between composite states** are the high-level flow (Source → Build → Deploy → Complete), while transitions within composites are the detailed steps. Two levels of reading for two audiences.