@brainfish-ai/devdoc 0.1.28 → 0.1.30

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

@@ -0,0 +1,112 @@
+---
+name: sync-docs
+description: Analyze existing documentation against codebase and identify/fix outdated content
+---
+
+## Instructions
+
+When syncing documentation with the codebase:
+
+### Step 1: Build Documentation Inventory
+
+Scan all MDX files and extract:
+- Documented functions, classes, components
+- Code examples and their imports
+- API endpoints referenced
+- Package versions mentioned
+- CLI commands documented
+
+### Step 2: Analyze Current Codebase
+
+Compare documentation against source code:
+- Check if documented functions still exist
+- Verify function signatures match (parameters, return types)
+- Confirm API endpoints are still valid
+- Check if package versions are current
+- Identify new exports not yet documented
+
+### Step 3: Generate Sync Report
+
+Output a report categorizing issues:
+
+```
+## Documentation Sync Report
+
+### Outdated (Breaking Changes)
+- `docs/api/users.mdx`: `createUser()` signature changed
+  - Documented: `createUser(name: string)`
+  - Current: `createUser(data: UserInput)`
+
+### Outdated (Minor Changes)  
+- `docs/quickstart.mdx`: Package version outdated
+  - Documented: `v1.2.0`
+  - Current: `v1.5.0`
+
+### Missing Documentation
+- `src/utils/validator.ts` - New export, not documented
+- `POST /api/v2/webhooks` - New endpoint, not documented
+
+### Up to Date
+- `docs/guides/authentication.mdx`
+- `docs/components/button.mdx`
+```
+
+### Step 4: Update Options
+
+Ask user preference:
+1. **Auto-fix all** - Update all outdated docs automatically
+2. **Interactive** - Review each change before applying
+3. **Report only** - Just show the report, don't change anything
+
+### Step 5: Apply Updates
+
+When updating:
+- Preserve existing prose and explanations
+- Update code examples to match current signatures
+- Add TODO markers for sections needing human review
+- Update version numbers
+- Add stubs for missing documentation
+
+## Detection Patterns
+
+| Documentation Pattern | Codebase Check |
+|----------------------|----------------|
+| `import { X } from 'pkg'` | Verify X is exported from pkg |
+| `function X(a, b)` | Check X signature in source |
+| `v1.2.3` version strings | Compare with package.json |
+| `POST /api/users` | Verify route exists |
+| `<Component prop={x}>` | Check component props interface |
+
+## Update Strategies
+
+### For Changed Function Signatures
+```mdx
+// Before (outdated)
+createUser(name: string, email: string)
+
+// After (updated)
+createUser(data: UserInput)
+// Where UserInput = { name: string, email: string, role?: string }
+```
+
+### For Removed Features
+```mdx
+<Warning>
+**Deprecated**: This feature was removed in v2.0. 
+See [migration guide](/guides/v2-migration) for alternatives.
+</Warning>
+```
+
+### For New Features (stub)
+```mdx
+---
+title: "New Feature"
+description: "Description"
+---
+
+{/* TODO: Document this feature */}
+
+## Overview
+
+Coming soon...
+```

package/ai-agents/.claude/skills/update-docs-json/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: update-docs-json
+description: Add new pages to docs.json navigation configuration
+---
+
+## Instructions
+
+When updating docs.json:
+
+1. Read the current docs.json structure
+2. Identify the appropriate group for the new page
+3. Add the page path (without .mdx extension)
+4. Maintain consistent ordering (introductory pages first)
+
+## Navigation Structure
+
+```json
+{
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Tab Name",
+        "type": "docs",
+        "groups": [
+          {
+            "group": "Group Name",
+            "icon": "phosphor-icon-name",
+            "pages": ["page-path", "folder/page-path"]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Page Path Format
+
+- Use relative paths from docs root
+- Omit the `.mdx` extension
+- Use forward slashes for nested paths
+- Examples: `"quickstart"`, `"guides/authentication"`
+
+## Common Icons (Phosphor)
+
+- `rocket-launch` - Getting started
+- `book-open` - Documentation
+- `terminal` - CLI/Commands
+- `gear` - Configuration
+- `code` - Development
+- `puzzle-piece` - Components
+- `key` - Authentication
+- `cloud-arrow-up` - Deployment
+
+## Best Practices
+
+1. Group related pages together
+2. Order pages from basic to advanced
+3. Use descriptive group names
+4. Keep navigation depth shallow (max 2 levels)

package/ai-agents/.cursor/rules/devdoc-bootstrap.mdc

@@ -0,0 +1,66 @@
+---
+description: Rules for bootstrapping documentation from repository analysis
+globs: ["**/README.md", "**/package.json", "**/src/**", "**/lib/**"]
+---
+
+# Repository Analysis for Documentation
+
+When asked to bootstrap or generate initial documentation:
+
+## Analysis Checklist
+
+1. Read README.md for project overview
+2. Check package.json for:
+   - Project name and description
+   - Dependencies (to understand tech stack)
+   - Scripts (for CLI documentation)
+3. Scan source directory structure
+4. Identify API endpoints or exported functions
+5. Look for existing OpenAPI/GraphQL specs
+6. Check for example files or tests
+
+## Documentation Generation Order
+
+1. index.mdx (homepage) - from README
+2. quickstart.mdx - installation + basic usage
+3. API reference - from specs or code analysis
+4. Feature guides - from major modules
+
+## Always Include
+
+- Real code examples from the codebase
+- Accurate installation commands
+- Links between related pages
+- TODO comments for sections needing review
+
+## File Structure to Generate
+
+```
+docs/
+├── docs.json           # Navigation config
+├── index.mdx           # Homepage
+├── quickstart.mdx      # Getting started
+├── guides/
+│   └── overview.mdx    # Architecture
+├── api-reference/      # If API exists
+│   ├── introduction.mdx
+│   └── openapi.json
+└── theme.json          # Theme config
+```
+
+## Content Extraction
+
+| Source | Documentation |
+|--------|---------------|
+| README.md | Homepage, overview |
+| package.json | Name, version, scripts |
+| src/index.ts | Main exports |
+| tests/ | Usage examples |
+| .env.example | Configuration options |
+
+## Quality Guidelines
+
+- Extract real examples, don't fabricate
+- Note areas needing human review
+- Generate SEO-friendly descriptions
+- Include all installation steps

package/ai-agents/.cursor/rules/devdoc-migrate.mdc

@@ -0,0 +1,62 @@
+---
+description: Rules for migrating documentation from other platforms to DevDoc
+globs: ["**/mint.json", "**/docusaurus.config.js", "**/SUMMARY.md", "**/mkdocs.yml", "**/*.graphql", "**/openapi.*", "**/swagger.*"]
+---
+
+# Documentation Migration Rules
+
+When asked to migrate documentation:
+
+## Platform Detection
+
+Check for these files to identify source platform:
+- mint.json → Mintlify
+- docusaurus.config.js → Docusaurus
+- SUMMARY.md → GitBook
+- mkdocs.yml → MkDocs
+- .vuepress/ → VuePress
+
+## Migration Priorities
+
+1. Configuration files first (navigation structure)
+2. Content files (preserve as much as possible)
+3. Assets (images, logos)
+4. API specs (copy and configure)
+
+## Component Conversion
+
+Always convert platform-specific components to DevDoc equivalents:
+
+### Mintlify
+- `<CodeGroup>` → `<Tabs>` with code blocks
+- `<Frame>` → `<img>` or remove wrapper
+- `<ResponseField>` → Markdown table
+- `<ParamField>` → Markdown table
+
+### Docusaurus
+- `:::note` → `<Note>`
+- `:::tip` → `<Tip>`
+- `:::info` → `<Info>`
+- `:::caution` → `<Warning>`
+- `:::danger` → `<Warning>`
+- `<TabItem>` → `<Tab>`
+
+### GitBook
+- `{% hint style="info" %}` → `<Info>`
+- `{% hint style="warning" %}` → `<Warning>`
+- `{% hint style="success" %}` → `<Tip>`
+- `{% tabs %}` → `<Tabs>`
+
+## Preserve Content
+
+- Keep all prose and explanations
+- Maintain heading hierarchy
+- Preserve code examples exactly
+- Keep frontmatter metadata
+
+## Post-Migration
+
+- Validate all internal links
+- Check component rendering
+- Verify navigation order
+- Test API playground if applicable

package/ai-agents/.cursor/rules/devdoc-sync.mdc

@@ -0,0 +1,70 @@
+---
+description: Rules for syncing and updating documentation with codebase changes
+globs: ["**/*.mdx", "**/docs.json"]
+---
+
+# Documentation Sync Rules
+
+When asked to sync, update, or check documentation:
+
+## Analysis Process
+
+1. Compare documented APIs against source code exports
+2. Verify code examples compile/run correctly
+3. Check version numbers match package.json
+4. Validate all internal links resolve
+5. Identify new features needing documentation
+
+## Common Outdated Patterns
+
+- Function signatures that changed
+- Removed or renamed exports
+- Changed configuration options
+- Updated CLI commands
+- New required parameters
+- Deprecated features still documented
+
+## Update Guidelines
+
+- Preserve existing explanations and prose
+- Only update technical details (code, signatures, versions)
+- Add TODO comments for sections needing human review
+- Create stubs for undocumented new features
+- Mark deprecated features with Warning callout
+
+## Detection Checklist
+
+| Check | How to Verify |
+|-------|---------------|
+| Function exists | Search source for export |
+| Signature matches | Compare params and return type |
+| Version current | Check package.json |
+| Route exists | Search API routes |
+| Component props | Check TypeScript interface |
+
+## Update Patterns
+
+### Changed Signature
+Update the documented signature to match source.
+
+### Removed Feature
+Add deprecation warning:
+```mdx
+<Warning>
+This feature was removed in vX.X.
+</Warning>
+```
+
+### New Feature
+Create stub with TODO:
+```mdx
+{/* TODO: Document this feature */}
+```
+
+## Report Format
+
+When checking docs, report:
+- Outdated items (with specific file:line)
+- Missing documentation
+- Broken links
+- Up-to-date items (summary)

package/ai-agents/.cursor/rules/devdoc.mdc

@@ -0,0 +1,94 @@
+---
+description: Rules for writing DevDoc documentation
+globs: ["**/*.mdx", "**/docs.json", "**/theme.json"]
+---
+
+# DevDoc Documentation Rules
+
+## MDX File Structure
+
+All MDX files must have:
+1. YAML frontmatter with `title` and `description`
+2. Clear introduction paragraph (no heading)
+3. Structured content with H2/H3 headings
+4. Component usage for visual hierarchy
+
+## Available Components
+
+### Callouts
+- `<Note>` - Additional information
+- `<Tip>` - Helpful hints
+- `<Warning>` - Important cautions
+- `<Info>` - General information
+
+### Layout
+- `<CardGroup cols={n}>` - Grid of cards (n = 1-4)
+- `<Card title="..." icon="..." href="...">` - Navigation card
+- `<Steps>` with `<Step title="...">` - Numbered steps
+- `<Tabs>` with `<Tab title="...">` - Tabbed content
+- `<AccordionGroup>` with `<Accordion title="...">` - Collapsible
+
+### Code
+- Use fenced code blocks with language
+- Add filename with `title` attribute when helpful
+- Include copy button for terminal commands
+
+## Style Guidelines
+
+1. Write in second person ("you can", "your project")
+2. Use active voice
+3. Keep paragraphs short (2-4 sentences)
+4. Include practical examples
+5. Link to related documentation
+6. End guides with "Next Steps" section
+
+## docs.json Best Practices
+
+1. Group related pages together
+2. Use descriptive group names
+3. Order pages from basic to advanced
+4. Use Phosphor icons for groups
+
+## Common Mistakes to Avoid
+
+- Missing frontmatter
+- Using H1 headings (title comes from frontmatter)
+- Inconsistent component usage
+- Missing code language tags
+- Broken internal links
+
+## Frontmatter Template
+
+```yaml
+---
+title: "Page Title"
+description: "Brief description for SEO (under 160 chars)"
+---
+```
+
+## Page Template
+
+```mdx
+---
+title: "Title"
+description: "Description"
+---
+
+Introduction paragraph explaining what this page covers.
+
+## Section One
+
+Content with components as needed.
+
+## Section Two
+
+More content.
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="Related" href="/path">
+    Description
+  </Card>
+</CardGroup>
+```

package/ai-agents/CLAUDE.md

@@ -0,0 +1,194 @@
+# DevDoc Documentation Project
+
+This is a DevDoc documentation project using MDX (Markdown + React components).
+
+## Project Structure
+
+```
+├── docs.json           # Navigation and site configuration
+├── theme.json          # Theme colors and styling
+├── custom.css          # Custom CSS overrides (optional)
+├── index.mdx           # Homepage
+├── quickstart.mdx      # Getting started guide
+├── guides/             # Documentation guides
+├── api-reference/      # API documentation
+│   ├── openapi.json    # OpenAPI specification
+│   └── schema.graphql  # GraphQL schema (if applicable)
+└── public/             # Static assets (images, logos)
+```
+
+## MDX File Format
+
+Every MDX file requires frontmatter:
+
+```yaml
+---
+title: "Page Title"
+description: "Brief description for SEO and navigation"
+---
+```
+
+**Important**: Do NOT use H1 headings (`#`) in content - the title comes from frontmatter.
+
+## Available Components
+
+### Callouts
+```mdx
+<Note>Additional information the reader should know.</Note>
+<Tip>Helpful hints and best practices.</Tip>
+<Warning>Important cautions and potential issues.</Warning>
+<Info>General informational content.</Info>
+```
+
+### Cards & Navigation
+```mdx
+<CardGroup cols={2}>
+  <Card title="Title" icon="icon-name" href="/path">
+    Card description text
+  </Card>
+</CardGroup>
+```
+
+### Steps (for tutorials)
+```mdx
+<Steps>
+  <Step title="Step 1">
+    Step content here
+  </Step>
+  <Step title="Step 2">
+    More content
+  </Step>
+</Steps>
+```
+
+### Tabs
+```mdx
+<Tabs>
+  <Tab title="JavaScript">
+    ```javascript
+    const x = 1;
+    ```
+  </Tab>
+  <Tab title="Python">
+    ```python
+    x = 1
+    ```
+  </Tab>
+</Tabs>
+```
+
+### Accordions
+```mdx
+<AccordionGroup>
+  <Accordion title="Question 1">
+    Answer content
+  </Accordion>
+</AccordionGroup>
+```
+
+### Code Blocks
+Use fenced code blocks with language tags:
+````mdx
+```javascript title="example.js"
+const hello = "world";
+```
+````
+
+## docs.json Configuration
+
+The `docs.json` file controls navigation and site settings:
+
+```json
+{
+  "name": "Project Name",
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Guides",
+        "type": "docs",
+        "groups": [
+          {
+            "group": "Getting Started",
+            "icon": "rocket-launch",
+            "pages": ["index", "quickstart"]
+          }
+        ]
+      },
+      {
+        "tab": "API Reference",
+        "type": "openapi",
+        "path": "/api-reference",
+        "spec": "api-reference/openapi.json"
+      }
+    ]
+  }
+}
+```
+
+**Page paths**: Use relative paths without `.mdx` extension.
+
+## Icons
+
+Use Phosphor icons (https://phosphoricons.com/). Common icons:
+- `rocket-launch` - Getting started
+- `book-open` - Documentation
+- `terminal` - CLI/Commands
+- `gear` - Configuration
+- `code` - Development
+- `puzzle-piece` - Components
+- `key` - Authentication
+- `cloud-arrow-up` - Deployment
+
+## Writing Guidelines
+
+1. **Introduction**: Start each page with a brief paragraph (no heading) explaining the topic
+2. **Structure**: Use H2 (`##`) for main sections, H3 (`###`) for subsections
+3. **Code examples**: Always include practical, working code examples
+4. **Navigation**: End guides with a `<CardGroup>` linking to related pages
+5. **Tone**: Write in second person ("you can", "your project")
+6. **Brevity**: Keep paragraphs short (2-4 sentences)
+
+## Common Tasks
+
+### Add a new page
+1. Create `new-page.mdx` with frontmatter
+2. Add to `docs.json` navigation in appropriate group
+
+### Add API documentation
+1. Place OpenAPI spec in `api-reference/openapi.json`
+2. Add tab with `"type": "openapi"` to docs.json
+
+### Customize theme
+Edit `theme.json`:
+```json
+{
+  "colors": {
+    "primary": "#0066FF",
+    "background": "#FFFFFF"
+  }
+}
+```
+
+## CLI Commands
+
+```bash
+# Start development server
+npm run dev
+
+# Build for production
+npm run build
+
+# Deploy to DevDoc hosting
+npx devdoc deploy
+```
+
+## DevDoc AI Agent Skills
+
+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
+- `/check-docs` - Health check for docs
+- `/create-doc-page` - Create new MDX page
+- `/update-docs-json` - Update navigation