@brainfish-ai/devdoc 0.1.32 → 0.1.34

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

@@ -0,0 +1,164 @@
+---
+name: delete-doc
+description: Delete documentation pages interactively with confirmation.
+---
+
+## Instructions
+
+When user wants to delete documentation:
+
+### Step 1: Understand What to Delete
+
+Ask the user:
+
+"What would you like to delete?
+
+1. **A specific page** - Tell me which page(s)
+2. **Find unused pages** - I'll identify orphan pages not in navigation
+3. **Deprecated content** - I'll find pages marked as deprecated
+4. **Clean up** - Describe what you want removed"
+
+### Step 2: Identify Pages
+
+Based on their choice:
+
+#### For Specific Page:
+- "Which page(s)? (e.g., `guides/old-feature.mdx`)"
+- Verify the file exists
+- Check for incoming links from other pages
+
+#### For Unused Pages:
+Scan for orphan pages:
+```
+Compare:
+- All .mdx files in docs/
+- Pages referenced in docs.json
+
+Orphan pages (not in navigation):
+- docs/drafts/unused.mdx
+- docs/old/deprecated-guide.mdx
+```
+
+#### For Deprecated Content:
+Search for deprecation markers:
+```
+Files with deprecation notices:
+- docs/api/legacy-auth.mdx (marked deprecated in v1.5)
+- docs/guides/old-workflow.mdx (marked deprecated in v2.0)
+```
+
+### Step 3: Analyze Impact
+
+Before deletion, check for:
+
+1. **Incoming links** - Other pages linking to this page
+2. **Navigation** - Entry in docs.json
+3. **Redirects** - Should we redirect to a new page?
+
+Show analysis:
+
+"**Deletion Analysis for `guides/old-feature.mdx`:**
+
+Incoming links (2 pages reference this):
+- `quickstart.mdx:45` → links to `/guides/old-feature`
+- `api/overview.mdx:23` → links to `/guides/old-feature#setup`
+
+Navigation:
+- Listed in docs.json under 'Guides' group
+
+Recommended actions:
+1. Remove from docs.json
+2. Update or remove links in other pages
+3. Consider redirect to replacement page"
+
+### Step 4: Confirm Deletion
+
+"Ready to delete `guides/old-feature.mdx`?
+
+This will:
+- ❌ Delete the file
+- ❌ Remove from docs.json navigation
+- ⚠️ Leave broken links in 2 pages (I can fix these)
+
+Options:
+1. **Delete and fix links** - Remove file, update linking pages
+2. **Delete and redirect** - Remove file, add redirect to `{new-page}`
+3. **Delete only** - Just remove the file
+4. **Cancel** - Don't delete"
+
+### Step 5: Execute Deletion
+
+Based on user choice:
+
+#### Delete and Fix Links:
+1. Delete the MDX file
+2. Update docs.json (remove page entry)
+3. Find and update/remove links in other pages:
+   ```mdx
+   // Before
+   See the [old feature guide](/guides/old-feature).
+   
+   // After
+   See the [new feature guide](/guides/new-feature).
+   // or remove the sentence entirely
+   ```
+
+#### Delete and Redirect:
+1. Delete the MDX file
+2. Update docs.json
+3. Add redirect to docs.json or redirects file:
+   ```json
+   {
+     "redirects": [
+       { "from": "/guides/old-feature", "to": "/guides/new-feature" }
+     ]
+   }
+   ```
+
+#### Delete Only:
+1. Delete the MDX file
+2. Update docs.json
+3. Warn about broken links
+
+### Step 6: Summary
+
+"Deleted:
+- ❌ `docs/guides/old-feature.mdx`
+- ✓ Removed from docs.json navigation
+- ✓ Updated links in `quickstart.mdx`, `api/overview.mdx`
+- ✓ Added redirect: `/guides/old-feature` → `/guides/new-feature`
+
+Want me to commit these changes? Use `/commit` when ready."
+
+---
+
+## Bulk Deletion
+
+For multiple pages:
+
+"Found 5 orphan pages not in navigation:
+
+| File | Last Modified | Size |
+|------|--------------|------|
+| `drafts/test.mdx` | 6 months ago | 2kb |
+| `old/legacy-api.mdx` | 1 year ago | 15kb |
+| `temp/scratch.mdx` | 3 months ago | 1kb |
+| `guides/draft-feature.mdx` | 2 months ago | 8kb |
+| `archive/v1-docs.mdx` | 1 year ago | 20kb |
+
+Options:
+1. **Delete all** - Remove all orphan pages
+2. **Select pages** - Choose which to delete
+3. **Review each** - Go through one by one
+4. **Cancel** - Keep all pages"
+
+---
+
+## Safety Guidelines
+
+- **Always confirm** before deleting
+- **Check for links** to prevent broken references
+- **Offer redirects** for removed public pages
+- **Show impact** before executing
+- **Keep backup** by suggesting to commit before deletion
+- **Never delete** docs.json or context.json without explicit confirmation

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

@@ -0,0 +1,219 @@
+---
+name: update-doc
+description: Update existing documentation by analyzing codebase changes or user references.
+---
+
+## Instructions
+
+When user wants to update 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
+- Avoid `terminology.avoidTerms`
+- Match `documentation.voice` for writing style
+
+### Step 1: Understand What to Update
+
+Ask the user:
+
+"What would you like to update?
+
+1. **A specific page** - Tell me which page to update
+2. **Sync with codebase** - I'll find outdated docs by comparing to code
+3. **Navigation structure** - Update docs.json organization
+4. **Multiple pages** - Describe the changes needed
+5. **Fix issues** - Point me to errors or problems"
+
+### Step 2: Analyze Current State
+
+Based on their choice:
+
+#### For Specific Page:
+- "Which page? (e.g., `guides/authentication.mdx`)"
+- Read the current page content
+- "What changes do you want?
+  - Update code examples
+  - Add new sections
+  - Fix errors/outdated info
+  - Rewrite for clarity
+  - Other (describe)"
+
+#### For Codebase Sync:
+- Locate source code (from context or `../`)
+- Compare documentation against code:
+  - Function signatures changed?
+  - New exports not documented?
+  - Removed features still documented?
+  - Version numbers outdated?
+- Generate sync report (see below)
+
+#### For Navigation:
+- Read current `docs.json`
+- "What navigation changes?
+  - Add new pages
+  - Reorganize groups
+  - Rename tabs
+  - Remove pages
+  - Other"
+
+#### For Multiple Pages:
+- "Which pages need updating?"
+- "What's the common change across them?"
+
+#### For Issues:
+- "What's the problem you're seeing?"
+- Analyze and propose fixes
+
+### Step 3: Generate Sync Report (if syncing)
+
+```
+## Documentation Sync Report
+
+### Outdated (Action Required)
+- `docs/api/users.mdx`: Function signature changed
+  - Documented: `createUser(name, email)`
+  - Current: `createUser(options: CreateUserInput)`
+  
+- `docs/quickstart.mdx`: Package version outdated
+  - Documented: v1.2.0
+  - Current: v2.0.0
+
+### Terminology Issues
+- `docs/guides/intro.mdx:15`: Uses "charge" instead of "payment"
+
+### Missing Documentation
+- `src/utils/newFeature.ts` - New export, not documented
+- `POST /api/v2/webhooks` - New endpoint
+
+### Up to Date ✓
+- `docs/guides/authentication.mdx`
+- `docs/api/errors.mdx`
+```
+
+Ask: "How would you like to proceed?
+1. **Fix all** - Update everything automatically
+2. **Interactive** - Review each change
+3. **Specific items** - Tell me which to fix"
+
+### Step 4: Propose Changes
+
+Before making changes, show what will be modified:
+
+"I'll make these changes:
+
+**`docs/api/users.mdx`**
+- Update `createUser` signature and examples
+- Add new `options` parameter documentation
+
+**`docs/quickstart.mdx`**  
+- Update version from 1.2.0 to 2.0.0
+- Update installation command
+
+**`docs.json`**
+- Add new page: `guides/webhooks.mdx`
+
+Proceed with these changes?"
+
+### Step 5: Apply Updates
+
+When updating:
+
+1. **Preserve prose** - Keep explanations, update technical details
+2. **Update code examples** - Match current signatures
+3. **Fix terminology** - Apply context.json rules
+4. **Add deprecation notices** for removed features:
+   ```mdx
+   <Warning>
+   **Deprecated in v2.0**: This feature was removed. 
+   See [migration guide](/guides/v2-migration).
+   </Warning>
+   ```
+5. **Create stubs** for new features:
+   ```mdx
+   {/* TODO: Document this new feature */}
+   ## New Feature
+   Coming soon...
+   ```
+
+### Step 6: Update Navigation (if needed)
+
+If pages were added/removed/moved:
+
+1. Read current `docs.json`
+2. Propose navigation changes
+3. Apply after user confirms
+
+### Step 7: Summary
+
+"Updated:
+- `docs/api/users.mdx` - Updated function signatures
+- `docs/quickstart.mdx` - Updated to v2.0.0
+- `docs.json` - Added webhooks page
+
+Changes ready for review. Run `npx @brainfish-ai/devdoc dev` to preview.
+
+Want me to commit these changes? Use `/commit` when ready."
+
+---
+
+## Update Patterns
+
+### Changed Function Signature
+```mdx
+// Before
+`createUser(name: string, email: string)`
+
+// After  
+`createUser(options: CreateUserInput)`
+
+Where `CreateUserInput`:
+```typescript
+interface CreateUserInput {
+  name: string;
+  email: string;
+  role?: 'admin' | 'user';
+}
+```
+```
+
+### Removed Feature
+```mdx
+<Warning>
+**Removed in v2.0**: The `legacyAuth` method was removed.
+Use `authenticate()` instead. See [migration guide](/migrate-v2).
+</Warning>
+```
+
+### New Feature Stub
+```mdx
+---
+title: "Webhooks"
+description: "Receive real-time notifications"
+---
+
+{/* TODO: Complete this documentation */}
+
+## Overview
+
+Documentation coming soon.
+
+## Quick Start
+
+```typescript
+// Example placeholder
+```
+```
+
+---
+
+## Quality Guidelines
+
+- Always show changes before applying
+- Preserve existing prose and explanations
+- Update only technical details (code, versions, signatures)
+- Add TODO markers for human review
+- Apply terminology from context.json
+- Create stubs rather than skip new features

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

@@ -0,0 +1,114 @@
+---
+description: Analyze documentation for duplicates, outdated content, and discrepancies
+globs: ["**/*.mdx", "**/docs.json", "**/src/**", "**/lib/**"]
+---
+
+# Blame Documentation
+
+When asked to analyze, audit, or blame documentation:
+
+## Step 0: Read Context
+
+Read `.devdoc/context.json` for terminology and conventions.
+
+## Step 1: Understand Scope
+
+Ask: "What should I analyze?
+1. **Full audit** - Check everything
+2. **Specific area** - Focus on one section
+3. **Duplicates only** - Find redundant content
+4. **Outdated only** - Find stale docs
+5. **Discrepancies only** - Find code/doc mismatches"
+
+## Step 2: Scan Sources
+
+**For Codebase:**
+- Read exported functions and types
+- Check API routes and endpoints
+- Find configuration options
+- Note version numbers
+
+**For Documentation:**
+- Read all MDX files
+- Extract code examples
+- List documented features
+- Check terminology usage
+
+## Step 3: Generate Report
+
+### Finding Duplicates
+
+Look for:
+- Same paragraphs in multiple files
+- Nearly identical code examples
+- Repeated setup instructions
+- Overlapping topic coverage
+
+Report format:
+```
+## Duplicate Content
+
+### Topic: [name]
+Found in: file1.mdx, file2.mdx, file3.mdx
+Recommendation: Consolidate to [primary], link from others
+
+Details:
+- file1.mdx:15-30 ≈ file2.mdx:45-60 (90% similar)
+```
+
+### Finding Outdated Content
+
+Compare docs to code:
+- Function signatures changed?
+- New parameters not documented?
+- Return types updated?
+- Versions outdated?
+
+Report format:
+```
+## Outdated Documentation
+
+### file.mdx
+Line 23: `getUser(id)` 
+Current:  `getUser(id, options?)` 
+Action: Update signature and add options table
+```
+
+### Finding Discrepancies
+
+Check for mismatches:
+- Documented vs actual return values
+- Stated vs real requirements
+- Described vs implemented behavior
+
+Report format:
+```
+## Discrepancies
+
+### api/auth.mdx vs src/auth.ts
+Documented: Returns { token }
+Actual: Returns { token, expiresAt, refreshToken }
+Impact: Users won't know about refresh tokens
+```
+
+## Step 4: Prioritize Issues
+
+Rank by severity:
+1. **Critical** - Wrong information misleading users
+2. **High** - Missing important features
+3. **Medium** - Outdated but still works
+4. **Low** - Style/consistency issues
+
+## Step 5: Suggest Fixes
+
+"Found X issues. I can:
+1. Fix the critical issues now
+2. Create a detailed fix plan
+3. Fix specific category only"
+
+## Quick Commands
+
+- "blame docs" → Full analysis
+- "find duplicates" → Duplicate content only
+- "find outdated" → Stale docs only
+- "compare code to docs" → Discrepancy analysis