@brainfish-ai/devdoc 0.1.36 → 0.1.38

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

@@ -7,7 +7,7 @@ description: Create new documentation pages interactively. Analyzes codebase and
 
 When user wants to create documentation:
 
-### Step 0: Read Context Memory
+### Step 0: Read Context & Code Graph
 
 **First, read `.devdoc/context.json` if it exists:**
 - Use `product.name` for product references
@@ -15,6 +15,13 @@ When user wants to create documentation:
 - Use `documentation.codeExamples.primaryLanguage` for code
 - Read templates from `documentation.templates`
 
+**Then, read `.devdoc/code-graph.json` if it exists:**
+- Use `modules` array to understand codebase structure
+- Reference exact function signatures from `exports`
+- Use `types` array for type definitions
+- Find examples in `examples` array
+- Reference `errors` for error handling docs
+
 ### Step 1: Understand What to Create
 
 Ask the user:
@@ -63,20 +70,30 @@ Based on their choice:
 
 When documenting code:
 
+**If `.devdoc/code-graph.json` exists:**
+```
+Read from code-graph.json:
+- modules[].exports → Function signatures, params, returns
+- types[] → Type definitions
+- examples[] → Code examples
+- api.endpoints[] → API routes
+- errors[] → Error types
+```
+
+**If code-graph.json doesn't exist:**
 ```
-Scan for:
+Scan the codebase 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
+"I found in code-graph.json:
+- Module: `auth` with 5 exports (login, logout, verifyToken...)
+- Types: User, AuthToken, Session
+- Examples: `examples/auth-flow.ts`
 
 Should I proceed with generating documentation for these?"
 
@@ -98,9 +115,29 @@ 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.)
+3. **Use code-graph.json** for accuracy:
+   - Get exact function signatures from `exports`
+   - Get type definitions from `types`
+   - Reference examples from `examples` array
+   - Document errors from `errors` array
+4. **Include mermaid diagrams** for flows/architecture
+5. **Add real code examples** from codebase/code-graph
+6. **Use proper MDX components** (Steps, Cards, Tabs, etc.)
+
+**Example using code-graph:**
+```
+// From code-graph.json:
+{
+  "name": "login",
+  "type": "function",
+  "signature": "login(email: string, password: string): Promise<AuthToken>",
+  "params": [...]
+}
+
+// Generate accurate documentation:
+## login(email, password)
+Authenticate user and return JWT token.
+```
 
 ### Step 6: Propose File Location
 

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

@@ -7,7 +7,7 @@ description: Update existing documentation by analyzing codebase changes or user
 
 When user wants to update documentation:
 
-### Step 0: Read Context Memory
+### Step 0: Read Context & Code Graph
 
 **First, read `.devdoc/context.json` if it exists:**
 - Use `product.name` for product references
@@ -15,6 +15,12 @@ When user wants to update documentation:
 - 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:
@@ -42,13 +48,24 @@ Based on their choice:
   - Other (describe)"
 
 #### For Codebase Sync:
-- Locate source code (from context or `../`)
-- Compare documentation against code:
+**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:
   - 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`
@@ -69,24 +86,31 @@ Based on their choice:
 
 ### Step 3: Generate Sync Report (if syncing)
 
+**Compare docs against code-graph.json:**
+
 ```
 ## Documentation Sync Report
 
-### Outdated (Action Required)
+### Signature Changes (from code-graph.json)
 - `docs/api/users.mdx`: Function signature changed
   - Documented: `createUser(name, email)`
-  - Current: `createUser(options: CreateUserInput)`
+  - Code-graph: `createUser(options: CreateUserInput)`
   
-- `docs/quickstart.mdx`: Package version outdated
-  - Documented: v1.2.0
-  - Current: v2.0.0
+### 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
 
-### Terminology Issues
-- `docs/guides/intro.mdx:15`: Uses "charge" instead of "payment"
+### Type Changes
+- `User` interface: Added `role` property
+- `AuthToken`: Changed `expiresAt` type
 
-### Missing Documentation
-- `src/utils/newFeature.ts` - New export, not documented
-- `POST /api/v2/webhooks` - New endpoint
+### New Endpoints (from code-graph.api.endpoints)
+- `POST /api/v2/webhooks` - Not documented
 
 ### Up to Date ✓
 - `docs/guides/authentication.mdx`
@@ -96,7 +120,8 @@ Based on their choice:
 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"
+3. **Specific items** - Tell me which to fix
+4. **Refresh code-graph first** - Re-scan codebase before updating"
 
 ### Step 4: Propose Changes