wonder-ai-docs/README.md

AI-assisted documentation management for developers, designed to work seamlessly with Cursor

# Wonder AI Docs

A docs utility for AI-assisted and agentic development, designed to work seamlessly with Cursor.

Reduce the rabbit trails, dead ends, and bad assumptions that ruin agentic coding sessions.  Give yourself a space to shape your project.  Increase Cursor's product IQ.

## Quick Start

1. Install the Wonder CLI:
   ```bash
   npm install -g wonder-ai-docs
   ```

2. Initialize your project:
   ```bash
   wonder init
   ```

   Optional initialization methods:
   ```bash
   # Initialize with a source file
   wonder init path/to/your/project.md
   
   # Initialize with example project context
   wonder init --demo
   ```

3. Start using Cursor with enhanced context:
   ```
   "Hi Cursor! I've just initialized Wonder Docs for this project. Could you help me create documentation using the templates?"
   ```

## Overview

Wonder Docs provides a structured approach to AI-assisted development by organizing your project's documentation and context in a `.wonder` directory. This helps Cursor better understand your project and provide more relevant assistance.

## Features

- **Template-Based Documentation**: Create documentation using AI-optimized templates
- **Context Management**: Maintain project context and history through checkpoints
- **Cursor Integration**: Seamless integration with Cursor's AI capabilities
- **Intelligent Assistance**: AI-powered documentation maintenance and improvement
- **Version Control**: Track changes and maintain reversion points

## Core Components

### Template Library
Located in `.wonder/templates/`, this is a growing collection of templates that Cursor can use to help create and structure documentation. Templates are organized by type and can be customized based on project needs.

### User Documentation
Documentation is created in the user's `.wonder` directory as needed, using templates from the template library. This keeps the actual documentation separate from the templates while maintaining consistent structure.

### Checkpoint System
The checkpoint system (in `.wonder/.cursor/checkpoints/`) helps track significant changes and progress:
- Creates checkpoints at important milestones
- Maintains reversion points for rollback
- Tracks changes and documentation updates
- Provides intelligent commit suggestions

> **Note**: The checkpoint system is optional. You can use Wonder without it, or enable it when you want to track significant changes in your project.

### Cursor Integration
The `.wonder/.cursor` directory contains instructions and tools for Cursor to:
- Use templates effectively
- Manage checkpoints
- Guide documentation creation
- Provide intelligent assistance

## Project Structure

The `.wonder` directory contains a comprehensive structure for organizing all aspects of your project:

```
.wonder/
├── .cursor/                    # Cursor-specific instructions and tools
│   ├── init.md                # Initialization instructions
│   ├── onboarding-guide.md    # Cursor onboarding guide
│   ├── initialization-checklist.md # Project setup checklist
│   ├── tidy.md                # Documentation maintenance guide
│   └── checkpoints/           # Checkpoint system for tracking progress
├── templates/                  # Template library for documentation
│   ├── architecture/          # Architecture documentation templates
│   ├── constraints/           # Project constraints templates
│   ├── decisions/             # Decision record templates
│   ├── documentation/         # General documentation templates
│   ├── environment/           # Environment setup templates
│   ├── issue-tracking/        # Issue tracking templates
│   ├── project/               # Project management templates
│   ├── references/            # Reference documentation templates
│   ├── requirements/          # Requirements documentation templates
│   └── user-stories/          # User story templates
└── [user-created-dirs]/       # Created as needed for user documentation
```

## CLI Commands

### Project Management
- `wonder init [source-file]` - Initialize a new Wonder project
  - `--demo` - Initialize with example project context
- `wonder check` - Verify project structure and dependencies
- `wonder update` - Update to the latest version
- `wonder list` - Show all Wonder-managed directories

### Documentation
- `wonder tidy` - Analyze and improve project documentation
  - `--dry-run` - Show what would change without making changes
  - `--force` - Apply changes without confirmation
  - `--verbose` - Show detailed output

### Configuration
- `wonder config` - Manage CLI settings
  - `set <key> <value>` - Set a configuration value
  - `get <key>` - Get a configuration value
  - `list` - Show all configuration settings

### Help
- `wonder help` - Show detailed help information
- `wonder version` - Show the CLI version

## Configuration

### Required Settings
Set your Anthropic API key to enable LLM features:
```bash
wonder config set llmApiKey your-anthropic-api-key
```

### Optional Settings
- `maxTokens` - Adjust token limit for larger documents (default: 20000)
- `model` - Specify the LLM model to use (default: claude-3-opus-20240229)

## Working with Cursor

### Getting Started

To activate Cursor's Wonder Docs awareness, start your conversation with:
```
"Hi Cursor! I've just initialized Wonder Docs for this project. Could you help me create documentation using the templates?"
```

Or more casually:
```
"Hey Cursor! I set up Wonder - ready to help me document this project?"
```

### Jump Right In

If you want to start describing your project immediately:
```
"Hi Cursor! I've got Wonder Docs set up. I'm building a [describe your project]"
```

Or be more specific:
```
"Cursor, I've initialized Wonder Docs. Let's start with the project overview - I'm building a [describe your project]"
```

### What to Expect

After your first message, Cursor will:
1. Recognize Wonder Docs
2. Start the documentation process
3. Ask relevant questions
4. Help structure your information
5. Guide you through the process

## Best Practices

1. **Getting Started**
   - Let Cursor guide you through the setup process
   - Review the initialization checklist
   - Start with a clear project description

2. **Working with Cursor**
   - Start conversations with natural language
   - Let Cursor guide you through documentation
   - Use checkpoints to track progress
   - Review and refine documentation regularly

3. **Documentation**
   - Let Cursor create documentation using templates
   - Review and refine documentation as needed
   - Keep documentation up to date with your project
   - Use clear, specific language when requesting changes

4. **Project Management**
   - Create checkpoints at project milestones
   - Use reversion points when needed
   - Let Cursor help maintain project structure
   - Review and approve significant changes

## Requirements

- Node.js >= 14.0.0
- An Anthropic API key for LLM features

## Version Information
- Framework Version: 1.2.0
- Last Updated: [Current Date]
- Features:
  - Template-based documentation
  - Context management
  - Checkpoint system
  - Git integration
  - Friendly communication
  - Reversion support

## License

BSL-1.1