@brainfish-ai/devdoc 0.1.40 → 0.1.42

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

@@ -100,10 +100,25 @@ What is the primary goal of this documentation?
 5. **Inform stakeholders** - Communicate architecture and decisions
 ```
 
-#### Question 2: Primary Audience (WHO)
+#### Question 2: Audiences & Roles (WHO)
 ```
-Who is your PRIMARY audience? (Choose one)
+Who are your documentation audiences?
 
+═══════════════════════════════════════════════════════════
+           SINGLE vs MULTI-ROLE PRODUCTS
+═══════════════════════════════════════════════════════════
+
+Does your product have multiple user roles with different permissions?
+
+A) **Single audience** - All users have same access
+   → Example: Open-source library, public API
+
+B) **Multiple roles** - Different users see different features
+   → Example: SaaS with Admin/User roles, Enterprise with permissions
+```
+
+**If Single Audience (A), choose one:**
+```
 1. **Internal Developer** - Engineers on your team
    → Needs: Code flow, architecture, debugging, contribution guides
    
@@ -120,6 +135,57 @@ Who is your PRIMARY audience? (Choose one)
    → Needs: Feature overview, roadmap, IA map
 ```
 
+**If Multiple Roles (B), define your role matrix:**
+```
+═══════════════════════════════════════════════════════════
+                 ROLE MATRIX DEFINITION
+═══════════════════════════════════════════════════════════
+
+List your user roles and their permissions:
+
+Example for a SaaS product:
+┌─────────────────┬────────────────────────────────────────┐
+│ Role            │ Permissions / Features                 │
+├─────────────────┼────────────────────────────────────────┤
+│ Admin           │ All features, user management, billing │
+│ Editor          │ Create/edit content, limited settings  │
+│ Viewer          │ Read-only access                       │
+│ API Developer   │ API access, webhooks, integrations     │
+└─────────────────┴────────────────────────────────────────┘
+
+Your roles:
+1. Role name: _______ 
+   - Permissions: _______
+   - Key features: _______
+
+2. Role name: _______
+   - Permissions: _______
+   - Key features: _______
+
+(Add more as needed)
+```
+
+**For Multi-Role Products, also ask:**
+```
+How should role-specific content be organized?
+
+1. **Separate sections** - Each role gets its own section/tab
+   docs/
+   ├── admin/           # Admin-only guides
+   ├── users/           # Regular user guides
+   └── developers/      # API/developer guides
+
+2. **Inline badges** - Mixed content with role indicators
+   <RoleBadge roles={["admin", "editor"]}>
+   This feature is only available to Admins and Editors.
+   </RoleBadge>
+
+3. **Permission gates** - Content varies by logged-in user
+   (Requires auth integration)
+
+4. **Hybrid** - Combination of above
+```
+
 #### Question 3: Documentation Domain
 ```
 What type of documentation are you creating?
@@ -219,6 +285,96 @@ docs/
 └── troubleshooting/       # [How-To] Problem solving
 ```
 
+#### For Multi-Role Products (with separate sections):
+```
+docs/
+├── index.mdx              # [Explanation] Product overview (all roles)
+├── getting-started/
+│   ├── quickstart.mdx     # [Tutorial] First experience (all roles)
+│   └── key-concepts.mdx   # [Explanation] Core concepts (all roles)
+│
+├── admin/                 # 🔒 ADMIN-ONLY SECTION
+│   ├── overview.mdx       # [Explanation] Admin dashboard overview
+│   ├── user-management.mdx # [How-To] Manage users & permissions
+│   ├── billing.mdx        # [How-To] Billing & subscriptions
+│   ├── settings.mdx       # [Reference] Admin settings
+│   └── audit-logs.mdx     # [Reference] Audit & compliance
+│
+├── users/                 # 👤 REGULAR USER SECTION
+│   ├── overview.mdx       # [Explanation] User dashboard
+│   ├── features/          # [How-To] Feature guides
+│   └── account.mdx        # [How-To] Account settings
+│
+├── developers/            # 💻 DEVELOPER SECTION
+│   ├── overview.mdx       # [Explanation] API overview
+│   ├── authentication.mdx # [How-To] API auth
+│   ├── webhooks.mdx       # [How-To] Webhook setup
+│   └── api-reference/     # [Reference] API docs
+│
+└── troubleshooting/       # [How-To] Problem solving (all roles)
+```
+
+#### For Multi-Role Products (with inline badges):
+```
+When using inline role badges, add to each page's frontmatter:
+
+---
+title: User Management
+description: Add and manage users in your organization
+roles: ["admin", "owner"]  # Roles that can access this feature
+---
+
+<RoleBadge roles={["admin", "owner"]}>
+  This feature requires Admin or Owner permissions.
+</RoleBadge>
+
+## Overview
+
+User management allows you to...
+```
+
+#### Role-Specific Content Patterns:
+
+**Pattern 1: Conditional sections within a page**
+```mdx
+## Basic Settings
+
+All users can configure these settings...
+
+<RoleSection roles={["admin"]}>
+## Advanced Settings (Admin Only)
+
+Administrators can additionally configure...
+</RoleSection>
+```
+
+**Pattern 2: Feature availability matrix**
+```mdx
+## Feature Availability
+
+| Feature | Viewer | Editor | Admin |
+|---------|--------|--------|-------|
+| View dashboards | ✅ | ✅ | ✅ |
+| Edit content | ❌ | ✅ | ✅ |
+| Manage users | ❌ | ❌ | ✅ |
+| Billing access | ❌ | ❌ | ✅ |
+```
+
+**Pattern 3: Navigation tabs by role**
+```json
+// docs.json with role-based tabs
+{
+  "navigation": {
+    "tabs": [
+      { "tab": "Getting Started", "groups": [...] },
+      { "tab": "Admin Guide", "icon": "shield", "groups": [...] },
+      { "tab": "User Guide", "icon": "user", "groups": [...] },
+      { "tab": "Developer", "icon": "code", "groups": [...] }
+    ]
+  }
+}
+```
+
 #### For Internal Docs:
 ```
 docs/
@@ -250,8 +406,24 @@ Present the **complete Information Architecture** to the user, covering:
 
 Based on your preferences:
   - Goal: [selected goal]
-  - Audience: [primary audience]  
+  - Audience: [primary audience OR "Multi-role"]  
   - Domain: [api/product/internal]
+  
+[If multi-role, show role matrix:]
+═══════════════════════════════════════════════════════════════
+                         USER ROLES
+═══════════════════════════════════════════════════════════════
+
+┌─────────────────┬────────────────────────────────────────┐
+│ Role            │ Documentation Sections                 │
+├─────────────────┼────────────────────────────────────────┤
+│ Admin           │ admin/, shared sections                │
+│ Editor          │ users/, shared sections                │
+│ Viewer          │ users/ (read-only features)            │
+│ Developer       │ developers/, api-reference/            │
+└─────────────────┴────────────────────────────────────────┘
+
+Role organization: [Separate sections | Inline badges | Hybrid]
 
 ═══════════════════════════════════════════════════════════════
                       NAVIGATION STRUCTURE
@@ -382,6 +554,8 @@ Does this architecture look complete?
 ### Step 6: Create Context File (After Approval)
 
 Save to `.devdoc/context.json`:
+
+**For Single Audience:**
 ```json
 {
   "$schema": "https://devdoc.sh/schemas/context.json",
@@ -391,6 +565,7 @@ Save to `.devdoc/context.json`:
   "strategy": {
     "goal": "Support API consumers",
     "audience": {
+      "type": "single",
       "primary": "External Developer",
       "needs": ["Quick start", "Authentication", "Code examples", "Reference"]
     }
@@ -402,54 +577,436 @@ Save to `.devdoc/context.json`:
     "codeLanguage": "TypeScript"
   },
   
-  "product": {
-    "name": "Product Name",
-    "description": "From README",
-    "type": "api"
-  },
+  "contentPlan": {
+    "approved": true,
+    "pages": [
+      { "path": "index.mdx", "type": "explanation", "priority": "high" },
+      { "path": "quickstart.mdx", "type": "tutorial", "priority": "high" }
+    ]
+  }
+}
+```
+
+**For Multi-Role Products:**
+```json
+{
+  "$schema": "https://devdoc.sh/schemas/context.json",
+  "version": "1.0",
+  "lastUpdated": "2026-01-25T10:00:00Z",
   
-  "api": {
-    "style": "REST",
-    "specPath": "api-reference/openapi.json",
-    "baseUrl": "https://api.example.com"
+  "strategy": {
+    "goal": "Support all user types",
+    "audience": {
+      "type": "multi-role",
+      "organization": "separate-sections",  // or "inline-badges" or "hybrid"
+      "roles": [
+        {
+          "name": "Admin",
+          "slug": "admin",
+          "permissions": ["all"],
+          "features": ["user-management", "billing", "settings", "audit-logs"],
+          "docSection": "admin/"
+        },
+        {
+          "name": "Editor",
+          "slug": "editor", 
+          "permissions": ["create", "edit", "delete"],
+          "features": ["content-management", "workflows"],
+          "docSection": "users/"
+        },
+        {
+          "name": "Viewer",
+          "slug": "viewer",
+          "permissions": ["read"],
+          "features": ["view-content", "search"],
+          "docSection": "users/"
+        },
+        {
+          "name": "Developer",
+          "slug": "developer",
+          "permissions": ["api-access", "webhooks"],
+          "features": ["api", "integrations", "webhooks"],
+          "docSection": "developers/"
+        }
+      ]
+    }
   },
   
-  "documentation": {
-    "voice": "professional",
-    "codeExamples": {
-      "primaryLanguage": "TypeScript"
-    }
+  "preferences": {
+    "docType": "product",
+    "codeLanguage": "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" }
+      // Shared pages (all roles)
+      { "path": "index.mdx", "type": "explanation", "roles": ["all"] },
+      { "path": "quickstart.mdx", "type": "tutorial", "roles": ["all"] },
+      
+      // Admin-only pages
+      { "path": "admin/overview.mdx", "type": "explanation", "roles": ["admin"] },
+      { "path": "admin/user-management.mdx", "type": "how-to", "roles": ["admin"] },
+      { "path": "admin/billing.mdx", "type": "how-to", "roles": ["admin"] },
+      
+      // User pages (editor, viewer)
+      { "path": "users/overview.mdx", "type": "explanation", "roles": ["editor", "viewer"] },
+      { "path": "users/content.mdx", "type": "how-to", "roles": ["editor"] },
+      
+      // Developer pages
+      { "path": "developers/overview.mdx", "type": "explanation", "roles": ["developer"] },
+      { "path": "developers/api-reference/", "type": "reference", "roles": ["developer"] }
     ]
   }
 }
 ```
 
-### Step 7: Generate Documentation
+### Step 7: Generate Documentation (WITH FILE SEARCH)
 
 **Only proceed after user has approved the IA structure in Step 5.**
 
-**Use project overview and Diátaxis principles:**
+**CRITICAL: Search and read relevant files BEFORE generating each page.**
+
+#### 7a. For EACH Page in the Content Plan:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    PAGE GENERATION FLOW                          │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  1. SEARCH for relevant files                                    │
+│     ↓                                                           │
+│  2. READ the files found                                        │
+│     ↓                                                           │
+│  3. ASSESS if enough information exists                         │
+│     ↓                                                           │
+│  ┌─────────────┐     ┌─────────────────────────────────┐        │
+│  │ Sufficient? │─YES─│ GENERATE content from real data │        │
+│  └──────┬──────┘     └─────────────────────────────────┘        │
+│         │NO                                                      │
+│         ↓                                                       │
+│  ┌─────────────────────────────────────────────────────┐        │
+│  │ FLAG and offer options:                              │        │
+│  │   1. Auto-correct IA (remove/modify page)           │        │
+│  │   2. Rename page to match what exists               │        │
+│  │   3. Mark as TODO and continue                      │        │
+│  │   4. Ask user for clarification                     │        │
+│  └─────────────────────────────────────────────────────┘        │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+#### 7b. File Search Strategy (Per Page)
+
+**Before generating each page, search for relevant source files:**
+
+```bash
+# For authentication.mdx - search auth-related files
+git ls-files | grep -iE "(auth|login|session|jwt|token|credential)"
+
+# For quickstart.mdx - search for README, examples, getting started
+git ls-files | grep -iE "(readme|example|getting.?started|quickstart)"
+
+# For errors.mdx - search for error handling
+git ls-files | grep -iE "(error|exception|fault|handler)"
+
+# For API reference - search for route handlers, controllers
+git ls-files | grep -iE "(route|controller|handler|endpoint|api)"
+```
+
+**Also search file contents:**
+```bash
+# Search for specific terms in code
+rg -l "authentication" --type ts
+rg -l "class.*Error" --type ts
+rg -l "export.*function" src/
+```
+
+#### 7c. Read and Extract Information
+
+**For each relevant file found:**
+
+1. **Read the file** - Get actual implementation details
+2. **Extract key information:**
+   - Function signatures and parameters
+   - Configuration options
+   - Error codes and messages
+   - Code examples from tests/examples folders
+3. **Note the source** - Reference where info came from
+
+#### 7d. Detect Feature Flags & Duplicates
+
+**Search for feature flags:**
+```bash
+rg -l "featureFlag|feature_flag|isEnabled|FF_" --type ts
+rg "if.*\(.*feature|process\.env\.FEATURE" --type ts
+```
+
+**Search for duplicate features:**
+```bash
+rg "export.*(login|authenticate|signIn)" --type ts -l
+```
+
+**Flag for user guidance:**
+```
+⚠️ FEATURE FLAGS DETECTED for [page]:
+
+📍 src/lib/auth/index.ts:45
+   Feature: newAuthFlow
+   - OLD implementation: lines 50-80 (current)
+   - NEW implementation: lines 82-120 (behind flag)
+   
+   Question: Which version to document?
+   1. Current (old) - stable
+   2. New (flagged) - upcoming
+   3. Both with notice
+
+🔄 DUPLICATE FEATURES DETECTED:
+
+Similar to [page]:
+- src/lib/auth/v2/authenticate.ts → authenticate()
+- src/lib/legacy/signIn.ts → signIn()
+
+Question: How to handle?
+1. Document primary only
+2. Document all with links
+3. Mark legacy as deprecated
+```
+
+#### 7e. Assess Information Sufficiency
+
+**Before writing, evaluate:**
+
+| Assessment | Criteria | Action |
+|------------|----------|--------|
+| ✅ **Sufficient** | Found source files, clear implementation | Generate with real data |
+| ⚠️ **Partial** | Some files found, gaps exist | Generate with TODOs for gaps |
+| ❌ **Insufficient** | No relevant files, unclear | Flag and offer options |
+
+#### 7e. Handle Unclear Sections
+
+**If information is insufficient, present options:**
+
+```
+⚠️ UNCLEAR SECTION DETECTED
+
+Page: authentication.mdx
+Issue: Could not find authentication implementation files.
+
+Searched for:
+  - **/auth/** → Not found
+  - **/*auth*.ts → Not found
+  - src/middleware/auth* → Not found
+
+Options:
+  1. 🔄 **Auto-correct IA** - Remove this page from the plan
+  2. ✏️  **Rename page** - Change to match what exists (e.g., "api-keys.mdx")
+  3. 📝 **Mark as TODO** - Create placeholder, document later
+  4. ❓ **Ask for path** - "Where is authentication implemented?"
+
+Choose an option (1-4):
+```
+
+#### 7g. Review Content with User (MANDATORY)
+
+**For EACH page, show draft content for approval before writing:**
+
+```
+═══════════════════════════════════════════════════════════
+              CONTENT REVIEW: authentication.mdx
+═══════════════════════════════════════════════════════════
+
+📂 SOURCES USED:
+  ✓ src/lib/auth/index.ts (main auth module)
+  ✓ src/lib/auth/jwt.ts (JWT handling)
+  ✓ examples/auth-example.ts (code example)
+
+───────────────────────────────────────────────────────────
+                    DRAFT CONTENT
+───────────────────────────────────────────────────────────
+
+---
+title: Authentication
+description: Secure your application with JWT authentication
+sources: ["src/lib/auth/index.ts", "src/lib/auth/jwt.ts"]
+---
+
+## Overview
+
+Authentication in this project uses JWT tokens...
+
+## login(email, password)
+
+Authenticate user and receive a JWT token.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| email | string | User email |
+| password | string | User password |
+
+**Returns:** `Promise<AuthToken>`
+
+### Example
+
+```typescript
+import { login } from '@package/auth';
+const token = await login('user@example.com', 'password');
+```
+
+───────────────────────────────────────────────────────────
+                    NOTICES
+───────────────────────────────────────────────────────────
+
+⚠️ FEATURE FLAG: newAuthFlow
+   Documenting: OLD implementation (current default)
+   Alternative: New OAuth flow behind flag
+   
+🔄 DUPLICATE: authenticate() exists in v2/
+   This doc covers: login() (primary)
+
+───────────────────────────────────────────────────────────
+                    OPTIONS
+───────────────────────────────────────────────────────────
+
+1. ✅ **Approve** - Create this file
+2. ✏️  **Edit** - Tell me what to change
+3. 🔄 **Switch version** - Document flagged version
+4. ➕ **Add duplicate** - Include related feature
+5. ⏭️  **Skip** - Don't create this page
+6. ❌ **Cancel** - Stop all generation
+
+Choose an option:
+```
+
+**Only proceed to write after user approves.**
+
+#### 7h. Generate With Real Data (After Approval)
+
+**Only generate content from actual source files:**
+
+```
+📄 CREATING: authentication.mdx (APPROVED)
+
+Writing file with:
+  - Auth methods: login(), logout(), verifyToken()
+  - Config options: JWT_SECRET, TOKEN_EXPIRY
+  - Example code from examples/auth-example.ts
+
+✓ File created successfully
+```
 
 #### Writing Guidelines (Expert Standards)
 
 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
+4. **Include Examples** - Use REAL examples from codebase, not fabricated
 5. **Progressive Disclosure** - Basic → Advanced ordering
+6. **Cite Sources** - Note which files information came from
+7. **Use Mermaid Diagrams** - For architecture, flows, sequences, and relationships
+
+#### Mermaid Diagram Guidelines (REQUIRED for visual content)
 
-#### Page Structure by Content Type
+**ALWAYS use mermaid diagrams for:**
+
+| Content Type | Diagram Type | When to Use |
+|--------------|--------------|-------------|
+| Architecture | `flowchart` | System components, module relationships |
+| Data Flow | `flowchart LR` | How data moves through the system |
+| Sequence | `sequenceDiagram` | API calls, request/response flows |
+| State | `stateDiagram-v2` | State machines, lifecycle |
+| Entity Relationships | `erDiagram` | Database schemas, data models |
+| Class Structure | `classDiagram` | OOP relationships, interfaces |
+| User Journey | `journey` | User flows, onboarding steps |
+
+**Mermaid Examples:**
+
+```mdx
+## Architecture Overview
+
+```mermaid
+flowchart TB
+    subgraph Client
+        UI[Web App]
+        SDK[SDK]
+    end
+    
+    subgraph API
+        Gateway[API Gateway]
+        Auth[Auth Service]
+        Core[Core Service]
+    end
+    
+    subgraph Data
+        DB[(Database)]
+        Cache[(Redis)]
+    end
+    
+    UI --> Gateway
+    SDK --> Gateway
+    Gateway --> Auth
+    Gateway --> Core
+    Core --> DB
+    Core --> Cache
+```
+
+## Authentication Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant App
+    participant API
+    participant Auth
+    
+    User->>App: Login request
+    App->>API: POST /auth/login
+    API->>Auth: Validate credentials
+    Auth-->>API: JWT token
+    API-->>App: Token response
+    App-->>User: Logged in
+```
+
+## Request Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> Pending
+    Pending --> Processing: Start
+    Processing --> Completed: Success
+    Processing --> Failed: Error
+    Failed --> Pending: Retry
+    Completed --> [*]
+```
+
+## Data Model
+
+```mermaid
+erDiagram
+    User ||--o{ Document : creates
+    User {
+        string id PK
+        string email
+        string name
+    }
+    Document {
+        string id PK
+        string title
+        string content
+        string userId FK
+    }
+```
+```
+
+**When to include diagrams:**
+- Architecture overview pages → flowchart
+- API documentation → sequenceDiagram
+- Feature explanations → flowchart or stateDiagram
+- Database/data model docs → erDiagram
+- Integration guides → sequenceDiagram
+- Onboarding flows → journey
+
+#### Page Templates (Use After File Search)
 
 **Tutorial Template:**
 ```mdx
@@ -457,26 +1014,21 @@ Save to `.devdoc/context.json`:
 title: Build [Something] with [Technology]
 description: A complete tutorial to [achieve outcome] from scratch
 contentType: tutorial
+sources: ["README.md", "examples/basic.ts"]  # Files used as reference
 ---
 
 ## What You'll Build
-
-[End result description + estimated time]
+[Based on actual example from examples/ folder]
 
 ## Prerequisites
-
-<Note>Before you begin, ensure you have: [requirements]</Note>
+[From package.json dependencies and README]
 
 ## Steps
-
 <Steps>
-  <Step title="Step 1">Content</Step>
-  <Step title="Step 2">Content</Step>
+  <Step title="Step 1">[Real code from source files]</Step>
 </Steps>
 
 ## Next Steps
-
-[Links to related content]
 ```
 
 **How-To Guide Template:**
@@ -485,25 +1037,19 @@ contentType: tutorial
 title: How to [Achieve Specific Goal]
 description: Learn how to [specific outcome]
 contentType: how-to
+sources: ["src/lib/feature.ts"]
 ---
 
 ## Overview
-
-[2-3 sentences: What, Who, Why]
-
-## Prerequisites (if applicable)
+[From source file docstrings/comments]
 
 ## Steps
-
 <Steps>
-  <Step title="[Action verb] [object]">Content</Step>
+  <Step title="[Action]">[Actual implementation steps]</Step>
 </Steps>
 
 ## Example
-
-[Complete working example]
-
-## Next Steps
+[Real code from tests or examples]
 ```
 
 **Reference Template:**
@@ -512,23 +1058,18 @@ contentType: how-to
 title: [Component/API/Config] Reference
 description: Complete reference for [topic]
 contentType: reference
+sources: ["src/types/config.ts", "src/lib/api.ts"]
 ---
 
-## Overview
-
-[Brief description]
-
 ## Properties/Parameters
+[Extracted from actual TypeScript interfaces/types]
 
 | Property | Type | Description | Default |
 |----------|------|-------------|---------|
-| ... | ... | ... | ... |
+[From real type definitions]
 
 ## Examples
-
-## Related
-
-[Links to related references]
+[From tests or examples folder]
 ```
 
 **Explanation Template:**
@@ -537,60 +1078,144 @@ contentType: reference
 title: Understanding [Concept]
 description: Deep dive into [topic] and how it works
 contentType: explanation
+sources: ["docs/architecture.md", "src/lib/core/"]
 ---
 
-## Overview
+## How It Works
+[From actual implementation, not made up]
 
-[Why this matters]
+## Key Concepts
+[Based on real code patterns found]
+```
 
-## How It Works
+### Step 8: Create/Update docs.json and theme.json
 
-[Conceptual explanation with diagrams]
+**CRITICAL: Read schema files before creating configuration files.**
 
-## Key Concepts
+#### 8a. Read Schema References (MANDATORY)
+
+Before creating or updating `docs.json` or `theme.json`, ALWAYS read the schema files:
+
+```
+📋 SCHEMA REFERENCES
 
-## When to Use
+Read these files before writing configuration:
 
-## Related
+1. .claude/skills/bootstrap-docs/../../schemas/docs.schema.json
+   → Full schema for docs.json with all valid properties
+   → Tab types: docs, openapi, graphql, changelog
+   → Group structure and icon options
+   → API and SEO configuration
 
-[Links to tutorials and how-tos that apply this concept]
+2. .claude/skills/bootstrap-docs/../../schemas/theme.schema.json
+   → Full schema for theme.json with all valid properties
+   → Logo configuration options
+   → Color presets (indigo, blue, green, amber, etc.)
+   → Header and navbar options
 ```
 
-### Step 8: Update docs.json
+**Schema file locations:**
+- `packages/devdoc/ai-agents/schemas/docs.schema.json`
+- `packages/devdoc/ai-agents/schemas/theme.schema.json`
 
-Configure navigation based on doc type:
+#### 8b. Review Configuration Before Writing (MANDATORY)
+
+**Show proposed configuration for user approval:**
+
+```
+═══════════════════════════════════════════════════════════
+              CONFIG REVIEW: docs.json
+═══════════════════════════════════════════════════════════
 
-**API Docs with OpenAPI:**
-```json
 {
-  "name": "Product Name",
-  "docType": "api",
+  "$schema": "https://devdoc.sh/docs.json",
+  "name": "[Product Name]",
+  "docType": "[api|product|internal]",
+  "favicon": "/favicon.svg",
   "navigation": {
     "tabs": [
       {
         "tab": "Guides",
+        "type": "docs",
         "groups": [
           {
             "group": "Getting Started",
             "icon": "rocket-launch",
             "pages": ["index", "quickstart", "authentication"]
-          },
-          {
-            "group": "Guides",
-            "icon": "book-open",
-            "pages": ["guides/overview"]
           }
         ]
-      },
-      {
-        "tab": "API Reference",
-        "type": "openapi",
-        "spec": "api-reference/openapi.json"
       }
     ]
   }
 }
+
+───────────────────────────────────────────────────────────
+Validated against: schemas/docs.schema.json ✓
+
+OPTIONS:
+1. ✅ Approve - Create this file
+2. ✏️  Edit - Make changes
+3. ❌ Cancel
+```
+
 ```
+═══════════════════════════════════════════════════════════
+              CONFIG REVIEW: theme.json
+═══════════════════════════════════════════════════════════
+
+{
+  "$schema": "https://devdoc.sh/theme.json",
+  "logo": {
+    "light": "/assets/logo/light.svg",
+    "dark": "/assets/logo/dark.svg",
+    "alt": "[Product Name]",
+    "width": 120
+  },
+  "colors": {
+    "primary": "#6366f1",
+    "primaryLight": "#818cf8",
+    "primaryDark": "#4f46e5"
+  },
+  "header": {
+    "showAskAI": true,
+    "showSearch": true,
+    "showThemeToggle": true
+  }
+}
+
+───────────────────────────────────────────────────────────
+Validated against: schemas/theme.schema.json ✓
+Color preset used: indigo
+
+OPTIONS:
+1. ✅ Approve - Create this file
+2. ✏️  Edit - Make changes
+3. 🎨 Change colors - Pick different preset
+4. ❌ Cancel
+```
+
+#### 8c. Quick Reference (from schemas)
+
+**docs.json Tab Types:**
+| Type | Description |
+|------|-------------|
+| `docs` | MDX documentation pages |
+| `openapi` | Auto-generated API reference |
+| `graphql` | GraphQL schema documentation |
+| `changelog` | Changelog entries |
+
+**Common Phosphor Icons:**
+`rocket-launch`, `book-open`, `code`, `gear`, `terminal`, `puzzle-piece`, `star`, `shield`, `user`, `robot`, `github-logo`, `discord-logo`
+
+**theme.json Color Presets:**
+| Preset | Primary |
+|--------|---------|
+| indigo | #6366f1 |
+| blue | #3b82f6 |
+| green | #10b981 |
+| amber | #f59e0b |
+| purple | #8b5cf6 |
+| pink | #ec4899 |
 
 ### Step 9: Summary
 
@@ -630,6 +1255,12 @@ Next steps:
 | **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 |
+| **Search before generate** | ALWAYS search/read relevant files before writing each page |
+| **No hallucination** | Only use real data from source files, never fabricate |
+| **Review before write** | ALWAYS show draft content for user approval |
+| **Flag feature flags** | Detect conditional features, ask which version to document |
+| **Flag duplicates** | Identify similar features, let user choose |
+| **Flag unclear sections** | If info not found, offer auto-correct IA options |
 | **Expert writing** | Second person, active voice, task-oriented |
 | **Mark unknowns** | Add TODO for sections needing review |