@saibolla/ada 0.1.2

package/skills/markdown-mermaid-writing/references/diagrams/flowchart.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) -->
+
+# Flowchart
+
+> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
+
+**Syntax keyword:** `flowchart`
+**Best for:** Sequential processes, workflows, decision logic, troubleshooting trees
+**When NOT to use:** Complex timing between actors (use [Sequence](sequence.md)), state machines (use [State](state.md))
+
+---
+
+## Exemplar Diagram
+
+```mermaid
+flowchart TB
+    accTitle: Feature Development Lifecycle
+    accDescr: End-to-end feature flow from idea through design, build, test, review, and release with a revision loop on failed reviews
+
+    idea([💡 Feature idea]) --> spec[📋 Write spec]
+    spec --> design[🎨 Design solution]
+    design --> build[🔧 Implement]
+    build --> test[🧪 Run tests]
+    test --> review{🔍 Review passed?}
+    review -->|Yes| release[🚀 Release to prod]
+    review -->|No| revise[✏️ Revise code]
+    revise --> test
+    release --> monitor([📊 Monitor metrics])
+
+    classDef start fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
+    classDef process fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
+    classDef decision fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
+    classDef success fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
+
+    class idea,monitor start
+    class spec,design,build,test,revise process
+    class review decision
+    class release success
+```
+
+---
+
+## Tips
+
+- Use `TB` (top-to-bottom) for processes, `LR` (left-to-right) for pipelines
+- Rounded rectangles `([text])` for start/end, diamonds `{text}` for decisions
+- Max 10 nodes — split larger flows into "Phase 1" / "Phase 2" diagrams
+- Max 3 decision points per diagram
+- Edge labels should be 1–4 words: `-->|Yes|`, `-->|All green|`
+- Use `classDef` for **semantic** coloring — decisions in amber, success in green, actions in blue
+
+## Subgraph Pattern
+
+When you need grouped stages:
+
+```mermaid
+flowchart TB
+    accTitle: CI/CD Pipeline Stages
+    accDescr: Three-stage pipeline grouping code quality checks, testing, and deployment into distinct phases
+
+    trigger([⚡ Push to main])
+
+    subgraph quality ["🔍 Code Quality"]
+        lint[📝 Lint code] --> format[⚙️ Check formatting]
+    end
+
+    subgraph testing ["🧪 Testing"]
+        unit[🧪 Unit tests] --> integration[🔗 Integration tests]
+    end
+
+    subgraph deploy ["🚀 Deployment"]
+        build[📦 Build artifacts] --> ship[☁️ Deploy to staging]
+    end
+
+    trigger --> quality
+    quality --> testing
+    testing --> deploy
+    deploy --> done([✅ Pipeline complete])
+
+    classDef trigger_style fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
+    classDef success fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
+
+    class trigger trigger_style
+    class done success
+```
+
+---
+
+## Template
+
+```mermaid
+flowchart TB
+    accTitle: Your Title Here (3-8 words)
+    accDescr: One or two sentences explaining what this diagram shows and what insight the reader gains
+
+    start([🏁 Starting point]) --> step1[⚙️ First action]
+    step1 --> decision{🔍 Check condition?}
+    decision -->|Yes| step2[✅ Positive path]
+    decision -->|No| step3[🔧 Alternative path]
+    step2 --> done([🏁 Complete])
+    step3 --> done
+```
+
+---
+
+## Complex Example
+
+A 20+ node e-commerce order pipeline organized into 5 subgraphs, each representing a processing phase. Subgraphs connect through internal nodes, decision points route orders to exception handling, and color classes distinguish phases at a glance.
+
+```mermaid
+flowchart TB
+    accTitle: E-Commerce Order Processing Pipeline
+    accDescr: Full order lifecycle from intake through fulfillment, shipping, and notification with exception handling paths for payment failures, stockouts, and delivery issues
+
+    order_in([📥 New order]) --> validate_pay{💰 Payment valid?}
+
+    subgraph intake ["📥 Order Intake"]
+        validate_pay -->|Yes| check_fraud{🔐 Fraud check}
+        validate_pay -->|No| pay_fail[❌ Payment **declined**]
+        check_fraud -->|Clear| check_stock{📦 In stock?}
+        check_fraud -->|Flagged| manual_review[🔍 Manual **review**]
+        manual_review --> check_stock
+    end
+
+    subgraph fulfill ["📦 Fulfillment"]
+        pick[📋 **Pick** items] --> pack[📦 Pack order]
+        pack --> label[🏷️ Generate **shipping** label]
+    end
+
+    subgraph ship ["🚚 Shipping"]
+        handoff[🚚 Carrier **handoff**] --> transit[📍 In transit]
+        transit --> deliver{✅ Delivered?}
+    end
+
+    subgraph notify ["📤 Notifications"]
+        confirm_email[📧 Order **confirmed**]
+        ship_update[📧 Shipping **update**]
+        deliver_email[📧 Delivery **confirmed**]
+    end
+
+    subgraph exception ["⚠️ Exception Handling"]
+        pay_fail --> retry_pay[🔄 Retry payment]
+        retry_pay --> validate_pay
+        out_of_stock[📦 **Backorder** created]
+        deliver_fail[🔄 **Reattempt** delivery]
+    end
+
+    check_stock -->|Yes| pick
+    check_stock -->|No| out_of_stock
+    label --> handoff
+    deliver -->|Yes| deliver_email
+    deliver -->|No| deliver_fail
+    deliver_fail --> transit
+
+    check_stock -->|Yes| confirm_email
+    handoff --> ship_update
+    deliver_email --> complete([✅ Order **complete**])
+
+    classDef intake_style fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
+    classDef fulfill_style fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
+    classDef ship_style fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
+    classDef warn_style fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
+    classDef danger_style fill:#fee2e2,stroke:#dc2626,stroke-width:2px,color:#7f1d1d
+
+    class validate_pay,check_fraud,check_stock,manual_review intake_style
+    class pick,pack,label fulfill_style
+    class handoff,transit,deliver ship_style
+    class confirm_email,ship_update,deliver_email warn_style
+    class pay_fail,retry_pay,out_of_stock,deliver_fail danger_style
+```
+
+### Why this works
+
+- **5 subgraphs map to real business phases** — intake, fulfillment, shipping, notification, and exceptions are how operations teams actually think about orders
+- **Exception handling is its own subgraph** — not scattered across phases. Agents and readers can see all failure paths in one place
+- **Color classes reinforce structure** — blue for intake, purple for fulfillment, green for shipping, amber for notifications, red for exceptions. Even without reading labels, the color pattern tells you which phase you're looking at
+- **Decisions route between subgraphs** — the diamonds (`{Payment valid?}`, `{In stock?}`, `{Delivered?}`) are the points where flow branches, and each branch leads to a clearly-labeled destination

package/skills/markdown-mermaid-writing/references/diagrams/gantt.md

@@ -0,0 +1,138 @@
+<!-- Source: https://github.com/SuperiorByteWorks-LLC/agent-project | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
+
+# Gantt Chart
+
+> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
+
+**Syntax keyword:** `gantt`
+**Best for:** Project timelines, roadmaps, phase planning, milestone tracking, task dependencies
+**When NOT to use:** Simple chronological events (use [Timeline](timeline.md)), process logic (use [Flowchart](flowchart.md))
+
+---
+
+## Exemplar Diagram
+
+```mermaid
+gantt
+    accTitle: Q1 Product Launch Roadmap
+    accDescr: Eight-week project timeline across discovery, design, build, and launch phases with milestones for design review and go/no-go decision
+
+    title 🚀 Q1 Product Launch Roadmap
+    dateFormat YYYY-MM-DD
+    axisFormat %b %d
+
+    section 📋 Discovery
+        User research          :done, research, 2026-01-05, 7d
+        Competitive analysis   :done, compete, 2026-01-05, 5d
+        Requirements doc       :done, reqs, after compete, 3d
+
+    section 🎨 Design
+        Wireframes             :done, wire, after reqs, 5d
+        Visual design          :active, visual, after wire, 7d
+        🏁 Design review       :milestone, review, after visual, 0d
+
+    section 🔧 Build
+        Core features          :crit, core, after visual, 10d
+        API integration        :api, after visual, 8d
+        Testing                :test, after core, 5d
+
+    section 🚀 Launch
+        Staging deploy         :staging, after test, 3d
+        🏁 Go / no-go          :milestone, decision, after staging, 0d
+        Production release     :crit, release, after staging, 2d
+```
+
+---
+
+## Tips
+
+- Use `section` with emoji prefix to group by phase or team
+- Mark milestones with `:milestone` and `0d` duration — prefix with 🏁
+- Status tags: `:done`, `:active`, `:crit` (critical path, highlighted)
+- Use `after taskId` for dependencies
+- Keep total timeline **under 3 months** for readability
+- Use `axisFormat` to control date display (`%b %d` = "Jan 05", `%m/%d` = "01/05")
+
+---
+
+## Template
+
+```mermaid
+gantt
+    accTitle: Your Title Here
+    accDescr: Describe the timeline scope and key milestones
+
+    title 📋 Your Roadmap Title
+    dateFormat YYYY-MM-DD
+    axisFormat %b %d
+
+    section 📋 Phase 1
+        Task one       :done, t1, 2026-01-01, 5d
+        Task two       :active, t2, after t1, 3d
+
+    section 🔧 Phase 2
+        Task three     :crit, t3, after t2, 7d
+        🏁 Milestone   :milestone, m1, after t3, 0d
+```
+
+---
+
+## Complex Example
+
+A cross-team platform migration spanning 4 months with 6 sections, 24 tasks, and 3 milestones. Shows dependencies across teams (backend migration blocks frontend migration), critical path items, and the full lifecycle from planning through launch monitoring.
+
+```mermaid
+gantt
+    accTitle: Multi-Team Platform Migration Roadmap
+    accDescr: Four-month migration project across planning, backend, frontend, data, QA, and launch teams with cross-team dependencies, critical path items, and three milestone gates
+
+    title 🚀 Platform Migration — Q1/Q2 2026
+    dateFormat YYYY-MM-DD
+    axisFormat %b %d
+
+    section 📋 Planning
+        Kickoff meeting               :done, plan1, 2026-01-05, 2d
+        Architecture review            :done, plan2, after plan1, 5d
+        Migration plan document        :done, plan3, after plan2, 5d
+        Risk assessment                :done, plan4, after plan2, 3d
+        🏁 Planning complete           :milestone, m_plan, after plan3, 0d
+
+    section 🔧 Backend Team
+        API redesign                   :crit, be1, after m_plan, 12d
+        Data migration scripts         :be2, after m_plan, 10d
+        New service deployment         :crit, be3, after be1, 8d
+        Backward compatibility layer   :be4, after be1, 6d
+
+    section 🎨 Frontend Team
+        Component library update       :fe1, after m_plan, 10d
+        Page migration                 :crit, fe2, after be3, 12d
+        A/B testing setup              :fe3, after fe2, 5d
+        Feature parity validation      :fe4, after fe2, 4d
+
+    section 🗄️ Data Team
+        Schema migration               :crit, de1, after be2, 8d
+        ETL pipeline update            :de2, after de1, 7d
+        Data validation suite          :de3, after de2, 5d
+        Rollback scripts               :de4, after de1, 4d
+
+    section 🧪 QA Team
+        Test plan creation             :qa1, after m_plan, 7d
+        Regression suite               :qa2, after be3, 10d
+        Performance testing            :crit, qa3, after qa2, 7d
+        UAT coordination               :qa4, after qa3, 5d
+        🏁 QA sign-off                 :milestone, m_qa, after qa4, 0d
+
+    section 🚀 Launch
+        Staging deploy                 :crit, l1, after m_qa, 3d
+        🏁 Go / no-go decision         :milestone, m_go, after l1, 0d
+        Production cutover             :crit, l2, after m_go, 2d
+        Post-launch monitoring         :l3, after l2, 10d
+        Legacy system decommission     :l4, after l3, 5d
+```
+
+### Why this works
+
+- **6 sections map to real teams** — each team sees their workstream at a glance. Cross-team dependencies (frontend waits for backend API, QA waits for backend deploy) are explicit via `after taskId`.
+- **`:crit` marks the critical path** — the chain of tasks that determines the total project duration. If any critical task slips, the launch date moves. Mermaid highlights these in red.
+- **3 milestones are decision gates** — Planning Complete, QA Sign-off, and Go/No-Go. These are the points where stakeholders make decisions, not just status updates.
+- **24 tasks across 4 months** is readable because sections group by team. Without sections, this would be an unreadable wall of bars.

package/skills/markdown-mermaid-writing/references/diagrams/git_graph.md

@@ -0,0 +1,74 @@
+<!-- Source: https://github.com/SuperiorByteWorks-LLC/agent-project | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
+
+# Git Graph
+
+> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
+
+**Syntax keyword:** `gitGraph`
+**Best for:** Branching strategies, merge workflows, release processes, git-flow visualization
+**When NOT to use:** General processes (use [Flowchart](flowchart.md)), project timelines (use [Gantt](gantt.md))
+
+---
+
+## Exemplar Diagram
+
+```mermaid
+gitGraph
+    accTitle: Trunk-Based Development Workflow
+    accDescr: Git history showing short-lived feature branches merging into main with release tags demonstrating trunk-based development
+
+    commit id: "init"
+    commit id: "setup CI"
+
+    branch feature/auth
+    checkout feature/auth
+    commit id: "add login"
+    commit id: "add tests"
+
+    checkout main
+    merge feature/auth id: "merge auth" tag: "v1.0"
+
+    commit id: "update deps"
+
+    branch feature/dashboard
+    checkout feature/dashboard
+    commit id: "add charts"
+    commit id: "add filters"
+
+    checkout main
+    merge feature/dashboard id: "merge dash"
+
+    commit id: "perf fixes" tag: "v1.1"
+```
+
+---
+
+## Tips
+
+- Use descriptive `id:` labels on commits
+- Add `tag:` for release versions
+- Branch names should match your actual convention (`feature/`, `fix/`, `release/`)
+- Show the **ideal** workflow — this is prescriptive, not descriptive
+- Use `type: HIGHLIGHT` on important merge commits
+- Keep to **10–15 commits** maximum for readability
+
+---
+
+## Template
+
+```mermaid
+gitGraph
+    accTitle: Your Title Here
+    accDescr: Describe the branching strategy and merge pattern
+
+    commit id: "initial"
+    commit id: "second commit"
+
+    branch feature/your-feature
+    checkout feature/your-feature
+    commit id: "feature work"
+    commit id: "add tests"
+
+    checkout main
+    merge feature/your-feature id: "merge feature" tag: "v1.0"
+```

package/skills/markdown-mermaid-writing/references/diagrams/kanban.md

@@ -0,0 +1,107 @@
+<!-- Source: https://github.com/SuperiorByteWorks-LLC/agent-project | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
+
+# Kanban Board
+
+> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
+
+**Syntax keyword:** `kanban`
+**Best for:** Task status boards, workflow columns, work-in-progress visualization, sprint status
+**When NOT to use:** Task timelines/dependencies (use [Gantt](gantt.md)), process logic (use [Flowchart](flowchart.md))
+
+> ⚠️ **Accessibility:** Kanban boards do **not** support `accTitle`/`accDescr`. Always place a descriptive _italic_ Markdown paragraph directly above the code block.
+
+---
+
+## Exemplar Diagram
+
+_Kanban board showing the current sprint's work items distributed across four workflow columns, with emoji indicating column status:_
+
+```mermaid
+kanban
+Backlog
+  task1[🔐 Upgrade auth library]
+  task2[🛡️ Add rate limiting]
+  task3[📚 Write API docs]
+In Progress
+  task4[📊 Build dashboard]
+  task5[🐛 Fix login bug]
+In Review
+  task6[💰 Refactor payments]
+Done
+  task7[📊 Deploy monitoring]
+  task8[⚙️ Update CI pipeline]
+```
+
+> ⚠️ **Tip:** Each task gets ONE domain emoji at the start — this is your primary visual signal for categorization. Column emoji indicates workflow state.
+
+---
+
+## Tips
+
+- Name columns with **status emoji** for instant visual scanning
+- Add **domain emoji** to tasks for quick categorization
+- Keep to **3–5 columns**
+- Limit to **3–4 items per column** (representative, not exhaustive)
+- Items are simple text descriptions — keep concise
+- Good for sprint snapshots in documentation
+- **Always** pair with a Markdown text description above for screen readers
+
+---
+
+## Template
+
+_Description of the workflow columns and what the board represents. Always show all 6 columns:_
+
+```mermaid
+kanban
+Backlog
+  task1[🔧 Task description]
+  task2[📝 Task description]
+In Progress
+  task3[⚙️ Task description]
+In Review
+  task4[👀 Task description]
+Done
+  task5[🚀 Task description]
+Blocked
+  task6[⛔ Task description]
+Won't Do
+  task7[❌ Task description]
+```
+
+> ⚠️ Always include all 6 columns — Backlog, In Progress, In Review, Done, Blocked, Won't Do. Even if a column is empty, include a placeholder item like [No items yet] to make the structure explicit.
+
+---
+
+## Complex Example
+
+_Sprint W07 board for the Payments Team showing a realistic distribution of work items across all six columns, including blocked items:_
+
+```mermaid
+kanban
+Backlog
+  b1[📊 Add pool monitoring to auth]
+  b2[🔍 Evaluate PgBouncer]
+  b3[📝 Update runbook for pool alerts]
+In Progress
+  ip1[📊 Build merchant dashboard MVP]
+  ip2[📚 Write v2 API migration guide]
+  ip3[🔐 Add OAuth2 PKCE flow]
+In Review
+  r1[🛡️ Request validation middleware]
+Done
+  d1[🛡️ Rate limiting on /v2/charges]
+  d2[🐛 Fix pool exhaustion errors]
+  d3[📊 Pool utilization alerts]
+Blocked
+  bl1[🔄 Auth service pool config]
+Won't Do
+  w1[❌ Mobile SDK in this sprint]
+```
+
+Tips for complex kanban diagrams:
+
+- Add a Blocked column to surface stalled work — this is the highest-signal column on any board
+- Keep items to 3–4 per column max even in complex boards — the diagram is a summary, not an exhaustive list
+- Use the same emoji per domain across columns for visual tracking (📊 = dashboards, 🛡️ = security, 🐛 = bugs)
+- Always show all 6 columns — use placeholder items like [No items] when a column is empty

package/skills/markdown-mermaid-writing/references/diagrams/mindmap.md

@@ -0,0 +1,74 @@
+<!-- Source: https://github.com/SuperiorByteWorks-LLC/agent-project | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
+
+# Mindmap
+
+> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
+
+**Syntax keyword:** `mindmap`
+**Best for:** Brainstorming, concept organization, knowledge hierarchies, topic breakdown
+**When NOT to use:** Sequential processes (use [Flowchart](flowchart.md)), timelines (use [Timeline](timeline.md))
+
+> ⚠️ **Accessibility:** Mindmaps do **not** support `accTitle`/`accDescr`. Always place a descriptive _italic_ Markdown paragraph directly above the code block.
+
+---
+
+## Exemplar Diagram
+
+_Mindmap showing a platform engineering team's key responsibility areas organized into infrastructure, developer experience, security, and observability domains:_
+
+```mermaid
+mindmap
+    root((🏗️ Platform Engineering))
+        ☁️ Infrastructure
+            Kubernetes clusters
+            Service mesh
+            Load balancing
+            Auto-scaling
+        🔧 Developer Experience
+            CI/CD pipelines
+            Local dev environments
+            Internal CLI tools
+            Documentation
+        🔐 Security
+            Secret management
+            Network policies
+            Vulnerability scanning
+            Access control
+        📊 Observability
+            Metrics collection
+            Log aggregation
+            Distributed tracing
+            Alerting rules
+```
+
+---
+
+## Tips
+
+- Keep to **3–4 main branches** with **3–5 sub-items** each
+- Use emoji on branch headers for visual distinction
+- Don't nest deeper than 3 levels
+- Root node uses `(( ))` for circle shape
+- **Always** pair with a Markdown text description above for screen readers
+
+---
+
+## Template
+
+_Description of what this mindmap shows and the key categories it covers:_
+
+```mermaid
+mindmap
+    root((🎯 Central Concept))
+        📋 Branch One
+            Sub-item A
+            Sub-item B
+            Sub-item C
+        🔧 Branch Two
+            Sub-item D
+            Sub-item E
+        📊 Branch Three
+            Sub-item F
+            Sub-item G
+            Sub-item H
+```

package/skills/markdown-mermaid-writing/references/diagrams/packet.md

@@ -0,0 +1,55 @@
+<!-- Source: https://github.com/SuperiorByteWorks-LLC/agent-project | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
+
+# Packet Diagram
+
+> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
+
+**Syntax keyword:** `packet-beta`
+**Best for:** Network protocol headers, data structure layouts, binary format documentation, bit-level specifications
+**When NOT to use:** General data models (use [ER](er.md)), system architecture (use [C4](c4.md) or [Architecture](architecture.md))
+
+> ⚠️ **Accessibility:** Packet diagrams do **not** support `accTitle`/`accDescr`. Always place a descriptive _italic_ Markdown paragraph directly above the code block.
+
+---
+
+## Exemplar Diagram
+
+_Packet diagram showing the structure of a simplified TCP header with field sizes in bits:_
+
+```mermaid
+packet-beta
+    0-15: "Source Port"
+    16-31: "Destination Port"
+    32-63: "Sequence Number"
+    64-95: "Acknowledgment Number"
+    96-99: "Data Offset"
+    100-105: "Reserved"
+    106-111: "Flags (URG,ACK,PSH,RST,SYN,FIN)"
+    112-127: "Window Size"
+    128-143: "Checksum"
+    144-159: "Urgent Pointer"
+```
+
+---
+
+## Tips
+
+- Ranges are `start-end:` in bits (0-indexed)
+- Keep field labels concise — abbreviate if needed
+- Use for any fixed-width binary format, not just network packets
+- Row width defaults to 32 bits — fields wrap naturally
+- **Always** pair with a Markdown text description above for screen readers
+
+---
+
+## Template
+
+_Description of the protocol or data format and its field structure:_
+
+```mermaid
+packet-beta
+    0-7: "Field A"
+    8-15: "Field B"
+    16-31: "Field C"
+    32-63: "Field D"
+```

package/skills/markdown-mermaid-writing/references/diagrams/pie.md

@@ -0,0 +1,52 @@
+<!-- Source: https://github.com/SuperiorByteWorks-LLC/agent-project | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
+
+# Pie Chart
+
+> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
+
+**Syntax keyword:** `pie`
+**Best for:** Simple proportional breakdowns, budget allocation, composition, survey results
+**When NOT to use:** Trends over time (use [XY Chart](xy_chart.md)), exact comparisons (use a table), more than 7 categories
+
+---
+
+## Exemplar Diagram
+
+```mermaid
+pie
+    accTitle: Engineering Time Allocation
+    accDescr: Pie chart showing how engineering team time is distributed across feature work, tech debt, bug fixes, on-call, and learning
+
+    title 📊 Engineering Time Allocation
+    "🔧 Feature development" : 45
+    "🔄 Tech debt reduction" : 20
+    "🐛 Bug fixes" : 20
+    "📱 On-call & support" : 10
+    "📚 Learning & growth" : 5
+```
+
+---
+
+## Tips
+
+- Values are proportional — they don't need to sum to 100
+- Use descriptive labels with **emoji prefix** for visual distinction
+- Limit to **7 slices maximum** — group small ones into "📦 Other"
+- Always include a `title` with relevant emoji
+- Order slices largest to smallest for readability
+
+---
+
+## Template
+
+```mermaid
+pie
+    accTitle: Your Title Here
+    accDescr: Describe what proportions are being shown
+
+    title 📊 Your Chart Title
+    "📋 Category A" : 40
+    "🔧 Category B" : 30
+    "📦 Category C" : 20
+    "🗂️ Other" : 10
+```