add-documentation

name	add-documentation
description	Add or update documentation in content/docs/ for features, APIs, or tools

Create well-structured documentation files in `content/docs/` for NowStack features, components, APIs, or tools. **ALWAYS use the provided script** to initialize new docs, then edit the generated file.

<quick_start> MANDATORY: Use the script to create new documentation files:

.agents/skills/add-documentation/scripts/create-doc.sh <filename> "<title>" "<description>"

# Example
.agents/skills/add-documentation/scripts/create-doc.sh dialog-system "Dialog System" "Global dialog system for modals"

This creates content/docs/<filename>.mdx with proper structure.

---

Template structure (auto-generated by script):

---
title: "Feature Name"
description: "Brief description of what this feature does"
keywords: ["keyword1", "keyword2", "feature"]
tags: ["developer", "components"]
order: 10
subcategory: "Components"
---

Brief introduction explaining what this feature does and why it's useful.

## Installation

How to set up or enable this feature (if needed).

## Import

\`\`\`tsx
import { Component } from "@/features/feature-name";
\`\`\`

## Usage

### Basic Example

\`\`\`tsx

<Component prop="value" />
\`\`\`

### Advanced Example

\`\`\`tsx

<Component
  prop="value"
  onAction={async () => {
    await doSomething();
  }}
/>
\`\`\`

## API Reference

| Option | Type     | Description             |
| ------ | -------- | ----------------------- |
| `prop` | `string` | Description of the prop |

## Best Practices

- Tip 1
- Tip 2

Run to verify: pnpm dev and check /docs/[slug] </quick_start>

<before_writing> CRITICAL: Think before documenting

Ask yourself these questions:

1. Who is the audience? (developers, end-users, admins)
2. What problem does this solve? (document the "why", not just the "how")
3. What's the minimal example? (start simple, then add complexity)
4. What are common mistakes? (add warnings/tips) </before_writing>

<frontmatter_reference>

Field	Type	Required	Description
title	string	Yes	Display title for the doc
description	string	Yes	Brief description (shown in search, SEO)
keywords	string[]	Yes	Search keywords
tags	string[]	Yes	Categories: developer, guide, api, components
order	number	Yes	Sort order in navigation (lower = first)
subcategory	string	Yes	Grouping: Guide, Components, API, Tools
</frontmatter_reference>

Choose the appropriate subcategory: - **Guide**: Getting started, tutorials, workflows - **Components**: UI components, dialog system, layout - **API**: REST endpoints, Convex functions/actions, integrations - **Tools**: CLI tools, development utilities

<structure_guidelines> <section_order>

1. Introduction - 1-2 sentences explaining what and why
2. Installation - Setup steps (if needed)
3. Import - Code import statement
4. Usage - Basic example first, then advanced
5. API Reference - Props/options table
6. Best Practices - Tips and common patterns
7. Troubleshooting - Common issues (optional) </section_order>

<code_examples>

• Always provide working, copy-paste-ready code
• Use TypeScript with proper types
• Include imports in examples
• Show async/await patterns when relevant </code_examples> </structure_guidelines>

<anti_patterns> Documentation without context:

## Usage

Use `dialogManager.confirm()` to show a dialog.

Documentation with context and example: ```mdx ## Usage The Dialog Manager handles confirmation dialogs with automatic loading states.

```tsx dialogManager.confirm({ title: "Delete Item", description: "This cannot be undone.", action: { label: "Delete", onClick: async () => { await deleteItem(); }, }, }); ```

</right>

<wrong>
Overly complex first example:
```mdx
## Basic Usage
\`\`\`tsx
<Component
  prop1="value"
  prop2={42}
  prop3={{ nested: true }}
  onAction={handleAction}
  variant="complex"
/>
\`\`\`

Start with minimal example: ```mdx ## Basic Usage \`\`\`tsx \`\`\`

With Options

```tsx ```

</right>
</anti_patterns>

<existing_docs>
Current documentation files in `content/docs/`:
- `getting-started.mdx` - Project setup guide
- `auth-components.mdx` - Authentication components
- `changelog.mdx` - Changelog page documentation
- `contact-components.mdx` - Contact form components
- `dialog-manager.mdx` - Dialog system documentation
- `zod-route.mdx` - Route validation with Zod
- `layout-components.mdx` - Layout components
- `markdown-components.mdx` - Markdown rendering
- `embedding.mdx` - Testimonial embedding
- `file-adapters.mdx` - File storage adapters
- `api-testimonials-*.mdx` - API documentation
</existing_docs>

<reference_guides>
For detailed documentation patterns and complete examples:

- **`references/documentation-format.md`** - Complete frontmatter reference and structure guidelines
- **`templates/doc-template.mdx`** - Base template used by the script
</reference_guides>

<critical_rules>
**NEVER create documentation files manually. ALWAYS use the script:**

```bash
.agents/skills/add-documentation/scripts/create-doc.sh <filename> "<title>" "<description>"

Then edit the generated file to add content. </critical_rules>

<success_criteria>

• Script used to create the file (MANDATORY)
• File created in content/docs/ with .mdx extension
• All required frontmatter fields present
• Clear introduction explaining the "why"
• Working code examples with proper imports
• API reference table for props/options
• Consistent formatting with existing docs </success_criteria>