@brainfish-ai/devdoc 0.1.31 → 0.1.33

package/ai-agents/.claude/skills/bootstrap-docs/SKILL.md

@@ -1,77 +1,203 @@
 ---
 name: bootstrap-docs
-description: Analyze repository and generate complete initial documentation structure
+description: Analyze repository and generate documentation. Reads docType from docs.json config, or asks if not set.
 ---
 
 ## Instructions
 
 When bootstrapping documentation from a repository:
 
-### Step 1: Analyze Repository Structure
-
-Scan and identify:
-- `README.md` - Project overview, installation, usage
-- `package.json` / `Cargo.toml` / `pyproject.toml` - Dependencies, scripts, metadata
-- `src/` or `lib/` - Main source code structure
-- `api/` or `routes/` - API endpoints (REST, GraphQL)
-- `components/` - UI components (React, Vue, etc.)
-- `docs/` - Existing documentation
-- `.env.example` - Environment variables
-- `docker-compose.yml` / `Dockerfile` - Deployment info
-- `openapi.json` / `swagger.yaml` - API specifications
+### Step 1: Detect Project Structure
+
+Determine where you are:
+
+**If `docs.json` exists in current directory:**
+- You're in a DevDoc docs folder
+- Source code is likely in `../` (parent directory)
+
+**If `package.json` and `src/` exist:**
+- You're at repo root
+- Create docs in `./docs/` subfolder
+
+**If neither matches:**
+- Ask user for the source code path
+
+### Step 2: Check for docType Configuration
+
+**Read `docs.json` and check for `docType` field:**
+
+```json
+{
+  "name": "Project Name",
+  "docType": "api",  // "internal" | "api" | "product"
+  ...
+}
+```
+
+**If `docType` is set:**
+- Use that value automatically
+- Tell user: "Using docType: {type} from docs.json"
+
+**If `docType` is NOT set, ask the user:**
+
+"What type of documentation are you creating?
+
+1. **internal** - For your team: setup guides, architecture, contribution guidelines
+2. **api** - For developers using your product: API reference, SDKs, integration guides
+3. **product** - For end users: feature guides, tutorials, FAQs"
+
+**IMPORTANT: After user answers, immediately update docs.json:**
+
+Add the `docType` field to docs.json so it's saved for future use:
+
+```json
+{
+  "name": "Project Name",
+  "docType": "api",  // Save their choice here
+  "navigation": { ... }
+}
+```
+
+Tell user: "Saved docType: {type} to docs.json - you won't be asked again."
+
+### Step 3: Analyze Repository
+
+Scan the source code for:
+- `README.md` - Project overview
+- `package.json` / `Cargo.toml` / `pyproject.toml` - Dependencies, metadata
+- `src/` or `lib/` - Source code structure
+- `api/` or `routes/` - API endpoints
+- `openapi.json` / `swagger.yaml` - API specs
 - `schema.graphql` - GraphQL schemas
 
-### Step 2: Generate Documentation Structure
+### Step 4: Generate Based on docType
+
+---
+
+## docType: "internal"
+
+For internal team documentation, create:
+
+```
+docs/
+├── docs.json
+├── index.mdx              # Project overview
+├── getting-started/
+│   ├── setup.mdx          # Dev environment setup
+│   ├── prerequisites.mdx  # Required tools/versions
+│   └── first-contribution.mdx
+├── architecture/
+│   ├── overview.mdx       # System architecture
+│   ├── folder-structure.mdx
+│   └── decisions.mdx      # ADRs, design decisions
+├── development/
+│   ├── workflow.mdx       # Git workflow, PR process
+│   ├── testing.mdx        # How to run/write tests
+│   ├── debugging.mdx      # Common issues, debugging tips
+│   └── deployment.mdx     # How to deploy
+├── api/                   # Internal API docs (if applicable)
+│   └── ...
+└── contributing.mdx       # Contribution guidelines
+```
+
+**Content focus:**
+- How to set up local development
+- Codebase architecture and patterns
+- Internal APIs and services
+- Debugging and troubleshooting
+- Team conventions and standards
+
+---
+
+## docType: "api"
 
-Create the following based on what's found:
+For external developers using your API/SDK, create:
 
 ```
 docs/
-├── docs.json              # Navigation config
-├── index.mdx              # Homepage (from README)
-├── quickstart.mdx         # Getting started guide
-├── installation.mdx       # Installation instructions
-├── configuration.mdx      # Environment/config setup
+├── docs.json
+├── index.mdx              # Product intro, value prop
+├── quickstart.mdx         # 5-minute getting started
+├── authentication.mdx     # Auth setup (API keys, OAuth)
 ├── guides/
-│   ├── overview.mdx       # Architecture overview
-│   └── {feature}.mdx      # Feature-specific guides
+│   ├── overview.mdx       # Concepts overview
+│   └── {use-case}.mdx     # Common use case tutorials
 ├── api-reference/
-│   ├── introduction.mdx   # API overview
-│   ├── authentication.mdx # Auth guide
-│   └── openapi.json       # (if found/generated)
-├── components/            # (if UI library)
-│   └── {component}.mdx
-└── deployment.mdx         # Deployment guide
+│   ├── introduction.mdx   # API overview, base URL, versioning
+│   ├── authentication.mdx # Auth details
+│   ├── errors.mdx         # Error codes and handling
+│   └── openapi.json       # Full API spec
+├── sdks/                  # If SDKs exist
+│   ├── javascript.mdx
+│   ├── python.mdx
+│   └── ...
+├── webhooks.mdx           # If webhooks exist
+└── changelog.mdx          # API changelog
 ```
 
-### Step 3: Content Generation
+**Content focus:**
+- Quick time-to-first-API-call
+- Authentication and authorization
+- API reference with examples
+- SDKs and client libraries
+- Error handling and troubleshooting
+- Rate limits and best practices
 
-For each page, generate:
-1. Frontmatter with title and description
-2. Clear introduction explaining the topic
-3. Code examples extracted from source
-4. Links to related documentation
+---
+
+## docType: "product"
+
+For end users of your product, create:
+
+```
+docs/
+├── docs.json
+├── index.mdx              # Product overview
+├── getting-started/
+│   ├── quickstart.mdx     # First steps
+│   ├── account-setup.mdx  # Account creation, onboarding
+│   └── key-concepts.mdx   # Core concepts explained
+├── features/
+│   ├── {feature-1}.mdx    # Feature guides
+│   ├── {feature-2}.mdx
+│   └── ...
+├── tutorials/
+│   ├── {workflow-1}.mdx   # Step-by-step tutorials
+│   └── ...
+├── integrations/          # If integrations exist
+│   └── ...
+├── troubleshooting/
+│   ├── common-issues.mdx
+│   └── faq.mdx
+└── release-notes.mdx      # What's new
+```
+
+**Content focus:**
+- Non-technical language (minimal code)
+- Screenshots and visual guides
+- Step-by-step tutorials
+- Use case focused
+- FAQs and troubleshooting
+- Feature explanations
+
+---
 
-### Step 4: Generate docs.json
+## docs.json Templates (with docType)
 
-Create navigation structure:
+### Internal Docs
 ```json
 {
-  "name": "{Project Name from package.json}",
+  "name": "{Project Name}",
+  "docType": "internal",
   "navigation": {
     "tabs": [
       {
-        "tab": "Guides",
-        "type": "docs",
+        "tab": "Documentation",
         "groups": [
-          {
-            "group": "Getting Started",
-            "pages": ["index", "quickstart", "installation"]
-          },
-          {
-            "group": "Guides",
-            "pages": ["guides/overview"]
-          }
+          { "group": "Getting Started", "pages": ["index", "getting-started/setup", "getting-started/prerequisites"] },
+          { "group": "Architecture", "pages": ["architecture/overview", "architecture/folder-structure"] },
+          { "group": "Development", "pages": ["development/workflow", "development/testing", "development/deployment"] },
+          { "group": "Contributing", "pages": ["contributing"] }
         ]
       }
     ]
@@ -79,24 +205,55 @@ Create navigation structure:
 }
 ```
 
-## What to Extract from Source Code
+### Customer API Docs
+```json
+{
+  "name": "{Product Name}",
+  "docType": "api",
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Guides",
+        "groups": [
+          { "group": "Getting Started", "pages": ["index", "quickstart", "authentication"] },
+          { "group": "Guides", "pages": ["guides/overview"] }
+        ]
+      },
+      {
+        "tab": "API Reference",
+        "type": "openapi",
+        "spec": "api-reference/openapi.json"
+      }
+    ]
+  }
+}
+```
 
-| Source | Documentation Generated |
-|--------|------------------------|
-| README.md | Homepage content, project overview |
-| package.json scripts | CLI commands, development workflow |
-| Exported functions | API reference pages |
-| React components | Component documentation with props |
-| API routes | Endpoint reference |
-| OpenAPI spec | Full API documentation |
-| GraphQL schema | GraphQL type documentation |
-| Config files | Configuration reference |
-| Tests | Usage examples |
+### Product Docs
+```json
+{
+  "name": "{Product Name}",
+  "docType": "product",
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Documentation",
+        "groups": [
+          { "group": "Getting Started", "pages": ["index", "getting-started/quickstart", "getting-started/key-concepts"] },
+          { "group": "Features", "pages": ["features/..."] },
+          { "group": "Tutorials", "pages": ["tutorials/..."] },
+          { "group": "Help", "pages": ["troubleshooting/common-issues", "troubleshooting/faq"] }
+        ]
+      }
+    ]
+  }
+}
+```
 
-## Output Quality Guidelines
+## Quality Guidelines
 
 - Extract real code examples, don't fabricate
-- Preserve existing documentation where found
-- Note areas that need human review with TODOs
-- Generate SEO-friendly descriptions
-- Include installation commands from package manager
+- Match tone to audience (technical vs non-technical)
+- Add TODO markers for sections needing human review
+- Include relevant screenshots for product docs
+- Test all code examples work

package/ai-agents/.claude/skills/check-docs/SKILL.md

@@ -1,11 +1,30 @@
 ---
 name: check-docs
-description: Quick check for documentation issues without making changes
+description: Quick health check for documentation issues without making changes. Reads docType from docs.json config.
 ---
 
 ## Instructions
 
-Run a quick audit of documentation health:
+Run a quick audit of documentation health.
+
+### First: Get Documentation Type
+
+**Read `docs.json` for `docType` field:**
+```json
+{ "docType": "api" }  // "internal" | "api" | "product"
+```
+
+**If not set, detect from structure:**
+- Has `architecture/`, `development/` → "internal"
+- Has `api-reference/`, `sdks/` → "api"
+- Has `features/`, `tutorials/` → "product"
+
+This helps tailor the checks:
+- **internal**: Should have setup guides, architecture docs
+- **api**: Should have authentication, error handling, API reference
+- **product**: Should have screenshots, tutorials, FAQs
+
+### Checks to Run:
 
 1. **Broken Links** - Check all internal href links resolve
 2. **Missing Pages** - Pages in docs.json but file doesn't exist

package/ai-agents/.claude/skills/create-doc-page/SKILL.md

@@ -1,57 +1,274 @@
 ---
 name: create-doc-page
-description: Create a new DevDoc MDX documentation page with proper structure and components
+description: Create a new documentation page. Reads docType from docs.json config, then asks about page topic and type.
 ---
 
 ## Instructions
 
 When creating a new documentation page:
 
-1. Ask for the page topic and type (guide, reference, tutorial)
-2. Generate MDX with:
-   - Proper frontmatter (title, description)
-   - Clear introduction paragraph
-   - Structured sections with H2/H3
-   - Appropriate components (Steps, Cards, Callouts)
-   - Navigation cards at the bottom
+### Step 1: Get Documentation Type from Config
 
-## Template Structure
+**Read `docs.json` for `docType` field:**
+```json
+{ "docType": "api" }  // "internal" | "api" | "product"
+```
+
+If set, use it automatically. If not set, ask user and then save their choice to docs.json.
+
+### Step 2: Gather Requirements
+
+Ask the user:
+
+1. **What is this page about?** (topic/title)
+
+2. **What kind of page?**
+   - Guide/Overview - Explains concepts
+   - Tutorial - Step-by-step walkthrough
+   - Reference - Technical specifications
+   - Troubleshooting - Problem/solution format
+
+(If `docType` not in docs.json, also ask which type of docs)
+
+### Step 2: Generate Based on Type
+
+---
+
+## Internal/Developer Docs Templates
+
+### Setup/Configuration Page
+```mdx
+---
+title: "{Feature} Setup"
+description: "How to configure {feature} for local development"
+---
+
+This guide covers setting up {feature} in your local development environment.
+
+## Prerequisites
+
+- Node.js 18+
+- Docker (optional)
+- Access to {internal resource}
+
+## Installation
+
+<Steps>
+  <Step title="Install dependencies">
+    ```bash
+    npm install
+    ```
+  </Step>
+  <Step title="Configure environment">
+    Copy `.env.example` to `.env` and set:
+    ```bash
+    FEATURE_API_KEY=your-key
+    ```
+  </Step>
+</Steps>
+
+## Configuration Options
 
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OPTION_1` | Description | `value` |
+
+## Troubleshooting
+
+<Accordion title="Common issue">
+Solution here
+</Accordion>
+```
+
+### Architecture Page
 ```mdx
 ---
-title: "{Title}"
-description: "{Description}"
+title: "{System} Architecture"
+description: "Technical overview of {system} design and components"
 ---
 
-{Introduction paragraph explaining the topic}
+Overview of how {system} is architected.
+
+## High-Level Design
+
+{Diagram or description}
+
+## Components
+
+### Component A
+{Description, responsibilities}
+
+### Component B
+{Description, responsibilities}
+
+## Data Flow
+
+<Steps>
+  <Step title="Step 1">Request comes in...</Step>
+  <Step title="Step 2">Processing...</Step>
+</Steps>
+
+## Design Decisions
+
+<Note>
+We chose X over Y because...
+</Note>
+```
+
+---
+
+## Customer API Docs Templates
+
+### API Guide Page
+```mdx
+---
+title: "{Feature} Guide"
+description: "Learn how to {action} using the {Product} API"
+---
 
-## {Section 1}
+This guide shows you how to {action} using the {Product} API.
 
-{Content with appropriate components}
+## Prerequisites
 
-## {Section 2}
+- A {Product} account ([sign up](https://...))
+- An API key ([get one here](/authentication))
 
-{More content}
+## Quick Example
+
+```javascript
+import { Client } from '{package}';
+
+const client = new Client({ apiKey: 'your-key' });
+const result = await client.feature.action();
+```
+
+## Step-by-Step
+
+<Steps>
+  <Step title="Initialize the client">
+    ```javascript
+    const client = new Client({ apiKey: process.env.API_KEY });
+    ```
+  </Step>
+  <Step title="Make your first request">
+    ```javascript
+    const response = await client.feature.action({ param: 'value' });
+    ```
+  </Step>
+</Steps>
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `param` | string | Yes | Description |
+
+## Response
+
+```json
+{
+  "id": "123",
+  "status": "success"
+}
+```
+
+## Error Handling
+
+<Warning>
+Always wrap API calls in try/catch blocks.
+</Warning>
+
+```javascript
+try {
+  const result = await client.feature.action();
+} catch (error) {
+  if (error.code === 'RATE_LIMITED') {
+    // Handle rate limiting
+  }
+}
+```
 
 ## Next Steps
 
 <CardGroup cols={2}>
-  <Card title="Related Topic" icon="icon-name" href="/path">
-    Brief description
+  <Card title="API Reference" icon="code" href="/api-reference">
+    Full API documentation
+  </Card>
+  <Card title="Examples" icon="github-logo" href="/examples">
+    See more examples
   </Card>
 </CardGroup>
 ```
 
-## Component Usage Guidelines
+---
+
+## Product/User Docs Templates
+
+### Feature Guide Page
+```mdx
+---
+title: "{Feature Name}"
+description: "Learn how to use {feature} in {Product}"
+---
 
-- Use `<Steps>` for procedural content
-- Use `<CardGroup>` for navigation/feature highlights
-- Use `<Tip>` for helpful hints
-- Use `<Warning>` for important cautions
-- Use `<Note>` for additional context
-- Use `<Accordion>` for optional/advanced details
+{Feature} helps you {benefit}. This guide walks you through everything you need to know.
+
+## Overview
+
+{Screenshot or visual}
+
+{Brief explanation of what the feature does}
+
+## Getting Started
+
+<Steps>
+  <Step title="Navigate to {Feature}">
+    Click on **Settings** → **{Feature}** in the sidebar.
+  </Step>
+  <Step title="Configure your preferences">
+    Select your preferred options...
+  </Step>
+</Steps>
+
+## Key Features
+
+<CardGroup cols={2}>
+  <Card title="Feature A" icon="star">
+    Description of capability
+  </Card>
+  <Card title="Feature B" icon="lightning">
+    Description of capability
+  </Card>
+</CardGroup>
+
+## Tips & Best Practices
+
+<Tip>
+Pro tip for getting the most out of this feature.
+</Tip>
+
+## Frequently Asked Questions
+
+<AccordionGroup>
+  <Accordion title="How do I...?">
+    Answer here
+  </Accordion>
+  <Accordion title="Can I...?">
+    Answer here
+  </Accordion>
+</AccordionGroup>
+
+## Need Help?
+
+<Card title="Contact Support" icon="chat-circle" href="/support">
+  Reach out to our support team
+</Card>
+```
+
+---
 
 ## After Creating
 
 1. Add the new page to `docs.json` navigation
 2. Link to the page from related documentation
+3. Verify all code examples work

package/ai-agents/.claude/skills/docs-from-code/SKILL.md

@@ -1,12 +1,20 @@
 ---
 name: docs-from-code
-description: Generate documentation from specific code files, functions, or modules
+description: Generate documentation from specific code files, functions, or modules. Can reference parent directory for source code.
 ---
 
 ## Instructions
 
 When generating docs from specific code:
 
+### Step 0: Locate Source Code
+
+If running from a docs folder (has `docs.json`), look for source code in:
+- Parent directory: `../src/`, `../lib/`, `../app/`
+- Or ask the user to specify the path
+
+### Step 1: Analyze Code
+
 1. Analyze the code structure and purpose
 2. Identify:
    - Public API/exports