wotann 0.5.0 → 0.5.39

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

@@ -0,0 +1,177 @@
+<!-- Source: https://github.com/SuperiorByteWorks-LLC/agent-project | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
+
+# Block Diagram
+
+> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
+
+**Syntax keyword:** `block-beta`
+**Best for:** System block composition, layered architectures, component topology where spatial layout matters
+**When NOT to use:** Process flows (use [Flowchart](flowchart.md)), infrastructure with cloud icons (use [Architecture](architecture.md))
+
+> ⚠️ **Accessibility:** Block diagrams do **not** support `accTitle`/`accDescr`. Always place a descriptive _italic_ Markdown paragraph directly above the code block.
+
+---
+
+## Exemplar Diagram
+
+_Block diagram showing a three-tier web application architecture from client-facing interfaces through application services to data storage, with emoji labels indicating component types:_
+
+```mermaid
+block-beta
+    columns 3
+
+    block:client:3
+        columns 3
+        browser["🌐 Browser"]
+        mobile["📱 Mobile App"]
+        cli["⌨️ CLI Tool"]
+    end
+
+    space:3
+
+    block:app:3
+        columns 3
+        api["🖥️ API Server"]
+        worker["⚙️ Worker"]
+        cache["⚡ Redis Cache"]
+    end
+
+    space:3
+
+    block:data:3
+        columns 2
+        db[("💾 PostgreSQL")]
+        storage["📦 Object Storage"]
+    end
+
+    browser --> api
+    mobile --> api
+    cli --> api
+    api --> worker
+    api --> cache
+    worker --> db
+    api --> db
+    worker --> storage
+```
+
+---
+
+## Tips
+
+- Use `columns N` to control the layout grid
+- Use `space:N` for empty cells (alignment/spacing)
+- Nest `block:name:span { ... }` for grouped sections
+- Connect blocks with `-->` arrows
+- Use **emoji in labels** `["🔧 Component"]` for visual distinction
+- Use cylinder `("text")` syntax for databases within blocks
+- Keep to **3–4 rows** with **3–4 columns** for readability
+- **Always** pair with a Markdown text description above for screen readers
+
+---
+
+## Template
+
+_Description of the system layers and how components connect:_
+
+```mermaid
+block-beta
+    columns 3
+
+    block:layer1:3
+        columns 3
+        comp_a["📋 Component A"]
+        comp_b["⚙️ Component B"]
+        comp_c["📦 Component C"]
+    end
+
+    space:3
+
+    block:layer2:3
+        columns 2
+        comp_d["💾 Component D"]
+        comp_e["🔧 Component E"]
+    end
+
+    comp_a --> comp_d
+    comp_b --> comp_d
+    comp_c --> comp_e
+```
+
+---
+
+## Complex Example
+
+_Enterprise platform architecture rendered as a 5-tier block diagram with 15 components. Each tier is a block group spanning the full width, with internal columns controlling component layout. Connections show the primary data flow paths between tiers:_
+
+```mermaid
+block-beta
+    columns 4
+
+    block:clients:4
+        columns 4
+        browser["🌐 Browser"]
+        mobile["📱 Mobile App"]
+        partner["🔌 Partner API"]
+        admin["🔐 Admin Console"]
+    end
+
+    space:4
+
+    block:gateway:4
+        columns 2
+        apigw["🌐 API **Gateway**"]
+        auth["🔐 Auth Service"]
+    end
+
+    space:4
+
+    block:services:4
+        columns 4
+        user_svc["👤 User Service"]
+        order_svc["📋 Order Service"]
+        product_svc["📦 Product Service"]
+        notify_svc["📤 Notification Service"]
+    end
+
+    space:4
+
+    block:data:4
+        columns 3
+        postgres[("💾 PostgreSQL")]
+        redis["⚡ Redis Cache"]
+        elastic["🔍 Elasticsearch"]
+    end
+
+    space:4
+
+    block:infra:4
+        columns 3
+        mq["📥 Message Queue"]
+        logs["📊 Log Aggregator"]
+        metrics["📊 Metrics Store"]
+    end
+
+    browser --> apigw
+    mobile --> apigw
+    partner --> apigw
+    admin --> auth
+    apigw --> auth
+    apigw --> user_svc
+    apigw --> order_svc
+    apigw --> product_svc
+    order_svc --> notify_svc
+    user_svc --> postgres
+    order_svc --> postgres
+    product_svc --> elastic
+    order_svc --> redis
+    notify_svc --> mq
+    order_svc --> mq
+    mq --> logs
+```
+
+### Why this works
+
+- **5 tiers read top-to-bottom** like a network diagram — clients, gateway, services, data, infrastructure. Each tier is a block spanning the full width with its own column layout.
+- **`space:4` creates visual separation** between tiers without unnecessary lines or borders, keeping the diagram clean and scannable.
+- **Cylinder syntax `("text")` for databases** — PostgreSQL renders as a cylinder, instantly recognizable as a data store. Other components use standard rectangles.
+- **Connections show real data paths** — not every possible connection, just the primary flows. A fully-connected diagram would be unreadable; this shows the key paths an engineer would trace during debugging.

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

@@ -0,0 +1,136 @@
+<!-- Source: https://github.com/SuperiorByteWorks-LLC/agent-project | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
+
+# C4 Diagram
+
+> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
+
+**Syntax keyword:** `C4Context`, `C4Container`, `C4Component`
+**Best for:** System architecture at varying zoom levels — context, containers, components
+**When NOT to use:** Infrastructure topology (use [Architecture](architecture.md)), runtime sequences (use [Sequence](sequence.md))
+
+---
+
+## Exemplar Diagram — System Context
+
+```mermaid
+C4Context
+    accTitle: Online Store System Context
+    accDescr: C4 context diagram showing how a customer interacts with the store and its external payment dependency
+
+    title Online Store - System Context
+
+    Person(customer, "Customer", "Places orders")
+    System(store, "Online Store", "Catalog and checkout")
+    System_Ext(payment, "Payment Provider", "Card processing")
+
+    Rel(customer, store, "Orders", "HTTPS")
+    Rel(store, payment, "Pays", "API")
+
+    UpdateRelStyle(customer, store, $offsetY="-40", $offsetX="-30")
+    UpdateRelStyle(store, payment, $offsetY="-40", $offsetX="-30")
+```
+
+---
+
+## C4 Zoom Levels
+
+| Level         | Keyword       | Shows                                   | Audience        |
+| ------------- | ------------- | --------------------------------------- | --------------- |
+| **Context**   | `C4Context`   | Systems + external actors               | Everyone        |
+| **Container** | `C4Container` | Apps, databases, queues within a system | Technical leads |
+| **Component** | `C4Component` | Internal modules within a container     | Developers      |
+
+## Tips
+
+- Use `Person()` for human actors
+- Use `System()` for internal systems, `System_Ext()` for external
+- Use `Container()`, `ContainerDb()`, `ContainerQueue()` at the container level
+- Label relationships with **verbs** and **protocols**: `"Reads from", "SQL/TLS"`
+- Use `Container_Boundary(id, "name") { ... }` to group containers
+- **Keep descriptions short** — long text causes label overlaps
+- **Limit to 4–5 elements** at the Context level to avoid crowding
+- **Avoid emoji in C4 labels** — the C4 renderer handles its own styling
+- Use `UpdateRelStyle()` to adjust label positions if overlaps occur
+
+---
+
+## Template
+
+```mermaid
+C4Context
+    accTitle: Your System Context
+    accDescr: Describe the system boundaries and external interactions
+
+    Person(user, "User", "Role description")
+
+    System(main_system, "Your System", "What it does")
+    System_Ext(external, "External Service", "What it provides")
+
+    Rel(user, main_system, "Uses", "HTTPS")
+    Rel(main_system, external, "Calls", "API")
+```
+
+---
+
+## Complex Example
+
+A C4 Container diagram for an e-commerce platform with 3 `Container_Boundary` groups, 10 containers, and 2 external systems. Shows how to use boundaries to organize services by layer, with `UpdateRelStyle` offsets preventing label overlaps.
+
+```mermaid
+C4Container
+    accTitle: E-Commerce Platform Container View
+    accDescr: C4 container diagram showing web and mobile frontends, core backend services, and data stores with external payment and email dependencies
+
+    Person(customer, "Customer", "Shops online")
+
+    Container_Boundary(frontend, "Frontend") {
+        Container(spa, "Web App", "React", "Single-page app")
+        Container(bff, "BFF API", "Node.js", "Backend for frontend")
+    }
+
+    Container_Boundary(services, "Core Services") {
+        Container(order_svc, "Order Service", "Go", "Order processing")
+        Container(catalog_svc, "Product Catalog", "Go", "Product data")
+        Container(user_svc, "User Service", "Go", "Auth and profiles")
+    }
+
+    Container_Boundary(data, "Data Layer") {
+        ContainerDb(pg, "PostgreSQL", "SQL", "Primary data store")
+        ContainerDb(redis, "Redis", "Cache", "Session and cache")
+        ContainerDb(search, "Elasticsearch", "Search", "Product search")
+    }
+
+    System_Ext(payment_gw, "Payment Gateway", "Card processing")
+    System_Ext(email_svc, "Email Service", "Transactional email")
+
+    Rel(customer, spa, "Browses", "HTTPS")
+    Rel(spa, bff, "Calls", "GraphQL")
+    Rel(bff, order_svc, "Places orders", "gRPC")
+    Rel(bff, catalog_svc, "Queries", "gRPC")
+    Rel(bff, user_svc, "Authenticates", "gRPC")
+    Rel(order_svc, pg, "Reads/writes", "SQL")
+    Rel(order_svc, payment_gw, "Charges", "API")
+    Rel(order_svc, email_svc, "Sends", "SMTP")
+    Rel(catalog_svc, search, "Indexes", "REST")
+    Rel(user_svc, redis, "Sessions", "TCP")
+    Rel(catalog_svc, pg, "Reads", "SQL")
+
+    UpdateRelStyle(customer, spa, $offsetY="-40", $offsetX="-50")
+    UpdateRelStyle(spa, bff, $offsetY="-30", $offsetX="10")
+    UpdateRelStyle(bff, order_svc, $offsetY="-30", $offsetX="-40")
+    UpdateRelStyle(bff, catalog_svc, $offsetY="-30", $offsetX="10")
+    UpdateRelStyle(bff, user_svc, $offsetY="-30", $offsetX="50")
+    UpdateRelStyle(order_svc, pg, $offsetY="-30", $offsetX="-50")
+    UpdateRelStyle(order_svc, payment_gw, $offsetY="-30", $offsetX="10")
+    UpdateRelStyle(order_svc, email_svc, $offsetY="10", $offsetX="10")
+    UpdateRelStyle(catalog_svc, search, $offsetY="-30", $offsetX="10")
+    UpdateRelStyle(user_svc, redis, $offsetY="-30", $offsetX="10")
+    UpdateRelStyle(catalog_svc, pg, $offsetY="10", $offsetX="30")
+```
+
+### Why this works
+
+- **Container_Boundary groups map to deployment units** — frontend, core services, and data layer each correspond to real infrastructure boundaries (CDN, Kubernetes namespace, managed databases)
+- **Every `Rel` has `UpdateRelStyle`** — C4's auto-layout stacks labels on top of each other by default. Offset every relationship to prevent overlaps, even if it seems fine at first (adding elements later will shift things)
+- **Descriptions are kept to 1-3 words** — "Card processing", "Session and cache", "Auth and profiles". Long descriptions are the #1 cause of C4 rendering issues
+- **Container types are semantic** — `ContainerDb` for databases gives them the cylinder icon, `Container` for services. The C4 renderer provides its own visual differentiation

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

@@ -0,0 +1,246 @@
+<!-- Source: https://github.com/SuperiorByteWorks-LLC/agent-project | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
+
+# Class Diagram
+
+> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
+
+**Syntax keyword:** `classDiagram`
+**Best for:** Object-oriented design, type hierarchies, interface contracts, domain models
+**When NOT to use:** Database schemas (use [ER](er.md)), runtime behavior (use [Sequence](sequence.md))
+
+---
+
+## Exemplar Diagram
+
+```mermaid
+classDiagram
+    accTitle: Payment Processing Class Hierarchy
+    accDescr: Interface and abstract base class with two concrete implementations for credit card and digital wallet payment processing
+
+    class PaymentProcessor {
+        <<interface>>
+        +processPayment(amount) bool
+        +refund(transactionId) bool
+        +getStatus(transactionId) string
+    }
+
+    class BaseProcessor {
+        <<abstract>>
+        #apiKey: string
+        #timeout: int
+        +validateAmount(amount) bool
+        #logTransaction(tx) void
+    }
+
+    class CreditCardProcessor {
+        -gateway: string
+        +processPayment(amount) bool
+        +refund(transactionId) bool
+        -tokenizeCard(card) string
+    }
+
+    class DigitalWalletProcessor {
+        -provider: string
+        +processPayment(amount) bool
+        +refund(transactionId) bool
+        -initiateHandshake() void
+    }
+
+    PaymentProcessor <|.. BaseProcessor : implements
+    BaseProcessor <|-- CreditCardProcessor : extends
+    BaseProcessor <|-- DigitalWalletProcessor : extends
+
+    style PaymentProcessor fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
+    style BaseProcessor fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
+    style CreditCardProcessor fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
+    style DigitalWalletProcessor fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
+```
+
+---
+
+## Tips
+
+- Use `<<interface>>` and `<<abstract>>` stereotypes for clarity
+- Show visibility: `+` public, `-` private, `#` protected
+- Keep to **4–6 classes** per diagram — split larger hierarchies
+- Use `style ClassName fill:...,stroke:...,color:...` for light semantic coloring:
+  - 🟣 Purple for interfaces/abstractions
+  - 🔵 Blue for base/abstract classes
+  - 🟢 Green for concrete implementations
+- Relationship arrows:
+  - `<|--` inheritance (extends)
+  - `<|..` implementation (implements)
+  - `*--` composition · `o--` aggregation · `-->` dependency
+
+---
+
+## Template
+
+```mermaid
+classDiagram
+    accTitle: Your Title Here
+    accDescr: Describe the class hierarchy and the key relationships between types
+
+    class InterfaceName {
+        <<interface>>
+        +methodOne() ReturnType
+        +methodTwo(param) ReturnType
+    }
+
+    class ConcreteClass {
+        -privateField: Type
+        +methodOne() ReturnType
+        +methodTwo(param) ReturnType
+    }
+
+    InterfaceName <|.. ConcreteClass : implements
+```
+
+---
+
+## Complex Example
+
+An event-driven notification platform with 11 classes organized into 3 `namespace` groups — core orchestration, delivery channels, and data models. Shows interface implementation, composition, and dependency relationships across layers.
+
+```mermaid
+classDiagram
+    accTitle: Event-Driven Notification Platform
+    accDescr: Multi-namespace class hierarchy for a notification system showing core orchestration, four delivery channel implementations, and supporting data models with composition and dependency relationships
+
+    namespace Core {
+        class NotificationService {
+            -queue: NotificationQueue
+            -registry: ChannelRegistry
+            +dispatch(notification) bool
+            +scheduleDelivery(notification, time) void
+            +getDeliveryStatus(id) DeliveryStatus
+        }
+
+        class NotificationQueue {
+            -pending: List~Notification~
+            -maxRetries: int
+            +enqueue(notification) void
+            +dequeue() Notification
+            +retry(attempt) bool
+        }
+
+        class ChannelRegistry {
+            -channels: Map~string, Channel~
+            +register(name, channel) void
+            +resolve(type) Channel
+            +healthCheck() Map~string, bool~
+        }
+    }
+
+    namespace Channels {
+        class Channel {
+            <<interface>>
+            +send(notification, recipient) DeliveryAttempt
+            +getStatus(attemptId) DeliveryStatus
+            +validateRecipient(recipient) bool
+        }
+
+        class EmailChannel {
+            -smtpHost: string
+            -templateEngine: TemplateEngine
+            +send(notification, recipient) DeliveryAttempt
+            +getStatus(attemptId) DeliveryStatus
+            +validateRecipient(recipient) bool
+        }
+
+        class SMSChannel {
+            -provider: string
+            -rateLimit: int
+            +send(notification, recipient) DeliveryAttempt
+            +getStatus(attemptId) DeliveryStatus
+            +validateRecipient(recipient) bool
+        }
+
+        class PushChannel {
+            -firebaseKey: string
+            -apnsKey: string
+            +send(notification, recipient) DeliveryAttempt
+            +getStatus(attemptId) DeliveryStatus
+            +validateRecipient(recipient) bool
+        }
+
+        class WebhookChannel {
+            -signingSecret: string
+            -timeout: int
+            +send(notification, recipient) DeliveryAttempt
+            +getStatus(attemptId) DeliveryStatus
+            +validateRecipient(recipient) bool
+        }
+    }
+
+    namespace Models {
+        class Notification {
+            +id: uuid
+            +channel: string
+            +subject: string
+            +body: string
+            +priority: string
+            +createdAt: timestamp
+        }
+
+        class Recipient {
+            +id: uuid
+            +email: string
+            +phone: string
+            +deviceTokens: List~string~
+            +preferences: Map~string, bool~
+        }
+
+        class DeliveryAttempt {
+            +id: uuid
+            +notificationId: uuid
+            +recipientId: uuid
+            +status: DeliveryStatus
+            +attemptNumber: int
+            +sentAt: timestamp
+        }
+
+        class DeliveryStatus {
+            <<enumeration>>
+            QUEUED
+            SENDING
+            DELIVERED
+            FAILED
+            BOUNCED
+        }
+    }
+
+    NotificationService *-- NotificationQueue : contains
+    NotificationService *-- ChannelRegistry : contains
+    ChannelRegistry --> Channel : resolves
+
+    Channel <|.. EmailChannel : implements
+    Channel <|.. SMSChannel : implements
+    Channel <|.. PushChannel : implements
+    Channel <|.. WebhookChannel : implements
+
+    Channel ..> Notification : receives
+    Channel ..> Recipient : delivers to
+    Channel ..> DeliveryAttempt : produces
+
+    DeliveryAttempt --> DeliveryStatus : has
+
+    style Channel fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
+    style DeliveryStatus fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
+    style NotificationService fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
+    style NotificationQueue fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
+    style ChannelRegistry fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
+    style EmailChannel fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
+    style SMSChannel fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
+    style PushChannel fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
+    style WebhookChannel fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
+    style Notification fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#1f2937
+    style Recipient fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#1f2937
+    style DeliveryAttempt fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#1f2937
+```
+
+### Why this works
+
+- **3 namespaces mirror architectural layers** — Core (orchestration), Channels (delivery implementations), Models (data). A developer can scan one namespace without reading the others.
+- **Color encodes the role** — purple for interfaces/enums, blue for core services, green for concrete implementations, gray for data models. The pattern is instantly recognizable.
+- **Relationship types are deliberate** — composition (`*--`) for "owns and manages", implementation (`<|..`) for "fulfills contract", dependency (`..>`) for "uses at runtime". Each arrow type carries meaning.