---
name: create-doc
description: Create new documentation pages interactively. Analyzes codebase and guides you through the process.
---

## Instructions

When user wants to create documentation:

### Step 0: Read Context & Code Graph

**First, read `.devdoc/context.json` if it exists:**
- Use `product.name` for product references
- Apply `terminology.glossary` for correct terms
- Use `documentation.codeExamples.primaryLanguage` for code
- Read templates from `documentation.templates`

**Then, read `.devdoc/code-graph.json` if it exists:**
- Use `modules` array to understand codebase structure
- Reference exact function signatures from `exports`
- Use `types` array for type definitions
- Find examples in `examples` array
- Reference `errors` for error handling docs

### Step 1: Understand What to Create

Ask the user:

"What would you like to document?

1. **A specific feature or concept** - I'll create a guide/tutorial
2. **Code files or functions** - Point me to the code, I'll generate docs
3. **API endpoints** - I'll analyze your API and create reference docs
4. **Something else** - Describe what you need"

### Step 2: Gather Information

Based on their choice:

#### For Feature/Concept:
- "What's the topic/title?"
- "What type of page?
  - Guide - Explains how to do something
  - Tutorial - Step-by-step walkthrough
  - Reference - Technical specifications
  - Troubleshooting - Problem/solution format"
- "Any specific sections you want included?"

#### For Code Documentation:
- "Which files or directories should I analyze?"
- "What should I focus on?
  - Public API/exports
  - Internal architecture
  - Usage examples
  - All of the above"
- Read the specified files
- Extract functions, classes, types, examples

#### For API Documentation:
- Check for existing OpenAPI/GraphQL specs
- If found: "I found `{spec}`. Should I generate docs from it?"
- If not: "Point me to your API routes/controllers"
- Extract endpoints, parameters, responses

#### For Other:
- Ask clarifying questions
- Understand the scope and purpose

### Step 3: Analyze Codebase (if applicable)

When documenting code:

**If `.devdoc/code-graph.json` exists:**
```
Read from code-graph.json:
- modules[].exports → Function signatures, params, returns
- types[] → Type definitions
- examples[] → Code examples
- api.endpoints[] → API routes
- errors[] → Error types
```

**If code-graph.json doesn't exist:**
```
Scan the codebase for:
- Function signatures and JSDoc/docstrings
- Type definitions and interfaces
- Usage examples in tests
- README sections about this feature
```

Show user what you found:
"I found in code-graph.json:
- Module: `auth` with 5 exports (login, logout, verifyToken...)
- Types: User, AuthToken, Session
- Examples: `examples/auth-flow.ts`

Should I proceed with generating documentation for these?"

### Step 4: Choose Template

Read the appropriate template from `.devdoc/templates/`:

| Content Type | Template |
|--------------|----------|
| How-to guide | `guide.md` |
| Tutorial | `tutorial.md` |
| API endpoint | `api-reference.md` |
| Quick start | `quickstart.md` |
| FAQ/Issues | `troubleshooting.md` |

### Step 5: Generate Content

Create the documentation:

1. **Read the template** for structure guidance
2. **Apply context** (terminology, voice, language)
3. **Use code-graph.json** for accuracy:
   - Get exact function signatures from `exports`
   - Get type definitions from `types`
   - Reference examples from `examples` array
   - Document errors from `errors` array
4. **Include mermaid diagrams** for flows/architecture
5. **Add real code examples** from codebase/code-graph
6. **Use proper MDX components** (Steps, Cards, Tabs, etc.)

**Example using code-graph:**
```
// From code-graph.json:
{
  "name": "login",
  "type": "function",
  "signature": "login(email: string, password: string): Promise<AuthToken>",
  "params": [...]
}

// Generate accurate documentation:
## login(email, password)
Authenticate user and return JWT token.
```

### Step 6: Propose File Location

Suggest where to save:

"I'll create this page at: `docs/guides/{topic}.mdx`

Does this location work, or would you prefer somewhere else?"

### Step 7: Create and Update Navigation

1. Write the MDX file
2. Ask: "Should I add this to the navigation in docs.json?"
3. If yes, update docs.json with the new page

### Step 8: Summary

"Created:
- `docs/guides/{topic}.mdx` - {description}
- Updated `docs.json` navigation

Preview with `npm run dev`

Want me to create another page or make changes to this one?"

---

## Code Documentation Examples

### From TypeScript/JavaScript:

```typescript
// Source: src/utils/auth.ts
export function validateToken(token: string): boolean {
  // ... implementation
}
```

Generates:

```mdx
## validateToken

Validates an authentication token.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `token` | `string` | The JWT token to validate |

### Returns

`boolean` - `true` if valid, `false` otherwise

### Example

```typescript
import { validateToken } from '@package/auth';

const isValid = validateToken(userToken);
if (!isValid) {
  throw new Error('Invalid token');
}
```
```

### From Python:

```python
# Source: src/auth.py
def validate_token(token: str) -> bool:
    """
    Validate an authentication token.
    
    Args:
        token: The JWT token to validate
        
    Returns:
        True if valid, False otherwise
    """
```

Generates similar documentation following the template structure.

---

## Quality Guidelines

- Extract real code examples, don't fabricate
- Include error handling in examples
- Add TODO markers for sections needing human review
- Use mermaid diagrams for complex flows
- Link to related documentation
- Apply terminology from context.json
