---
name: sync-docs
description: Analyze existing documentation against codebase and identify/fix outdated content. Reads docType from docs.json config.
---

## Instructions

When syncing documentation with the codebase:

### Step 0: Locate Source Code

First, determine where the source code is relative to current directory:
- If `docs.json` exists here → you're in docs folder, source code is in `../`
- If `package.json` and `src/` exist here → you're at repo root
- Check both current directory AND parent directory for source files

### Step 1: Get Documentation Type from Config

**Read `docs.json` and check for `docType` field:**

```json
{
  "docType": "api"  // "internal" | "api" | "product"
}
```

**If `docType` is set:** Use that value automatically.

**If `docType` is NOT set, detect from structure:**
- Has `architecture/`, `development/` → "internal"
- Has `api-reference/`, `sdks/` → "api"  
- Has `features/`, `tutorials/` → "product"

**If still unclear, ask:**
"What type of documentation is this?
1. internal - for your team
2. api - for developers using your product
3. product - for end users"

**After user answers, save to docs.json:**
Add `"docType": "{choice}"` to docs.json so it's remembered.
Tell user: "Saved docType to docs.json - you won't be asked again."

### Step 2: Build Documentation Inventory

Scan all MDX files and extract:
- Documented functions, classes, components
- Code examples and their imports
- API endpoints referenced
- Package versions mentioned
- CLI commands documented

### Step 2: Analyze Current Codebase

Compare documentation against source code:
- Check if documented functions still exist
- Verify function signatures match (parameters, return types)
- Confirm API endpoints are still valid
- Check if package versions are current
- Identify new exports not yet documented

### Step 3: Generate Sync Report

Output a report categorizing issues:

```
## Documentation Sync Report

### Outdated (Breaking Changes)
- `docs/api/users.mdx`: `createUser()` signature changed
  - Documented: `createUser(name: string)`
  - Current: `createUser(data: UserInput)`

### Outdated (Minor Changes)  
- `docs/quickstart.mdx`: Package version outdated
  - Documented: `v1.2.0`
  - Current: `v1.5.0`

### Missing Documentation
- `src/utils/validator.ts` - New export, not documented
- `POST /api/v2/webhooks` - New endpoint, not documented

### Up to Date
- `docs/guides/authentication.mdx`
- `docs/components/button.mdx`
```

### Step 4: Update Options

Ask user preference:
1. **Auto-fix all** - Update all outdated docs automatically
2. **Interactive** - Review each change before applying
3. **Report only** - Just show the report, don't change anything

### Step 5: Apply Updates

When updating:
- Preserve existing prose and explanations
- Update code examples to match current signatures
- Add TODO markers for sections needing human review
- Update version numbers
- Add stubs for missing documentation

## Detection Patterns

| Documentation Pattern | Codebase Check |
|----------------------|----------------|
| `import { X } from 'pkg'` | Verify X is exported from pkg |
| `function X(a, b)` | Check X signature in source |
| `v1.2.3` version strings | Compare with package.json |
| `POST /api/users` | Verify route exists |
| `<Component prop={x}>` | Check component props interface |

## Update Strategies

### For Changed Function Signatures
```mdx
// Before (outdated)
createUser(name: string, email: string)

// After (updated)
createUser(data: UserInput)
// Where UserInput = { name: string, email: string, role?: string }
```

### For Removed Features
```mdx
<Warning>
**Deprecated**: This feature was removed in v2.0. 
See [migration guide](/guides/v2-migration) for alternatives.
</Warning>
```

### For New Features (stub)
```mdx
---
title: "New Feature"
description: "Description"
---

{/* TODO: Document this feature */}

## Overview

Coming soon...
```
