@brainfish-ai/devdoc 0.1.39 → 0.1.41

package/ai-agents/.claude/skills/bootstrap-docs/SKILL.md

@@ -1,74 +1,140 @@
 ---
 name: bootstrap-docs
-description: Analyze repository and generate documentation with user-driven preferences and comprehensive code memory.
+description: Expert-level documentation bootstrap using Diátaxis framework and audience-driven planning.
 ---
 
 ## Instructions
 
-When bootstrapping documentation from a repository:
+When bootstrapping documentation from a repository, follow the **Documentation Planning Pyramid** approach used by documentation experts:
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                    DOCUMENTATION PLANNING PYRAMID                    │
+├─────────────────────────────────────────────────────────────────────┤
+│                         ┌─────────────┐                              │
+│                         │  STRATEGY   │  ← WHY (Step 1-2)            │
+│                         │  Overview & │                              │
+│                         │  Audience   │                              │
+│                         └──────┬──────┘                              │
+│                                │                                     │
+│                    ┌───────────┴───────────┐                         │
+│                    │  INFORMATION          │  ← WHAT (Step 3-4)      │
+│                    │  ARCHITECTURE         │                         │
+│                    └───────────┬───────────┘                         │
+│                                │                                     │
+│                       ┌────────┴────────┐                            │
+│                       │    APPROVAL     │  ← CONFIRM (Step 5)        │
+│                       │  User confirms  │                            │
+│                       │   IA structure  │                            │
+│                       └────────┬────────┘                            │
+│                                │                                     │
+│             ┌──────────────────┴──────────────────┐                  │
+│             │              CONTENT                │  ← HOW (Step 6-8) │
+│             │      Pages using Diátaxis Types     │                  │
+│             └─────────────────────────────────────┘                  │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Phase 1: Strategy (WHY)
+
+### Step 1: Project Overview (Quick Scan)
+
+**Get a quick understanding of the project using git:**
 
-### Step 1: Check Existing Context & Codebase
+```bash
+# List all tracked files
+git ls-files
+
+# Get folder structure (top-level)
+git ls-files | cut -d'/' -f1 | sort -u
 
-**First, detect if there's a codebase to scan:**
+# Check for key files
+git ls-files | grep -E "(README|package\.json|openapi|swagger|schema\.graphql)"
 ```
-Look for:
-- package.json, pyproject.toml, Cargo.toml, go.mod
-- src/, lib/, app/ directories
-- Any source code files
+
+**Generate a brief project summary (<100 words):**
+
+```
+📁 PROJECT OVERVIEW
+
+Name: [from package.json or README]
+Type: [API/Library/CLI/Web App]
+Language: [TypeScript/Python/Go/etc.]
+Framework: [Next.js/Express/FastAPI/etc.]
+
+Structure:
+├── src/           → Source code
+├── lib/           → Library code
+├── api/           → API routes
+├── docs/          → Documentation (if exists)
+└── tests/         → Test files
+
+Key Files:
+• README.md        → Project description
+• package.json     → Dependencies
+• openapi.json     → API spec (if exists)
+
+Summary: [One sentence describing what this project does]
 ```
 
 **If NO codebase found:**
 - Tell user: "No codebase detected. Creating docs-only project."
-- Skip code-graph generation entirely
-- Proceed to Step 2 for preferences, then Step 6 for structure
+- Skip to Step 2
 
-**If codebase exists, check git state:**
-```bash
-git rev-parse HEAD                    # Current commit hash
-git rev-parse --abbrev-ref HEAD       # Current branch
-```
+**If `.devdoc/context.json` exists:** Read and use existing preferences.
 
-**If `.devdoc/code-graph.json` exists:**
-1. Read `git.commitHash` from the file
-2. Compare to current HEAD:
-   - **Same commit** → "Code graph up to date (commit: {short_hash})"
-     - Skip to Step 6 (Plan Documentation)
-   - **Different commit** → Changes detected
-     - Run: `git diff {old_hash}..HEAD --name-only`
-     - Tell user: "{N} files changed since last scan"
-     - Ask: "1. Full rescan  2. Incremental (changed files only)  3. Skip"
+### Step 2: Define Documentation Goals & Audience
 
-**If `.devdoc/context.json` exists and is populated:**
-- Read the context file
-- Tell user: "Found existing product context."
-- If code-graph needs refresh → Go to Step 4
-- If code-graph is current → Skip to Step 6
+**Ask the user strategic questions before any scanning:**
 
-**If neither exists:**
-- Proceed to Step 2 (Ask User Preferences)
+#### Question 1: Documentation Purpose (WHY)
+```
+What is the primary goal of this documentation?
 
-### Step 2: Ask User Preferences First
+1. **Enable team productivity** - Help internal developers work faster
+2. **Onboard new developers** - Get new team members up to speed  
+3. **Support API consumers** - Help external devs integrate your API
+4. **Guide product users** - Help end users accomplish tasks
+5. **Inform stakeholders** - Communicate architecture and decisions
+```
 
-**Don't scan yet - ask the user what they want:**
+#### Question 2: Primary Audience (WHO)
+```
+Who is your PRIMARY audience? (Choose one)
 
-#### Question 1: Documentation Type
+1. **Internal Developer** - Engineers on your team
+   → Needs: Code flow, architecture, debugging, contribution guides
+   
+2. **External Developer** - API consumers, SDK users
+   → Needs: Quick start, authentication, code examples, reference
+   
+3. **Product User** - End users of your product
+   → Needs: Tutorials, feature guides, troubleshooting
+   
+4. **Content Author** - Technical writers, doc contributors
+   → Needs: MDX syntax, structure guidelines, publishing workflow
+   
+5. **Product Manager/Stakeholder** - Non-technical team members
+   → Needs: Feature overview, roadmap, IA map
+```
+
+#### Question 3: Documentation Domain
 ```
 What type of documentation are you creating?
 
 1. **API Docs** - REST/GraphQL API reference for developers
+   → Voice: Professional, code-focused
+   
 2. **Product Docs** - Feature guides and tutorials for end users
+   → Voice: Friendly, approachable
+   
 3. **Internal Docs** - Team setup, architecture, contribution guides
+   → Voice: Technical, direct
 ```
 
-#### Question 2: Codebase Connection (if codebase detected)
-```
-I detected a codebase. Would you like me to:
-
-1. **Scan codebase** - Build code-graph for accurate docs (recommended)
-2. **Skip scanning** - I'll write docs without code analysis
-```
-
-#### Question 3: API Type (if API Docs selected)
+#### Question 4: API Type (if API Docs selected)
 ```
 What type of API do you have?
 
@@ -78,18 +144,16 @@ What type of API do you have?
 4. **Manual** - I'll document the API manually (no spec file)
 ```
 
-#### Question 3: Target Audience
-```
-Who is your primary audience?
-(e.g., "Backend developers integrating our payment API", "Internal engineering team")
-```
-
-#### Question 4: Code Examples Language
+#### Question 5: Code Examples Language
 ```
 What language should code examples use?
 (e.g., TypeScript, Python, curl, Go)
 ```
 
+---
+
+## Phase 2: Information Architecture (WHAT)
+
 ### Step 3: Locate & Import API Specs (if applicable)
 
 **Only if user selected OpenAPI or GraphQL:**
@@ -112,310 +176,384 @@ Do you have a GraphQL schema? Please provide the path, or I can search for:
 2. Validate the spec
 3. Extract metadata (endpoints, types, auth)
 
-### Step 4: Build Code Graph (Optional)
+### Step 4: Plan Content Using Diátaxis Framework
 
-**Skip this step if:**
-- No codebase detected
-- User chose "Skip scanning" in Question 2
-- User is creating docs-only project
+**Classify each planned page by content type:**
 
-**If scanning, comprehensively analyze the codebase and build `.devdoc/code-graph.json`:**
+| Type | Purpose | When to Use | Example Pages |
+|------|---------|-------------|---------------|
+| **Tutorial** | Learning-oriented | First-time experience, guided learning | "Build Your First..." |
+| **How-To Guide** | Task-oriented | Accomplish specific goals | "Add Custom Domain", "Configure Theme" |
+| **Reference** | Information-oriented | Look up facts, specifications | Component props, CLI flags, Config schema |
+| **Explanation** | Understanding-oriented | Deeper comprehension | "How MDX Processing Works", Architecture |
 
-#### 4a. Project Metadata
-```
-Scan and extract:
-├── README.md → Product name, description, features
-├── package.json → Language, framework, dependencies
-├── LICENSE → License type
-└── .env.example → Required environment variables
-```
+**Map documentation structure based on domain:**
 
-#### 4b. Source Code Structure
+#### For API Docs:
 ```
-Map all directories:
-├── src/
-│   ├── api/ → API routes, controllers
-│   ├── models/ → Data models, schemas
-│   ├── services/ → Business logic
-│   ├── utils/ → Helper functions
-│   └── types/ → Type definitions
-├── tests/ → Test files (for code examples)
-└── examples/ → Example usage
+docs/
+├── index.mdx              # [Explanation] Overview, value prop
+├── quickstart.mdx         # [Tutorial] 5-min getting started
+├── authentication.mdx     # [How-To] Auth setup
+├── guides/
+│   ├── overview.mdx       # [Explanation] Core concepts
+│   └── {use-cases}.mdx    # [How-To] Common use cases
+├── api-reference/
+│   ├── openapi.json       # Imported spec
+│   ├── introduction.mdx   # [Explanation] API overview
+│   └── errors.mdx         # [Reference] Error codes
+└── sdks/                  # [Reference] SDK docs
 ```
 
-#### 4c. Deep Code Analysis
+#### For Product Docs:
 ```
-For each module, extract:
-- All public functions with FULL signatures
-- Class definitions with methods
-- Interface/type definitions
-- Exported constants
-- Error types and codes
-- Configuration options
+docs/
+├── index.mdx              # [Explanation] Product overview
+├── getting-started/
+│   ├── quickstart.mdx     # [Tutorial] First experience
+│   └── key-concepts.mdx   # [Explanation] Core concepts
+├── features/
+│   └── {feature}.mdx      # [How-To] Feature guides
+├── tutorials/
+│   └── {tutorial}.mdx     # [Tutorial] Step-by-step learning
+└── troubleshooting/       # [How-To] Problem solving
 ```
 
-#### 4d. Create Code Graph File
+#### For Internal Docs:
+```
+docs/
+├── index.mdx              # [Explanation] Project overview
+├── getting-started/
+│   ├── setup.mdx          # [How-To] Environment setup
+│   └── prerequisites.mdx  # [Reference] Requirements
+├── architecture/
+│   ├── overview.mdx       # [Explanation] System design
+│   ├── data-flow.mdx      # [Explanation] How data flows
+│   └── decisions/         # [Explanation] ADRs
+├── development/
+│   ├── workflow.mdx       # [How-To] Dev workflow
+│   └── debugging.mdx      # [How-To] Debugging guide
+└── contributing.mdx       # [How-To] Contribution guide
+```
+
+### Step 5: Present IA for Approval (REQUIRED)
+
+**IMPORTANT: Always get user approval before generating documentation.**
+
+Present the **complete Information Architecture** to the user, covering:
+1. **Navigation Structure** - Tabs, groups, and page ordering (what users see in sidebar)
+2. **File Structure** - Actual files to be created
+3. **Content Summary** - Diátaxis content type breakdown
+
+```
+📋 PROPOSED DOCUMENTATION ARCHITECTURE
+
+Based on your preferences:
+  - Goal: [selected goal]
+  - Audience: [primary audience]  
+  - Domain: [api/product/internal]
+
+═══════════════════════════════════════════════════════════════
+                      NAVIGATION STRUCTURE
+           (How documentation appears in the sidebar)
+═══════════════════════════════════════════════════════════════
+
+📑 TAB: Guides
+├── 📁 Getting Started
+│   ├── Introduction                    # index.mdx [explanation]
+│   ├── Quickstart                      # quickstart.mdx [tutorial]
+│   └── Authentication                  # authentication.mdx [how-to]
+│
+├── 📁 Core Concepts
+│   ├── Overview                        # guides/overview.mdx [explanation]
+│   ├── Working with Resources          # guides/resources.mdx [how-to]
+│   └── Error Handling                  # guides/errors.mdx [how-to]
+│
+└── 📁 SDKs
+    └── TypeScript SDK                  # sdks/typescript.mdx [reference]
+
+📑 TAB: API Reference (OpenAPI)
+└── [Auto-generated from openapi.json]
+    ├── Introduction                    # api-reference/introduction.mdx [explanation]
+    ├── Authentication                  # (from spec)
+    ├── Endpoints                       # (from spec)
+    └── Error Codes                     # api-reference/errors.mdx [reference]
+
+═══════════════════════════════════════════════════════════════
+                        FILE STRUCTURE
+              (Actual files to be created in docs/)
+═══════════════════════════════════════════════════════════════
 
-Save to `.devdoc/code-graph.json`:
-```json
-{
-  "$schema": "https://devdoc.sh/schemas/code-graph.json",
-  "version": "1.0",
-  "generatedAt": "2026-01-24T10:00:00Z",
-  
-  "git": {
-    "commitHash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
-    "commitShort": "a1b2c3d",
-    "branch": "main",
-    "commitMessage": "feat: add user authentication",
-    "commitDate": "2026-01-24T09:30:00Z",
-    "isDirty": false
-  },
-  
-  "project": {
-    "name": "Project Name",
-    "description": "From README",
-    "language": "TypeScript",
-    "framework": "Express",
-    "rootDir": "src/"
-  },
-  
-  "structure": {
-    "sourceDir": "src/",
-    "testsDir": "tests/",
-    "examplesDir": "examples/",
-    "docsDir": "docs/"
-  },
-  
-  "modules": [
-    {
-      "name": "auth",
-      "path": "src/auth/",
-      "description": "Authentication and authorization",
-      "files": ["index.ts", "jwt.ts", "middleware.ts"],
-      "exports": [
-        {
-          "name": "login",
-          "type": "function",
-          "signature": "login(email: string, password: string): Promise<AuthToken>",
-          "description": "Authenticate user and return JWT",
-          "params": [
-            { "name": "email", "type": "string", "description": "User email" },
-            { "name": "password", "type": "string", "description": "User password" }
-          ],
-          "returns": { "type": "Promise<AuthToken>", "description": "JWT token" },
-          "async": true
-        },
-        {
-          "name": "verifyToken",
-          "type": "function",
-          "signature": "verifyToken(token: string): Promise<User>",
-          "async": true
-        }
-      ],
-      "dependencies": ["users", "config"],
-      "docPriority": "high"
-    }
-  ],
-  
-  "types": [
-    {
-      "name": "User",
-      "path": "src/types/user.ts",
-      "kind": "interface",
-      "definition": "interface User { id: string; email: string; name: string; }",
-      "properties": [
-        { "name": "id", "type": "string" },
-        { "name": "email", "type": "string" },
-        { "name": "name", "type": "string" }
-      ]
-    },
-    {
-      "name": "AuthToken",
-      "path": "src/types/auth.ts",
-      "kind": "interface",
-      "definition": "interface AuthToken { token: string; expiresAt: Date; }"
-    }
-  ],
-  
-  "api": {
-    "type": "REST",
-    "baseUrl": "/api/v1",
-    "specPath": "api-reference/openapi.json",
-    "authentication": {
-      "type": "bearer",
-      "headerName": "Authorization",
-      "description": "JWT token required"
-    },
-    "endpoints": [
-      {
-        "method": "POST",
-        "path": "/auth/login",
-        "handler": "src/routes/auth.ts:login",
-        "description": "User login",
-        "auth": "none"
-      },
-      {
-        "method": "GET",
-        "path": "/users/:id",
-        "handler": "src/routes/users.ts:getUser",
-        "auth": "required",
-        "responseType": "User"
-      }
-    ]
-  },
-  
-  "examples": [
-    {
-      "path": "examples/basic-auth.ts",
-      "description": "Basic authentication flow",
-      "tags": ["auth", "login"],
-      "runnable": true
-    }
-  ],
+docs/
+├── index.mdx                 # Introduction
+├── quickstart.mdx            # Quickstart guide
+├── authentication.mdx        # Auth setup
+├── guides/
+│   ├── overview.mdx          # Core concepts
+│   ├── resources.mdx         # Working with resources
+│   └── errors.mdx            # Error handling
+├── api-reference/
+│   ├── openapi.json          # Imported spec
+│   ├── introduction.mdx      # API overview
+│   └── errors.mdx            # Error codes reference
+└── sdks/
+    └── typescript.mdx        # TypeScript SDK
+
+═══════════════════════════════════════════════════════════════
+                       CONTENT SUMMARY
+═══════════════════════════════════════════════════════════════
+
+By Diátaxis Content Type:
+  📚 Tutorials: 1 page
+     └── quickstart.mdx
   
-  "config": {
-    "envVars": [
-      { "name": "JWT_SECRET", "description": "Secret for JWT signing", "required": true },
-      { "name": "DATABASE_URL", "description": "Database connection string", "required": true }
-    ]
-  },
+  📝 How-To Guides: 4 pages
+     ├── authentication.mdx
+     ├── guides/resources.mdx
+     └── guides/errors.mdx
   
-  "errors": [
-    { "name": "AuthenticationError", "code": "AUTH_FAILED", "message": "Invalid credentials" },
-    { "name": "NotFoundError", "code": "NOT_FOUND", "message": "Resource not found" }
-  ],
+  📖 Reference: 2 pages
+     ├── api-reference/errors.mdx
+     └── sdks/typescript.mdx
   
-  "dependencies": {
-    "express": "^4.18.0",
-    "jsonwebtoken": "^9.0.0"
-  }
-}
+  💡 Explanations: 3 pages
+     ├── index.mdx (overview)
+     ├── guides/overview.mdx
+     └── api-reference/introduction.mdx
+
+Total: 10 pages to generate
+
+═══════════════════════════════════════════════════════════════
+                         GAPS ANALYSIS
+═══════════════════════════════════════════════════════════════
+
+Potential missing documentation:
+  ⚠️  No troubleshooting guide
+  ⚠️  No changelog/release notes
+  ⚠️  No migration guide
+
+───────────────────────────────────────────────────────────────
+
+Does this architecture look complete?
+
+1. ✅ **Approve** - Generate documentation with this structure
+2. ✏️  **Modify** - I want to add/remove/change pages or navigation
+3. ➕ **Add suggested** - Add the suggested missing docs
+4. ❌ **Restart** - Let's reconsider the goals and audience
 ```
 
-### Step 5: Create Context File
+**If user chooses "Modify":**
+- Ask what they want to change:
+  - Add/remove pages?
+  - Change navigation grouping?
+  - Rename tabs or groups?
+  - Reorder pages?
+- Update the proposed structure
+- Present again for approval
+
+**If user chooses "Add suggested":**
+- Add the suggested missing documentation to the plan
+- Present updated structure for final approval
+
+**If user chooses "Restart":**
+- Go back to Step 2 (Define Documentation Goals & Audience)
+
+**If user chooses "Approve":**
+- Proceed to Step 6 (Create Context File)
+
+**What the IA approval covers:**
+
+| Aspect | What's Shown |
+|--------|--------------|
+| **Navigation** | Tabs, groups, page ordering (sidebar view) |
+| **Files** | Actual file paths and folder structure |
+| **Content Types** | Diátaxis classification per page |
+| **Gaps** | Suggested missing documentation |
+| **Scope** | Total page count and effort estimate |
+
+**Why this step matters:**
+- Clarifies exactly what will be created
+- Shows how users will navigate the docs
+- Identifies missing documentation before writing
+- Allows user to adjust navigation structure
+- Prevents wasted effort on unwanted content
+- Ensures alignment on scope and priorities
+
+### Step 6: Create Context File (After Approval)
 
 Save to `.devdoc/context.json`:
 ```json
 {
   "$schema": "https://devdoc.sh/schemas/context.json",
   "version": "1.0",
-  "lastUpdated": "2026-01-24T10:00:00Z",
-  "git": {
-    "commitHash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
-    "commitShort": "a1b2c3d",
-    "branch": "main"
+  "lastUpdated": "2026-01-25T10:00:00Z",
+  
+  "strategy": {
+    "goal": "Support API consumers",
+    "audience": {
+      "primary": "External Developer",
+      "needs": ["Quick start", "Authentication", "Code examples", "Reference"]
+    }
   },
+  
   "preferences": {
     "docType": "api",
     "apiType": "openapi",
-    "audience": "Backend developers",
     "codeLanguage": "TypeScript"
   },
+  
   "product": {
     "name": "Product Name",
     "description": "From README",
     "type": "api"
   },
+  
   "api": {
     "style": "REST",
     "specPath": "api-reference/openapi.json",
     "baseUrl": "https://api.example.com"
   },
+  
   "documentation": {
     "voice": "professional",
     "codeExamples": {
       "primaryLanguage": "TypeScript"
     }
+  },
+  
+  "contentPlan": {
+    "approved": true,
+    "approvedAt": "2026-01-25T10:00:00Z",
+    "pages": [
+      { "path": "index.mdx", "type": "explanation", "priority": "high", "status": "planned" },
+      { "path": "quickstart.mdx", "type": "tutorial", "priority": "high", "status": "planned" },
+      { "path": "authentication.mdx", "type": "how-to", "priority": "high", "status": "planned" },
+      { "path": "guides/overview.mdx", "type": "explanation", "priority": "medium", "status": "planned" },
+      { "path": "api-reference/errors.mdx", "type": "reference", "priority": "medium", "status": "planned" }
+    ]
   }
 }
 ```
 
-**Tell user:**
-```
-✅ Context saved!
+### Step 7: Generate Documentation
 
-- Doc Type: API Documentation
-- API: REST (45 endpoints)
-- Audience: Backend developers
-- Code examples: TypeScript
+**Only proceed after user has approved the IA structure in Step 5.**
 
-Memory map created with 12 modules scanned.
-Ready to generate documentation.
-```
+**Use project overview and Diátaxis principles:**
 
-### Step 6: Plan Documentation Structure
+#### Writing Guidelines (Expert Standards)
 
-Based on user preferences, plan the structure:
+1. **Use Second Person** - "You can configure..." not "Users can configure..."
+2. **Active Voice** - "Run the command" not "The command should be run"
+3. **Task-Oriented Headings** - "How to add a custom domain" not "Custom domains"
+4. **Include Examples** - Every concept needs a code example
+5. **Progressive Disclosure** - Basic → Advanced ordering
 
-#### For API Docs:
-```
-docs/
-├── index.mdx              # Overview, value prop
-├── quickstart.mdx         # 5-min getting started
-├── authentication.mdx     # Auth setup
-├── guides/
-│   ├── overview.mdx       # Core concepts
-│   └── {use-cases}.mdx    # Common use cases
-├── api-reference/
-│   ├── openapi.json       # Imported spec
-│   ├── introduction.mdx
-│   └── errors.mdx
-└── sdks/                  # If SDKs exist
-```
+#### Page Structure by Content Type
 
-#### For Product Docs:
-```
-docs/
-├── index.mdx
-├── getting-started/
-│   ├── quickstart.mdx
-│   └── key-concepts.mdx
-├── features/
-│   └── {feature}.mdx
-├── tutorials/
-└── troubleshooting/
-```
+**Tutorial Template:**
+```mdx
+---
+title: Build [Something] with [Technology]
+description: A complete tutorial to [achieve outcome] from scratch
+contentType: tutorial
+---
 
-#### For Internal Docs:
-```
-docs/
-├── index.mdx
-├── getting-started/
-│   ├── setup.mdx
-│   └── prerequisites.mdx
-├── architecture/
-├── development/
-└── contributing.mdx
-```
+## What You'll Build
 
-### Step 7: Generate Documentation
+[End result description + estimated time]
+
+## Prerequisites
+
+<Note>Before you begin, ensure you have: [requirements]</Note>
 
-**Use the code graph to write accurate docs:**
+## Steps
 
-1. **Read `.devdoc/code-graph.json`** before writing each page
-2. **Reference exact function signatures** from the graph
-3. **Extract real code examples** from the examples array
-4. **Use correct types** from the types array
-5. **Match voice to audience** (technical for API, friendly for product)
+<Steps>
+  <Step title="Step 1">Content</Step>
+  <Step title="Step 2">Content</Step>
+</Steps>
 
-**For each page:**
+## Next Steps
+
+[Links to related content]
 ```
-1. Read code-graph.json to find relevant modules
-2. Use exact signatures from exports array
-3. Reference types from types array
-4. Extract examples from examples array or source
-5. Document errors from errors array
-6. Add TODO markers for sections needing review
+
+**How-To Guide Template:**
+```mdx
+---
+title: How to [Achieve Specific Goal]
+description: Learn how to [specific outcome]
+contentType: how-to
+---
+
+## Overview
+
+[2-3 sentences: What, Who, Why]
+
+## Prerequisites (if applicable)
+
+## Steps
+
+<Steps>
+  <Step title="[Action verb] [object]">Content</Step>
+</Steps>
+
+## Example
+
+[Complete working example]
+
+## Next Steps
 ```
 
-**Example - Writing auth docs:**
+**Reference Template:**
+```mdx
+---
+title: [Component/API/Config] Reference
+description: Complete reference for [topic]
+contentType: reference
+---
+
+## Overview
+
+[Brief description]
+
+## Properties/Parameters
+
+| Property | Type | Description | Default |
+|----------|------|-------------|---------|
+| ... | ... | ... | ... |
+
+## Examples
+
+## Related
+
+[Links to related references]
 ```
-1. Find "auth" module in code-graph.json
-2. Get login() signature: "login(email: string, password: string): Promise<AuthToken>"
-3. Get AuthToken type definition
-4. Find auth example in examples array
-5. Write docs with EXACT signatures and types
+
+**Explanation Template:**
+```mdx
+---
+title: Understanding [Concept]
+description: Deep dive into [topic] and how it works
+contentType: explanation
+---
+
+## Overview
+
+[Why this matters]
+
+## How It Works
+
+[Conceptual explanation with diagrams]
+
+## Key Concepts
+
+## When to Use
+
+## Related
+
+[Links to tutorials and how-tos that apply this concept]
 ```
 
 ### Step 8: Update docs.json
@@ -431,7 +569,18 @@ Configure navigation based on doc type:
     "tabs": [
       {
         "tab": "Guides",
-        "groups": [...]
+        "groups": [
+          {
+            "group": "Getting Started",
+            "icon": "rocket-launch",
+            "pages": ["index", "quickstart", "authentication"]
+          },
+          {
+            "group": "Guides",
+            "icon": "book-open",
+            "pages": ["guides/overview"]
+          }
+        ]
       },
       {
         "tab": "API Reference",
@@ -443,39 +592,26 @@ Configure navigation based on doc type:
 }
 ```
 
-**API Docs with GraphQL:**
-```json
-{
-  "navigation": {
-    "tabs": [
-      { "tab": "Guides", "groups": [...] },
-      {
-        "tab": "GraphQL API",
-        "type": "graphql",
-        "schema": "api-reference/schema.graphql",
-        "endpoint": "https://api.example.com/graphql"
-      }
-    ]
-  }
-}
-```
-
 ### Step 9: Summary
 
 ```
 ✅ Documentation Generated!
 
-Files created:
-  - docs.json (navigation configured)
-  - index.mdx
-  - quickstart.mdx
-  - authentication.mdx
-  - guides/overview.mdx
-  - api-reference/openapi.json (imported)
+Strategy:
+  - Goal: [selected goal]
+  - Audience: [primary audience]
+  - Domain: [api/product/internal]
 
-Code graph files:
-  - .devdoc/context.json (user preferences)
-  - .devdoc/code-graph.json (complete code analysis)
+Content Plan (Diátaxis):
+  - Tutorials: X pages
+  - How-To Guides: X pages
+  - Reference: X pages
+  - Explanations: X pages
+
+Files created:
+  - docs.json (navigation)
+  - .devdoc/context.json (strategy & preferences)
+  - [list of mdx files with content types]
 
 Next steps:
   1. Run `devdoc dev` to preview
@@ -489,17 +625,22 @@ Next steps:
 
 | Principle | Description |
 |-----------|-------------|
-| Ask first | Get user preferences before scanning |
-| Build code graph | Scan entire codebase, extract all signatures |
-| Store the graph | Save to code-graph.json for updates |
-| Use real code | Reference exact signatures, never fabricate |
-| Mark unknowns | Add TODO for sections needing review |
-
-## Code Graph Usage
-
-The code-graph.json enables:
-- **Accurate docs** - Use exact function signatures
-- **Complete coverage** - Know all exports to document
-- **Easy updates** - Re-scan to refresh the graph
-- **No hallucination** - Only document what exists
-- **Type accuracy** - Reference real type definitions
+| **Project overview first** | Quick scan using git to understand structure |
+| **Strategy first** | Define goals and audience before structure |
+| **Audience-driven** | Match content to user needs |
+| **Diátaxis types** | Classify every page by content type |
+| **IA approval required** | Always get user approval before generating content |
+| **Expert writing** | Second person, active voice, task-oriented |
+| **Mark unknowns** | Add TODO for sections needing review |
+
+## Quality Checklist
+
+Before completing, verify:
+
+- [ ] Title is clear and specific
+- [ ] Introduction explains the "why"
+- [ ] Content type matches page purpose
+- [ ] Code examples are complete and tested
+- [ ] Links to related docs included
+- [ ] Follows writing guidelines (2nd person, active voice)
+- [ ] Progressive disclosure (basic → advanced)