@brainfish-ai/devdoc 0.1.32 → 0.1.34

package/ai-agents/.devdoc/context.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://devdoc.sh/schemas/context.json",
+  "version": "1.0",
+  "lastUpdated": null,
+  "product": {
+    "name": "",
+    "description": "",
+    "type": null,
+    "domain": "",
+    "targetAudience": "",
+    "keyFeatures": []
+  },
+  "terminology": {
+    "glossary": {},
+    "avoidTerms": [],
+    "brandNames": {}
+  },
+  "api": {
+    "style": null,
+    "baseUrl": "",
+    "authentication": {
+      "type": null,
+      "headerName": "",
+      "description": ""
+    },
+    "conventions": {
+      "pagination": "",
+      "errorFormat": "",
+      "dateFormat": "",
+      "idFormat": ""
+    },
+    "commonPatterns": []
+  },
+  "codebase": {
+    "language": "",
+    "framework": "",
+    "sourceLocation": "../",
+    "keyDirectories": {},
+    "namingConventions": {
+      "files": "",
+      "functions": "",
+      "classes": "",
+      "variables": ""
+    }
+  },
+  "documentation": {
+    "voice": "",
+    "perspective": null,
+    "codeExamples": {
+      "primaryLanguage": "",
+      "additionalLanguages": [],
+      "style": ""
+    },
+    "templates": {
+      "guide": ".devdoc/templates/guide.md",
+      "apiReference": ".devdoc/templates/api-reference.md",
+      "tutorial": ".devdoc/templates/tutorial.md",
+      "quickstart": ".devdoc/templates/quickstart.md",
+      "troubleshooting": ".devdoc/templates/troubleshooting.md"
+    }
+  },
+  "learned": {
+    "insights": [],
+    "corrections": []
+  }
+}

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

@@ -0,0 +1,211 @@
+# API Reference Template
+
+Use this structure when creating API endpoint documentation.
+
+## Format
+
+```mdx
+---
+title: [HTTP Method] [Endpoint Name]
+description: [Brief description of what this endpoint does]
+---
+
+## Endpoint
+
+<ParamField method="POST" path="/v1/resource">
+  Brief description of the endpoint's purpose.
+</ParamField>
+
+## Request Flow
+
+Visualize the API flow with a sequence diagram:
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant API
+    participant Auth
+    participant Database
+    
+    Client->>API: POST /v1/resource
+    API->>Auth: Validate token
+    Auth-->>API: Valid
+    API->>Database: Create resource
+    Database-->>API: resource_id
+    API-->>Client: 201 Created
+```
+
+## Authentication
+
+<Note>
+This endpoint requires [authentication type]. Include your API key in the `Authorization` header.
+</Note>
+
+## Request
+
+### Headers
+
+| Header | Required | Description |
+|--------|----------|-------------|
+| `Authorization` | Yes | Bearer token or API key |
+| `Content-Type` | Yes | `application/json` |
+
+### Path Parameters
+
+<ParamField path="id" type="string" required>
+  The unique identifier of the resource.
+</ParamField>
+
+### Query Parameters
+
+<ParamField query="limit" type="integer" default="20">
+  Maximum number of results to return.
+</ParamField>
+
+### Request Body
+
+<ParamField body="name" type="string" required>
+  The name of the resource.
+</ParamField>
+
+<ParamField body="metadata" type="object">
+  Optional metadata object.
+</ParamField>
+
+## Response
+
+### Success Response (200)
+
+```json
+{
+  "id": "res_123",
+  "name": "Example",
+  "created_at": "2026-01-24T10:00:00Z"
+}
+```
+
+### Error Responses
+
+| Status | Code | Description |
+|--------|------|-------------|
+| 400 | `invalid_request` | Request validation failed |
+| 401 | `unauthorized` | Invalid or missing API key |
+| 404 | `not_found` | Resource not found |
+
+## Error Flow
+
+```mermaid
+flowchart TD
+    A[Request] --> B{Valid Auth?}
+    B -->|No| C[401 Unauthorized]
+    B -->|Yes| D{Valid Body?}
+    D -->|No| E[400 Bad Request]
+    D -->|Yes| F{Resource Exists?}
+    F -->|No| G[404 Not Found]
+    F -->|Yes| H[200 Success]
+```
+
+## Code Examples
+
+<CodeGroup>
+```bash cURL
+curl -X POST https://api.example.com/v1/resource \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Example"}'
+```
+
+```typescript TypeScript
+const response = await client.resource.create({
+  name: "Example"
+});
+```
+
+```python Python
+response = client.resource.create(
+    name="Example"
+)
+```
+</CodeGroup>
+```
+
+## Mermaid Diagram Guidelines
+
+### Sequence Diagrams for API Flows
+
+Show the complete request lifecycle:
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant G as Gateway
+    participant A as Auth
+    participant S as Service
+    participant D as Database
+    
+    C->>G: Request
+    G->>A: Validate
+    A-->>G: Token valid
+    G->>S: Forward
+    S->>D: Query
+    D-->>S: Data
+    S-->>G: Response
+    G-->>C: JSON
+```
+
+### Error Handling Flow
+
+```mermaid
+flowchart TD
+    A[API Request] --> B{Rate Limited?}
+    B -->|Yes| C[429 Too Many Requests]
+    B -->|No| D{Authenticated?}
+    D -->|No| E[401 Unauthorized]
+    D -->|Yes| F{Authorized?}
+    F -->|No| G[403 Forbidden]
+    F -->|Yes| H{Valid Request?}
+    H -->|No| I[400 Bad Request]
+    H -->|Yes| J[Process Request]
+    J --> K{Success?}
+    K -->|Yes| L[200 OK]
+    K -->|No| M[500 Server Error]
+```
+
+### Webhook Flow
+
+```mermaid
+sequenceDiagram
+    participant Your API
+    participant DevDoc
+    participant Your Server
+    
+    Your API->>DevDoc: Event occurs
+    DevDoc->>Your Server: POST /webhook
+    Your Server->>Your Server: Verify signature
+    Your Server->>Your Server: Process event
+    Your Server-->>DevDoc: 200 OK
+```
+
+### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> pending
+    pending --> processing: start_processing
+    processing --> completed: success
+    processing --> failed: error
+    failed --> processing: retry
+    completed --> [*]
+    failed --> cancelled: cancel
+    cancelled --> [*]
+```
+
+## Guidelines
+
+- Always show request and response examples
+- Include all possible error codes
+- Provide examples in multiple languages
+- Document rate limits if applicable
+- **Use sequence diagrams** for complex flows
+- **Use flowcharts** for error handling logic
+- **Use state diagrams** for resource lifecycles

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

@@ -0,0 +1,133 @@
+# Guide Template
+
+Use this structure when creating guide documentation.
+
+## Format
+
+```mdx
+---
+title: [Action] + [Topic]
+description: Learn how to [achieve specific outcome]
+---
+
+## 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="Step name">
+    Explanation of what this step does.
+    
+    ```language
+    // Code example
+    ```
+  </Step>
+  
+  <Step title="Next step">
+    Continue with clear, actionable steps.
+  </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
+
+```mermaid
+erDiagram
+    USER ||--o{ ORDER : places
+    ORDER ||--|{ LINE_ITEM : contains
+    PRODUCT ||--o{ LINE_ITEM : "ordered in"
+```
+
+### State Diagram Example
+
+```mermaid
+stateDiagram-v2
+    [*] --> Pending
+    Pending --> Processing: start
+    Processing --> Completed: success
+    Processing --> Failed: error
+    Failed --> Processing: retry
+    Completed --> [*]
+```
+
+## 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

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

@@ -0,0 +1,179 @@
+# Quickstart Template
+
+Use this structure for getting-started documentation.
+
+## Format
+
+```mdx
+---
+title: Quickstart
+description: Get up and running with [Product] in 5 minutes
+---
+
+## Overview
+
+[Product] helps you [main value proposition]. This guide gets you from zero to [first success metric] in under 5 minutes.
+
+## How It Works
+
+```mermaid
+flowchart LR
+    A[Install] --> B[Configure]
+    B --> C[First Request]
+    C --> D[Success!]
+```
+
+## 1. Install
+
+<CodeGroup>
+```bash npm
+npm install package-name
+```
+
+```bash yarn
+yarn add package-name
+```
+
+```bash pnpm
+pnpm add package-name
+```
+</CodeGroup>
+
+## 2. Configure
+
+Create a configuration file or set environment variables:
+
+```bash
+export API_KEY=your_api_key_here
+```
+
+Or create a config file:
+
+```json
+{
+  "apiKey": "your_api_key_here"
+}
+```
+
+<Note>
+Get your API key from the [dashboard](https://example.com/dashboard).
+</Note>
+
+## 3. First Request
+
+Make your first API call:
+
+```typescript
+import { Client } from 'package-name';
+
+const client = new Client({ apiKey: process.env.API_KEY });
+
+const result = await client.doSomething({
+  input: "Hello, world!"
+});
+
+console.log(result);
+```
+
+Expected output:
+
+```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
+```
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="Core Concepts" icon="book" href="/concepts">
+    Understand how [Product] works.
+  </Card>
+  <Card title="API Reference" icon="code" href="/api-reference">
+    Explore all available endpoints.
+  </Card>
+  <Card title="Examples" icon="folder" href="/examples">
+    See real-world use cases.
+  </Card>
+  <Card title="SDKs" icon="puzzle" href="/sdks">
+    Official client libraries.
+  </Card>
+</CardGroup>
+```
+
+## Mermaid Diagram Guidelines
+
+### Simple Flow for Quickstart
+
+Keep it simple - show the journey:
+
+```mermaid
+flowchart LR
+    A["📦 Install"] --> B["⚙️ Configure"]
+    B --> C["🚀 Use"]
+    C --> D["✅ Done!"]
+```
+
+### 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
+```
+
+### 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
+```
+
+## Guidelines
+
+- 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