@brainfish-ai/devdoc 0.1.32 → 0.1.34

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

@@ -1,12 +1,54 @@
 ---
 name: check-docs
-description: Quick check for documentation issues without making changes
+description: Quick health check for documentation issues. Reads context memory for validation.
 ---
 
 ## Instructions
 
-Run a quick audit of documentation health:
+Run a quick audit of documentation health.
 
+### Step 0: Read Context Memory
+
+**First, read `.devdoc/context.json` if it exists:**
+
+```json
+{
+  "product": { "name": "..." },
+  "terminology": { 
+    "glossary": { "term": "definition" },
+    "avoidTerms": [{ "wrong": "...", "correct": "..." }],
+    "brandNames": { "ProductName": "ProductName" }
+  },
+  "api": { "style": "REST", "authentication": { "type": "api_key" } }
+}
+```
+
+**Use context for additional checks:**
+- Verify terminology usage matches glossary
+- Flag usage of terms in `avoidTerms`
+- Check brand name capitalization
+- Validate API patterns match `api.conventions`
+
+### Step 1: 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
+
+### Step 2: Run Checks
+
+#### Standard Checks:
 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
@@ -14,33 +56,78 @@ Run a quick audit of documentation health:
 5. **Outdated Examples** - Compare imports against package exports
 6. **Stale Versions** - Check version numbers against package.json
 
-## Output Format
+#### Context-Based Checks (if context.json exists):
+7. **Terminology** - Flag incorrect terms from `avoidTerms`
+8. **Brand Names** - Check capitalization matches `brandNames`
+9. **Product Name** - Ensure consistent use of `product.name`
+10. **API Patterns** - Verify examples follow `api.conventions`
+
+### Output Format
 
 ```
 Documentation Health Check
 ==========================
 
+Context: Using .devdoc/context.json ✓
+DocType: api
+
 Summary: X issues found
 
-Broken Links (count)
+## Critical Issues
+
+### Broken Links (count)
    file.mdx:line → /path (page not found)
 
-Outdated Code (count)
+### Missing Pages (count)
+   docs.json references 'page' but file not found
+
+## Warnings
+
+### Terminology Issues (count)
+   file.mdx:line → Uses "charge" instead of "payment"
+   file.mdx:line → Uses "transaction" instead of "payment"
+   (per terminology.avoidTerms in context)
+
+### Brand Name Issues (count)
+   file.mdx:line → "productname" should be "ProductName"
+
+### Outdated Code (count)
    file.mdx:line → import { oldFunc } from 'pkg'
    'oldFunc' no longer exported, use 'newFunc'
 
-Orphan Pages (count)
+### Orphan Pages (count)
    path/to/file.mdx (not in navigation)
 
-Missing Pages (count)
-   docs.json references 'page' but file not found
+## Passed
 
-All version numbers current
-All pages in docs.json exist
-No syntax errors in code blocks
+✓ All version numbers current
+✓ All internal links resolve
+✓ No syntax errors in code blocks
+✓ Product name used consistently
 ```
 
-## Checks Performed
+## Checks By DocType
+
+### For docType: "internal"
+- [ ] Setup guide exists and references correct tools
+- [ ] Architecture docs present
+- [ ] Development workflow documented
+- [ ] Prerequisites clearly listed
+
+### For docType: "api"
+- [ ] Authentication page exists
+- [ ] Error codes documented
+- [ ] API reference present (OpenAPI or manual)
+- [ ] Quickstart under 5 minutes
+- [ ] Code examples in primary language
+
+### For docType: "product"
+- [ ] Screenshots present and described
+- [ ] Tutorials have clear steps
+- [ ] FAQ section exists
+- [ ] Non-technical language used
+
+## Detailed Checks
 
 ### Link Validation
 - Internal links (`href="/path"`)
@@ -51,6 +138,7 @@ No syntax errors in code blocks
 - Language tag present
 - Valid syntax (basic check)
 - Import statements resolve
+- Uses correct primary language from context
 
 ### Navigation Validation
 - All pages in docs.json exist
@@ -62,6 +150,11 @@ No syntax errors in code blocks
 - No H1 headings (title from frontmatter)
 - Images have alt text
 
+### Terminology Validation (from context)
+- No terms from `avoidTerms` used
+- Brand names capitalized correctly
+- Glossary terms used consistently
+
 ## Quick Fixes
 
 After running check, common fixes:
@@ -70,3 +163,5 @@ After running check, common fixes:
 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
+5. **Wrong terminology** → Replace with correct term from context
+6. **Brand name** → Fix capitalization per context.json

package/ai-agents/.claude/skills/commit-doc/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: commit-doc
+description: Commit documentation changes to git after reviewing and confirming.
+---
+
+## Instructions
+
+When user wants to commit documentation changes:
+
+### Step 1: Check Current Status
+
+Run git status to see what's changed:
+
+```bash
+git status
+git diff --stat
+```
+
+Show summary to user:
+
+"**Documentation Changes Ready to Commit:**
+
+Modified files (3):
+- `docs/guides/authentication.mdx` - Updated code examples
+- `docs/api/users.mdx` - Added new endpoint docs
+- `docs.json` - Updated navigation
+
+New files (1):
+- `docs/guides/webhooks.mdx` - New webhook guide
+
+Deleted files (1):
+- `docs/old/deprecated-api.mdx` - Removed deprecated docs
+
+Would you like to:
+1. **Review changes** - Show me the detailed diff
+2. **Commit all** - Commit everything with a message
+3. **Selective commit** - Choose which files to commit
+4. **Cancel** - Don't commit yet"
+
+### Step 2: Review Changes (if requested)
+
+Show meaningful diff summary:
+
+"**Changes in `docs/guides/authentication.mdx`:**
+
+```diff
+- const token = auth.getToken(user);
++ const token = await auth.getToken(user, { refresh: true });
+```
+
+Added:
+- New `refresh` parameter documentation
+- Updated example code
+- Added error handling section
+
+**Changes in `docs.json`:**
+- Added 'Webhooks' to Guides group
+- Removed 'Deprecated API' from navigation
+
+Continue to commit?"
+
+### Step 3: Generate Commit Message
+
+Analyze changes and suggest a commit message:
+
+"Suggested commit message:
+
+```
+docs: update authentication guide and add webhooks documentation
+
+- Update auth.getToken() examples with new refresh parameter
+- Add webhook integration guide
+- Remove deprecated API documentation
+- Update navigation structure
+```
+
+Options:
+1. **Use this message** - Commit with suggested message
+2. **Edit message** - Modify the commit message
+3. **Custom message** - Write your own message"
+
+### Step 4: Confirm and Commit
+
+"Ready to commit with message:
+
+```
+docs: update authentication guide and add webhooks documentation
+```
+
+This will commit:
+- 3 modified files
+- 1 new file
+- 1 deleted file
+
+**Proceed with commit?** (yes/no)"
+
+### Step 5: Execute Commit
+
+```bash
+git add docs/
+git add docs.json
+git commit -m "docs: update authentication guide and add webhooks documentation
+
+- Update auth.getToken() examples with new refresh parameter
+- Add webhook integration guide
+- Remove deprecated API documentation
+- Update navigation structure"
+```
+
+### Step 6: Summary and Next Steps
+
+"✓ **Committed successfully!**
+
+Commit: `abc1234`
+Branch: `main`
+Files: 5 changed
+
+**Next steps:**
+1. **Push changes**: `git push origin main`
+2. **Deploy docs**: `npx @brainfish-ai/devdoc deploy`
+3. **Create PR**: If on a feature branch
+
+Would you like me to push the changes?"
+
+---
+
+## Commit Message Guidelines
+
+### Format
+```
+<type>: <short description>
+
+<detailed description>
+
+<list of changes>
+```
+
+### Types
+- `docs:` - Documentation changes (most common)
+- `fix:` - Fix documentation errors
+- `feat:` - New documentation features
+- `refactor:` - Reorganize documentation
+- `chore:` - Maintenance tasks
+
+### Examples
+
+**New documentation:**
+```
+docs: add webhook integration guide
+
+- Add complete webhook setup guide
+- Include payload examples
+- Add troubleshooting section
+```
+
+**Update existing:**
+```
+docs: update authentication examples for v2.0
+
+- Update code examples to use async/await
+- Add new refresh token parameter
+- Fix deprecated method references
+```
+
+**Fix errors:**
+```
+fix(docs): correct API endpoint URLs
+
+- Fix base URL from /v1 to /v2
+- Update authentication header name
+- Fix typos in error codes
+```
+
+**Reorganize:**
+```
+refactor(docs): reorganize guide structure
+
+- Move tutorials to dedicated folder
+- Update navigation hierarchy
+- Add cross-references between guides
+```
+
+---
+
+## Selective Commit
+
+When user wants to commit specific files:
+
+"Select files to commit:
+
+[ ] `docs/guides/authentication.mdx`
+[ ] `docs/api/users.mdx`
+[ ] `docs/guides/webhooks.mdx`
+[x] `docs.json`
+
+Enter file numbers to toggle (e.g., '1,3' or 'all'):"
+
+After selection:
+```bash
+git add docs.json
+git add docs/guides/webhooks.mdx
+git commit -m "docs: add webhooks guide and update navigation"
+```
+
+---
+
+## Safety Guidelines
+
+- **Always show changes** before committing
+- **Generate meaningful messages** based on actual changes
+- **Don't commit sensitive data** - check for API keys, secrets
+- **Suggest pushing** but don't auto-push
+- **Keep commits focused** - one logical change per commit
+- **Reference issues** if mentioned by user (e.g., "Fixes #123")

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

@@ -0,0 +1,198 @@
+---
+name: create-doc
+description: Create new documentation pages interactively. Analyzes codebase and guides you through the process.
+---
+
+## Instructions
+
+When user wants to create documentation:
+
+### Step 0: Read Context Memory
+
+**First, read `.devdoc/context.json` if it exists:**
+- Use `product.name` for product references
+- Apply `terminology.glossary` for correct terms
+- Use `documentation.codeExamples.primaryLanguage` for code
+- Read templates from `documentation.templates`
+
+### Step 1: Understand What to Create
+
+Ask the user:
+
+"What would you like to document?
+
+1. **A specific feature or concept** - I'll create a guide/tutorial
+2. **Code files or functions** - Point me to the code, I'll generate docs
+3. **API endpoints** - I'll analyze your API and create reference docs
+4. **Something else** - Describe what you need"
+
+### Step 2: Gather Information
+
+Based on their choice:
+
+#### For Feature/Concept:
+- "What's the topic/title?"
+- "What type of page?
+  - Guide - Explains how to do something
+  - Tutorial - Step-by-step walkthrough
+  - Reference - Technical specifications
+  - Troubleshooting - Problem/solution format"
+- "Any specific sections you want included?"
+
+#### For Code Documentation:
+- "Which files or directories should I analyze?"
+- "What should I focus on?
+  - Public API/exports
+  - Internal architecture
+  - Usage examples
+  - All of the above"
+- Read the specified files
+- Extract functions, classes, types, examples
+
+#### For API Documentation:
+- Check for existing OpenAPI/GraphQL specs
+- If found: "I found `{spec}`. Should I generate docs from it?"
+- If not: "Point me to your API routes/controllers"
+- Extract endpoints, parameters, responses
+
+#### For Other:
+- Ask clarifying questions
+- Understand the scope and purpose
+
+### Step 3: Analyze Codebase (if applicable)
+
+When documenting code:
+
+```
+Scan for:
+- Function signatures and JSDoc/docstrings
+- Type definitions and interfaces
+- Usage examples in tests
+- README sections about this feature
+- Existing related documentation
+```
+
+Show user what you found:
+"I found:
+- 5 exported functions in `src/utils/`
+- Type definitions in `types/index.ts`
+- 3 test files with usage examples
+
+Should I proceed with generating documentation for these?"
+
+### Step 4: Choose Template
+
+Read the appropriate template from `.devdoc/templates/`:
+
+| Content Type | Template |
+|--------------|----------|
+| How-to guide | `guide.md` |
+| Tutorial | `tutorial.md` |
+| API endpoint | `api-reference.md` |
+| Quick start | `quickstart.md` |
+| FAQ/Issues | `troubleshooting.md` |
+
+### Step 5: Generate Content
+
+Create the documentation:
+
+1. **Read the template** for structure guidance
+2. **Apply context** (terminology, voice, language)
+3. **Include mermaid diagrams** for flows/architecture
+4. **Add real code examples** from codebase
+5. **Use proper MDX components** (Steps, Cards, Tabs, etc.)
+
+### Step 6: Propose File Location
+
+Suggest where to save:
+
+"I'll create this page at: `docs/guides/{topic}.mdx`
+
+Does this location work, or would you prefer somewhere else?"
+
+### Step 7: Create and Update Navigation
+
+1. Write the MDX file
+2. Ask: "Should I add this to the navigation in docs.json?"
+3. If yes, update docs.json with the new page
+
+### Step 8: Summary
+
+"Created:
+- `docs/guides/{topic}.mdx` - {description}
+- Updated `docs.json` navigation
+
+Preview with `npx @brainfish-ai/devdoc dev`
+
+Want me to create another page or make changes to this one?"
+
+---
+
+## Code Documentation Examples
+
+### From TypeScript/JavaScript:
+
+```typescript
+// Source: src/utils/auth.ts
+export function validateToken(token: string): boolean {
+  // ... implementation
+}
+```
+
+Generates:
+
+```mdx
+## validateToken
+
+Validates an authentication token.
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `token` | `string` | The JWT token to validate |
+
+### Returns
+
+`boolean` - `true` if valid, `false` otherwise
+
+### Example
+
+```typescript
+import { validateToken } from '@package/auth';
+
+const isValid = validateToken(userToken);
+if (!isValid) {
+  throw new Error('Invalid token');
+}
+```
+```
+
+### From Python:
+
+```python
+# Source: src/auth.py
+def validate_token(token: str) -> bool:
+    """
+    Validate an authentication token.
+    
+    Args:
+        token: The JWT token to validate
+        
+    Returns:
+        True if valid, False otherwise
+    """
+```
+
+Generates similar documentation following the template structure.
+
+---
+
+## Quality Guidelines
+
+- Extract real code examples, don't fabricate
+- Include error handling in examples
+- Add TODO markers for sections needing human review
+- Use mermaid diagrams for complex flows
+- Link to related documentation
+- Apply terminology from context.json