@brainfish-ai/devdoc 0.1.37 → 0.1.38

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

@@ -1,492 +1,437 @@
 ---
 name: bootstrap-docs
-description: Analyze repository and generate documentation. Creates context memory for consistent AI assistance.
+description: Analyze repository and generate documentation with user-driven preferences and comprehensive code memory.
 ---
 
 ## Instructions
 
 When bootstrapping documentation from a repository:
 
-### Step 1: Check Context Memory
+### Step 1: Check Existing Context & Codebase
 
-**First, check if `.devdoc/context.json` exists:**
-
-**If context.json exists and is populated:**
-- Read the context file
-- Tell user: "Found existing product context. Using saved configuration."
-- Skip to Step 5 (Generate Documentation)
-
-**If context.json is empty or doesn't exist:**
-- Proceed to Step 2 (Discovery Flow)
+**First, detect if there's a codebase to scan:**
+```
+Look for:
+- package.json, pyproject.toml, Cargo.toml, go.mod
+- src/, lib/, app/ directories
+- Any source code files
+```
 
-### Step 2: Discovery Flow (Context Creation)
+**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
 
-#### 2a. Detect Project Structure
+**If codebase exists, check git state:**
+```bash
+git rev-parse HEAD                    # Current commit hash
+git rev-parse --abbrev-ref HEAD       # Current branch
+```
 
-**If `docs.json` exists in current directory:**
-- You're in a DevDoc docs folder
-- Source code is likely in `../` (parent directory)
+**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"
+
+**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
 
-**If `package.json` and `src/` exist:**
-- You're at repo root
-- Create docs in `./docs/` subfolder
+**If neither exists:**
+- Proceed to Step 2 (Ask User Preferences)
 
-**If neither matches:**
-- Ask user for the source code path
+### Step 2: Ask User Preferences First
 
-#### 2b. Scan for Existing API Specs
+**Don't scan yet - ask the user what they want:**
 
-**Search for OpenAPI specs:**
-```
-openapi.json, openapi.yaml, openapi.yml
-swagger.json, swagger.yaml, swagger.yml
-api-spec.json, api-spec.yaml
-**/openapi.*, **/swagger.*
+#### Question 1: Documentation Type
 ```
+What type of documentation are you creating?
 
-**Search for GraphQL schemas:**
+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
 ```
-schema.graphql, schema.gql
-*.graphql, *.gql
-**/schema.graphql
+
+#### Question 2: Codebase Connection (if codebase detected)
 ```
+I detected a codebase. Would you like me to:
 
-**If found, store the paths for later use.**
+1. **Scan codebase** - Build code-graph for accurate docs (recommended)
+2. **Skip scanning** - I'll write docs without code analysis
+```
 
-#### 2c. Auto-Discover Information
+#### Question 3: API Type (if API Docs selected)
+```
+What type of API do you have?
 
-Scan the repository and extract:
+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 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")
 ```
-From README.md:
-- Product name
-- Description
-- Key features
 
-From package.json / pyproject.toml / Cargo.toml:
-- Primary language
-- Framework (from dependencies)
-- Project type (library, cli, api, etc.)
+#### Question 4: Code Examples Language
+```
+What language should code examples use?
+(e.g., TypeScript, Python, curl, Go)
+```
 
-From OpenAPI spec (if exists):
-- API style: REST
-- Base URL
-- Authentication type
-- Endpoints count
-- Common patterns
+### Step 3: Locate & Import API Specs (if applicable)
 
-From GraphQL schema (if exists):
-- API style: GraphQL
-- Types count
-- Queries/Mutations
+**Only if user selected OpenAPI or GraphQL:**
 
-From source code structure:
-- Key directories
-- Naming conventions
+For OpenAPI:
+```
+Do you have an OpenAPI spec file? Please provide the path, or I can search for:
+- openapi.json / openapi.yaml
+- swagger.json / swagger.yaml
 ```
 
-#### 2d. Ask Key Questions
-
-After auto-discovery, ask the user to confirm/provide:
-
-**Question 1: Documentation Type**
-"What type of documentation are you creating?
-1. **internal** - For your team: setup guides, architecture, contribution guidelines
-2. **api** - For developers using your product: API reference, SDKs, integration guides  
-3. **product** - For end users: feature guides, tutorials, FAQs"
+For GraphQL:
+```
+Do you have a GraphQL schema? Please provide the path, or I can search for:
+- schema.graphql / schema.gql
+```
 
----
+**After locating spec:**
+1. Copy to `api-reference/` folder
+2. Validate the spec
+3. Extract metadata (endpoints, types, auth)
 
-**Question 2: Import Existing API Spec (if detected)**
-
-**If OpenAPI spec found:**
-"I found an OpenAPI specification at `{path}`:
-- {endpoint_count} endpoints
-- Base URL: {base_url}
-- Auth: {auth_type}
-
-Would you like me to:
-1. **Import it** - Copy to `api-reference/openapi.json` and generate API Reference tab
-2. **Reference it** - Point docs.json to existing location: `{path}`
-3. **Skip** - Don't include API reference (I'll create manual docs instead)"
-
-**If GraphQL schema found:**
-"I found a GraphQL schema at `{path}`:
-- {types_count} types
-- {queries_count} queries
-- {mutations_count} mutations
-
-Would you like me to:
-1. **Import it** - Copy to `api-reference/schema.graphql` and generate GraphQL tab
-2. **Reference it** - Point docs.json to existing location: `{path}`
-3. **Skip** - Don't include GraphQL playground"
-
-**If multiple specs found:**
-"I found multiple API specifications:
-- OpenAPI: `{openapi_path}`
-- GraphQL: `{graphql_path}`
-
-Which would you like to use for the API Reference?
-1. **OpenAPI (REST)** - Interactive REST API playground
-2. **GraphQL** - GraphQL playground with schema explorer
-3. **Both** - Create separate tabs for each
-4. **Skip** - Manual documentation only"
+### Step 4: Build Code Graph (Optional)
 
----
+**Skip this step if:**
+- No codebase detected
+- User chose "Skip scanning" in Question 2
+- User is creating docs-only project
 
-**Question 3: Target Audience**
-"Who is your primary audience?
-(e.g., 'Backend developers integrating our payment API', 'Internal engineering team', 'Non-technical business users')"
+**If scanning, comprehensively analyze the codebase and build `.devdoc/code-graph.json`:**
 
-**Question 4: Terminology (optional)**
-"Any specific terminology I should know? For example:
-- Brand names with specific capitalization
-- Terms to avoid or prefer
-- Domain-specific vocabulary
-
-(Press Enter to skip)"
+#### 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
+```
 
-**Question 5: Code Examples**
-"What language should I use for code examples?
-(e.g., TypeScript, Python, curl)"
+#### 4b. Source Code Structure
+```
+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
+```
 
-#### 2e. Create Context Memory
+#### 4c. Deep Code Analysis
+```
+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
+```
 
-Create `.devdoc/` folder and `context.json` with discovered + user info:
+#### 4d. Create Code Graph File
 
+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": "2026-01-24T10:30:00Z",
-  "product": {
-    "name": "[from README/package.json]",
-    "description": "[from README]",
-    "type": "[api/sdk/platform/cli/library]",
-    "domain": "[inferred or asked]",
-    "targetAudience": "[from Question 3]",
-    "keyFeatures": ["[from README]"]
+  "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
   },
-  "terminology": {
-    "glossary": {},
-    "avoidTerms": [],
-    "brandNames": {}
+  
+  "project": {
+    "name": "Project Name",
+    "description": "From README",
+    "language": "TypeScript",
+    "framework": "Express",
+    "rootDir": "src/"
   },
-  "api": {
-    "style": "[REST/GraphQL/etc if detected]",
-    "specPath": "[path to imported/referenced spec]",
-    "baseUrl": "[from OpenAPI if found]",
-    "authentication": {
-      "type": "[from OpenAPI if found]",
-      "headerName": "",
-      "description": ""
-    },
-    "conventions": {},
-    "commonPatterns": []
-  },
-  "codebase": {
-    "language": "[from package.json]",
-    "framework": "[from dependencies]",
-    "sourceLocation": "../"
+  
+  "structure": {
+    "sourceDir": "src/",
+    "testsDir": "tests/",
+    "examplesDir": "examples/",
+    "docsDir": "docs/"
   },
-  "documentation": {
-    "voice": "[based on docType]",
-    "perspective": "second_person",
-    "codeExamples": {
-      "primaryLanguage": "[from Question 5]",
-      "additionalLanguages": []
+  
+  "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" }
+      ]
     },
-    "templates": {
-      "guide": ".devdoc/templates/guide.md",
-      "apiReference": ".devdoc/templates/api-reference.md",
-      "tutorial": ".devdoc/templates/tutorial.md",
-      "quickstart": ".devdoc/templates/quickstart.md",
-      "troubleshooting": ".devdoc/templates/troubleshooting.md"
+    {
+      "name": "AuthToken",
+      "path": "src/types/auth.ts",
+      "kind": "interface",
+      "definition": "interface AuthToken { token: string; expiresAt: Date; }"
     }
-  },
-  "learned": {
-    "insights": [],
-    "corrections": []
-  }
-}
-```
-
-Also copy template files to `.devdoc/templates/` if they don't exist.
-
-Tell user: 
-"Created product context in `.devdoc/context.json`
-- Product: {name}
-- Type: {docType}
-- API: {REST/GraphQL} (imported from {spec_path})
-- Audience: {targetAudience}
-- Code examples: {primaryLanguage}
-
-This context will be used for consistent documentation generation."
-
-### Step 3: Import API Spec (if selected)
-
-**For OpenAPI (Import option):**
-1. Copy spec to `api-reference/openapi.json` (or `.yaml`)
-2. Validate the spec is valid OpenAPI 3.x
-3. Extract key info for context.json
-
-**For OpenAPI (Reference option):**
-1. Note the relative path for docs.json
-2. Extract key info for context.json
-
-**For GraphQL (Import option):**
-1. Copy schema to `api-reference/schema.graphql`
-2. Validate the schema
-3. Extract types/queries/mutations for context
-
-**For GraphQL (Reference option):**
-1. Note the relative path for docs.json
-2. Extract schema info for context
-
-### Step 4: Update docs.json with API Reference
-
-**Read existing `docs.json` or create new one.**
-
-Add the `docType` field and API reference tab:
-
-**For OpenAPI:**
-```json
-{
-  "name": "Project Name",
-  "docType": "api",
-  "navigation": {
-    "tabs": [
+  ],
+  
+  "api": {
+    "type": "REST",
+    "baseUrl": "/api/v1",
+    "specPath": "api-reference/openapi.json",
+    "authentication": {
+      "type": "bearer",
+      "headerName": "Authorization",
+      "description": "JWT token required"
+    },
+    "endpoints": [
       {
-        "tab": "Guides",
-        "groups": [...]
+        "method": "POST",
+        "path": "/auth/login",
+        "handler": "src/routes/auth.ts:login",
+        "description": "User login",
+        "auth": "none"
       },
       {
-        "tab": "API Reference",
-        "type": "openapi",
-        "spec": "api-reference/openapi.json"
+        "method": "GET",
+        "path": "/users/:id",
+        "handler": "src/routes/users.ts:getUser",
+        "auth": "required",
+        "responseType": "User"
       }
     ]
-  }
-}
-```
-
-**For GraphQL:**
-```json
-{
-  "name": "Project Name",
-  "docType": "api",
-  "navigation": {
-    "tabs": [
-      {
-        "tab": "Guides",
-        "groups": [...]
-      },
-      {
-        "tab": "GraphQL API",
-        "type": "graphql",
-        "schema": "api-reference/schema.graphql",
-        "endpoint": "https://api.example.com/graphql"
-      }
+  },
+  
+  "examples": [
+    {
+      "path": "examples/basic-auth.ts",
+      "description": "Basic authentication flow",
+      "tags": ["auth", "login"],
+      "runnable": true
+    }
+  ],
+  
+  "config": {
+    "envVars": [
+      { "name": "JWT_SECRET", "description": "Secret for JWT signing", "required": true },
+      { "name": "DATABASE_URL", "description": "Database connection string", "required": true }
     ]
+  },
+  
+  "errors": [
+    { "name": "AuthenticationError", "code": "AUTH_FAILED", "message": "Invalid credentials" },
+    { "name": "NotFoundError", "code": "NOT_FOUND", "message": "Resource not found" }
+  ],
+  
+  "dependencies": {
+    "express": "^4.18.0",
+    "jsonwebtoken": "^9.0.0"
   }
 }
 ```
 
-**For Both:**
+### Step 5: Create Context File
+
+Save to `.devdoc/context.json`:
 ```json
 {
-  "navigation": {
-    "tabs": [
-      { "tab": "Guides", "groups": [...] },
-      { "tab": "REST API", "type": "openapi", "spec": "api-reference/openapi.json" },
-      { "tab": "GraphQL API", "type": "graphql", "schema": "api-reference/schema.graphql" }
-    ]
+  "$schema": "https://devdoc.sh/schemas/context.json",
+  "version": "1.0",
+  "lastUpdated": "2026-01-24T10:00:00Z",
+  "git": {
+    "commitHash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
+    "commitShort": "a1b2c3d",
+    "branch": "main"
+  },
+  "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"
+    }
   }
 }
 ```
 
-Tell user: "Configured API Reference with {spec_type} from {path}"
-
-### Step 5: Generate Documentation
+**Tell user:**
+```
+✅ Context saved!
 
-**Read context from `.devdoc/context.json` before generating.**
+- Doc Type: API Documentation
+- API: REST (45 endpoints)
+- Audience: Backend developers
+- Code examples: TypeScript
 
-**Read the appropriate template** from `.devdoc/templates/` for each page type:
-- For guides: read `.devdoc/templates/guide.md`
-- For API reference: read `.devdoc/templates/api-reference.md`
-- For quickstart: read `.devdoc/templates/quickstart.md`
-- For tutorials: read `.devdoc/templates/tutorial.md`
+Memory map created with 12 modules scanned.
+Ready to generate documentation.
+```
 
-**Apply context throughout:**
-- Use correct product name from `product.name`
-- Use terminology from `terminology.glossary`
-- Avoid terms from `terminology.avoidTerms`
-- Use code language from `documentation.codeExamples.primaryLanguage`
-- Match voice from `documentation.voice`
-- Reference API spec path from `api.specPath`
+### Step 6: Plan Documentation Structure
 
----
+Based on user preferences, plan the structure:
 
-## docType: "internal"
+#### 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
+```
 
-For internal team documentation, create:
+#### For Product Docs:
+```
+docs/
+├── index.mdx
+├── getting-started/
+│   ├── quickstart.mdx
+│   └── key-concepts.mdx
+├── features/
+│   └── {feature}.mdx
+├── tutorials/
+└── troubleshooting/
+```
 
+#### For Internal Docs:
 ```
 docs/
-├── .devdoc/
-│   ├── context.json
-│   └── templates/
-├── docs.json
-├── index.mdx              # Project overview
+├── index.mdx
 ├── getting-started/
-│   ├── setup.mdx          # Dev environment setup
-│   ├── prerequisites.mdx  # Required tools/versions
-│   └── first-contribution.mdx
+│   ├── setup.mdx
+│   └── prerequisites.mdx
 ├── architecture/
-│   ├── overview.mdx       # System architecture
-│   ├── folder-structure.mdx
-│   └── decisions.mdx      # ADRs, design decisions
 ├── development/
-│   ├── workflow.mdx       # Git workflow, PR process
-│   ├── testing.mdx        # How to run/write tests
-│   ├── debugging.mdx      # Common issues, debugging tips
-│   └── deployment.mdx     # How to deploy
-├── api/                   # Internal API docs (if applicable)
-│   └── ...
-└── contributing.mdx       # Contribution guidelines
+└── contributing.mdx
 ```
 
-**Content focus:**
-- How to set up local development
-- Codebase architecture and patterns
-- Internal APIs and services
-- Debugging and troubleshooting
-- Team conventions and standards
-
-**Voice:** Technical, direct, assumes familiarity with codebase
-
----
+### Step 7: Generate Documentation
 
-## docType: "api"
+**Use the code graph to write accurate docs:**
 
-For external developers using your API/SDK, create:
+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)
 
+**For each page:**
 ```
-docs/
-├── .devdoc/
-│   ├── context.json
-│   └── templates/
-├── docs.json
-├── index.mdx              # Product intro, value prop
-├── quickstart.mdx         # 5-minute getting started
-├── authentication.mdx     # Auth setup (API keys, OAuth)
-├── guides/
-│   ├── overview.mdx       # Concepts overview
-│   └── {use-case}.mdx     # Common use case tutorials
-├── api-reference/
-│   ├── introduction.mdx   # API overview, base URL, versioning
-│   ├── authentication.mdx # Auth details
-│   ├── errors.mdx         # Error codes and handling
-│   ├── openapi.json       # Full API spec (if imported)
-│   └── schema.graphql     # GraphQL schema (if imported)
-├── sdks/                  # If SDKs exist
-│   ├── javascript.mdx
-│   ├── python.mdx
-│   └── ...
-├── webhooks.mdx           # If webhooks exist
-└── changelog.mdx          # API changelog
-```
-
-**Content focus:**
-- Quick time-to-first-API-call
-- Authentication and authorization
-- API reference with examples
-- SDKs and client libraries
-- Error handling and troubleshooting
-- Rate limits and best practices
-
-**Voice:** Professional, helpful, code-focused
-
----
-
-## docType: "product"
-
-For end users of your product, create:
-
+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
 ```
-docs/
-├── .devdoc/
-│   ├── context.json
-│   └── templates/
-├── docs.json
-├── index.mdx              # Product overview
-├── getting-started/
-│   ├── quickstart.mdx     # First steps
-│   ├── account-setup.mdx  # Account creation, onboarding
-│   └── key-concepts.mdx   # Core concepts explained
-├── features/
-│   ├── {feature-1}.mdx    # Feature guides
-│   ├── {feature-2}.mdx
-│   └── ...
-├── tutorials/
-│   ├── {workflow-1}.mdx   # Step-by-step tutorials
-│   └── ...
-├── integrations/          # If integrations exist
-│   └── ...
-├── troubleshooting/
-│   ├── common-issues.mdx
-│   └── faq.mdx
-└── release-notes.mdx      # What's new
-```
-
-**Content focus:**
-- Non-technical language (minimal code)
-- Screenshots and visual guides
-- Step-by-step tutorials
-- Use case focused
-- FAQs and troubleshooting
-- Feature explanations
-
-**Voice:** Friendly, supportive, non-technical
 
----
+**Example - Writing auth docs:**
+```
+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
+```
 
-## docs.json Templates (with docType)
+### Step 8: Update docs.json
 
-### Internal Docs
-```json
-{
-  "name": "{Project Name}",
-  "docType": "internal",
-  "navigation": {
-    "tabs": [
-      {
-        "tab": "Documentation",
-        "groups": [
-          { "group": "Getting Started", "pages": ["index", "getting-started/setup", "getting-started/prerequisites"] },
-          { "group": "Architecture", "pages": ["architecture/overview", "architecture/folder-structure"] },
-          { "group": "Development", "pages": ["development/workflow", "development/testing", "development/deployment"] },
-          { "group": "Contributing", "pages": ["contributing"] }
-        ]
-      }
-    ]
-  }
-}
-```
+Configure navigation based on doc type:
 
-### Customer API Docs (with OpenAPI)
+**API Docs with OpenAPI:**
 ```json
 {
-  "name": "{Product Name}",
+  "name": "Product Name",
   "docType": "api",
   "navigation": {
     "tabs": [
       {
         "tab": "Guides",
-        "groups": [
-          { "group": "Getting Started", "pages": ["index", "quickstart", "authentication"] },
-          { "group": "Guides", "pages": ["guides/overview"] }
-        ]
+        "groups": [...]
       },
       {
         "tab": "API Reference",
@@ -498,20 +443,12 @@ docs/
 }
 ```
 
-### Customer API Docs (with GraphQL)
+**API Docs with GraphQL:**
 ```json
 {
-  "name": "{Product Name}",
-  "docType": "api",
   "navigation": {
     "tabs": [
-      {
-        "tab": "Guides",
-        "groups": [
-          { "group": "Getting Started", "pages": ["index", "quickstart", "authentication"] },
-          { "group": "Guides", "pages": ["guides/overview"] }
-        ]
-      },
+      { "tab": "Guides", "groups": [...] },
       {
         "tab": "GraphQL API",
         "type": "graphql",
@@ -523,35 +460,46 @@ docs/
 }
 ```
 
-### Product Docs
-```json
-{
-  "name": "{Product Name}",
-  "docType": "product",
-  "navigation": {
-    "tabs": [
-      {
-        "tab": "Documentation",
-        "groups": [
-          { "group": "Getting Started", "pages": ["index", "getting-started/quickstart", "getting-started/key-concepts"] },
-          { "group": "Features", "pages": ["features/..."] },
-          { "group": "Tutorials", "pages": ["tutorials/..."] },
-          { "group": "Help", "pages": ["troubleshooting/common-issues", "troubleshooting/faq"] }
-        ]
-      }
-    ]
-  }
-}
+### 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)
+
+Code graph files:
+  - .devdoc/context.json (user preferences)
+  - .devdoc/code-graph.json (complete code analysis)
+
+Next steps:
+  1. Run `devdoc dev` to preview
+  2. Review TODO markers in generated docs
+  3. Run `/whisk-theme` to match your branding
+```
+
+---
+
+## Key Principles
+
+| 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 |
 
-## Quality Guidelines
+## Code Graph Usage
 
-- Extract real code examples from source, don't fabricate
-- Match tone to audience based on docType
-- Add TODO markers for sections needing human review
-- Include relevant screenshots for product docs
-- Test all code examples work
-- Always use terminology from context.json
-- Update context.json if you learn new information
-- **Import existing API specs** rather than creating manual docs
-- **Validate specs** before importing
+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