@brainfish-ai/devdoc 0.1.39 → 0.1.41

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

@@ -1,6 +1,11 @@
-# Quickstart Template
+# Quickstart Template (Diátaxis: Tutorial)
 
-Use this structure for getting-started documentation.
+**Purpose:** Get users to their first success in minimal time.
+
+**When to use:**
+- First page new users see after the intro
+- 5-10 minute "time to hello world"
+- Builds confidence and momentum
 
 ## Format
 
@@ -8,172 +13,146 @@ Use this structure for getting-started documentation.
 ---
 title: Quickstart
 description: Get up and running with [Product] in 5 minutes
+contentType: tutorial
 ---
 
 ## Overview
 
-[Product] helps you [main value proposition]. This guide gets you from zero to [first success metric] in under 5 minutes.
+In this quickstart, you'll learn how to:
 
-## How It Works
+- [Outcome 1]
+- [Outcome 2]
+- [Outcome 3]
 
-```mermaid
-flowchart LR
-    A[Install] --> B[Configure]
-    B --> C[First Request]
-    C --> D[Success!]
-```
+**Time to complete:** ~5 minutes
 
-## 1. Install
+## Prerequisites
 
-<CodeGroup>
-```bash npm
-npm install package-name
-```
+<Note>
+Before you begin, ensure you have:
+- [Prerequisite 1]
+- [Prerequisite 2]
+</Note>
 
-```bash yarn
-yarn add package-name
-```
+## Step 1: [First Action]
 
-```bash pnpm
-pnpm add package-name
-```
-</CodeGroup>
+Brief explanation of what we're doing.
 
-## 2. Configure
+<Tabs>
+  <Tab title="npm">
+    ```bash
+    npm install package-name
+    ```
+  </Tab>
+  <Tab title="yarn">
+    ```bash
+    yarn add package-name
+    ```
+  </Tab>
+  <Tab title="pnpm">
+    ```bash
+    pnpm add package-name
+    ```
+  </Tab>
+</Tabs>
 
-Create a configuration file or set environment variables:
+## Step 2: [Second Action]
 
-```bash
-export API_KEY=your_api_key_here
-```
+Explanation of this step.
 
-Or create a config file:
+```typescript
+// Code example with comments
+import { something } from 'package';
 
-```json
-{
-  "apiKey": "your_api_key_here"
-}
+const result = something();
 ```
 
-<Note>
-Get your API key from the [dashboard](https://example.com/dashboard).
-</Note>
-
-## 3. First Request
+## Step 3: [Third Action]
 
-Make your first API call:
+Final step to complete the quickstart.
 
 ```typescript
-import { Client } from 'package-name';
+// Final code
+console.log('Success!');
+```
 
-const client = new Client({ apiKey: process.env.API_KEY });
+## Verify It Works
 
-const result = await client.doSomething({
-  input: "Hello, world!"
-});
+Run the following to confirm everything is set up:
 
-console.log(result);
+```bash
+npm run dev
 ```
 
-Expected output:
+You should see:
 
-```json
-{
-  "success": true,
-  "data": "..."
-}
 ```
-
-## What Happens Behind the Scenes
-
-```mermaid
-sequenceDiagram
-    participant You
-    participant SDK
-    participant API
-    
-    You->>SDK: client.doSomething()
-    SDK->>API: POST /v1/action
-    API-->>SDK: Response
-    SDK-->>You: Result object
+✓ Server started on http://localhost:3000
 ```
 
+<Tip>
+If you see an error, check the [Troubleshooting](/troubleshooting) guide.
+</Tip>
+
+## What You've Built
+
+Congratulations! You now have:
+
+- [Achievement 1]
+- [Achievement 2]
+- [Achievement 3]
+
 ## Next Steps
 
 <CardGroup cols={2}>
-  <Card title="Core Concepts" icon="book" href="/concepts">
-    Understand how [Product] works.
+  <Card title="Core Concepts" icon="book-open" href="/concepts">
+    Understand the key concepts
   </Card>
-  <Card title="API Reference" icon="code" href="/api-reference">
-    Explore all available endpoints.
+  <Card title="Full Tutorial" icon="graduation-cap" href="/tutorial">
+    Build a complete project
   </Card>
-  <Card title="Examples" icon="folder" href="/examples">
-    See real-world use cases.
+  <Card title="Configuration" icon="gear" href="/config">
+    Customize your setup
   </Card>
-  <Card title="SDKs" icon="puzzle" href="/sdks">
-    Official client libraries.
+  <Card title="API Reference" icon="code" href="/reference">
+    Explore the full API
   </Card>
 </CardGroup>
 ```
 
-## Mermaid Diagram Guidelines
+## Guidelines
 
-### Simple Flow for Quickstart
+- **Keep it short** - 5 minutes or less
+- **Show immediate value** - User sees something working fast
+- **Use tabs for alternatives** - npm/yarn/pnpm, different languages
+- **End with success** - User should feel accomplished
+- **Link forward** - Guide to next learning steps
+- **Minimal explanation** - Save deep dives for tutorials
 
-Keep it simple - show the journey:
+## Diátaxis Principles for Quickstart
 
-```mermaid
-flowchart LR
-    A["📦 Install"] --> B["⚙️ Configure"]
-    B --> C["🚀 Use"]
-    C --> D["✅ Done!"]
-```
+| Principle | Application |
+|-----------|-------------|
+| Learning-oriented | User builds understanding through action |
+| Minimal | Only essential steps, no extras |
+| Success-focused | Every step moves toward working result |
+| Motivating | Builds confidence for deeper learning |
 
-### SDK Architecture
-
-```mermaid
-flowchart TB
-    subgraph "Your App"
-        A[Your Code]
-    end
-    subgraph "SDK"
-        B[Client]
-        C[Auth]
-        D[Retry Logic]
-    end
-    subgraph "Cloud"
-        E[API]
-    end
-    A --> B
-    B --> C
-    B --> D
-    B --> E
-```
+## Quick vs Tutorial
 
-### Authentication Flow
-
-```mermaid
-sequenceDiagram
-    participant App
-    participant SDK
-    participant Auth
-    participant API
-    
-    App->>SDK: Initialize with API key
-    SDK->>Auth: Validate key
-    Auth-->>SDK: Valid
-    App->>SDK: Make request
-    SDK->>API: Authenticated request
-    API-->>SDK: Response
-    SDK-->>App: Data
-```
+| Quickstart | Tutorial |
+|------------|----------|
+| 5 minutes | 15-30 minutes |
+| Essential steps only | Comprehensive learning |
+| Working result | Deep understanding |
+| Links to more | Self-contained |
+| One path | Multiple sections |
 
-## Guidelines
+## Content Type
+
+Quickstarts are a specialized form of **Tutorial** (learning-oriented):
 
-- Keep it under 5 minutes to complete
-- Use the minimum viable example
-- Show expected output at each step
-- Link to deeper documentation at the end
-- Include multiple installation methods
-- **Use simple flowcharts** to show the process
-- **Use sequence diagrams** to explain what happens
+```yaml
+contentType: tutorial
+subType: quickstart
+```

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

@@ -0,0 +1,264 @@
+# Reference Template (Diátaxis: Information-Oriented)
+
+**Purpose:** Provide accurate, complete information for lookup.
+
+**When to use:**
+- API documentation
+- Configuration options
+- Component props
+- CLI commands
+- Error codes
+
+## Format
+
+```mdx
+---
+title: [Component/API/Config] Reference
+description: Complete reference for [topic]
+contentType: reference
+---
+
+## Overview
+
+Brief description of what this reference covers and when to use it.
+
+## Properties / Parameters
+
+| Property | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `name` | `string` | Yes | - | The display name |
+| `enabled` | `boolean` | No | `true` | Whether feature is enabled |
+| `options` | `Options` | No | `{}` | Configuration options |
+
+## Type Definitions
+
+```typescript
+interface Options {
+  /** Maximum number of items */
+  maxItems?: number;
+  
+  /** Callback when item is selected */
+  onSelect?: (item: Item) => void;
+  
+  /** Custom renderer */
+  render?: (item: Item) => React.ReactNode;
+}
+
+interface Item {
+  id: string;
+  label: string;
+  value: unknown;
+}
+```
+
+## Methods / Functions
+
+### `functionName(params)`
+
+Brief description of what this function does.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `param1` | `string` | Yes | Description |
+| `param2` | `Options` | No | Configuration |
+
+**Returns:** `ReturnType` - Description of return value.
+
+**Throws:**
+- `ErrorType` - When this error occurs.
+
+**Example:**
+
+```typescript
+const result = functionName('value', { option: true });
+```
+
+## Configuration Options
+
+### `configOption`
+
+<Note>
+This option requires [prerequisite].
+</Note>
+
+**Type:** `string | string[]`
+
+**Default:** `"default"`
+
+Description of what this option does and when to use it.
+
+```json
+{
+  "configOption": "value"
+}
+```
+
+## Error Codes
+
+| Code | Name | Description | Resolution |
+|------|------|-------------|------------|
+| `E001` | `InvalidInput` | Input validation failed | Check input format |
+| `E002` | `NotFound` | Resource not found | Verify resource exists |
+| `E003` | `Unauthorized` | Authentication required | Add auth header |
+
+## Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `MAX_SIZE` | `1000` | Maximum allowed size |
+| `DEFAULT_TIMEOUT` | `30000` | Default timeout in ms |
+
+## Examples
+
+### Basic Usage
+
+```typescript
+import { Component } from 'package';
+
+const instance = new Component({
+  name: 'example',
+  enabled: true,
+});
+```
+
+### Advanced Usage
+
+```typescript
+import { Component, Options } from 'package';
+
+const options: Options = {
+  maxItems: 100,
+  onSelect: (item) => console.log(item),
+};
+
+const instance = new Component({
+  name: 'advanced',
+  options,
+});
+```
+
+## Related
+
+- [Configuration Guide](/config) - How to configure this feature
+- [Tutorial](/tutorial) - Step-by-step introduction
+- [Other Reference](/other) - Related reference documentation
+```
+
+## Guidelines
+
+- **Be accurate** - Every detail must be correct
+- **Be complete** - Cover all properties, methods, options
+- **Be consistent** - Use same format throughout
+- **Be concise** - No unnecessary explanation
+- **Include types** - Always show TypeScript types
+- **Show examples** - Every feature needs an example
+- **Link to context** - Point to related how-tos and tutorials
+
+## Diátaxis Principles for Reference
+
+| Principle | Application |
+|-----------|-------------|
+| Information-oriented | Focus on describing accurately |
+| Consistent | Same structure for similar items |
+| Complete | Cover everything, omit nothing |
+| Neutral | No opinions, just facts |
+| Well-organized | Easy to find specific info |
+
+## Reference Patterns
+
+### API Endpoint Reference
+
+```mdx
+### `POST /users`
+
+Create a new user.
+
+**Request Body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `email` | `string` | Yes | User email |
+| `name` | `string` | Yes | Display name |
+
+**Response:** `201 Created`
+
+```json
+{
+  "id": "usr_123",
+  "email": "user@example.com",
+  "name": "John Doe",
+  "createdAt": "2026-01-25T10:00:00Z"
+}
+```
+
+**Errors:**
+
+| Status | Code | Description |
+|--------|------|-------------|
+| `400` | `VALIDATION_ERROR` | Invalid input |
+| `409` | `ALREADY_EXISTS` | Email taken |
+```
+
+### CLI Command Reference
+
+```mdx
+### `devdoc deploy`
+
+Deploy documentation to DevDoc hosting.
+
+**Usage:**
+
+```bash
+devdoc deploy [options]
+```
+
+**Options:**
+
+| Flag | Short | Description | Default |
+|------|-------|-------------|---------|
+| `--project` | `-p` | Project ID | From config |
+| `--branch` | `-b` | Target branch | `main` |
+| `--message` | `-m` | Deploy message | Auto |
+| `--dry-run` | | Preview without deploying | `false` |
+
+**Examples:**
+
+```bash
+# Basic deploy
+devdoc deploy
+
+# Deploy to specific project
+devdoc deploy --project proj_123
+
+# Preview changes
+devdoc deploy --dry-run
+```
+```
+
+### Component Props Reference
+
+```mdx
+### `<Button>`
+
+A customizable button component.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'primary' \| 'secondary' \| 'ghost'` | `'primary'` | Button style |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button size |
+| `disabled` | `boolean` | `false` | Disable button |
+| `onClick` | `() => void` | - | Click handler |
+| `children` | `React.ReactNode` | - | Button content |
+
+**Example:**
+
+```tsx
+<Button variant="primary" size="lg" onClick={handleClick}>
+  Click me
+</Button>
+```
+```

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

@@ -1,6 +1,11 @@
-# Tutorial Template
+# Tutorial Template (Diátaxis: Learning-Oriented)
 
-Use this structure when creating step-by-step tutorials.
+**Purpose:** Guide users through a learning experience to build understanding.
+
+**When to use:**
+- First-time user experiences
+- Teaching new concepts hands-on
+- Building something from scratch
 
 ## Format
 
@@ -8,6 +13,7 @@ Use this structure when creating step-by-step tutorials.
 ---
 title: Build [Something] with [Technology]
 description: A complete tutorial to [achieve outcome] from scratch
+contentType: tutorial
 ---
 
 ## What You'll Build
@@ -20,7 +26,7 @@ Brief description of the end result and why it's useful.
 
 ## Architecture Overview
 
-Show the system architecture with a mermaid diagram:
+Show the system with a mermaid diagram:
 
 ```mermaid
 flowchart TB
@@ -118,11 +124,13 @@ Expected output:
 
 ## Troubleshooting
 
-<Accordion title="Error: [Common error message]">
-  **Cause:** Explanation of why this happens.
-  
-  **Solution:** How to fix it.
-</Accordion>
+<AccordionGroup>
+  <Accordion title="Error: [Common error message]">
+    **Cause:** Explanation of why this happens.
+    
+    **Solution:** How to fix it.
+  </Accordion>
+</AccordionGroup>
 
 ## Next Steps
 
@@ -132,6 +140,15 @@ Now that you've built [X], you can:
 - [Enhancement 2]
 - [Related tutorial link]
 
+<CardGroup cols={2}>
+  <Card title="Next Tutorial" href="/path">
+    Continue learning with the next tutorial
+  </Card>
+  <Card title="Reference" href="/path">
+    Deep dive into the API reference
+  </Card>
+</CardGroup>
+
 ## Complete Code
 
 <Accordion title="View complete source code">
@@ -141,72 +158,23 @@ Now that you've built [X], you can:
 </Accordion>
 ```
 
-## Mermaid Diagram Guidelines
-
-### Architecture Diagrams
-
-Use subgraphs to group related components:
-
-```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
-```
-
-### Process Flow
-
-Show the build/deploy process:
-
-```mermaid
-flowchart LR
-    A[Code] --> B[Build]
-    B --> C[Test]
-    C --> D{Pass?}
-    D -->|Yes| E[Deploy]
-    D -->|No| F[Fix]
-    F --> B
-```
-
-### Class/Component Diagram
-
-```mermaid
-classDiagram
-    class User {
-        +String id
-        +String email
-        +create()
-        +update()
-    }
-    class Order {
-        +String id
-        +String userId
-        +submit()
-    }
-    User "1" --> "*" Order
-```
-
 ## Guidelines
 
-- Show the end result first to motivate readers
-- Break into digestible parts (10-15 min each)
-- Include checkpoints where readers can verify progress
-- Provide complete code at the end for reference
-- Add troubleshooting for common issues
+- **Show the end result first** to motivate readers
+- **Break into digestible parts** (10-15 min each)
+- **Include checkpoints** where readers can verify progress
+- **Provide complete code** at the end for reference
+- **Add troubleshooting** for common issues
 - **Use architecture diagrams** at the start
 - **Use sequence diagrams** for API interactions
 - **Use flowcharts** for decision logic
+
+## Diátaxis Principles for Tutorials
+
+| Principle | Application |
+|-----------|-------------|
+| Learning-oriented | Focus on building understanding, not just completing tasks |
+| Practical | Users learn by doing something meaningful |
+| Safe | Mistakes are ok - provide recovery paths |
+| Structured | Clear beginning, middle, end with milestones |
+| Repeatable | Can be followed step-by-step to same result |