@brainfish-ai/devdoc 0.1.37 → 0.1.39

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
 

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

@@ -1,5 +1,5 @@
 ---
-description: Rules for bootstrapping documentation with context memory and API spec detection
+description: Rules for bootstrapping documentation with user-driven preferences and code memory mapping
 globs: ["**/README.md", "**/package.json", "**/src/**", "**/lib/**"]
 ---
 
@@ -7,131 +7,224 @@ globs: ["**/README.md", "**/package.json", "**/src/**", "**/lib/**"]
 
 When asked to bootstrap or generate initial documentation:
 
-## Step 1: Check Context Memory
+## Step 1: Check Existing Context & Codebase
 
-**First, check if `.devdoc/context.json` exists:**
+**Detect if codebase exists:**
+- Look for: package.json, src/, lib/, app/, *.py, *.ts, *.go
 
-- **If populated:** Read and use existing context. Tell user: "Using existing product context."
-- **If empty/missing:** Run Discovery Flow below.
+**If NO codebase:**
+- "No codebase detected. Creating docs-only project."
+- Skip code-graph, go to Step 2 → Step 6
 
-## Step 2: Discovery Flow
+**If codebase exists, check git:**
+```bash
+git rev-parse HEAD           # Current commit
+```
 
-### 2a. Locate Project
+**If `.devdoc/code-graph.json` exists:**
+1. Compare `git.commitHash` vs current HEAD
+2. **Same commit** → "Code graph up to date" → Skip to Step 6
+3. **Different commit** → "{N} files changed"
+   - Ask: "1. Full rescan  2. Incremental  3. Skip"
 
-- If `docs.json` exists → you're in docs folder, source is in `../`
-- If `package.json` + `src/` exist → you're at repo root
-- Otherwise, ask user for source code path
+**If `.devdoc/context.json` exists:** Read and use it.
+**If missing:** Proceed to ask user preferences first.
 
-### 2b. Scan for API Specs
+## Step 2: Ask User Preferences First
 
-**Search for OpenAPI:**
-- `openapi.json`, `openapi.yaml`, `swagger.json`, `swagger.yaml`
-- `**/openapi.*`, `**/swagger.*`
+**Don't auto-scan yet. Ask what they want:**
 
-**Search for GraphQL:**
-- `schema.graphql`, `schema.gql`
-- `**/*.graphql`
+### Question 1: Documentation Type
+```
+What type of documentation are you creating?
 
-**Store paths for import prompt.**
+1. API Docs - REST/GraphQL API reference for developers
+2. Product Docs - Feature guides and tutorials for end users
+3. Internal Docs - Team setup, architecture, contribution guides
+```
 
-### 2c. Auto-Discover
+### Question 2: API Type (if API Docs)
+```
+What type of API do you have?
 
-Scan and extract:
-- **README.md:** Product name, description, features
-- **package.json:** Language, framework, dependencies
-- **OpenAPI:** API style, base URL, auth, endpoint count
-- **GraphQL:** Types, queries, mutations count
-- **Source structure:** Key directories, conventions
+1. OpenAPI/REST - I have an OpenAPI/Swagger spec
+2. GraphQL - I have a GraphQL schema
+3. Both - REST and GraphQL APIs
+4. Manual - I'll document manually (no spec)
+```
 
-### 2d. Ask Key Questions
+### Question 3: Target Audience
+```
+Who is your primary audience?
+```
 
-1. **Documentation Type:**
-   "What type of documentation?
-   1. **internal** - Team setup, architecture
-   2. **api** - API reference, SDKs for developers
-   3. **product** - Feature guides for end users"
+### Question 4: Code Examples Language
+```
+What language for code examples? (TypeScript, Python, curl, etc.)
+```
 
-2. **Import API Spec (if found):**
+## Step 3: Import API Spec (if applicable)
 
-   **For OpenAPI:**
-   "Found OpenAPI spec at `{path}` with {n} endpoints.
-   1. **Import** - Copy to api-reference/openapi.json
-   2. **Reference** - Point to existing location
-   3. **Skip** - Manual docs only"
+**Ask user for spec path or search:**
 
-   **For GraphQL:**
-   "Found GraphQL schema at `{path}` with {n} types.
-   1. **Import** - Copy to api-reference/schema.graphql
-   2. **Reference** - Point to existing location  
-   3. **Skip** - Manual docs only"
+OpenAPI: `openapi.json`, `swagger.json`, `**/openapi.*`
+GraphQL: `schema.graphql`, `schema.gql`, `**/*.graphql`
 
-   **For Both:**
-   "Found OpenAPI and GraphQL specs.
-   1. **OpenAPI** - REST API playground
-   2. **GraphQL** - GraphQL playground
-   3. **Both** - Separate tabs for each
-   4. **Skip** - Manual only"
+1. Copy spec to `api-reference/`
+2. Validate format
+3. Extract metadata (endpoints, auth, types)
 
-3. **Target Audience:**
-   "Who is your primary audience?"
+## Step 4: Build Code Graph (Optional)
 
-4. **Terminology (optional):**
-   "Any terms to use/avoid? Brand names? (Enter to skip)"
+**Skip if:** No codebase, user chose skip, or docs-only project.
 
-5. **Code Examples:**
-   "Primary language for code examples?"
+**If scanning, create `.devdoc/code-graph.json`:**
 
-### 2e. Create Context Memory
+```
+Scan and map:
+├── README.md → name, description, features
+├── package.json → language, framework, deps
+├── src/
+│   ├── api/ → routes, controllers
+│   ├── models/ → data schemas
+│   ├── services/ → business logic
+│   └── types/ → type definitions
+├── tests/ → code examples
+└── examples/ → usage examples
+```
 
-Create `.devdoc/context.json`:
+**For each module, extract:**
+- All public functions with FULL signatures
+- Class definitions with methods
+- Type/interface definitions
+- Exported constants
+- Error types and codes
 
+**Save to `.devdoc/code-graph.json`:**
 ```json
 {
-  "$schema": "https://devdoc.sh/schemas/context.json",
+  "$schema": "https://devdoc.sh/schemas/code-graph.json",
   "version": "1.0",
-  "lastUpdated": "[timestamp]",
-  "product": {
-    "name": "[discovered]",
-    "description": "[discovered]",
-    "type": "[api/sdk/platform/cli]",
-    "targetAudience": "[from question]"
-  },
-  "api": {
-    "style": "[REST/GraphQL if detected]",
-    "specPath": "[imported spec path]",
-    "baseUrl": "[from spec]",
-    "authentication": { "type": "[from spec]" }
+  "generatedAt": "[timestamp]",
+  "git": {
+    "commitHash": "[full 40-char hash]",
+    "commitShort": "[7-char hash]",
+    "branch": "[branch name]",
+    "isDirty": false
   },
-  "codebase": {
-    "language": "[detected]",
-    "framework": "[detected]",
-    "sourceLocation": "../"
+  "project": {
+    "name": "[name]",
+    "language": "[lang]",
+    "framework": "[framework]",
+    "rootDir": "src/"
   },
-  "documentation": {
-    "voice": "[based on docType]",
-    "codeExamples": { "primaryLanguage": "[from question]" },
-    "templates": {
-      "guide": ".devdoc/templates/guide.md",
-      "apiReference": ".devdoc/templates/api-reference.md"
+  "modules": [
+    {
+      "name": "auth",
+      "path": "src/auth/",
+      "description": "Authentication",
+      "exports": [
+        {
+          "name": "login",
+          "type": "function",
+          "signature": "login(email: string, password: string): Promise<AuthToken>",
+          "params": [
+            { "name": "email", "type": "string" },
+            { "name": "password", "type": "string" }
+          ],
+          "returns": { "type": "Promise<AuthToken>" },
+          "async": true
+        }
+      ],
+      "docPriority": "high"
+    }
+  ],
+  "types": [
+    {
+      "name": "AuthToken",
+      "path": "src/types/auth.ts",
+      "kind": "interface",
+      "definition": "interface AuthToken { token: string; expiresAt: Date; }"
     }
+  ],
+  "examples": [
+    { "path": "examples/basic.ts", "description": "Basic usage", "tags": ["auth"] }
+  ],
+  "errors": [
+    { "name": "AuthError", "code": "AUTH_FAILED", "message": "Invalid credentials" }
+  ]
+}
+```
+
+## Step 5: Save Context
+
+Create `.devdoc/context.json`:
+```json
+{
+  "preferences": {
+    "docType": "[api/product/internal]",
+    "apiType": "[openapi/graphql/both/manual]",
+    "audience": "[target audience]",
+    "codeLanguage": "[language]"
+  },
+  "product": {
+    "name": "[name]",
+    "description": "[desc]"
+  },
+  "api": {
+    "style": "[REST/GraphQL]",
+    "specPath": "[path if imported]"
   }
 }
 ```
 
-## Step 3: Import API Spec
+## Step 6: Plan Structure Based on Preferences
 
-**For Import option:**
-1. Copy spec to `api-reference/`
-2. Validate spec format
-3. Update context.json with spec info
+### API Docs
+```
+docs/
+├── index.mdx
+├── quickstart.mdx
+├── authentication.mdx
+├── guides/
+├── api-reference/
+│   ├── openapi.json (or schema.graphql)
+│   └── introduction.mdx
+└── sdks/
+```
 
-**For Reference option:**
-1. Note relative path for docs.json
-2. Update context.json with spec info
+### Product Docs
+```
+docs/
+├── index.mdx
+├── getting-started/
+├── features/
+├── tutorials/
+└── troubleshooting/
+```
+
+### Internal Docs
+```
+docs/
+├── index.mdx
+├── getting-started/
+├── architecture/
+├── development/
+└── contributing.mdx
+```
+
+## Step 7: Generate Documentation
+
+**Use code graph for accuracy:**
 
-## Step 4: Update docs.json
+1. Read `.devdoc/code-graph.json` before each page
+2. Use EXACT function signatures from exports
+3. Reference types from types array
+4. Extract examples from examples array
+5. Document errors from errors array
+6. Add TODO markers for uncertain sections
 
-Add `docType` and API reference:
+## Step 8: Update docs.json
 
 **OpenAPI:**
 ```json
@@ -149,84 +242,49 @@ Add `docType` and API reference:
 **GraphQL:**
 ```json
 {
-  "docType": "api",
   "navigation": {
     "tabs": [
       { "tab": "Guides", "groups": [...] },
-      { "tab": "GraphQL API", "type": "graphql", "schema": "api-reference/schema.graphql", "endpoint": "https://..." }
+      { "tab": "GraphQL API", "type": "graphql", "schema": "api-reference/schema.graphql" }
     ]
   }
 }
 ```
 
-## Step 5: Generate Documentation
-
-**Before generating, always:**
-1. Read `.devdoc/context.json`
-2. Read appropriate template from `.devdoc/templates/`
-3. Apply terminology from context
-4. Use correct product name
-5. Match voice to docType
-6. Reference imported API spec
+## Step 9: Summary
 
-### docType: "internal"
 ```
-docs/
-├── .devdoc/context.json
-├── docs.json (docType: "internal")
-├── index.mdx
-├── getting-started/
-├── architecture/
-├── development/
-└── contributing.mdx
-```
-**Voice:** Technical, direct
+✅ Documentation Generated!
 
-### docType: "api"
-```
-docs/
-├── .devdoc/context.json
-├── docs.json (docType: "api")
-├── index.mdx
-├── quickstart.mdx
-├── authentication.mdx
-├── guides/
-├── api-reference/
-│   ├── openapi.json    # If imported
-│   └── schema.graphql  # If imported
-├── sdks/
-└── changelog.mdx
-```
-**Voice:** Professional, code-focused
+Preferences:
+  - Type: API Documentation
+  - API: OpenAPI/REST
+  - Audience: [audience]
+  - Code: [language]
 
-### docType: "product"
-```
-docs/
-├── .devdoc/context.json
-├── docs.json (docType: "product")
-├── index.mdx
-├── getting-started/
-├── features/
-├── tutorials/
-├── troubleshooting/
-└── release-notes.mdx
+Files created:
+  - .devdoc/context.json (preferences)
+  - .devdoc/code-graph.json (code analysis)
+  - docs.json
+  - [list of mdx files]
+
+Next: Run `devdoc dev` to preview, then "whisk theme" for branding.
 ```
-**Voice:** Friendly, non-technical
 
-## Content Guidelines
+## Key Principles
 
-| docType | Focus | Tone | Code |
-|---------|-------|------|------|
-| internal | Setup, architecture | Technical | Heavy |
-| api | Endpoints, auth, examples | Professional | Heavy |
-| product | Features, workflows | Friendly | Minimal |
+| Principle | Description |
+|-----------|-------------|
+| Ask first | Get user preferences before scanning |
+| Build code graph | Scan entire codebase with full signatures |
+| Store the graph | Save to code-graph.json for updates |
+| Real code only | Use exact signatures, never fabricate |
+| Mark unknowns | Add TODO for sections needing review |
 
-## Quality Guidelines
+## Code Graph Benefits
 
-- Use terminology from context.json consistently
-- Read templates before generating each page type
-- Extract real examples, don't fabricate
-- Add TODO for sections needing review
-- **Import existing API specs** instead of manual docs
-- **Validate specs** before importing
-- Update context.json if you learn new info
+- **Accurate docs** - Exact function signatures
+- **Complete coverage** - All exports documented
+- **Easy updates** - Re-scan refreshes the graph
+- **No hallucination** - Only document real code
+- **Type safety** - Reference actual type definitions

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

@@ -7,9 +7,16 @@ globs: ["**/*.mdx", "**/docs.json"]
 
 When asked to create documentation:
 
-## Step 0: Read Context
+## Step 0: Read Context & Code Graph
 
-Read `.devdoc/context.json` if exists for terminology, templates, and code language.
+Read `.devdoc/context.json` for terminology, templates, and code language.
+
+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
 
 ## Step 1: Understand What to Create
 
@@ -49,9 +56,14 @@ Read from `.devdoc/templates/`:
 
 1. Follow template structure
 2. Apply context (terminology, voice)
-3. Include mermaid diagrams for flows
-4. Add real code examples
-5. Use MDX components (Steps, Cards, etc.)
+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