@brainfish-ai/devdoc 0.1.41 → 0.1.42

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

@@ -1,26 +1,20 @@
 ---
 name: update-doc
-description: Update existing documentation by analyzing codebase changes or user references.
+description: Update existing documentation by searching codebase for current implementation.
 ---
 
 ## Instructions
 
 When user wants to update documentation:
 
-### Step 0: Read Context & Code Graph
+### Step 0: Read Context
 
-**First, read `.devdoc/context.json` if it exists:**
+**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
 
-**Then, read `.devdoc/code-graph.json` if it exists:**
-- Compare documented signatures vs code-graph exports
-- Check if new exports need documentation
-- Verify types match code-graph definitions
-- Find new examples to include
-
 ### Step 1: Understand What to Update
 
 Ask the user:
@@ -47,21 +41,34 @@ Based on their choice:
   - Rewrite for clarity
   - Other (describe)"
 
-#### For Codebase Sync:
-**If code-graph.json exists:**
-- Re-scan codebase to update code-graph.json
-- Compare OLD code-graph vs NEW code-graph:
-  - Changed function signatures
-  - New exports added
-  - Removed exports
-  - Changed types
-- Generate sync report (see below)
-
-**If code-graph.json doesn't exist:**
-- Run bootstrap first: "Run `/bootstrap-docs` first to create code-graph.json"
-- Or manually scan source code
-
-Compare documentation against code-graph:
+#### For Codebase Sync (Search Real Files):
+
+**Step 2a: Search for source files related to documented topics:**
+```bash
+# Find all exported functions/classes
+rg "export (function|class|const|interface|type)" --type ts -l
+
+# Find specific topic files
+git ls-files | grep -iE "(auth|user|api)"
+```
+
+**Step 2b: Read both doc files AND source files:**
+1. Read the doc file to see what's documented
+2. Search and read the corresponding source file
+3. Compare documented vs actual implementation
+
+**Step 2c: Generate comparison:**
+```
+DOCUMENTED (from docs/api/users.mdx):
+  - createUser(name: string, email: string)
+
+ACTUAL (from src/lib/users.ts):
+  - createUser(options: CreateUserInput)
+
+→ SIGNATURE MISMATCH - needs update
+```
+
+Compare documentation against actual source:
   - Function signatures changed?
   - New exports not documented?
   - Removed features still documented?
@@ -84,67 +91,137 @@ Compare documentation against code-graph:
 - "What's the problem you're seeing?"
 - Analyze and propose fixes
 
-### Step 3: Generate Sync Report (if syncing)
+### Step 3: Detect Feature Flags & Duplicates
+
+**Search for feature flags in source:**
+```bash
+rg -l "featureFlag|feature_flag|isEnabled|FF_" --type ts
+rg "if.*\(.*feature|process\.env\.FEATURE" --type ts
+```
+
+**Search for duplicate/similar features:**
+```bash
+rg "export.*(login|authenticate|signIn)" --type ts -l
+```
+
+**Include in sync report:**
 
-**Compare docs against code-graph.json:**
+### Step 4: Generate Sync Report (From File Search)
+
+**Compare docs against actual source files:**
 
 ```
 ## Documentation Sync Report
 
-### Signature Changes (from code-graph.json)
-- `docs/api/users.mdx`: Function signature changed
+### Signature Changes (from source files)
+- `docs/api/users.mdx` vs `src/lib/users.ts`:
   - Documented: `createUser(name, email)`
-  - Code-graph: `createUser(options: CreateUserInput)`
+  - Source file: `createUser(options: CreateUserInput)`
+  - Action: Update signature and params
   
-### New Exports (in code-graph, not in docs)
-- Module `auth`: `refreshToken()` - Not documented
-- Module `users`: `deleteUser()` - Not documented
-- Type: `SessionConfig` - Not documented
-
-### Removed (in docs, not in code-graph)
-- `legacyAuth()` - Removed from codebase
-- Type: `OldUserFormat` - No longer exists
+### New Exports (in source, not in docs)
+- `src/lib/auth.ts`: `refreshToken()` - Not documented
+- `src/lib/users.ts`: `deleteUser()` - Not documented
 
-### Type Changes
-- `User` interface: Added `role` property
-- `AuthToken`: Changed `expiresAt` type
-
-### New Endpoints (from code-graph.api.endpoints)
-- `POST /api/v2/webhooks` - Not documented
+### Removed (in docs, not in source)
+- `legacyAuth()` - Not found in any source file
 
 ### Up to Date ✓
-- `docs/guides/authentication.mdx`
-- `docs/api/errors.mdx`
+- `docs/guides/authentication.mdx` matches `src/lib/auth/`
+
+### Unable to Verify (source not found)
+⚠️ `docs/legacy/old-api.mdx` - No matching source file
+
+═══════════════════════════════════════════════════════════
+                 FEATURE FLAGS DETECTED
+═══════════════════════════════════════════════════════════
+
+⚠️ src/lib/auth/index.ts:45 - newAuthFlow
+   Current docs: OLD implementation
+   Feature flag: NEW implementation available
+   
+   Question: Update docs to which version?
+   1. Keep current (old)
+   2. Update to new (feature-flagged)
+   3. Document both with toggle notice
+
+═══════════════════════════════════════════════════════════
+                 DUPLICATE FEATURES
+═══════════════════════════════════════════════════════════
+
+🔄 Similar functions found:
+   - src/lib/auth/login.ts → login()
+   - src/lib/auth/v2/authenticate.ts → authenticate()
+   
+   Question: How to handle?
+   1. Document primary only
+   2. Document all with comparison
+   3. Mark duplicates as deprecated
 ```
 
 Ask: "How would you like to proceed?
-1. **Fix all** - Update everything automatically
-2. **Interactive** - Review each change
+1. **Fix all** - Update everything (choose defaults for flags/duplicates)
+2. **Interactive** - Review each change with me
 3. **Specific items** - Tell me which to fix
-4. **Refresh code-graph first** - Re-scan codebase before updating"
+4. **Re-search** - Search for different file patterns"
+
+### Step 5: Review Each Change with User (MANDATORY)
+
+**For EACH file being updated, show before/after:**
+
+```
+═══════════════════════════════════════════════════════════
+              CHANGE REVIEW: docs/api/users.mdx
+═══════════════════════════════════════════════════════════
+
+📄 BEFORE (current):
+───────────────────────────────────────────────────────────
+## createUser(name, email)
 
-### Step 4: Propose Changes
+Creates a new user account.
 
-Before making changes, show what will be modified:
+| Parameter | Type |
+|-----------|------|
+| name | string |
+| email | string |
+───────────────────────────────────────────────────────────
 
-"I'll make these changes:
+📄 AFTER (proposed):
+───────────────────────────────────────────────────────────
+## createUser(options)
 
-**`docs/api/users.mdx`**
-- Update `createUser` signature and examples
-- Add new `options` parameter documentation
+Creates a new user account.
 
-**`docs/quickstart.mdx`**  
-- Update version from 1.2.0 to 2.0.0
-- Update installation command
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| options | CreateUserInput | User creation options |
 
-**`docs.json`**
-- Add new page: `guides/webhooks.mdx`
+### CreateUserInput
 
-Proceed with these changes?"
+| Property | Type | Required |
+|----------|------|----------|
+| name | string | Yes |
+| email | string | Yes |
+| role | 'admin' \| 'user' | No |
+───────────────────────────────────────────────────────────
 
-### Step 5: Apply Updates
+⚠️ NOTICES:
+- Source: src/lib/users.ts:23
+- Feature flag: None
+- Duplicates: None
 
-When updating:
+OPTIONS:
+1. ✅ **Approve** - Apply this change
+2. ✏️  **Edit** - Modify the proposed content
+3. ⏭️  **Skip** - Don't update this file
+4. ❌ **Cancel all** - Stop updating
+
+Choose an option:
+```
+
+### Step 6: Apply Updates (After Approval)
+
+**Only after user approves each change:**
 
 1. **Preserve prose** - Keep explanations, update technical details
 2. **Update code examples** - Match current signatures
@@ -156,7 +233,13 @@ When updating:
    See [migration guide](/guides/v2-migration).
    </Warning>
    ```
-5. **Create stubs** for new features:
+5. **Add feature flag notices** where applicable:
+   ```mdx
+   <Note>
+   **Feature Flag**: This feature requires `newAuthFlow` to be enabled.
+   </Note>
+   ```
+6. **Create stubs** for new features:
    ```mdx
    {/* TODO: Document this new feature */}
    ## New Feature
@@ -234,11 +317,27 @@ Documentation coming soon.
 
 ---
 
+## Key Principles
+
+| Principle | Description |
+|-----------|-------------|
+| **Search before update** | ALWAYS read source files before changing docs |
+| **No hallucination** | Only update based on actual file contents |
+| **Review before write** | ALWAYS show before/after for user approval |
+| **Flag feature flags** | Detect and highlight conditional features |
+| **Flag duplicates** | Identify similar/related features |
+| **Verify changes** | Read source to confirm what changed |
+
 ## Quality Guidelines
 
+- **SEARCH FIRST** - Read source files before making any update
+- **REVIEW WITH USER** - Show before/after for each change
+- **DETECT FEATURE FLAGS** - Search for conditional features
+- **DETECT DUPLICATES** - Find similar functions/features
 - Always show changes before applying
 - Preserve existing prose and explanations
 - Update only technical details (code, versions, signatures)
+- Flag when source file not found - offer auto-correct options
 - Add TODO markers for human review
 - Apply terminology from context.json
 - Create stubs rather than skip new features

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

@@ -63,16 +63,41 @@ What is the primary goal?
 5. **Inform stakeholders** - Architecture/decisions
 ```
 
-#### Question 2: Primary Audience
+#### Question 2: Audience & Roles
 ```
-Who is your PRIMARY audience?
+Does your product have multiple user roles?
 
-1. **Internal Developer** → Code flow, architecture, debugging
-2. **External Developer** → Quick start, auth, code examples
+A) **Single audience** - All users have same access
+B) **Multiple roles** - Different users see different features
+   (e.g., Admin/Editor/Viewer, different permission levels)
+```
+
+**If Single (A):**
+```
+1. **Internal Developer** → Code flow, architecture
+2. **External Developer** → Quick start, auth, examples
 3. **Product User** → Tutorials, feature guides
 4. **Content Author** → MDX syntax, structure
 ```
 
+**If Multi-role (B):**
+```
+Define your roles:
+┌─────────────────┬────────────────────────────┐
+│ Role            │ Features/Permissions       │
+├─────────────────┼────────────────────────────┤
+│ Admin           │ All features, user mgmt    │
+│ Editor          │ Create/edit content        │
+│ Viewer          │ Read-only access           │
+│ Developer       │ API access, webhooks       │
+└─────────────────┴────────────────────────────┘
+
+How to organize role-specific content?
+1. **Separate sections** - admin/, users/, developers/
+2. **Inline badges** - <RoleBadge roles={["admin"]}>
+3. **Hybrid** - Both approaches
+```
+
 #### Question 3: Documentation Domain
 ```
 1. **API Docs** - Voice: Professional, code-focused
@@ -241,31 +266,129 @@ Create `.devdoc/context.json`:
 }
 ```
 
-### Step 7: Generate Using Writing Guidelines
+### Step 7: Generate WITH File Search (CRITICAL)
 
 **Only after user approval in Step 5.**
 
+**For EACH page in the content plan:**
+
+```
+1. SEARCH for relevant files
+   git ls-files | grep -iE "(auth|login|token)"
+   rg -l "authentication" --type ts
+
+2. READ the files found
+   - Extract real signatures, types, examples
+   - Note the source files
+
+3. DETECT feature flags & duplicates
+   rg -l "featureFlag|isEnabled|FF_" --type ts
+   rg "export.*(login|authenticate)" --type ts -l
+   
+   ⚠️ FEATURE FLAG: newAuthFlow
+      OLD vs NEW implementation
+      → Ask user which to document
+   
+   🔄 DUPLICATE: authenticate() in v2/
+      → Ask user how to handle
+
+4. ASSESS if enough info exists
+   ✅ Sufficient → Draft content
+   ⚠️ Partial → Draft with TODOs
+   ❌ Insufficient → Flag and offer options
+
+5. REVIEW DRAFT with user (MANDATORY)
+   ═══════════════════════════════════
+   CONTENT REVIEW: authentication.mdx
+   ═══════════════════════════════════
+   
+   [Show full draft content]
+   
+   NOTICES:
+   ⚠️ Feature flag: newAuthFlow
+   🔄 Duplicate: authenticate() in v2/
+   
+   OPTIONS:
+   1. ✅ Approve - Create file
+   2. ✏️ Edit - Make changes
+   3. 🔄 Switch version - Use flagged version
+   4. ➕ Add duplicate - Include related
+   5. ⏭️ Skip - Don't create
+   
+6. WRITE only after user approves
+```
+
 **Expert Writing Standards:**
-1. **Second Person** - "You can configure..."
-2. **Active Voice** - "Run the command"
-3. **Task-Oriented Headings** - "How to add..."
-4. **Include Examples** - Every concept
-5. **Progressive Disclosure** - Basic → Advanced
+1. **Search before write** - ALWAYS find source files first
+2. **No hallucination** - Only real data from files
+3. **Review with user** - Show draft before creating
+4. **Flag feature flags** - Ask which version
+5. **Flag duplicates** - Let user choose
+6. **Second Person** - "You can configure..."
+7. **Include REAL Examples** - From tests/examples
+8. **Use Mermaid Diagrams** - For architecture, flows, sequences
+
+**Mermaid Diagram Requirements:**
+| Content | Diagram Type |
+|---------|--------------|
+| Architecture | `flowchart TB` |
+| Data flow | `flowchart LR` |
+| API calls | `sequenceDiagram` |
+| State machine | `stateDiagram-v2` |
+| Data models | `erDiagram` |
+
+Example:
+```mermaid
+sequenceDiagram
+    User->>API: Request
+    API->>Service: Process
+    Service-->>API: Response
+    API-->>User: Result
+```
 
-### Step 8: Update docs.json
+### Step 8: Create docs.json and theme.json
+
+**CRITICAL: Read schema files before creating config files.**
+
+```
+📋 SCHEMA REFERENCES (Read before writing)
+
+1. schemas/docs.schema.json → docs.json structure
+2. schemas/theme.schema.json → theme.json structure
+```
+
+**Review config with user before writing:**
+
+```
+═══════════════════════════════════════════════════
+CONFIG REVIEW: docs.json
+═══════════════════════════════════════════════════
 
-```json
 {
-  "docType": "api",
+  "$schema": "https://devdoc.sh/docs.json",
+  "name": "[Product Name]",
+  "docType": "[api|product|internal]",
   "navigation": {
     "tabs": [
-      { "tab": "Guides", "groups": [...] },
-      { "tab": "API Reference", "type": "openapi", "spec": "api-reference/openapi.json" }
+      { "tab": "Guides", "type": "docs", "groups": [...] },
+      { "tab": "API Reference", "type": "openapi" }
     ]
   }
 }
+
+Validated against: schemas/docs.schema.json ✓
+
+OPTIONS:
+1. ✅ Approve
+2. ✏️ Edit
+3. ❌ Cancel
 ```
 
+**Quick Reference:**
+- Tab types: `docs`, `openapi`, `graphql`, `changelog`
+- Icons: `rocket-launch`, `book-open`, `code`, `gear`, `terminal`, `star`
+- Colors: indigo (#6366f1), blue (#3b82f6), green (#10b981)
+
 ### Step 9: Summary
 
 ```
@@ -299,8 +422,15 @@ Next: `devdoc dev` to preview
 | **Project overview first** | Quick git scan to understand structure |
 | **Strategy first** | Goals and audience before structure |
 | **Audience-driven** | Match content to user needs |
+| **Support multi-role** | Handle products with multiple user roles |
 | **Diátaxis types** | Classify every page |
 | **IA approval required** | User confirms before generating |
+| **Search before generate** | ALWAYS search/read files before each page |
+| **No hallucination** | Only use real data from source files |
+| **Review before write** | ALWAYS show draft for user approval |
+| **Flag feature flags** | Detect conditional features, ask which version |
+| **Flag duplicates** | Find similar features, let user choose |
+| **Flag unclear sections** | Offer auto-correct IA if info not found |
 | **Expert writing** | 2nd person, active voice |
 | **Mark unknowns** | Add TODO for review |