@brainfish-ai/devdoc 0.1.32 → 0.1.34

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

@@ -0,0 +1,215 @@
+# Troubleshooting Template
+
+Use this structure for troubleshooting and FAQ documentation.
+
+## Format
+
+```mdx
+---
+title: Troubleshooting [Topic]
+description: Solutions for common [Topic] issues
+---
+
+## Decision Tree
+
+Use this to find your issue:
+
+```mermaid
+flowchart TD
+    A[Having Issues?] --> B{Can you install?}
+    B -->|No| C[Installation Issues]
+    B -->|Yes| D{Can you authenticate?}
+    D -->|No| E[Auth Issues]
+    D -->|Yes| F{Getting errors?}
+    F -->|Yes| G[Error Reference]
+    F -->|No| H[Performance Issues]
+    
+    click C "#installation-issues"
+    click E "#authentication-issues"
+    click G "#error-reference"
+    click H "#performance-issues"
+```
+
+## Common Issues
+
+### Error: [Exact error message]
+
+<Accordion title="[Short description of the error]">
+**Symptoms:**
+- What the user sees
+- When it typically occurs
+
+**Cause:**
+Brief explanation of why this happens.
+
+**Solution:**
+
+<Steps>
+  <Step title="Check [first thing]">
+    ```bash
+    command to diagnose
+    ```
+  </Step>
+  <Step title="Fix [the issue]">
+    ```bash
+    command to fix
+    ```
+  </Step>
+</Steps>
+
+**Prevention:**
+How to avoid this in the future.
+</Accordion>
+
+### [Another common issue]
+
+<Accordion title="[Description]">
+**Symptoms:**
+- Symptom 1
+- Symptom 2
+
+**Cause:**
+Explanation.
+
+**Solution:**
+Step-by-step fix.
+</Accordion>
+
+## Error Flow Reference
+
+```mermaid
+flowchart LR
+    subgraph "400 Errors"
+        A[400 Bad Request]
+        B[401 Unauthorized]
+        C[403 Forbidden]
+        D[404 Not Found]
+        E[429 Rate Limited]
+    end
+    subgraph "500 Errors"
+        F[500 Server Error]
+        G[502 Bad Gateway]
+        H[503 Unavailable]
+    end
+```
+
+## Diagnostic Commands
+
+Useful commands for debugging:
+
+```bash
+# Check version
+package-name --version
+
+# Verify configuration
+package-name config validate
+
+# Test connection
+package-name ping
+
+# Debug mode
+DEBUG=* package-name command
+```
+
+## Connection Troubleshooting
+
+```mermaid
+sequenceDiagram
+    participant You
+    participant CLI
+    participant API
+    
+    You->>CLI: Run command
+    CLI->>API: Connect
+    
+    alt Success
+        API-->>CLI: 200 OK
+        CLI-->>You: ✓ Connected
+    else Timeout
+        API--xCLI: Timeout
+        CLI-->>You: ✗ Connection timeout
+        Note over You,CLI: Check network/firewall
+    else Auth Error
+        API-->>CLI: 401 Unauthorized
+        CLI-->>You: ✗ Invalid API key
+        Note over You,CLI: Regenerate API key
+    end
+```
+
+## Getting Help
+
+If you're still experiencing issues:
+
+1. **Search existing issues:** [GitHub Issues](https://github.com/org/repo/issues)
+2. **Community support:** [Discord](https://discord.gg/example)
+3. **Contact support:** [support@example.com](mailto:support@example.com)
+
+When reporting an issue, include:
+- Error message (full stack trace)
+- Package version (`package-name --version`)
+- Environment (OS, Node version, etc.)
+- Steps to reproduce
+```
+
+## Mermaid Diagram Guidelines
+
+### Decision Trees
+
+Help users find their issue:
+
+```mermaid
+flowchart TD
+    A{What's happening?}
+    A -->|Can't install| B[Check Node version >= 18]
+    A -->|Can't connect| C[Check API key]
+    A -->|Slow performance| D[Check rate limits]
+    A -->|Unexpected results| E[Check request params]
+    
+    B --> B1[npm cache clean]
+    C --> C1[Regenerate key]
+    D --> D1[Implement caching]
+    E --> E1[Enable debug mode]
+```
+
+### Error Code Reference
+
+```mermaid
+flowchart LR
+    subgraph Client["Client Errors (4xx)"]
+        A[400] --> A1[Bad Request]
+        B[401] --> B1[Unauthorized]
+        C[403] --> C1[Forbidden]
+        D[404] --> D1[Not Found]
+        E[429] --> E1[Rate Limited]
+    end
+    subgraph Server["Server Errors (5xx)"]
+        F[500] --> F1[Server Error]
+        G[502] --> G1[Bad Gateway]
+        H[503] --> H1[Unavailable]
+    end
+```
+
+### Retry Logic
+
+```mermaid
+flowchart TD
+    A[Request] --> B{Success?}
+    B -->|Yes| C[Done]
+    B -->|No| D{Retryable?}
+    D -->|No| E[Fail]
+    D -->|Yes| F{Retries < 3?}
+    F -->|No| E
+    F -->|Yes| G[Wait with backoff]
+    G --> A
+```
+
+## Guidelines
+
+- Use exact error messages as headings (searchable)
+- Provide copy-paste solutions
+- Include diagnostic commands
+- Explain the "why" not just the "how"
+- Link to support channels
+- **Use decision trees** to guide users to solutions
+- **Use sequence diagrams** for debugging flows
+- **Use flowcharts** for retry/error handling logic

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

@@ -0,0 +1,212 @@
+# Tutorial Template
+
+Use this structure when creating step-by-step tutorials.
+
+## Format
+
+```mdx
+---
+title: Build [Something] with [Technology]
+description: A complete tutorial to [achieve outcome] from scratch
+---
+
+## What You'll Build
+
+[Screenshot or diagram of the final result]
+
+Brief description of the end result and why it's useful.
+
+**Time to complete:** ~X minutes
+
+## Architecture Overview
+
+Show the system architecture with a mermaid diagram:
+
+```mermaid
+flowchart TB
+    subgraph Frontend
+        A[React App]
+    end
+    subgraph Backend
+        B[API Server]
+        C[Database]
+    end
+    A -->|REST API| B
+    B --> C
+```
+
+## Prerequisites
+
+- [Prerequisite 1 with link]
+- [Prerequisite 2 with link]
+- Basic knowledge of [topic]
+
+## Project Setup
+
+<Steps>
+  <Step title="Create a new project">
+    ```bash
+    mkdir my-project && cd my-project
+    npm init -y
+    ```
+  </Step>
+  
+  <Step title="Install dependencies">
+    ```bash
+    npm install package-name
+    ```
+  </Step>
+</Steps>
+
+## Part 1: [First Major Section]
+
+### Step 1.1: [Specific Task]
+
+Explanation of what we're doing and why.
+
+```language
+// Code with comments explaining key parts
+```
+
+<Tip>
+Pro tip or best practice related to this step.
+</Tip>
+
+### Step 1.2: [Next Task]
+
+Continue building on the previous step.
+
+## Part 2: [Second Major Section]
+
+### Data Flow
+
+Visualize the data flow:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Frontend
+    participant API
+    participant DB
+    
+    User->>Frontend: Click button
+    Frontend->>API: POST /action
+    API->>DB: Query
+    DB-->>API: Result
+    API-->>Frontend: Response
+    Frontend-->>User: Update UI
+```
+
+### Step 2.1: [Task]
+
+Break complex tutorials into logical parts.
+
+## Testing Your Implementation
+
+How to verify everything works:
+
+```bash
+npm test
+# or
+npm run dev
+```
+
+Expected output:
+```
+✓ All tests passed
+```
+
+## Troubleshooting
+
+<Accordion title="Error: [Common error message]">
+  **Cause:** Explanation of why this happens.
+  
+  **Solution:** How to fix it.
+</Accordion>
+
+## Next Steps
+
+Now that you've built [X], you can:
+
+- [Enhancement 1]
+- [Enhancement 2]
+- [Related tutorial link]
+
+## Complete Code
+
+<Accordion title="View complete source code">
+```language
+// Full working code
+```
+</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
+- **Use architecture diagrams** at the start
+- **Use sequence diagrams** for API interactions
+- **Use flowcharts** for decision logic

package/ai-agents/CLAUDE.md

@@ -2,6 +2,15 @@
 
 This is a DevDoc documentation project using MDX (Markdown + React components).
 
+## Source Code Location
+
+If this docs folder is inside a larger repository, the source code is in the parent directory:
+- Source code: `../src/` or `../lib/`
+- Package config: `../package.json`
+- README: `../README.md`
+
+When generating documentation, always check the parent directory (`../`) for source code to document.
+
 ## Project Structure
 
 ```
@@ -188,7 +197,10 @@ If you have Claude Code skills installed (`devdoc ai`):
 
 - `/bootstrap-docs` - Generate documentation from codebase
 - `/migrate-docs` - Migrate from other platforms
-- `/sync-docs` - Update outdated documentation
+- `/import-api-spec` - Import OpenAPI, GraphQL, or AsyncAPI specs
 - `/check-docs` - Health check for docs
-- `/create-doc-page` - Create new MDX page
-- `/update-docs-json` - Update navigation
+- `/blame-doc` - Find duplicates, outdated content, discrepancies
+- `/create-doc` - Create new documentation page
+- `/update-doc` - Update existing documentation
+- `/delete-doc` - Delete documentation pages
+- `/commit-doc` - Commit documentation changes

package/ai-agents/schemas/context.schema.json

@@ -0,0 +1,259 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://devdoc.sh/schemas/context.json",
+  "title": "DevDoc Context Memory",
+  "description": "AI agent context memory for understanding and documenting products consistently",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference"
+    },
+    "version": {
+      "type": "string",
+      "description": "Schema version",
+      "default": "1.0"
+    },
+    "lastUpdated": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of last update"
+    },
+    "product": {
+      "type": "object",
+      "description": "Core product information",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Product or company name"
+        },
+        "description": {
+          "type": "string",
+          "description": "Brief description of what the product does"
+        },
+        "type": {
+          "type": "string",
+          "enum": ["api", "sdk", "platform", "cli", "library", "saas", "other"],
+          "description": "Type of product being documented"
+        },
+        "domain": {
+          "type": "string",
+          "description": "Industry or domain (e.g., fintech, healthcare, devtools)"
+        },
+        "targetAudience": {
+          "type": "string",
+          "description": "Primary audience for the documentation"
+        },
+        "keyFeatures": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Main features or capabilities"
+        }
+      }
+    },
+    "terminology": {
+      "type": "object",
+      "description": "Product-specific terminology and language rules",
+      "properties": {
+        "glossary": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Term definitions (key: term, value: definition)"
+        },
+        "avoidTerms": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "wrong": { "type": "string" },
+              "correct": { "type": "string" },
+              "reason": { "type": "string" }
+            },
+            "required": ["wrong", "correct"]
+          },
+          "description": "Terms to avoid and their correct alternatives"
+        },
+        "brandNames": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Correct capitalization/spelling of brand names"
+        }
+      }
+    },
+    "api": {
+      "type": "object",
+      "description": "API-specific information (if applicable)",
+      "properties": {
+        "style": {
+          "type": "string",
+          "enum": ["REST", "GraphQL", "gRPC", "WebSocket", "mixed"],
+          "description": "API architecture style"
+        },
+        "baseUrl": {
+          "type": "string",
+          "description": "Base URL for API requests"
+        },
+        "authentication": {
+          "type": "object",
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": ["api_key", "oauth2", "jwt", "basic", "bearer", "custom"],
+              "description": "Authentication method"
+            },
+            "headerName": {
+              "type": "string",
+              "description": "Header name for auth (if applicable)"
+            },
+            "description": {
+              "type": "string",
+              "description": "How to obtain/use credentials"
+            }
+          }
+        },
+        "conventions": {
+          "type": "object",
+          "properties": {
+            "pagination": { "type": "string" },
+            "errorFormat": { "type": "string" },
+            "dateFormat": { "type": "string" },
+            "idFormat": { "type": "string" }
+          },
+          "description": "API conventions and patterns"
+        },
+        "commonPatterns": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Common patterns used across the API"
+        }
+      }
+    },
+    "codebase": {
+      "type": "object",
+      "description": "Source code information",
+      "properties": {
+        "language": {
+          "type": "string",
+          "description": "Primary programming language"
+        },
+        "framework": {
+          "type": "string",
+          "description": "Main framework used"
+        },
+        "sourceLocation": {
+          "type": "string",
+          "description": "Relative path to source code from docs folder"
+        },
+        "keyDirectories": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Important directories in the codebase"
+        },
+        "namingConventions": {
+          "type": "object",
+          "properties": {
+            "files": { "type": "string" },
+            "functions": { "type": "string" },
+            "classes": { "type": "string" },
+            "variables": { "type": "string" }
+          },
+          "description": "Code naming conventions"
+        }
+      }
+    },
+    "documentation": {
+      "type": "object",
+      "description": "Documentation style and conventions",
+      "properties": {
+        "voice": {
+          "type": "string",
+          "description": "Writing voice (e.g., professional, friendly, technical)"
+        },
+        "perspective": {
+          "type": "string",
+          "enum": ["first_person", "second_person", "third_person"],
+          "description": "Writing perspective"
+        },
+        "codeExamples": {
+          "type": "object",
+          "properties": {
+            "primaryLanguage": {
+              "type": "string",
+              "description": "Default language for code examples"
+            },
+            "additionalLanguages": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Other languages to include"
+            },
+            "style": {
+              "type": "string",
+              "description": "Code example style (e.g., complete, minimal)"
+            }
+          }
+        },
+        "templates": {
+          "type": "object",
+          "properties": {
+            "guide": { 
+              "type": "string",
+              "description": "Path to guide template file"
+            },
+            "apiReference": { 
+              "type": "string",
+              "description": "Path to API reference template file"
+            },
+            "tutorial": { 
+              "type": "string",
+              "description": "Path to tutorial template file"
+            },
+            "quickstart": { 
+              "type": "string",
+              "description": "Path to quickstart template file"
+            },
+            "troubleshooting": { 
+              "type": "string",
+              "description": "Path to troubleshooting template file"
+            }
+          },
+          "description": "Paths to documentation template files"
+        }
+      }
+    },
+    "learned": {
+      "type": "object",
+      "description": "Information learned during documentation sessions",
+      "properties": {
+        "insights": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "date": { "type": "string", "format": "date" },
+              "category": { "type": "string" },
+              "insight": { "type": "string" },
+              "source": { "type": "string" }
+            },
+            "required": ["date", "insight"]
+          },
+          "description": "Discovered patterns and insights"
+        },
+        "corrections": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "date": { "type": "string", "format": "date" },
+              "wrong": { "type": "string" },
+              "correct": { "type": "string" },
+              "context": { "type": "string" }
+            },
+            "required": ["date", "wrong", "correct"]
+          },
+          "description": "Corrections made based on user feedback"
+        }
+      }
+    }
+  },
+  "required": ["version"]
+}