@graphikartistry/cursor-doc-automation/docs/ONBOARDING.md

Cursor IDE extension for autonomous documentation and ticket management

# Onboarding Guide for Cursor Documentation Automation

## Prerequisites

Before you begin, ensure you have:
- Node.js (v14 or higher)
- npm or yarn package manager
- Git installed and configured
- Access to:
  - GitHub repository
  - Jira instance

## Step 1: Initial Setup

1. **Clone the Repository**
   ```bash
   git clone https://github.com/yourusername/cursor-doc-automation.git
   cd cursor-doc-automation
   ```

2. **Install Dependencies**
   ```bash
   npm install
   ```

3. **Configure Environment Variables**
   Create a `.env` file in the root directory:
   ```env
   # Jira Configuration
   JIRA_PROJECT_KEY=your_jira_project_key
   JIRA_API_TOKEN=your_jira_api_token
   JIRA_EMAIL=your_jira_email
   JIRA_DOMAIN=your_jira_domain

   # GitHub Configuration
   GITHUB_TOKEN=your_github_token
   GITHUB_REPOSITORY=your_github_repository
   ```

## Step 2: Understanding the Extension

The extension provides three main functionalities:

1. **Documentation Analysis**
   - Automatically analyzes code changes
   - Generates technical documentation
   - Identifies related components

2. **GitHub Integration**
   - Creates pull requests
   - Updates documentation
   - Manages branches

3. **Jira Integration**
   - Creates backlog items
   - Links documentation to tickets
   - Updates ticket status

## Step 3: Quick Start

1. **Build the Extension**
   ```bash
   npm run build
   ```

2. **Run the Test Script**
   ```bash
   npm run test-docs
   ```

3. **Check the Results**
   - Review the generated documentation in `docs/auto-generated.md`
   - Check your GitHub repository for the new pull request
   - Verify the Jira ticket creation

## Step 4: Using in Your Project

1. **Install the Extension**
   ```bash
   npm install /path/to/cursor-doc-automation-1.0.0.tgz
   ```

2. **Basic Usage**
   ```typescript
   import { DocumentationService } from 'cursor-doc-automation';

   const docService = new DocumentationService();

   // Analyze changes
   const analysis = await docService.analyzeChanges();

   // Create documentation PR
   await docService.createDocumentationPR(analysis);

   // Create Jira ticket
   await docService.createJiraBacklogItem(analysis);
   ```

## Step 5: Testing

The extension includes comprehensive automated tests:

1. **Run Tests**
   ```bash
   # Run all tests
   npm test

   # Run tests in watch mode
   npm run test:watch

   # Run tests with coverage report
   npm run test:coverage
   ```

2. **Test Coverage**
   - Tests cover all major functionality
   - Includes unit tests for services
   - Integration tests for API clients
   - Error handling scenarios

3. **Writing Tests**
   ```typescript
   import { DocumentationService } from 'cursor-doc-automation';

   describe('DocumentationService', () => {
     it('should analyze changes', async () => {
       const service = new DocumentationService();
       const analysis = await service.analyzeChanges();
       expect(analysis).toBeDefined();
     });
   });
   ```

## Step 6: Best Practices

1. **Documentation**
   - Keep documentation up to date
   - Review auto-generated content
   - Add manual notes when needed

2. **GitHub Workflow**
   - Create feature branches
   - Use meaningful commit messages
   - Review PRs before merging

3. **Jira Integration**
   - Link PRs to Jira tickets
   - Update ticket status
   - Add relevant comments

4. **Testing**
   - Run tests before committing
   - Maintain test coverage
   - Add tests for new features

## Troubleshooting

Common issues and solutions:

1. **Environment Variables**
   - Verify all required variables are set
   - Check for typos in API keys
   - Ensure proper permissions

2. **GitHub Integration**
   - Verify GitHub token permissions
   - Check repository access
   - Ensure branch naming follows conventions

3. **Jira Integration**
   - Verify Jira API token
   - Check project key validity
   - Ensure proper permissions

4. **Testing Issues**
   - Check test environment setup
   - Verify mock implementations
   - Review test coverage reports

## Getting Help

If you encounter issues:
1. Check the [GitHub Issues](https://github.com/yourusername/cursor-doc-automation/issues)
2. Review the documentation
3. Contact the development team

## Next Steps

1. Review the [API Documentation](API.md)
2. Explore [Advanced Features](ADVANCED.md)
3. Join the community discussions