@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/generating-mermaid-diagrams/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: generating-mermaid-diagrams
+description: "Salesforce architecture diagrams using Mermaid with ASCII fallback. Use this skill when generating text-based diagrams for Salesforce architecture, OAuth flows, ERDs, integration sequences, or Agentforce structure. TRIGGER when: user says \"diagram\", \"visualize\", \"ERD\", or asks for sequence diagrams, flowcharts, class diagrams, or architecture visualizations in Mermaid. DO NOT TRIGGER when: user wants PNG/SVG image output (use generating-visual-diagrams), or asks about non-Salesforce systems."
+license: MIT
+compatibility: "Requires Mermaid-capable renderer for diagram previews"
+metadata:
+  version: "1.0"
+---
+
+# generating-mermaid-diagrams: Salesforce Diagram Generation
+
+Use this skill when the user needs **text-based diagrams**: Mermaid diagrams for architecture, OAuth, integration flows, ERDs, or Agentforce structure, plus ASCII fallback when plain-text compatibility matters.
+
+## Scope
+
+### In Scope
+Use `generating-mermaid-diagrams` when the user wants:
+- Mermaid output
+- ASCII fallback diagrams
+- architecture, sequence, flowchart, or ERD views in markdown-friendly form
+- diagrams that can live directly in docs, READMEs, or issues
+
+### Out of Scope — Delegate elsewhere when the user wants:
+- rendered PNG/SVG images or polished mockups → [generating-visual-diagrams](../generating-visual-diagrams/SKILL.md)
+- non-Salesforce systems only → use a more general diagramming skill
+- object discovery before an ERD → [generating-custom-object](../generating-custom-object/SKILL.md) or [generating-custom-field](../generating-custom-field/SKILL.md)
+
+---
+
+## Supported Diagram Families
+
+| Type | Preferred Mermaid form | Typical use |
+|---|---|---|
+| OAuth / auth flows | `sequenceDiagram` | Authorization Code, JWT, PKCE, Device Flow |
+| ERD / data model | `flowchart LR` | object relationships and sharing context |
+| integration sequence | `sequenceDiagram` | request/response or event choreography |
+| system landscape | `flowchart` | high-level architecture |
+| role / access hierarchy | `flowchart` | users, profiles, permissions |
+| Agentforce behavior map | `flowchart` | agent → topic → action relationships |
+
+---
+
+## Required Context to Gather First
+
+Ask for or infer:
+- diagram type
+- scope and entities / systems involved
+- output preference: Mermaid only, ASCII only, or both
+- whether styling should be minimal, documentation-first, or presentation-friendly
+- for ERDs: whether org metadata is available for grounding
+
+---
+
+## Recommended Workflow
+
+### 1. Pick the right diagram structure
+- use `sequenceDiagram` for time-ordered interactions
+- use `flowchart LR` for ERDs and capability maps
+- keep a single primary story per diagram when possible
+
+### 2. Gather data
+For ERDs and grounded diagrams:
+- use [generating-custom-object](../generating-custom-object/SKILL.md) or [generating-custom-field](../generating-custom-field/SKILL.md) when real schema discovery is needed
+- optionally use the local metadata helper script for counts / relationship context when appropriate
+
+### 3. Generate Mermaid first
+Apply:
+- accurate labels
+- simple readable node text
+- consistent relationship notation
+- restrained styling that renders cleanly in markdown viewers
+
+### 4. Add ASCII fallback when useful
+Provide an ASCII version when the user wants terminal compatibility or plaintext documentation.
+
+### 5. Explain the diagram briefly
+Call out the key relationships, flow direction, and any assumptions.
+
+---
+
+## High-Signal Rules
+
+### For sequence diagrams
+- use `autonumber` when step order matters
+- distinguish requests vs responses clearly
+- use notes sparingly for protocol detail
+
+### For ERDs
+- prefer `flowchart LR`
+- keep object cards simple
+- use clear relationship arrows
+- avoid field overload unless the user explicitly asks for field-level detail
+- color-code object types only when it improves readability
+
+### For ASCII output
+- keep width reasonable
+- align arrows and boxes consistently
+- optimize for readability over decoration
+
+---
+
+## Output Format
+
+````markdown
+## <Diagram Title>
+
+### Mermaid Diagram
+```mermaid
+<diagram>
+```
+
+### ASCII Fallback
+```text
+<ascii>
+```
+
+### Notes
+- <key point>
+- <assumption or limitation>
+````
+
+---
+
+## Cross-Skill Integration
+
+| Need | Delegate to | Reason |
+|---|---|---|
+| real object / field definitions | [generating-custom-object](../generating-custom-object/SKILL.md) / [generating-custom-field](../generating-custom-field/SKILL.md) | grounded ERD generation |
+| rendered diagram / image output | [generating-visual-diagrams](../generating-visual-diagrams/SKILL.md) | visual polish beyond Mermaid |
+| connected-app auth setup context | [configuring-connected-apps](../configuring-connected-apps/SKILL.md) | accurate OAuth flows |
+| Agentforce logic visualization | [developing-agentforce](../developing-agentforce/SKILL.md) | source-of-truth behavior details |
+| Flow behavior diagrams | [generating-flow](../generating-flow/SKILL.md) | actual Flow logic grounding |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|---|---|
+| Mermaid renderer not available | Provide ASCII fallback automatically; note that the Mermaid block still carries the diagram for copy-paste into a renderer |
+| ERD becomes unreadable with too many objects | Split into sub-diagrams by domain (Sales, Service, etc.) and link them in prose |
+| Sequence diagram step order unclear | Use `autonumber` directive to make step ordering explicit |
+| OAuth flow actors differ by grant type | Read the relevant asset template first before generating to avoid actor mismatch |
+
+---
+
+## Reference File Index
+
+### Conventions & rules — read before generating
+- [references/diagram-conventions.md](references/diagram-conventions.md) — consistency rules for all diagram types
+- [references/mermaid-reference.md](references/mermaid-reference.md) — Mermaid syntax quick reference
+- [references/usage-examples.md](references/usage-examples.md) — worked examples per diagram type
+
+### Styling
+- [references/mermaid-styling.md](references/mermaid-styling.md) — theming and annotation patterns
+- [references/color-palette.md](references/color-palette.md) — color-blind-friendly palette with hex values
+- [references/erd-conventions.md](references/erd-conventions.md) — ERD-specific layout and notation rules
+
+### Preview
+- [references/preview-guide.md](references/preview-guide.md) — how to render Mermaid locally
+- [scripts/README.md](scripts/README.md) — setup and usage instructions for all scripts in this skill
+- [scripts/mermaid_preview.py](scripts/mermaid_preview.py) — live-reload preview server; run to preview diagrams in browser
+- [scripts/query-org-metadata.py](scripts/query-org-metadata.py) — queries org schema to ground ERD generation
+
+### OAuth flow templates — load the matching template when generating OAuth diagrams
+- [assets/oauth/authorization-code.md](assets/oauth/authorization-code.md) — Authorization Code grant
+- [assets/oauth/authorization-code-pkce.md](assets/oauth/authorization-code-pkce.md) — PKCE variant for mobile/SPA
+- [assets/oauth/jwt-bearer.md](assets/oauth/jwt-bearer.md) — JWT Bearer server-to-server
+- [assets/oauth/client-credentials.md](assets/oauth/client-credentials.md) — Client Credentials service accounts
+- [assets/oauth/device-authorization.md](assets/oauth/device-authorization.md) — Device Flow for CLI/IoT
+- [assets/oauth/refresh-token.md](assets/oauth/refresh-token.md) — Refresh Token renewal flow
+- [assets/oauth/user-agent-social-sign-on.md](assets/oauth/user-agent-social-sign-on.md) — User-Agent / Social Sign-On
+
+### Data model ERD templates — load the matching template when generating ERDs
+- [assets/datamodel/salesforce-erd.md](assets/datamodel/salesforce-erd.md) — core Salesforce objects
+- [assets/datamodel/sales-cloud-erd.md](assets/datamodel/sales-cloud-erd.md) — Sales Cloud objects
+- [assets/datamodel/service-cloud-erd.md](assets/datamodel/service-cloud-erd.md) — Service Cloud objects
+- [assets/datamodel/b2b-commerce-erd.md](assets/datamodel/b2b-commerce-erd.md) — B2B Commerce objects
+- [assets/datamodel/campaigns-erd.md](assets/datamodel/campaigns-erd.md) — Campaigns and campaign member model
+- [assets/datamodel/consent-erd.md](assets/datamodel/consent-erd.md) — Consent and privacy objects
+- [assets/datamodel/files-erd.md](assets/datamodel/files-erd.md) — Files and ContentDocument model
+- [assets/datamodel/forecasting-erd.md](assets/datamodel/forecasting-erd.md) — Forecasting objects
+- [assets/datamodel/fsl-erd.md](assets/datamodel/fsl-erd.md) — Field Service Lightning objects
+- [assets/datamodel/party-model-erd.md](assets/datamodel/party-model-erd.md) — Party model objects
+- [assets/datamodel/quote-order-erd.md](assets/datamodel/quote-order-erd.md) — Quote and Order objects
+- [assets/datamodel/revenue-cloud-erd.md](assets/datamodel/revenue-cloud-erd.md) — Revenue Cloud objects
+- [assets/datamodel/scheduler-erd.md](assets/datamodel/scheduler-erd.md) — Scheduler objects
+- [assets/datamodel/territory-management-erd.md](assets/datamodel/territory-management-erd.md) — Territory Management objects
+
+### Other diagram templates
+- [assets/architecture/system-landscape.md](assets/architecture/system-landscape.md) — system landscape overview template
+- [assets/integration/api-sequence.md](assets/integration/api-sequence.md) — API callout sequence template
+- [assets/agentforce/agent-flow.md](assets/agentforce/agent-flow.md) — Agentforce agent → topic → action flow
+- [assets/role-hierarchy/user-hierarchy.md](assets/role-hierarchy/user-hierarchy.md) — role and permission hierarchy template
+
+---
+
+## Output Expectations
+
+Deliverables produced by this skill for each request:
+
+- **Mermaid code block** — fenced ` ```mermaid ` block ready to paste into GitHub, Confluence, or any Mermaid-capable renderer
+- **ASCII fallback** (when requested or when Mermaid renderer is unavailable) — text-only diagram using box/arrow characters
+- **Brief explanation** — 2-5 bullet points calling out key relationships, flow direction, and any assumptions or limitations in the diagram
+- For ERDs: object cards with field labels and relationship type annotations
+- For sequence diagrams: numbered steps (`autonumber`) with clear actor labels
+
+---
+
+## Score Guide
+
+| Score | Meaning |
+|---|---|
+| 72–80 | production-ready diagram |
+| 60–71 | clear and useful with minor polish left |
+| 48–59 | functional but could be clearer |
+| 35–47 | needs structural improvement |
+| < 35 | inaccurate or incomplete |

package/skills/generating-mermaid-diagrams/assets/agentforce/agent-flow.md

@@ -0,0 +1,313 @@
+# Agentforce Flow Diagram Template
+
+Flowchart template for visualizing Agentforce agent architecture and conversation flows.
+
+## When to Use
+- Documenting Agentforce agent structure
+- Planning agent topics and actions
+- Visualizing conversation flows
+- Architecture reviews
+
+## Mermaid Template - Agent Structure
+
+```mermaid
+%%{init: {"flowchart": {"nodeSpacing": 80, "rankSpacing": 70}} }%%
+flowchart TB
+    subgraph agent["🤖 SERVICE AGENT"]
+        direction TB
+
+        DESC[/"Agent Description:<br/>AI-powered customer service<br/>assistant for order management"/]
+
+        subgraph topics["📋 TOPICS"]
+            direction LR
+            T1[Order Status]
+            T2[Return Request]
+            T3[Product Info]
+            T4[Escalation]
+        end
+
+        subgraph instructions["📝 INSTRUCTIONS"]
+            I1[Greet professionally]
+            I2[Verify customer identity]
+            I3[Use knowledge base first]
+            I4[Escalate if frustrated]
+        end
+    end
+
+    subgraph topic_order["📦 TOPIC: ORDER STATUS"]
+        direction TB
+        TO_DESC[/"Help customers check<br/>order and shipping status"/]
+        TO_SCOPE[Scope: Order tracking,<br/>delivery estimates]
+
+        subgraph to_actions["ACTIONS"]
+            TO_A1[Get Order Details<br/>⚡ Apex]
+            TO_A2[Check Shipping<br/>🔄 Flow]
+        end
+    end
+
+    subgraph topic_return["🔄 TOPIC: RETURN REQUEST"]
+        direction TB
+        TR_DESC[/"Process return and<br/>refund requests"/]
+        TR_SCOPE[Scope: Returns, refunds,<br/>exchanges]
+
+        subgraph tr_actions["ACTIONS"]
+            TR_A1[Create Case<br/>🔄 Flow]
+            TR_A2[Generate Label<br/>⚡ Apex]
+            TR_A3[Process Refund<br/>⚡ Apex]
+        end
+    end
+
+    %% Connections
+    T1 --> topic_order
+    T2 --> topic_return
+
+    TO_A1 --> ORDER_SVC[Order Service]
+    TO_A2 --> SHIP_API[Shipping API]
+
+    TR_A1 --> CASE_OBJ[(Case Object)]
+    TR_A2 --> SHIP_API
+    TR_A3 --> PAY_API[Payment API]
+
+    %% Node Styling - Topics (violet-200)
+    style T1 fill:#ddd6fe,stroke:#6d28d9,color:#1f2937
+    style T2 fill:#ddd6fe,stroke:#6d28d9,color:#1f2937
+    style T3 fill:#ddd6fe,stroke:#6d28d9,color:#1f2937
+    style T4 fill:#ddd6fe,stroke:#6d28d9,color:#1f2937
+
+    %% Node Styling - Actions (emerald-200)
+    style TO_A1 fill:#a7f3d0,stroke:#047857,color:#1f2937
+    style TO_A2 fill:#a7f3d0,stroke:#047857,color:#1f2937
+    style TR_A1 fill:#a7f3d0,stroke:#047857,color:#1f2937
+    style TR_A2 fill:#a7f3d0,stroke:#047857,color:#1f2937
+    style TR_A3 fill:#a7f3d0,stroke:#047857,color:#1f2937
+
+    %% Node Styling - External (orange-200)
+    style ORDER_SVC fill:#fed7aa,stroke:#c2410c,color:#1f2937
+    style SHIP_API fill:#fed7aa,stroke:#c2410c,color:#1f2937
+    style PAY_API fill:#fed7aa,stroke:#c2410c,color:#1f2937
+    style CASE_OBJ fill:#fde68a,stroke:#b45309,color:#1f2937
+
+    %% Node Styling - Descriptions (slate-200)
+    style DESC fill:#e2e8f0,stroke:#334155,color:#1f2937
+    style TO_DESC fill:#e2e8f0,stroke:#334155,color:#1f2937
+    style TO_SCOPE fill:#e2e8f0,stroke:#334155,color:#1f2937
+    style TR_DESC fill:#e2e8f0,stroke:#334155,color:#1f2937
+    style TR_SCOPE fill:#e2e8f0,stroke:#334155,color:#1f2937
+    style I1 fill:#e2e8f0,stroke:#334155,color:#1f2937
+    style I2 fill:#e2e8f0,stroke:#334155,color:#1f2937
+    style I3 fill:#e2e8f0,stroke:#334155,color:#1f2937
+    style I4 fill:#e2e8f0,stroke:#334155,color:#1f2937
+
+    %% Subgraph Styling - 50-level fills with dashed borders
+    style agent fill:#fdf2f8,stroke:#be185d,stroke-dasharray:5
+    style topics fill:#f5f3ff,stroke:#6d28d9,stroke-dasharray:5
+    style instructions fill:#f8fafc,stroke:#334155,stroke-dasharray:5
+    style topic_order fill:#f5f3ff,stroke:#6d28d9,stroke-dasharray:5
+    style to_actions fill:#ecfdf5,stroke:#047857,stroke-dasharray:5
+    style topic_return fill:#f5f3ff,stroke:#6d28d9,stroke-dasharray:5
+    style tr_actions fill:#ecfdf5,stroke:#047857,stroke-dasharray:5
+```
+
+## Mermaid Template - Conversation Flow
+
+```mermaid
+%%{init: {"flowchart": {"nodeSpacing": 80, "rankSpacing": 70}} }%%
+flowchart TD
+    START([🟢 Conversation Start])
+
+    START --> GREET[Greet Customer]
+    GREET --> CLASSIFY{Classify Intent}
+
+    CLASSIFY -->|Order Related| ORDER_TOPIC
+    CLASSIFY -->|Return Related| RETURN_TOPIC
+    CLASSIFY -->|General Question| KB_SEARCH
+    CLASSIFY -->|Unknown| CLARIFY
+
+    subgraph ORDER_TOPIC["📦 ORDER STATUS TOPIC"]
+        ORD_1[Ask for Order Number]
+        ORD_2[Retrieve Order Details<br/>⚡ GetOrderDetails Action]
+        ORD_3{Order Found?}
+        ORD_4[Display Status]
+        ORD_5[Offer Additional Help]
+
+        ORD_1 --> ORD_2 --> ORD_3
+        ORD_3 -->|Yes| ORD_4 --> ORD_5
+        ORD_3 -->|No| ORD_1
+    end
+
+    subgraph RETURN_TOPIC["🔄 RETURN REQUEST TOPIC"]
+        RET_1[Verify Order Eligible]
+        RET_2{Eligible for Return?}
+        RET_3[Create Return Case<br/>🔄 CreateReturnCase Action]
+        RET_4[Generate Return Label<br/>⚡ GenerateLabel Action]
+        RET_5[Provide Instructions]
+        RET_6[Explain Policy]
+
+        RET_1 --> RET_2
+        RET_2 -->|Yes| RET_3 --> RET_4 --> RET_5
+        RET_2 -->|No| RET_6
+    end
+
+    KB_SEARCH[Search Knowledge Base<br/>📚 Knowledge Action]
+    KB_SEARCH --> KB_RESULT{Found Answer?}
+    KB_RESULT -->|Yes| PROVIDE_ANSWER[Provide Answer]
+    KB_RESULT -->|No| ESCALATE
+
+    CLARIFY[Ask Clarifying Question]
+    CLARIFY --> CLASSIFY
+
+    ESCALATE[Escalate to Human<br/>👤 Transfer Action]
+
+    ORD_5 --> SATISFIED{Customer Satisfied?}
+    RET_5 --> SATISFIED
+    PROVIDE_ANSWER --> SATISFIED
+
+    SATISFIED -->|Yes| END_SUCCESS([🟢 End - Resolved])
+    SATISFIED -->|No| ESCALATE
+
+    ESCALATE --> END_TRANSFER([🟡 End - Transferred])
+
+    %% Node Styling - Start/End (emerald-200)
+    style START fill:#a7f3d0,stroke:#047857,color:#1f2937
+    style END_SUCCESS fill:#a7f3d0,stroke:#047857,color:#1f2937
+    style END_TRANSFER fill:#fde68a,stroke:#b45309,color:#1f2937
+
+    %% Node Styling - Decisions (violet-200)
+    style CLASSIFY fill:#ddd6fe,stroke:#6d28d9,color:#1f2937
+    style ORD_3 fill:#ddd6fe,stroke:#6d28d9,color:#1f2937
+    style RET_2 fill:#ddd6fe,stroke:#6d28d9,color:#1f2937
+    style KB_RESULT fill:#ddd6fe,stroke:#6d28d9,color:#1f2937
+    style SATISFIED fill:#ddd6fe,stroke:#6d28d9,color:#1f2937
+
+    %% Node Styling - Actions (cyan-200)
+    style GREET fill:#a5f3fc,stroke:#0e7490,color:#1f2937
+    style ORD_1 fill:#a5f3fc,stroke:#0e7490,color:#1f2937
+    style ORD_2 fill:#a5f3fc,stroke:#0e7490,color:#1f2937
+    style ORD_4 fill:#a5f3fc,stroke:#0e7490,color:#1f2937
+    style ORD_5 fill:#a5f3fc,stroke:#0e7490,color:#1f2937
+    style RET_1 fill:#a5f3fc,stroke:#0e7490,color:#1f2937
+    style RET_3 fill:#a5f3fc,stroke:#0e7490,color:#1f2937
+    style RET_4 fill:#a5f3fc,stroke:#0e7490,color:#1f2937
+    style RET_5 fill:#a5f3fc,stroke:#0e7490,color:#1f2937
+    style RET_6 fill:#a5f3fc,stroke:#0e7490,color:#1f2937
+    style KB_SEARCH fill:#a5f3fc,stroke:#0e7490,color:#1f2937
+    style PROVIDE_ANSWER fill:#a5f3fc,stroke:#0e7490,color:#1f2937
+    style CLARIFY fill:#a5f3fc,stroke:#0e7490,color:#1f2937
+    style ESCALATE fill:#fed7aa,stroke:#c2410c,color:#1f2937
+
+    %% Subgraph Styling - 50-level fills with dashed borders
+    style ORDER_TOPIC fill:#f5f3ff,stroke:#6d28d9,stroke-dasharray:5
+    style RETURN_TOPIC fill:#f5f3ff,stroke:#6d28d9,stroke-dasharray:5
+```
+
+## ASCII Fallback Template
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        🤖 SERVICE AGENT STRUCTURE                           │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  AGENT: Customer Service Bot                                                │
+│  ─────────────────────────────                                              │
+│  Description: AI-powered assistant for order and return inquiries           │
+│                                                                             │
+│  Instructions:                                                              │
+│  • Greet customers professionally                                           │
+│  • Verify identity before sharing order details                             │
+│  • Search knowledge base before escalating                                  │
+│  • Escalate if customer expresses frustration                               │
+└─────────────────────────────────────────────────────────────────────────────┘
+          │
+          │
+          ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  📋 TOPICS                                                                  │
+│  ┌───────────────────┐  ┌───────────────────┐  ┌───────────────────┐       │
+│  │  📦 Order Status  │  │ 🔄 Return Request │  │  ❓ General Help  │       │
+│  │                   │  │                   │  │                   │       │
+│  │  Scope:           │  │  Scope:           │  │  Scope:           │       │
+│  │  - Track orders   │  │  - Process return │  │  - FAQ answers    │       │
+│  │  - Delivery ETA   │  │  - Generate label │  │  - Knowledge base │       │
+│  │  - Order history  │  │  - Refund status  │  │  - Escalation     │       │
+│  └─────────┬─────────┘  └─────────┬─────────┘  └─────────┬─────────┘       │
+└────────────│──────────────────────│──────────────────────│──────────────────┘
+             │                      │                      │
+             ▼                      ▼                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  ⚡ ACTIONS                                                                 │
+│  ┌───────────────────┐  ┌───────────────────┐  ┌───────────────────┐       │
+│  │ GetOrderDetails   │  │ CreateReturnCase  │  │ SearchKnowledge   │       │
+│  │ [Apex Invocable]  │  │ [Flow]            │  │ [Standard Action] │       │
+│  ├───────────────────┤  ├───────────────────┤  ├───────────────────┤       │
+│  │ Input:            │  │ Input:            │  │ Input:            │       │
+│  │ - orderNumber     │  │ - orderId         │  │ - query           │       │
+│  │ - customerId      │  │ - reason          │  │ - language        │       │
+│  │                   │  │ - quantity        │  │                   │       │
+│  │ Output:           │  │ Output:           │  │ Output:           │       │
+│  │ - status          │  │ - caseId          │  │ - articles[]      │       │
+│  │ - items[]         │  │ - returnLabel     │  │ - confidence      │       │
+│  │ - trackingUrl     │  │ - instructions    │  │                   │       │
+│  └───────────────────┘  └───────────────────┘  └───────────────────┘       │
+└─────────────────────────────────────────────────────────────────────────────┘
+             │                      │                      │
+             ▼                      ▼                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  🔗 INTEGRATIONS                                                            │
+│  ┌───────────────────┐  ┌───────────────────┐  ┌───────────────────┐       │
+│  │   Order Service   │  │   Shipping API    │  │  Knowledge Base   │       │
+│  │   (Salesforce)    │  │   (FedEx/UPS)     │  │   (Salesforce)    │       │
+│  └───────────────────┘  └───────────────────┘  └───────────────────┘       │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Agent Components
+
+| Component | Description | Example |
+|-----------|-------------|---------|
+| Agent | The AI assistant container | Service Agent, SDR Agent |
+| Topic | Conversation category | Order Status, Returns |
+| Action | Executable capability | Apex method, Flow |
+| Instruction | Behavioral guideline | "Always verify identity" |
+| Scope | Topic boundaries | What's in/out of scope |
+
+## Action Types
+
+| Type | Icon | Use Case |
+|------|------|----------|
+| Apex Invocable | ⚡ | Complex logic, callouts |
+| Flow | 🔄 | Record creation, updates |
+| Standard | 📚 | Knowledge search, case creation |
+| Prompt Template | 💬 | Dynamic response generation |
+
+## Conversation Flow Patterns
+
+### 1. Linear Flow
+```
+Start → Topic → Action → Response → End
+```
+
+### 2. Branching Flow
+```
+Start → Classify → [Topic A | Topic B | Escalate]
+```
+
+### 3. Loop Back
+```
+Start → Topic → Action → Validate → [Success | Retry]
+```
+
+## Best Practices
+
+1. **Clear topic boundaries** - Don't overlap scope
+2. **Minimal actions per topic** - 3-5 max
+3. **Always have escalation path** - Human handoff
+4. **Use knowledge base first** - Before custom actions
+5. **Verify before acting** - Confirm understanding
+
+## Customization Points
+
+- Replace example topics with actual use cases
+- Add specific action inputs/outputs
+- Include actual integration endpoints
+- Show conversation sample flows