@brainfish-ai/devdoc 0.1.41 → 0.1.43

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

@@ -1,5 +1,5 @@
 ---
-description: Create new documentation pages interactively
+description: Create new documentation pages by searching codebase first
 globs: ["**/*.mdx", "**/docs.json"]
 ---
 
@@ -7,16 +7,20 @@ globs: ["**/*.mdx", "**/docs.json"]
 
 When asked to create documentation:
 
-## Step 0: Read Context & Code Graph
+## Key Principles
 
-Read `.devdoc/context.json` for terminology, templates, and code language.
+| Principle | Description |
+|-----------|-------------|
+| **Search before generate** | ALWAYS search/read files before writing |
+| **No hallucination** | Only use data from actual source files |
+| **Review before write** | ALWAYS show draft for user approval |
+| **Flag feature flags** | Detect conditional features |
+| **Flag duplicates** | Identify similar features |
+| **Flag unclear sections** | Offer options if info not found |
+
+## Step 0: Read Context
 
-Read `.devdoc/code-graph.json` for:
-- `modules[].exports` → Function signatures, params, returns
-- `types[]` → Type definitions
-- `examples[]` → Code examples to include
-- `api.endpoints[]` → API routes
-- `errors[]` → Error types to document
+Read `.devdoc/context.json` for terminology, templates, and code language.
 
 ## Step 1: Understand What to Create
 
@@ -31,71 +35,118 @@ Ask: "What would you like to document?
 **For Feature/Concept:**
 - Topic/title?
 - Page type? (Guide, Tutorial, Reference, Troubleshooting)
-- Specific sections?
 
-**For Code Documentation:**
+**For Code/API:**
 - Which files/directories?
-- Focus? (Public API, Architecture, Examples, All)
-- Read and extract functions, types, examples
+- Focus? (Public API, Architecture, Examples)
 
-**For API Documentation:**
-- Check for OpenAPI/GraphQL specs
-- If found, offer to generate from spec
-- Extract endpoints, parameters, responses
+## Step 3: Search Codebase (CRITICAL)
 
-## Step 3: Read Template
+**ALWAYS search and read actual files:**
 
-Read from `.devdoc/templates/`:
-- Guide → `guide.md`
-- Tutorial → `tutorial.md`
-- API → `api-reference.md`
-- Quickstart → `quickstart.md`
-- Troubleshooting → `troubleshooting.md`
+```bash
+# Find related files
+git ls-files | grep -iE "(auth|login|session)"
 
-## Step 4: Generate Content
+# Search file contents
+rg -l "export.*function.*login" --type ts
+rg -l "interface.*User" --type ts
 
-1. Follow template structure
-2. Apply context (terminology, voice)
-3. **Use code-graph.json for accuracy:**
-   - Get exact signatures from `modules[].exports`
-   - Get type definitions from `types[]`
-   - Find examples from `examples[]`
-   - Document errors from `errors[]`
-4. Include mermaid diagrams for flows
-5. Add real code examples from code-graph
-6. Use MDX components (Steps, Cards, etc.)
-
-## Step 5: Save and Update Navigation
+# Find examples
+git ls-files | grep -iE "(example|test)"
+```
 
-1. Propose file location
-2. Create MDX file
-3. Ask to update docs.json
-4. Show summary
+**Read the files found and extract:**
+- Function signatures and parameters
+- Type definitions
+- Code examples from tests
+
+**If files not found:**
+```
+⚠️ UNCLEAR TOPIC: [topic]
 
-## Code to Doc Example
+Options:
+1. 🔄 Skip this doc
+2. ✏️ Different topic
+3. 📝 Mark as TODO
+4. ❓ Ask for path
+```
 
-```typescript
-// Source
-export function validateToken(token: string): boolean
+**Detect feature flags & duplicates:**
+```bash
+rg -l "featureFlag|isEnabled|FF_" --type ts
+rg "export.*(login|authenticate)" --type ts -l
+```
+
+Flag findings:
+```
+⚠️ FEATURE FLAG: newAuthFlow
+   Question: Document which version?
+   
+🔄 DUPLICATE: authenticate() in v2/
+   Question: Document primary or all?
 ```
 
-Generates:
-```mdx
-## validateToken
+## Step 4: Read Template
 
-Validates an authentication token.
+Read from `.devdoc/templates/` for structure.
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `token` | `string` | JWT token to validate |
+## Step 5: Draft Content (From Files Only)
 
-**Returns:** `boolean`
+**ONLY use data from files you read:**
+
+1. Follow template structure
+2. Get exact signatures FROM SOURCE FILES
+3. Get types FROM TYPE FILES
+4. Get examples FROM TEST/EXAMPLE FILES
+5. Include mermaid diagrams for flows
+6. Use MDX components
+
+## Step 6: Review with User (MANDATORY)
+
+**ALWAYS show draft before creating:**
+
+```
+═══════════════════════════════════
+CONTENT REVIEW: [filename].mdx
+═══════════════════════════════════
+
+[Full draft content here]
+
+NOTICES:
+⚠️ Feature flag: [name]
+🔄 Duplicate: [function] in [path]
+
+OPTIONS:
+1. ✅ Approve - Create file
+2. ✏️ Edit - Make changes
+3. 🔄 Switch version - Use flagged
+4. ➕ Add duplicate - Include related
+5. ❌ Cancel
 ```
 
+## Step 7: Save and Update Navigation
+
+**Only after user approves:**
+1. Propose file location
+2. Create MDX file
+3. Ask to update docs.json
+
 ## Guidelines
 
-- Extract real examples, don't fabricate
-- Include error handling
+- **SEARCH FIRST** - Never generate without reading files
+- **USE MERMAID DIAGRAMS** - For architecture, flows, sequences
+- Flag insufficient info with auto-correct options
+- Include error handling from source code
 - Add TODO for sections needing review
-- Use mermaid for complex flows
-- Apply terminology from context.json
+- Cite source files in frontmatter
+
+## Mermaid Diagrams (Required)
+
+| Content | Diagram Type |
+|---------|--------------|
+| Architecture | `flowchart TB` |
+| Data flow | `flowchart LR` |
+| API calls | `sequenceDiagram` |
+| State machine | `stateDiagram-v2` |
+| Data models | `erDiagram` |

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

@@ -1,5 +1,5 @@
 ---
-description: Update existing documentation by analyzing codebase
+description: Update documentation by searching actual source files
 globs: ["**/*.mdx", "**/docs.json"]
 ---
 
@@ -7,15 +7,20 @@ globs: ["**/*.mdx", "**/docs.json"]
 
 When asked to update documentation:
 
-## Step 0: Read Context & Code Graph
+## Key Principles
 
-Read `.devdoc/context.json` for terminology and conventions.
+| Principle | Description |
+|-----------|-------------|
+| **Search before update** | ALWAYS read source files before changing |
+| **No hallucination** | Only update based on actual files |
+| **Review before write** | ALWAYS show before/after for approval |
+| **Flag feature flags** | Detect conditional features |
+| **Flag duplicates** | Identify similar features |
+| **Flag unclear sections** | Offer options if source not found |
+
+## Step 0: Read Context
 
-Read `.devdoc/code-graph.json` to compare:
-- Current exports vs documented functions
-- Current types vs documented types
-- New endpoints not in docs
-- Removed features still documented
+Read `.devdoc/context.json` for terminology and conventions.
 
 ## Step 1: Understand What to Update
 
@@ -23,90 +28,108 @@ Ask: "What would you like to update?
 1. **A specific page** - Tell me which page
 2. **Sync with codebase** - I'll find outdated docs
 3. **Navigation** - Update docs.json
-4. **Multiple pages** - Describe changes
-5. **Fix issues** - Point me to problems"
+4. **Multiple pages** - Describe changes"
 
-## Step 2: Analyze
+## Step 2: Search Source Files (CRITICAL)
 
 **For Specific Page:**
-- Read current content
-- Ask what changes needed
+- Read the doc file
+- Search for corresponding source file
+- Compare documented vs actual
 
 **For Codebase Sync:**
 
-1. Re-scan codebase to update code-graph.json
-2. Compare docs vs code-graph.json:
-   - Signatures changed? (exports array)
-   - New exports undocumented?
-   - Removed exports still documented?
-   - Types changed?
-   - New endpoints? (api.endpoints)
+```bash
+# Find all exports
+rg "export (function|class|const)" --type ts -l
 
-Generate sync report:
+# Search for specific features
+git ls-files | grep -iE "(auth|user|api)"
 ```
-## Sync Report (from code-graph.json)
 
-### Signatures Changed
-- `api/users.mdx`: createUser signature changed
-  - Documented: createUser(name, email)
-  - Code-graph: createUser(options: CreateUserInput)
+Read both doc files AND source files, then compare:
 
-### New Exports (not documented)
-- auth.refreshToken()
-- users.deleteUser()
-
-### Removed (documented but not in code-graph)
-- legacyAuth() - removed
+```
+DOCUMENTED (from docs/api/users.mdx):
+  - createUser(name, email)
 
-### Types Changed
-- User interface: added `role` property
+ACTUAL (from src/lib/users.ts):
+  - createUser(options: CreateUserInput)
 
-### Up to Date ✓
-- `guides/auth.mdx`
+→ SIGNATURE MISMATCH
 ```
 
-**For Navigation:**
-- Read docs.json
-- Ask what to change
+Generate sync report:
+```
+## Sync Report (from source files)
 
-## Step 3: Propose Changes
+### Signatures Changed
+- `docs/api/users.mdx` vs `src/lib/users.ts`:
+  - Documented: createUser(name, email)
+  - Source: createUser(options: CreateUserInput)
+
+### New Exports (in source, not docs)
+- src/lib/auth.ts: refreshToken()
+
+### Unable to Verify (source not found)
+⚠️ docs/legacy/old-api.mdx - No matching source
+   Options:
+   1. 🔄 Remove doc
+   2. ❓ Ask for path
+   3. 📝 Mark as needs-review
+
+### Feature Flags Detected
+⚠️ src/lib/auth/index.ts - newAuthFlow
+   Current docs: OLD implementation
+   Question: Update to which version?
+
+### Duplicates Detected
+🔄 authenticate() in v2/ similar to login()
+   Question: How to handle?
+```
 
-Show what will change before applying:
+## Step 3: Review Each Change (MANDATORY)
 
-"I'll make these changes:
-- `api/users.mdx`: Update signature
-- `quickstart.mdx`: Update version
-- `docs.json`: Add new page
+**Show before/after for EACH file:**
 
-Proceed?"
+```
+═══════════════════════════════════
+CHANGE REVIEW: docs/api/users.mdx
+═══════════════════════════════════
+
+BEFORE:
+## createUser(name, email)
+
+AFTER:
+## createUser(options)
+| Property | Type |
+|----------|------|
+| options | CreateUserInput |
+
+NOTICES:
+⚠️ Feature flag: None
+🔄 Duplicate: None
+
+OPTIONS:
+1. ✅ Approve - Apply change
+2. ✏️ Edit - Modify
+3. ⏭️ Skip - Don't update
+4. ❌ Cancel all
+```
 
-## Step 4: Apply Updates
+## Step 4: Apply Updates (After Approval)
 
+- **Only after user approves each change**
 - Preserve prose, update technical details
-- Fix terminology per context.json
+- Add feature flag notices where applicable
 - Add deprecation notices for removed features
 - Create stubs for new features
 
-## Update Patterns
-
-**Changed Signature:**
-Update code and parameters table.
-
-**Removed Feature:**
-```mdx
-<Warning>
-**Deprecated in v2.0**: Use `newMethod()` instead.
-</Warning>
-```
-
-**New Feature:**
-```mdx
-{/* TODO: Document this */}
-## New Feature
-Coming soon...
-```
-
-## Summary
+## Guidelines
 
-Show what was updated and suggest:
-"Use `/commit-doc` when ready to commit changes."
+- **SEARCH FIRST** - Read source files before any update
+- **REVIEW WITH USER** - Show before/after for each change
+- **FLAG FEATURE FLAGS** - Detect and ask which version
+- **FLAG DUPLICATES** - Let user decide how to handle
+- Preserve existing prose
+- Add TODO for unverified sections

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

@@ -5,6 +5,27 @@ globs: ["**/*.mdx", "**/docs.json", "**/theme.json"]
 
 # DevDoc Documentation Rules
 
+## Core Principle: Search Before Generate
+
+**CRITICAL: ALWAYS search and read source files before generating or updating documentation.**
+
+```
+┌─────────────────────────────────────────┐
+│ DOCUMENTATION GENERATION FLOW           │
+├─────────────────────────────────────────┤
+│ 1. SEARCH for relevant source files     │
+│ 2. READ the files found                 │
+│ 3. GENERATE from real data only         │
+│ 4. FLAG if info not found               │
+└─────────────────────────────────────────┘
+```
+
+**Never hallucinate content. If source files not found:**
+- Offer to auto-correct the plan
+- Suggest renaming to match what exists
+- Mark as TODO
+- Ask user for file path
+
 ## MDX File Structure
 
 All MDX files must have: