@brainfish-ai/devdoc 0.1.39 → 0.1.41

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

@@ -117,7 +117,7 @@ Files: 5 changed
 
 **Next steps:**
 1. **Push changes**: `git push origin main`
-2. **Deploy docs**: `npx @brainfish-ai/devdoc deploy`
+2. **Deploy docs**: `npm run deploy`
 3. **Create PR**: If on a feature branch
 
 Would you like me to push the changes?"

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

@@ -159,7 +159,7 @@ Does this location work, or would you prefer somewhere else?"
 - `docs/guides/{topic}.mdx` - {description}
 - Updated `docs.json` navigation
 
-Preview with `npx @brainfish-ai/devdoc dev`
+Preview with `npm run dev`
 
 Want me to create another page or make changes to this one?"
 

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

@@ -178,7 +178,7 @@ If pages were added/removed/moved:
 - `docs/quickstart.mdx` - Updated to v2.0.0
 - `docs.json` - Added webhooks page
 
-Changes ready for review. Run `npx @brainfish-ai/devdoc dev` to preview.
+Changes ready for review. Run `npm run dev` to preview.
 
 Want me to commit these changes? Use `/commit` when ready."
 

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

@@ -1,290 +1,314 @@
 ---
-description: Rules for bootstrapping documentation with user-driven preferences and code memory mapping
+description: Expert documentation bootstrap using Diátaxis framework and audience-driven planning
 globs: ["**/README.md", "**/package.json", "**/src/**", "**/lib/**"]
 ---
 
-# Repository Analysis for Documentation
+# Expert Documentation Bootstrap
 
-When asked to bootstrap or generate initial documentation:
+When bootstrapping documentation, follow the **Documentation Planning Pyramid**:
 
-## Step 1: Check Existing Context & Codebase
+```
+OVERVIEW  →  STRATEGY  →  IA  →  APPROVAL  →  CONTENT
+```
+
+## Phase 1: Strategy (WHY & WHO)
 
-**Detect if codebase exists:**
-- Look for: package.json, src/, lib/, app/, *.py, *.ts, *.go
+### Step 1: Project Overview (Quick Scan)
 
-**If NO codebase:**
-- "No codebase detected. Creating docs-only project."
-- Skip code-graph, go to Step 2 → Step 6
+**Get a quick understanding using git:**
 
-**If codebase exists, check git:**
 ```bash
-git rev-parse HEAD           # Current commit
+git ls-files                                    # List all files
+git ls-files | cut -d'/' -f1 | sort -u         # Top-level folders
+git ls-files | grep -E "(README|package\.json|openapi|swagger)"  # Key files
+```
+
+**Generate brief summary (<100 words):**
+
+```
+📁 PROJECT OVERVIEW
+
+Name: [from package.json/README]
+Type: [API/Library/CLI/Web App]
+Language: [TypeScript/Python/Go]
+Framework: [Next.js/Express/FastAPI]
+
+Structure:
+├── src/     → Source code
+├── lib/     → Library
+├── api/     → API routes
+└── tests/   → Tests
+
+Key Files: README.md, package.json, openapi.json
+
+Summary: [One sentence describing what this project does]
 ```
 
-**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 NO codebase:** "No codebase detected. Creating docs-only project."
 
-**If `.devdoc/context.json` exists:** Read and use it.
-**If missing:** Proceed to ask user preferences first.
+**If `.devdoc/context.json` exists:** Read and use existing preferences.
 
-## Step 2: Ask User Preferences First
+### Step 2: Define Goals & Audience
 
-**Don't auto-scan yet. Ask what they want:**
+**Ask strategic questions:**
 
-### Question 1: Documentation Type
+#### Question 1: Documentation Purpose
 ```
-What type of documentation are you creating?
+What is the primary goal?
 
-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
+1. **Enable team productivity** - Internal developers
+2. **Onboard new developers** - New team members
+3. **Support API consumers** - External developers
+4. **Guide product users** - End users
+5. **Inform stakeholders** - Architecture/decisions
 ```
 
-### Question 2: API Type (if API Docs)
+#### Question 2: Primary Audience
 ```
-What type of API do you have?
+Who is your PRIMARY audience?
 
-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)
+1. **Internal Developer** → Code flow, architecture, debugging
+2. **External Developer** → Quick start, auth, code examples
+3. **Product User** → Tutorials, feature guides
+4. **Content Author** → MDX syntax, structure
 ```
 
-### Question 3: Target Audience
+#### Question 3: Documentation Domain
 ```
-Who is your primary audience?
+1. **API Docs** - Voice: Professional, code-focused
+2. **Product Docs** - Voice: Friendly, approachable
+3. **Internal Docs** - Voice: Technical, direct
 ```
 
-### Question 4: Code Examples Language
+#### Question 4: API Type (if API Docs)
 ```
-What language for code examples? (TypeScript, Python, curl, etc.)
+1. **OpenAPI/REST** - Have spec file
+2. **GraphQL** - Have schema
+3. **Both** - REST and GraphQL
+4. **Manual** - No spec file
 ```
 
-## Step 3: Import API Spec (if applicable)
+#### Question 5: Code Examples Language
+```
+TypeScript, Python, curl, Go, etc.
+```
+
+---
+
+## Phase 2: Information Architecture (WHAT)
 
-**Ask user for spec path or search:**
+### Step 3: Import API Specs (if applicable)
 
-OpenAPI: `openapi.json`, `swagger.json`, `**/openapi.*`
-GraphQL: `schema.graphql`, `schema.gql`, `**/*.graphql`
+**OpenAPI:** Search for `openapi.json`, `swagger.json`
+**GraphQL:** Search for `schema.graphql`
 
 1. Copy spec to `api-reference/`
 2. Validate format
-3. Extract metadata (endpoints, auth, types)
+3. Extract metadata
 
-## Step 4: Build Code Graph (Optional)
+### Step 4: Plan Content Using Diátaxis Framework
 
-**Skip if:** No codebase, user chose skip, or docs-only project.
+| Type | Purpose | Examples |
+|------|---------|----------|
+| **Tutorial** | Learning-oriented | "Build Your First..." |
+| **How-To** | Task-oriented | "Add Custom Domain" |
+| **Reference** | Information lookup | CLI flags, Config |
+| **Explanation** | Understanding | Architecture, Concepts |
 
-**If scanning, create `.devdoc/code-graph.json`:**
+**Structure by Domain:**
 
+#### API Docs
 ```
-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
+docs/
+├── index.mdx           # [explanation]
+├── quickstart.mdx      # [tutorial]
+├── authentication.mdx  # [how-to]
+├── guides/             # [explanation/how-to]
+└── api-reference/      # [reference]
 ```
 
-**For each module, extract:**
-- All public functions with FULL signatures
-- Class definitions with methods
-- Type/interface definitions
-- Exported constants
-- Error types and codes
+#### Product Docs
+```
+docs/
+├── index.mdx           # [explanation]
+├── getting-started/    # [tutorial]
+├── features/           # [how-to]
+└── troubleshooting/    # [how-to]
+```
 
-**Save to `.devdoc/code-graph.json`:**
-```json
-{
-  "$schema": "https://devdoc.sh/schemas/code-graph.json",
-  "version": "1.0",
-  "generatedAt": "[timestamp]",
-  "git": {
-    "commitHash": "[full 40-char hash]",
-    "commitShort": "[7-char hash]",
-    "branch": "[branch name]",
-    "isDirty": false
-  },
-  "project": {
-    "name": "[name]",
-    "language": "[lang]",
-    "framework": "[framework]",
-    "rootDir": "src/"
-  },
-  "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" }
-  ]
-}
+#### Internal Docs
+```
+docs/
+├── index.mdx           # [explanation]
+├── getting-started/    # [how-to]
+├── architecture/       # [explanation]
+├── development/        # [how-to]
+└── contributing.mdx    # [how-to]
 ```
 
-## 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]"
-  }
-}
-```
+## Phase 3: Approval (REQUIRED)
 
-## Step 6: Plan Structure Based on Preferences
+### Step 5: Present IA for User Approval
+
+**IMPORTANT: Always get user approval before generating.**
 
-### API Docs
 ```
+📋 PROPOSED DOCUMENTATION ARCHITECTURE
+
+Based on your preferences:
+  - Goal: [selected goal]
+  - Audience: [primary audience]  
+  - Domain: [api/product/internal]
+
+═══════════════════════════════════════════════════
+              NAVIGATION STRUCTURE
+═══════════════════════════════════════════════════
+
+📑 TAB: Guides
+├── 📁 Getting Started
+│   ├── Introduction           # index.mdx [explanation]
+│   ├── Quickstart             # quickstart.mdx [tutorial]
+│   └── Authentication         # authentication.mdx [how-to]
+└── 📁 Core Concepts
+    └── Overview               # guides/overview.mdx [explanation]
+
+📑 TAB: API Reference (OpenAPI)
+└── [Auto-generated from openapi.json]
+
+═══════════════════════════════════════════════════
+                FILE STRUCTURE
+═══════════════════════════════════════════════════
+
 docs/
 ├── index.mdx
 ├── quickstart.mdx
 ├── authentication.mdx
-├── guides/
-├── api-reference/
-│   ├── openapi.json (or schema.graphql)
-│   └── introduction.mdx
-└── sdks/
-```
+└── api-reference/openapi.json
 
-### Product Docs
-```
-docs/
-├── index.mdx
-├── getting-started/
-├── features/
-├── tutorials/
-└── troubleshooting/
-```
+═══════════════════════════════════════════════════
+               CONTENT SUMMARY
+═══════════════════════════════════════════════════
 
-### Internal Docs
-```
-docs/
-├── index.mdx
-├── getting-started/
-├── architecture/
-├── development/
-└── contributing.mdx
-```
+📚 Tutorials: 1 page
+📝 How-To Guides: 1 page
+💡 Explanations: 2 pages
+
+Total: 4 pages
+
+═══════════════════════════════════════════════════
+                GAPS ANALYSIS
+═══════════════════════════════════════════════════
 
-## Step 7: Generate Documentation
+⚠️  No troubleshooting guide
+⚠️  No changelog
 
-**Use code graph for accuracy:**
+───────────────────────────────────────────────────
+
+Does this look complete?
+
+1. ✅ **Approve** - Generate with this structure
+2. ✏️  **Modify** - Change pages/navigation
+3. ➕ **Add suggested** - Add missing docs
+4. ❌ **Restart** - Reconsider goals
+```
+
+---
 
-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
+## Phase 4: Content (HOW)
 
-## Step 8: Update docs.json
+### Step 6: Save Context (After Approval)
 
-**OpenAPI:**
+Create `.devdoc/context.json`:
 ```json
 {
-  "docType": "api",
-  "navigation": {
-    "tabs": [
-      { "tab": "Guides", "groups": [...] },
-      { "tab": "API Reference", "type": "openapi", "spec": "api-reference/openapi.json" }
+  "strategy": {
+    "goal": "[goal]",
+    "audience": { "primary": "[type]", "needs": [...] }
+  },
+  "preferences": {
+    "docType": "[api/product/internal]",
+    "codeLanguage": "[language]"
+  },
+  "contentPlan": {
+    "approved": true,
+    "pages": [
+      { "path": "index.mdx", "type": "explanation" },
+      { "path": "quickstart.mdx", "type": "tutorial" }
     ]
   }
 }
 ```
 
-**GraphQL:**
+### Step 7: Generate Using Writing Guidelines
+
+**Only after user approval in Step 5.**
+
+**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
+
+### Step 8: Update docs.json
+
 ```json
 {
+  "docType": "api",
   "navigation": {
     "tabs": [
       { "tab": "Guides", "groups": [...] },
-      { "tab": "GraphQL API", "type": "graphql", "schema": "api-reference/schema.graphql" }
+      { "tab": "API Reference", "type": "openapi", "spec": "api-reference/openapi.json" }
     ]
   }
 }
 ```
 
-## Step 9: Summary
+### Step 9: Summary
 
 ```
 ✅ Documentation Generated!
 
-Preferences:
-  - Type: API Documentation
-  - API: OpenAPI/REST
+Strategy:
+  - Goal: [goal]
   - Audience: [audience]
-  - Code: [language]
+  - Domain: [domain]
+
+Content (Diátaxis):
+  - Tutorials: X pages
+  - How-To: X pages
+  - Reference: X pages
+  - Explanations: X pages
 
 Files created:
-  - .devdoc/context.json (preferences)
-  - .devdoc/code-graph.json (code analysis)
+  - .devdoc/context.json
   - docs.json
-  - [list of mdx files]
+  - [mdx files]
 
-Next: Run `devdoc dev` to preview, then "whisk theme" for branding.
+Next: `devdoc dev` to preview
 ```
 
+---
+
 ## Key Principles
 
 | 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 |
-
-## Code Graph Benefits
-
-- **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
+| **Project overview first** | Quick git scan to understand structure |
+| **Strategy first** | Goals and audience before structure |
+| **Audience-driven** | Match content to user needs |
+| **Diátaxis types** | Classify every page |
+| **IA approval required** | User confirms before generating |
+| **Expert writing** | 2nd person, active voice |
+| **Mark unknowns** | Add TODO for review |
+
+## Quality Checklist
+
+- [ ] Title is clear
+- [ ] Intro explains "why"
+- [ ] Content type matches purpose
+- [ ] Code examples included
+- [ ] Links to related docs
+- [ ] Progressive disclosure

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

@@ -83,7 +83,7 @@ Branch: `main`
 
 Next steps:
 1. Push: `git push`
-2. Deploy: `npx @brainfish-ai/devdoc deploy`
+2. Deploy: `npm run deploy`
 
 Push changes?"