@brainfish-ai/devdoc 0.1.36 → 0.1.38

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
 

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

@@ -7,10 +7,16 @@ globs: ["**/*.mdx", "**/docs.json"]
 
 When asked to update documentation:
 
-## Step 0: Read Context
+## Step 0: Read Context & Code Graph
 
 Read `.devdoc/context.json` for terminology and conventions.
 
+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
+
 ## Step 1: Understand What to Update
 
 Ask: "What would you like to update?
@@ -27,22 +33,33 @@ Ask: "What would you like to update?
 - Ask what changes needed
 
 **For Codebase Sync:**
-Compare docs vs code:
-- Function signatures changed?
-- New exports undocumented?
-- Removed features still documented?
-- Versions outdated?
+
+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)
 
 Generate sync report:
 ```
-## Sync Report
+## Sync Report (from code-graph.json)
+
+### Signatures Changed
+- `api/users.mdx`: createUser signature changed
+  - Documented: createUser(name, email)
+  - Code-graph: createUser(options: CreateUserInput)
+
+### New Exports (not documented)
+- auth.refreshToken()
+- users.deleteUser()
 
-### Outdated
-- `api/users.mdx`: signature changed
-- `quickstart.mdx`: version outdated
+### Removed (documented but not in code-graph)
+- legacyAuth() - removed
 
-### Missing
-- New endpoint not documented
+### Types Changed
+- User interface: added `role` property
 
 ### Up to Date ✓
 - `guides/auth.mdx`