@brainfish-ai/devdoc 0.1.39 → 0.1.41

package/ai-agents/.devdoc/templates/explanation.md

@@ -0,0 +1,292 @@
+# Explanation Template (Diátaxis: Understanding-Oriented)
+
+**Purpose:** Help users understand concepts, architecture, and the "why" behind decisions.
+
+**When to use:**
+- Architecture documentation
+- Conceptual overviews
+- Background knowledge
+- Design decisions (ADRs)
+- "How it works" content
+
+## Format
+
+```mdx
+---
+title: Understanding [Concept]
+description: Deep dive into [topic] and how it works
+contentType: explanation
+---
+
+## Overview
+
+Why this matters: 2-3 sentences explaining the importance of understanding this concept.
+
+## Background / Context
+
+What problem does this solve? What existed before?
+
+## How It Works
+
+### High-Level Architecture
+
+```mermaid
+flowchart TB
+    subgraph Client[Browser]
+        UI[User Interface]
+    end
+    
+    subgraph Server[Backend]
+        API[API Layer]
+        Logic[Business Logic]
+        DB[(Database)]
+    end
+    
+    UI --> API
+    API --> Logic
+    Logic --> DB
+```
+
+### Key Components
+
+| Component | Responsibility | Location |
+|-----------|----------------|----------|
+| Component A | Does X | `src/a/` |
+| Component B | Does Y | `src/b/` |
+| Component C | Does Z | `src/c/` |
+
+### The Flow
+
+1. **Step 1**: What happens first and why
+2. **Step 2**: What happens next
+3. **Step 3**: Final result
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant System
+    participant External
+    
+    User->>System: Action
+    System->>External: Request
+    External-->>System: Response
+    System-->>User: Result
+```
+
+## Key Concepts
+
+### Concept A
+
+Explanation of the concept with examples.
+
+<Tip>
+Key insight or mental model to help understanding.
+</Tip>
+
+### Concept B
+
+Another important concept.
+
+### Concept C
+
+Third concept with its relationships to A and B.
+
+## Design Decisions
+
+### Why [Decision X]?
+
+**Context:** What situation led to this decision?
+
+**Decision:** What we decided.
+
+**Rationale:** Why this approach over alternatives.
+
+**Trade-offs:**
+- ✅ Benefit 1
+- ✅ Benefit 2
+- ⚠️ Trade-off 1
+- ⚠️ Trade-off 2
+
+### Alternatives Considered
+
+| Option | Pros | Cons | Why Not |
+|--------|------|------|---------|
+| Option A | Fast | Complex | Too much overhead |
+| Option B (chosen) | Simple, maintainable | Slower | Best balance |
+
+## When to Use
+
+| Scenario | Recommendation |
+|----------|----------------|
+| Scenario A | Use this approach |
+| Scenario B | Consider alternative |
+| Scenario C | Not recommended |
+
+## Common Misconceptions
+
+<Warning>
+**Misconception:** [Common wrong belief]
+
+**Reality:** [Correct understanding]
+</Warning>
+
+## Deeper Dive
+
+For those who want to understand more:
+
+- [Technical detail 1]
+- [Technical detail 2]
+- [Edge cases]
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Tutorial" href="/tutorial">
+    Learn by building with this concept
+  </Card>
+  <Card title="How-To Guide" href="/how-to">
+    Practical tasks using this concept
+  </Card>
+  <Card title="Reference" href="/reference">
+    Complete API reference
+  </Card>
+</CardGroup>
+```
+
+## Guidelines
+
+- **Focus on understanding** - Explain the "why", not just the "what"
+- **Use analogies** - Relate to familiar concepts
+- **Provide context** - Historical background helps understanding
+- **Show relationships** - How concepts connect to each other
+- **Address misconceptions** - Clear up common confusion
+- **Use diagrams liberally** - Visual aids help comprehension
+- **Link to practical content** - Connect to tutorials and how-tos
+
+## Diátaxis Principles for Explanation
+
+| Principle | Application |
+|-----------|-------------|
+| Understanding-oriented | Focus on comprehension |
+| Conceptual | Abstract from specifics |
+| Reflective | Encourage thinking |
+| Connected | Show relationships |
+| Contextual | Provide background |
+
+## Mermaid Diagrams for Explanations
+
+### Architecture Diagram
+
+```mermaid
+flowchart TB
+    subgraph Client["Client Layer"]
+        A[Web App]
+        B[Mobile App]
+    end
+    subgraph Services["Service Layer"]
+        C[Auth Service]
+        D[API Gateway]
+    end
+    subgraph Data["Data Layer"]
+        E[(Database)]
+        F[(Cache)]
+    end
+    A --> D
+    B --> D
+    D --> C
+    D --> E
+    D --> F
+```
+
+### Data Flow Diagram
+
+```mermaid
+flowchart LR
+    A[Request] --> B[Validate]
+    B --> C{Valid?}
+    C -->|Yes| D[Process]
+    C -->|No| E[Error]
+    D --> F[Response]
+    E --> F
+```
+
+### Entity Relationship
+
+```mermaid
+erDiagram
+    USER ||--o{ ORDER : places
+    ORDER ||--|{ LINE_ITEM : contains
+    PRODUCT ||--o{ LINE_ITEM : "ordered in"
+```
+
+### State Machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft
+    Draft --> Pending: submit
+    Pending --> Approved: approve
+    Pending --> Rejected: reject
+    Approved --> Published: publish
+    Rejected --> Draft: revise
+    Published --> [*]
+```
+
+## ADR (Architecture Decision Record) Format
+
+```mdx
+---
+title: "ADR-001: [Decision Title]"
+description: Architecture decision record for [topic]
+contentType: explanation
+---
+
+## Status
+
+Accepted | Proposed | Deprecated | Superseded by ADR-XXX
+
+## Context
+
+What situation led to this decision?
+
+## Decision
+
+What did we decide?
+
+## Rationale
+
+Why this approach over alternatives?
+
+## Consequences
+
+### Positive
+- Benefit 1
+- Benefit 2
+
+### Negative
+- Trade-off 1
+- Trade-off 2
+
+### Neutral
+- Change 1
+- Change 2
+
+## Alternatives Considered
+
+### Option A: [Name]
+- Pros: ...
+- Cons: ...
+- Why not: ...
+
+### Option B: [Name] (Chosen)
+- Pros: ...
+- Cons: ...
+- Why chosen: ...
+
+## Related Decisions
+
+- [ADR-002](/decisions/002)
+- [ADR-003](/decisions/003)
+```

package/ai-agents/.devdoc/templates/guide.md

@@ -1,133 +1,60 @@
-# Guide Template
+# Guide Template (Diátaxis: How-To)
 
-Use this structure when creating guide documentation.
+**Note:** This template is an alias for the How-To template. Use `how-to.md` for new guides.
 
-## Format
+Guides are task-oriented documentation that help users accomplish specific goals.
 
-```mdx
----
-title: [Action] + [Topic]
-description: Learn how to [achieve specific outcome]
----
+## When to Use
 
-## Overview
+- User needs to solve a specific problem
+- Task-focused documentation  
+- Practical, goal-oriented scenarios
 
-Brief introduction (2-3 sentences):
-- What this guide covers
-- Who it's for
-- What you'll achieve
+## See Also
 
-## Prerequisites
+For the full template, refer to: `how-to.md`
 
-<Note>
-Before you begin, ensure you have:
-- [Requirement 1]
-- [Requirement 2]
-</Note>
+## Quick Reference
 
-## Architecture / Flow (if applicable)
+```mdx
+---
+title: How to [Achieve Specific Goal]
+description: Learn how to [specific outcome]
+contentType: how-to
+---
 
-Use mermaid diagrams to visualize:
+## Overview
 
-```mermaid
-flowchart LR
-    A[Input] --> B[Process]
-    B --> C[Output]
-```
+[2-3 sentences: What, Who, Why]
+
+## Prerequisites (if applicable)
 
 ## Steps
 
 <Steps>
-  <Step title="Step name">
-    Explanation of what this step does.
-    
-    ```language
-    // Code example
-    ```
-  </Step>
-  
-  <Step title="Next step">
-    Continue with clear, actionable steps.
-  </Step>
+  <Step title="[Action verb] [object]">Content</Step>
 </Steps>
 
 ## Example
 
-Complete working example showing the end result.
-
-```language
-// Full example code
-```
-
 ## Next Steps
-
-<CardGroup cols={2}>
-  <Card title="Related Guide" href="/path">
-    Brief description
-  </Card>
-</CardGroup>
-```
-
-## Mermaid Diagram Guidelines
-
-### When to Use Diagrams
-
-- **Flowcharts**: For processes, decision trees, workflows
-- **Sequence diagrams**: For API calls, request/response flows
-- **Entity diagrams**: For data models, relationships
-- **State diagrams**: For state machines, status transitions
-
-### Flowchart Example
-
-```mermaid
-flowchart TD
-    A[Start] --> B{Decision?}
-    B -->|Yes| C[Action 1]
-    B -->|No| D[Action 2]
-    C --> E[End]
-    D --> E
-```
-
-### Sequence Diagram Example
-
-```mermaid
-sequenceDiagram
-    participant Client
-    participant API
-    participant Database
-    
-    Client->>API: POST /users
-    API->>Database: INSERT user
-    Database-->>API: user_id
-    API-->>Client: 201 Created
 ```
 
-### Entity Relationship Example
+## Content Type Classification
 
-```mermaid
-erDiagram
-    USER ||--o{ ORDER : places
-    ORDER ||--|{ LINE_ITEM : contains
-    PRODUCT ||--o{ LINE_ITEM : "ordered in"
-```
-
-### State Diagram Example
+When creating documentation, classify each page using the Diátaxis framework:
 
-```mermaid
-stateDiagram-v2
-    [*] --> Pending
-    Pending --> Processing: start
-    Processing --> Completed: success
-    Processing --> Failed: error
-    Failed --> Processing: retry
-    Completed --> [*]
-```
+| Type | Template | Purpose |
+|------|----------|---------|
+| Tutorial | `tutorial.md` | Learning-oriented, build understanding |
+| How-To Guide | `how-to.md` | Task-oriented, accomplish goals |
+| Reference | `reference.md` | Information-oriented, look up facts |
+| Explanation | `explanation.md` | Understanding-oriented, comprehension |
 
-## Guidelines
+## Writing Guidelines
 
-- Start with the outcome, not the process
-- Each step should be independently verifiable
-- Include error handling in code examples
-- Link to related guides at the end
-- **Use mermaid diagrams** to visualize complex flows
-- Keep diagrams simple - max 7-10 nodes
+1. **Second Person** - "You can configure..." not "Users can configure..."
+2. **Active Voice** - "Run the command" not "The command should be run"
+3. **Task-Oriented Headings** - "How to add a custom domain" not "Custom domains"
+4. **Include Examples** - Every concept needs a code example
+5. **Progressive Disclosure** - Basic → Advanced ordering

package/ai-agents/.devdoc/templates/how-to.md

@@ -0,0 +1,166 @@
+# How-To Guide Template (Diátaxis: Task-Oriented)
+
+**Purpose:** Help users accomplish a specific real-world task.
+
+**When to use:**
+- Users need to solve a specific problem
+- Task-focused documentation
+- Practical, goal-oriented scenarios
+
+## Format
+
+```mdx
+---
+title: How to [Achieve Specific Goal]
+description: Learn how to [specific outcome]
+contentType: how-to
+---
+
+## Overview
+
+Brief introduction (2-3 sentences):
+- What this guide covers
+- Who it's for
+- What you'll achieve
+
+## Prerequisites
+
+<Note>
+Before you begin, ensure you have:
+- [Requirement 1]
+- [Requirement 2]
+</Note>
+
+## Architecture / Flow (if applicable)
+
+Use mermaid diagrams to visualize:
+
+```mermaid
+flowchart LR
+    A[Input] --> B[Process]
+    B --> C[Output]
+```
+
+## Steps
+
+<Steps>
+  <Step title="[Action verb] + [object]">
+    Explanation of what this step does and why.
+    
+    ```language
+    // Code example
+    ```
+    
+    <Tip>
+    Pro tip for this step.
+    </Tip>
+  </Step>
+  
+  <Step title="[Next action]">
+    Continue with clear, actionable steps.
+    
+    Each step should be independently verifiable.
+  </Step>
+  
+  <Step title="[Final action]">
+    Complete the task.
+  </Step>
+</Steps>
+
+## Example
+
+Complete working example showing the end result.
+
+```language
+// Full example code with all pieces together
+```
+
+## Variations
+
+<Tabs>
+  <Tab title="Option A">
+    Alternative approach for specific use case.
+  </Tab>
+  <Tab title="Option B">
+    Another variation.
+  </Tab>
+</Tabs>
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="[Common issue]">
+    **Problem:** Description of the issue.
+    
+    **Solution:** How to resolve it.
+  </Accordion>
+</AccordionGroup>
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="Related Guide" href="/path">
+    Brief description of related task
+  </Card>
+  <Card title="Reference" href="/path">
+    Deep dive into configuration options
+  </Card>
+</CardGroup>
+```
+
+## Guidelines
+
+- **Start with the outcome** - readers should know what they'll achieve
+- **Each step should be independently verifiable** - readers can check progress
+- **Use action verbs** in step titles - "Configure", "Add", "Create", "Enable"
+- **Include error handling** in code examples
+- **Provide alternatives** when multiple approaches exist
+- **Link to related guides** at the end
+- **Use mermaid diagrams** to visualize complex flows
+- **Keep diagrams simple** - max 7-10 nodes
+
+## Diátaxis Principles for How-To Guides
+
+| Principle | Application |
+|-----------|-------------|
+| Task-oriented | Focus on achieving a specific goal |
+| Practical | Solves a real problem |
+| Flexible | Can adapt to different contexts |
+| Direct | Gets to the point quickly |
+| Assumes competence | Reader knows the basics |
+
+## Mermaid Diagram Types for How-To Guides
+
+### Flowchart (for processes)
+```mermaid
+flowchart TD
+    A[Start] --> B{Decision?}
+    B -->|Yes| C[Action 1]
+    B -->|No| D[Action 2]
+    C --> E[End]
+    D --> E
+```
+
+### Sequence (for API calls)
+```mermaid
+sequenceDiagram
+    participant Client
+    participant API
+    participant Database
+    
+    Client->>API: POST /users
+    API->>Database: INSERT user
+    Database-->>API: user_id
+    API-->>Client: 201 Created
+```
+
+### State (for status transitions)
+```mermaid
+stateDiagram-v2
+    [*] --> Pending
+    Pending --> Processing: start
+    Processing --> Completed: success
+    Processing --> Failed: error
+    Failed --> Processing: retry
+    Completed --> [*]
+```