@brainfish-ai/devdoc 0.1.33 → 0.1.35

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

@@ -1,5 +1,5 @@
 ---
-description: Rules for bootstrapping documentation from repository analysis
+description: Rules for bootstrapping documentation with context memory and API spec detection
 globs: ["**/README.md", "**/package.json", "**/src/**", "**/lib/**"]
 ---
 
@@ -7,114 +7,226 @@ globs: ["**/README.md", "**/package.json", "**/src/**", "**/lib/**"]
 
 When asked to bootstrap or generate initial documentation:
 
-## Step 1: Check for docType Configuration
+## Step 1: Check Context Memory
 
-**Read `docs.json` and check for `docType` field:**
+**First, check if `.devdoc/context.json` exists:**
+
+- **If populated:** Read and use existing context. Tell user: "Using existing product context."
+- **If empty/missing:** Run Discovery Flow below.
+
+## Step 2: Discovery Flow
+
+### 2a. Locate Project
+
+- 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
+
+### 2b. Scan for API Specs
+
+**Search for OpenAPI:**
+- `openapi.json`, `openapi.yaml`, `swagger.json`, `swagger.yaml`
+- `**/openapi.*`, `**/swagger.*`
+
+**Search for GraphQL:**
+- `schema.graphql`, `schema.gql`
+- `**/*.graphql`
+
+**Store paths for import prompt.**
+
+### 2c. Auto-Discover
+
+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
+
+### 2d. Ask Key Questions
+
+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"
+
+2. **Import API Spec (if found):**
+
+   **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"
+
+   **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"
+
+   **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"
+
+3. **Target Audience:**
+   "Who is your primary audience?"
+
+4. **Terminology (optional):**
+   "Any terms to use/avoid? Brand names? (Enter to skip)"
+
+5. **Code Examples:**
+   "Primary language for code examples?"
+
+### 2e. Create Context Memory
+
+Create `.devdoc/context.json`:
 
 ```json
 {
-  "name": "Project Name",
-  "docType": "api"  // "internal" | "api" | "product"
+  "$schema": "https://devdoc.sh/schemas/context.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]" }
+  },
+  "codebase": {
+    "language": "[detected]",
+    "framework": "[detected]",
+    "sourceLocation": "../"
+  },
+  "documentation": {
+    "voice": "[based on docType]",
+    "codeExamples": { "primaryLanguage": "[from question]" },
+    "templates": {
+      "guide": ".devdoc/templates/guide.md",
+      "apiReference": ".devdoc/templates/api-reference.md"
+    }
+  }
 }
 ```
 
-**If `docType` is set:** Use that value automatically. Tell user: "Using docType: {type} from docs.json"
+## Step 3: Import API Spec
 
-**If `docType` is NOT set, ask:**
+**For Import option:**
+1. Copy spec to `api-reference/`
+2. Validate spec format
+3. Update context.json with spec info
 
-"What type of documentation are you creating?
-1. **internal** - For your team: setup guides, architecture
-2. **api** - For developers using your product: API reference, SDKs
-3. **product** - For end users: feature guides, tutorials"
+**For Reference option:**
+1. Note relative path for docs.json
+2. Update context.json with spec info
 
-**After user answers, immediately save to docs.json:**
-Add `"docType": "{choice}"` to docs.json so it's saved for future use.
-Tell user: "Saved docType: {type} to docs.json - you won't be asked again."
+## Step 4: Update docs.json
 
-## Step 2: Locate Source Code
+Add `docType` and API reference:
 
-- 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
+**OpenAPI:**
+```json
+{
+  "docType": "api",
+  "navigation": {
+    "tabs": [
+      { "tab": "Guides", "groups": [...] },
+      { "tab": "API Reference", "type": "openapi", "spec": "api-reference/openapi.json" }
+    ]
+  }
+}
+```
 
-## Step 3: Analysis Checklist
+**GraphQL:**
+```json
+{
+  "docType": "api",
+  "navigation": {
+    "tabs": [
+      { "tab": "Guides", "groups": [...] },
+      { "tab": "GraphQL API", "type": "graphql", "schema": "api-reference/schema.graphql", "endpoint": "https://..." }
+    ]
+  }
+}
+```
 
-1. Read README.md for project overview
-2. Check package.json for name, description, dependencies, scripts
-3. Scan source directory structure
-4. Identify API endpoints or exported functions
-5. Look for OpenAPI/GraphQL specs
-6. Check for example files or tests
+## Step 5: Generate Documentation
 
-## Step 4: Generate Based on docType
+**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
 
 ### docType: "internal"
 ```
 docs/
-├── docs.json (with "docType": "internal")
-├── index.mdx              # Project overview
+├── .devdoc/context.json
+├── docs.json (docType: "internal")
+├── index.mdx
 ├── getting-started/
-│   ├── setup.mdx          # Dev environment setup
-│   ├── prerequisites.mdx
-│   └── first-contribution.mdx
 ├── architecture/
-│   ├── overview.mdx       # System design
-│   └── folder-structure.mdx
 ├── development/
-│   ├── workflow.mdx       # Git workflow, PR process
-│   ├── testing.mdx
-│   └── deployment.mdx
 └── contributing.mdx
 ```
+**Voice:** Technical, direct
 
 ### docType: "api"
 ```
 docs/
-├── docs.json (with "docType": "api")
-├── index.mdx              # Product intro
-├── quickstart.mdx         # 5-minute getting started
-├── authentication.mdx     # API keys, OAuth
+├── .devdoc/context.json
+├── docs.json (docType: "api")
+├── index.mdx
+├── quickstart.mdx
+├── authentication.mdx
 ├── guides/
-│   └── overview.mdx
 ├── api-reference/
-│   ├── introduction.mdx
-│   ├── errors.mdx
-│   └── openapi.json
-├── sdks/                  # If SDKs exist
-│   └── ...
+│   ├── openapi.json    # If imported
+│   └── schema.graphql  # If imported
+├── sdks/
 └── changelog.mdx
 ```
+**Voice:** Professional, code-focused
 
 ### docType: "product"
 ```
 docs/
-├── docs.json (with "docType": "product")
-├── index.mdx              # Product overview
+├── .devdoc/context.json
+├── docs.json (docType: "product")
+├── index.mdx
 ├── getting-started/
-│   ├── quickstart.mdx
-│   └── key-concepts.mdx
 ├── features/
-│   └── {feature}.mdx
 ├── tutorials/
-│   └── {workflow}.mdx
 ├── troubleshooting/
-│   ├── common-issues.mdx
-│   └── faq.mdx
 └── release-notes.mdx
 ```
+**Voice:** Friendly, non-technical
 
-## Content Guidelines by docType
+## Content Guidelines
 
 | docType | Focus | Tone | Code |
 |---------|-------|------|------|
-| internal | Setup, architecture, processes | Technical | Heavy |
-| api | Endpoints, auth, examples | Technical | Heavy |
-| product | Features, workflows, FAQs | Friendly | Minimal |
+| internal | Setup, architecture | Technical | Heavy |
+| api | Endpoints, auth, examples | Professional | Heavy |
+| product | Features, workflows | Friendly | Minimal |
 
 ## Quality Guidelines
 
+- Use terminology from context.json consistently
+- Read templates before generating each page type
 - Extract real examples, don't fabricate
-- Note areas needing human review with TODO
-- Generate SEO-friendly descriptions
-- Match tone to audience
-- Always set `docType` in generated docs.json
+- 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

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

@@ -0,0 +1,103 @@
+---
+description: Commit documentation changes to git
+globs: ["**/*.mdx", "**/docs.json"]
+---
+
+# Commit Documentation
+
+When asked to commit documentation changes:
+
+## Step 1: Check Status
+
+Run git status and show summary:
+
+"**Changes Ready to Commit:**
+
+Modified (3):
+- `guides/auth.mdx` - Updated examples
+- `api/users.mdx` - Added endpoint
+- `docs.json` - Updated navigation
+
+New (1):
+- `guides/webhooks.mdx`
+
+Deleted (1):
+- `old/deprecated.mdx`
+
+Options:
+1. Review changes
+2. Commit all
+3. Select files
+4. Cancel"
+
+## Step 2: Review (if requested)
+
+Show meaningful diff:
+```diff
+- const token = auth.getToken(user);
++ const token = await auth.getToken(user, { refresh: true });
+```
+
+## Step 3: Generate Message
+
+Suggest commit message based on changes:
+
+```
+docs: update authentication and add webhooks guide
+
+- Update auth.getToken() with refresh parameter
+- Add webhook integration guide
+- Remove deprecated API docs
+```
+
+Options:
+1. Use this message
+2. Edit message
+3. Custom message
+
+## Step 4: Confirm
+
+"Ready to commit:
+
+```
+docs: update authentication and add webhooks guide
+```
+
+Files: 5 changed
+
+Proceed? (yes/no)"
+
+## Step 5: Execute
+
+```bash
+git add docs/
+git commit -m "message"
+```
+
+## Step 6: Summary
+
+"✓ Committed!
+
+Commit: `abc1234`
+Branch: `main`
+
+Next steps:
+1. Push: `git push`
+2. Deploy: `npx @brainfish-ai/devdoc deploy`
+
+Push changes?"
+
+## Commit Types
+
+- `docs:` - Documentation changes
+- `fix:` - Fix doc errors
+- `feat:` - New doc features
+- `refactor:` - Reorganize docs
+- `chore:` - Maintenance
+
+## Safety
+
+- Always show changes first
+- Generate meaningful messages
+- Don't commit secrets
+- Suggest pushing, don't auto-push

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

@@ -0,0 +1,89 @@
+---
+description: Create new documentation pages interactively
+globs: ["**/*.mdx", "**/docs.json"]
+---
+
+# Create Documentation
+
+When asked to create documentation:
+
+## Step 0: Read Context
+
+Read `.devdoc/context.json` if exists for terminology, templates, and code language.
+
+## Step 1: Understand What to Create
+
+Ask: "What would you like to document?
+1. **A feature or concept** - I'll create a guide/tutorial
+2. **Code files** - Point me to the code, I'll generate docs
+3. **API endpoints** - I'll analyze your API
+4. **Something else** - Describe what you need"
+
+## Step 2: Gather Information
+
+**For Feature/Concept:**
+- Topic/title?
+- Page type? (Guide, Tutorial, Reference, Troubleshooting)
+- Specific sections?
+
+**For Code Documentation:**
+- Which files/directories?
+- Focus? (Public API, Architecture, Examples, All)
+- Read and extract functions, types, examples
+
+**For API Documentation:**
+- Check for OpenAPI/GraphQL specs
+- If found, offer to generate from spec
+- Extract endpoints, parameters, responses
+
+## Step 3: Read Template
+
+Read from `.devdoc/templates/`:
+- Guide → `guide.md`
+- Tutorial → `tutorial.md`
+- API → `api-reference.md`
+- Quickstart → `quickstart.md`
+- Troubleshooting → `troubleshooting.md`
+
+## Step 4: Generate Content
+
+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.)
+
+## Step 5: Save and Update Navigation
+
+1. Propose file location
+2. Create MDX file
+3. Ask to update docs.json
+4. Show summary
+
+## Code to Doc Example
+
+```typescript
+// Source
+export function validateToken(token: string): boolean
+```
+
+Generates:
+```mdx
+## validateToken
+
+Validates an authentication token.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `token` | `string` | JWT token to validate |
+
+**Returns:** `boolean`
+```
+
+## Guidelines
+
+- Extract real examples, don't fabricate
+- Include error handling
+- Add TODO for sections needing review
+- Use mermaid for complex flows
+- Apply terminology from context.json

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

@@ -0,0 +1,101 @@
+---
+description: Delete documentation pages interactively
+globs: ["**/*.mdx", "**/docs.json"]
+---
+
+# Delete Documentation
+
+When asked to delete documentation:
+
+## Step 1: Understand What to Delete
+
+Ask: "What would you like to delete?
+1. **A specific page** - Tell me which page(s)
+2. **Find unused pages** - I'll identify orphans
+3. **Deprecated content** - I'll find deprecated pages
+4. **Clean up** - Describe what to remove"
+
+## Step 2: Identify Pages
+
+**For Specific Page:**
+- Verify file exists
+- Check for incoming links
+
+**For Unused Pages:**
+Compare .mdx files vs docs.json:
+```
+Orphan pages (not in navigation):
+- drafts/unused.mdx
+- old/deprecated.mdx
+```
+
+**For Deprecated:**
+Search for deprecation markers in files.
+
+## Step 3: Analyze Impact
+
+Before deletion, check:
+- Incoming links from other pages
+- Entry in docs.json
+- Should redirect to new page?
+
+Show analysis:
+```
+Deleting `guides/old-feature.mdx`:
+
+Links from:
+- quickstart.mdx:45
+- api/overview.mdx:23
+
+In docs.json: Yes
+
+Options:
+1. Delete and fix links
+2. Delete and redirect
+3. Delete only
+4. Cancel
+```
+
+## Step 4: Confirm
+
+"Ready to delete?
+
+This will:
+- ❌ Delete the file
+- ❌ Remove from docs.json
+- ⚠️ Leave broken links (I can fix)
+
+Proceed?"
+
+## Step 5: Execute
+
+**Delete and Fix Links:**
+1. Delete file
+2. Update docs.json
+3. Fix links in other pages
+
+**Delete and Redirect:**
+1. Delete file
+2. Update docs.json
+3. Add redirect rule
+
+**Delete Only:**
+1. Delete file
+2. Update docs.json
+3. Warn about broken links
+
+## Summary
+
+"Deleted:
+- ❌ `guides/old-feature.mdx`
+- ✓ Removed from navigation
+- ✓ Fixed links in 2 pages
+
+Use `/commit-doc` when ready to commit."
+
+## Safety
+
+- Always confirm before deleting
+- Check for incoming links
+- Offer redirects for public pages
+- Never delete docs.json without explicit confirmation

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

@@ -0,0 +1,95 @@
+---
+description: Update existing documentation by analyzing codebase
+globs: ["**/*.mdx", "**/docs.json"]
+---
+
+# Update Documentation
+
+When asked to update documentation:
+
+## Step 0: Read Context
+
+Read `.devdoc/context.json` for terminology and conventions.
+
+## Step 1: Understand What to Update
+
+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"
+
+## Step 2: Analyze
+
+**For Specific Page:**
+- Read current content
+- Ask what changes needed
+
+**For Codebase Sync:**
+Compare docs vs code:
+- Function signatures changed?
+- New exports undocumented?
+- Removed features still documented?
+- Versions outdated?
+
+Generate sync report:
+```
+## Sync Report
+
+### Outdated
+- `api/users.mdx`: signature changed
+- `quickstart.mdx`: version outdated
+
+### Missing
+- New endpoint not documented
+
+### Up to Date ✓
+- `guides/auth.mdx`
+```
+
+**For Navigation:**
+- Read docs.json
+- Ask what to change
+
+## Step 3: Propose Changes
+
+Show what will change before applying:
+
+"I'll make these changes:
+- `api/users.mdx`: Update signature
+- `quickstart.mdx`: Update version
+- `docs.json`: Add new page
+
+Proceed?"
+
+## Step 4: Apply Updates
+
+- Preserve prose, update technical details
+- Fix terminology per context.json
+- 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
+
+Show what was updated and suggest:
+"Use `/commit-doc` when ready to commit changes."