@brainfish-ai/devdoc 0.1.28 → 0.1.30

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

@@ -0,0 +1,102 @@
+---
+name: bootstrap-docs
+description: Analyze repository and generate complete initial documentation structure
+---
+
+## 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
+- `schema.graphql` - GraphQL schemas
+
+### Step 2: Generate Documentation Structure
+
+Create the following based on what's found:
+
+```
+docs/
+├── docs.json              # Navigation config
+├── index.mdx              # Homepage (from README)
+├── quickstart.mdx         # Getting started guide
+├── installation.mdx       # Installation instructions
+├── configuration.mdx      # Environment/config setup
+├── guides/
+│   ├── overview.mdx       # Architecture overview
+│   └── {feature}.mdx      # Feature-specific guides
+├── 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
+```
+
+### Step 3: Content Generation
+
+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
+
+### Step 4: Generate docs.json
+
+Create navigation structure:
+```json
+{
+  "name": "{Project Name from package.json}",
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Guides",
+        "type": "docs",
+        "groups": [
+          {
+            "group": "Getting Started",
+            "pages": ["index", "quickstart", "installation"]
+          },
+          {
+            "group": "Guides",
+            "pages": ["guides/overview"]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## What to Extract from Source Code
+
+| 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 |
+
+## Output 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

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

@@ -0,0 +1,72 @@
+---
+name: check-docs
+description: Quick check for documentation issues without making changes
+---
+
+## Instructions
+
+Run a quick audit of documentation health:
+
+1. **Broken Links** - Check all internal href links resolve
+2. **Missing Pages** - Pages in docs.json but file doesn't exist
+3. **Orphan Pages** - MDX files not in docs.json navigation
+4. **Code Validity** - Syntax check code blocks
+5. **Outdated Examples** - Compare imports against package exports
+6. **Stale Versions** - Check version numbers against package.json
+
+## Output Format
+
+```
+Documentation Health Check
+==========================
+
+Summary: X issues found
+
+Broken Links (count)
+   file.mdx:line → /path (page not found)
+
+Outdated Code (count)
+   file.mdx:line → import { oldFunc } from 'pkg'
+   'oldFunc' no longer exported, use 'newFunc'
+
+Orphan Pages (count)
+   path/to/file.mdx (not in navigation)
+
+Missing Pages (count)
+   docs.json references 'page' but file not found
+
+All version numbers current
+All pages in docs.json exist
+No syntax errors in code blocks
+```
+
+## Checks Performed
+
+### Link Validation
+- Internal links (`href="/path"`)
+- Anchor links (`href="#section"`)
+- Cross-references between pages
+
+### Code Block Validation
+- Language tag present
+- Valid syntax (basic check)
+- Import statements resolve
+
+### Navigation Validation
+- All pages in docs.json exist
+- No duplicate entries
+- Valid group structure
+
+### Content Validation
+- Frontmatter present (title, description)
+- No H1 headings (title from frontmatter)
+- Images have alt text
+
+## Quick Fixes
+
+After running check, common fixes:
+
+1. **Broken link** → Update href or create missing page
+2. **Orphan page** → Add to docs.json or delete if unused
+3. **Missing frontmatter** → Add title and description
+4. **Outdated import** → Update to current export name

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

@@ -0,0 +1,57 @@
+---
+name: create-doc-page
+description: Create a new DevDoc MDX documentation page with proper structure and components
+---
+
+## 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
+
+## Template Structure
+
+```mdx
+---
+title: "{Title}"
+description: "{Description}"
+---
+
+{Introduction paragraph explaining the topic}
+
+## {Section 1}
+
+{Content with appropriate components}
+
+## {Section 2}
+
+{More content}
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="Related Topic" icon="icon-name" href="/path">
+    Brief description
+  </Card>
+</CardGroup>
+```
+
+## Component Usage Guidelines
+
+- 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
+
+## After Creating
+
+1. Add the new page to `docs.json` navigation
+2. Link to the page from related documentation

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

@@ -0,0 +1,73 @@
+---
+name: docs-from-code
+description: Generate documentation from specific code files, functions, or modules
+---
+
+## Instructions
+
+When generating docs from specific code:
+
+1. Analyze the code structure and purpose
+2. Identify:
+   - Public API/exports
+   - Function signatures and parameters
+   - Return types and values
+   - Usage patterns from tests or examples
+3. Generate documentation with:
+   - Overview of the module/function
+   - Parameter descriptions
+   - Code examples
+   - Common use cases
+
+## Output Format
+
+```mdx
+---
+title: "{Module/Function Name}"
+description: "{Brief purpose}"
+---
+
+{Overview paragraph}
+
+## Installation
+
+{If applicable}
+
+## Usage
+
+<Steps>
+  <Step title="Import">
+    ```typescript
+    import { function } from 'package';
+    ```
+  </Step>
+  <Step title="Basic Usage">
+    {Example code}
+  </Step>
+</Steps>
+
+## API Reference
+
+### `functionName(params)`
+
+{Description}
+
+**Parameters:**
+| Name | Type | Description |
+|------|------|-------------|
+| param1 | `type` | Description |
+
+**Returns:** `type` - Description
+
+## Examples
+
+{Practical examples with code blocks}
+```
+
+## Best Practices
+
+1. Extract real code examples - don't fabricate
+2. Include TypeScript types when available
+3. Show common use cases
+4. Document edge cases and error handling
+5. Link to related functions/modules

package/ai-agents/.claude/skills/generate-api-docs/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: generate-api-docs
+description: Generate API documentation pages from OpenAPI spec or code
+---
+
+## Instructions
+
+1. Analyze the OpenAPI spec or API code
+2. Create documentation pages for:
+   - Introduction/Overview
+   - Authentication guide
+   - Error handling
+   - Rate limiting (if applicable)
+3. Update docs.json to include API reference tab
+
+## OpenAPI Tab Configuration
+
+```json
+{
+  "tab": "API Reference",
+  "type": "openapi",
+  "path": "/api-reference",
+  "spec": "api-reference/openapi.json",
+  "groups": [
+    {
+      "group": "Overview",
+      "pages": ["api-reference/introduction", "api-reference/authentication"]
+    }
+  ]
+}
+```
+
+## GraphQL Tab Configuration
+
+```json
+{
+  "tab": "GraphQL API",
+  "type": "graphql",
+  "path": "/graphql-api",
+  "schema": "api-reference/schema.graphql",
+  "endpoint": "https://api.example.com/graphql"
+}
+```
+
+## Generated Pages
+
+### api-reference/introduction.mdx
+```mdx
+---
+title: "API Introduction"
+description: "Overview of the API"
+---
+
+Brief overview of the API capabilities.
+
+## Base URL
+
+\`\`\`
+https://api.example.com/v1
+\`\`\`
+
+## Authentication
+
+All requests require authentication. See [Authentication](/api-reference/authentication).
+```
+
+### api-reference/authentication.mdx
+```mdx
+---
+title: "Authentication"
+description: "How to authenticate API requests"
+---
+
+<Tabs>
+  <Tab title="Bearer Token">
+    Include the token in the Authorization header:
+    \`\`\`bash
+    curl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/v1/users
+    \`\`\`
+  </Tab>
+  <Tab title="API Key">
+    Include the API key in the header:
+    \`\`\`bash
+    curl -H "X-API-Key: YOUR_KEY" https://api.example.com/v1/users
+    \`\`\`
+  </Tab>
+</Tabs>
+```
+
+## After Generating
+
+1. Review and customize the generated content
+2. Add real examples from your API
+3. Update authentication details

package/ai-agents/.claude/skills/import-api-spec/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: import-api-spec
+description: Import and configure API specification (OpenAPI, GraphQL, AsyncAPI) for documentation
+---
+
+## Instructions
+
+When importing an API specification:
+
+### Step 1: Detect Spec Type
+
+| File Pattern | Type | Version |
+|--------------|------|---------|
+| `openapi.json/yaml` | OpenAPI | 3.x |
+| `swagger.json/yaml` | Swagger | 2.0 |
+| `schema.graphql` | GraphQL | - |
+| `asyncapi.json/yaml` | AsyncAPI | 2.x/3.x |
+| `*.proto` | Protobuf/gRPC | - |
+
+### Step 2: Validate & Process
+
+1. Validate spec syntax
+2. Check for $ref resolution issues
+3. Identify auth schemes
+4. Extract server URLs
+
+### Step 3: Generate Documentation
+
+For OpenAPI/Swagger:
+```
+api-reference/
+├── openapi.json          # Cleaned/validated spec
+├── introduction.mdx      # API overview from info
+├── authentication.mdx    # From securitySchemes
+├── errors.mdx           # From error response schemas
+└── rate-limiting.mdx    # If x-rateLimit extension exists
+```
+
+For GraphQL:
+```
+api-reference/
+├── schema.graphql       # Schema file
+├── introduction.mdx     # Overview
+├── authentication.mdx   # Auth guide
+├── queries.mdx          # Query documentation
+├── mutations.mdx        # Mutation documentation
+└── subscriptions.mdx    # If subscriptions exist
+```
+
+### Step 4: Update docs.json
+
+Add appropriate tab configuration:
+
+```json
+// OpenAPI
+{
+  "tab": "API Reference",
+  "type": "openapi",
+  "path": "/api-reference",
+  "spec": "api-reference/openapi.json",
+  "groups": [
+    {
+      "group": "Overview",
+      "pages": [
+        "api-reference/introduction",
+        "api-reference/authentication"
+      ]
+    }
+  ]
+}
+```
+
+```json
+// GraphQL
+{
+  "tab": "GraphQL API", 
+  "type": "graphql",
+  "path": "/graphql-api",
+  "schema": "api-reference/schema.graphql",
+  "endpoint": "https://api.example.com/graphql"
+}
+```
+
+### Step 5: Generate Supporting Pages
+
+#### introduction.mdx
+```mdx
+---
+title: "API Introduction"
+description: "Overview of the {API Name}"
+---
+
+{Description from spec info}
+
+## Base URL
+
+Production: `{server URL}`
+
+## Authentication
+
+{Summary of auth methods}
+
+See [Authentication](/api-reference/authentication) for details.
+```
+
+#### authentication.mdx
+```mdx
+---
+title: "Authentication"
+description: "How to authenticate API requests"
+---
+
+{Content based on securitySchemes}
+```

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

@@ -0,0 +1,116 @@
+---
+name: migrate-docs
+description: Migrate documentation from other platforms (Mintlify, Docusaurus, GitBook, README) to DevDoc format
+---
+
+## Instructions
+
+When migrating documentation from another platform:
+
+### Step 1: Detect Source Format
+
+Identify the documentation source by looking for:
+
+| Platform | Detection Files |
+|----------|-----------------|
+| Mintlify | `mint.json`, `.mintlify/` |
+| Docusaurus | `docusaurus.config.js`, `sidebars.js` |
+| GitBook | `SUMMARY.md`, `.gitbook.yaml` |
+| ReadMe | `readme-oas.json`, `.readme/` |
+| VuePress | `.vuepress/config.js` |
+| MkDocs | `mkdocs.yml` |
+| Sphinx | `conf.py`, `index.rst` |
+| README only | `README.md` (no other docs) |
+
+### Step 2: Migration Mappings
+
+#### Mintlify → DevDoc
+
+```
+mint.json → docs.json
+├── name → name
+├── logo → (extract to assets/logo/)
+├── favicon → favicon
+├── colors → theme.json
+├── navigation → navigation.tabs + groups
+├── topbarLinks → navbar
+├── anchors → navigation.global.anchors
+└── api → api
+
+Component Mappings:
+├── <Accordion> → <Accordion>
+├── <AccordionGroup> → <AccordionGroup>
+├── <Card> → <Card>
+├── <CardGroup> → <CardGroup>
+├── <CodeGroup> → <Tabs> with code
+├── <Tabs> → <Tabs>
+├── <Tab> → <Tab>
+├── <Info> → <Info>
+├── <Note> → <Note>
+├── <Tip> → <Tip>
+├── <Warning> → <Warning>
+├── <Check> → <Tip> (with check icon)
+├── <Steps> → <Steps>
+├── <Step> → <Step>
+├── <Frame> → (image wrapper, convert to <img>)
+├── <ResponseField> → (convert to table)
+└── <ParamField> → (convert to table)
+```
+
+#### Docusaurus → DevDoc
+
+```
+docusaurus.config.js → docs.json
+├── title → name
+├── favicon → favicon
+├── themeConfig.navbar → navbar
+├── themeConfig.footer → (extract links to anchors)
+└── docs.sidebarPath → navigation
+
+sidebars.js → navigation.tabs[].groups
+
+Component Mappings:
+├── :::note → <Note>
+├── :::tip → <Tip>
+├── :::info → <Info>
+├── :::caution → <Warning>
+├── :::danger → <Warning>
+├── <Tabs> → <Tabs>
+├── <TabItem> → <Tab>
+└── import/export → (inline or convert to snippets)
+```
+
+#### GitBook → DevDoc
+
+```
+SUMMARY.md → docs.json navigation
+├── # Group → groups[].group
+├── * [Page](path.md) → groups[].pages[]
+└── Nested items → nested groups
+
+Component Mappings:
+├── {% hint style="info" %} → <Info>
+├── {% hint style="warning" %} → <Warning>
+├── {% hint style="danger" %} → <Warning>
+├── {% hint style="success" %} → <Tip>
+├── {% tabs %} → <Tabs>
+├── {% tab title="X" %} → <Tab title="X">
+├── {% code title="X" %} → ```language title="X"
+└── {% embed url="X" %} → <iframe> or link
+```
+
+### Step 3: Execute Migration
+
+1. Convert configuration files
+2. Transform MDX/MD content with component mappings
+3. Copy and organize assets
+4. Generate docs.json navigation
+5. Create theme.json from color settings
+
+### Step 4: Post-Migration Validation
+
+After migration:
+1. Run `/check-docs` to verify all links work
+2. Preview with `devdoc dev`
+3. Check component rendering
+4. Verify navigation structure