@voodocs/cli 1.0.5 → 1.0.7

package/CHANGELOG.md

@@ -1,3 +1,62 @@
+## [1.0.7] - 2024-12-21
+
+### Added
+- **Enhanced Init Wizard**: Complete interactive setup experience
+  - Auto-detects project details (name, version, repository)
+  - Generates AI instructions automatically
+  - Configures privacy settings (.gitignore)
+  - Creates example annotated files
+  - **Rerunnable for upgrades**: Detects existing config and adds missing features
+  - Smart defaults for non-interactive mode
+  - Beautiful CLI interface with status icons and summaries
+
+### Changed
+- `voodocs init` now includes full wizard experience
+- Wizard supports both fresh install and upgrade scenarios
+- Auto-detection of AI environment (Cursor, Claude)
+
+### Fixed
+- Init command now properly integrates with instruct command
+- Upgrade path for users installing new versions
+
+## v1.0.6 (2024-12-21)
+
+### 🐛 Bug Fix: Missing Instructions Directory in npm Package
+
+**Problem:** The `voodocs instruct` command failed with "Error: Instructions directory not found" because the `lib/darkarts/instructions/` directory was not included in the npm package.
+
+**Root Cause:** The `instructions/` directory was not listed in the `files` array in `package.json`.
+
+**Fix:** Added `lib/darkarts/instructions/` to the `files` array in `package.json`.
+
+---
+
+### Changes
+
+- Added `lib/darkarts/instructions/` to package.json `files` array
+- Verified that all instruction templates are now included in the package:
+  - `claude.md`
+  - `cursor.md`
+  - `default.md`
+
+---
+
+### Testing
+
+| Test Case | Status |
+|-----------|--------|
+| Instructions directory included in package | ✅ Pass |
+| `voodocs instruct --list-templates` | ✅ Pass |
+| `voodocs instruct --ai cursor` | ✅ Pass |
+
+---
+
+### Upgrade
+
+```bash
+npm install -g @voodocs/cli@1.0.6
+```
+
 ## v1.0.5 (2024-12-21)
 
 ### 🐛 Bug Fix: Instruct Command Import Error

package/lib/cli/__init__.py

@@ -16,7 +16,7 @@ This module provides the command-line interface for VooDocs.
 import click
 from typing import Optional
 
-__version__ = "1.0.5"
+__version__ = "1.0.7"
 
 
 @click.group()

package/lib/cli/init.py

@@ -1,8 +1,8 @@
 """@darkarts
-⊢{cli:init}
-∂{click,pathlib,json}
+⊢{cli:init-wizard}
+∂{click,pathlib,json,os,subprocess}
 ⚠{write-access:cwd}
-⊨{idempotent:config-creation}
+⊨{idempotent:config-creation,rerunnable:upgrade-support}
 🔒{read-write:filesystem}
 ⚡{O(1):file-creation}
 """
@@ -10,52 +10,277 @@
 """
 VooDocs Init Command
 
-Initialize a new project with VooDocs configuration and example annotations.
+Interactive wizard to initialize or upgrade a project with VooDocs.
+Re-runnable to add missing features after upgrades.
 """
 
 import click
 import json
+import os
+import subprocess
 from pathlib import Path
+from typing import Optional, Dict, Any
 
 
 @click.command()
 @click.option(
-    '--format',
-    type=click.Choice(['voodocs', 'darkarts'], case_sensitive=False),
-    default='voodocs',
-    help='Annotation format to use (voodocs or darkarts symbolic)'
+    '--non-interactive',
+    is_flag=True,
+    help='Skip interactive prompts and use defaults'
 )
 @click.option(
-    '--config-only',
+    '--upgrade',
     is_flag=True,
-    help='Only create configuration file, skip example files'
+    help='Upgrade existing configuration (add missing features)'
 )
-def init(format, config_only):
+def init(non_interactive, upgrade):
     """
-    Initialize a new project with VooDocs.
+    Initialize or upgrade a project with VooDocs.
+    
+    This interactive wizard will:
+    - Set up your project configuration
+    - Auto-detect project details (version, repository, AI environment)
+    - Create AI instructions for your coding assistant
+    - Configure privacy settings (.gitignore)
+    - Generate example annotated files
     
-    Creates a .voodocs.json configuration file and optionally generates
-    example annotated files to help you get started.
+    Re-run after upgrading to add new features!
     
     Examples:
-        voodocs init                    # Initialize with @voodocs format
-        voodocs init --format darkarts  # Initialize with symbolic @darkarts format
-        voodocs init --config-only      # Only create config file
+        voodocs init                    # Interactive wizard
+        voodocs init --upgrade          # Upgrade existing config
+        voodocs init --non-interactive  # Use all defaults
     """
+    
     cwd = Path.cwd()
     config_path = cwd / '.voodocs.json'
     
-    # Check if config already exists
-    if config_path.exists():
-        click.echo(click.style('⚠ .voodocs.json already exists', fg='yellow'))
-        if not click.confirm('Overwrite existing configuration?'):
+    # Check if this is an upgrade or fresh install
+    existing_config = None
+    is_upgrade = config_path.exists()
+    
+    if is_upgrade:
+        try:
+            with open(config_path) as f:
+                existing_config = json.load(f)
+        except:
+            existing_config = None
+    
+    # Print welcome header
+    click.echo()
+    if is_upgrade:
+        click.echo(click.style('╔══════════════════════════════════════════╗', fg='yellow', bold=True))
+        click.echo(click.style('║   🔄 VooDocs Upgrade Wizard             ║', fg='yellow', bold=True))
+        click.echo(click.style('╚══════════════════════════════════════════╝', fg='yellow', bold=True))
+        click.echo()
+        click.echo(click.style('Existing configuration detected!', fg='yellow'))
+        click.echo('This wizard will help you add any missing features.')
+    else:
+        click.echo(click.style('╔══════════════════════════════════════════╗', fg='cyan', bold=True))
+        click.echo(click.style('║   🎉 Welcome to VooDocs Setup Wizard   ║', fg='cyan', bold=True))
+        click.echo(click.style('╚══════════════════════════════════════════╝', fg='cyan', bold=True))
+    click.echo()
+    
+    # Detect what's already configured
+    has_ai_instructions = _check_ai_instructions(cwd)
+    has_examples = (cwd / 'voodocs-examples').exists()
+    has_gitignore_entry = _check_gitignore(cwd, '.voodocs.json')
+    
+    if is_upgrade and not non_interactive:
+        click.echo(click.style('Current Setup:', fg='cyan', bold=True))
+        click.echo(f'  Configuration:     {_status_icon(True)} .voodocs.json exists')
+        click.echo(f'  AI Instructions:   {_status_icon(has_ai_instructions)} {_get_ai_file_status(cwd)}')
+        click.echo(f'  Example Files:     {_status_icon(has_examples)} voodocs-examples/')
+        click.echo(f'  .gitignore:        {_status_icon(has_gitignore_entry)} .voodocs.json entry')
+        click.echo()
+        
+        if not click.confirm('Continue with upgrade?', default=True):
             click.echo('Aborted.')
             return
+        click.echo()
+    
+    # Step 1: Project Information
+    click.echo(click.style('📋 Step 1: Project Information', fg='blue', bold=True))
+    click.echo()
+    
+    # Auto-detect or use existing config
+    project_name = _get_value(existing_config, 'project.name', _detect_project_name(cwd))
+    project_version = _get_value(existing_config, 'project.version', _detect_version(cwd))
+    repository_url = _get_value(existing_config, 'project.repository', _detect_repository(cwd))
+    project_purpose = _get_value(existing_config, 'project.purpose', f'{project_name} project')
+    
+    if non_interactive:
+        name = project_name
+        version = project_version
+        repository = repository_url
+        purpose = project_purpose
+    else:
+        if is_upgrade:
+            click.echo(f'Current values (press Enter to keep):')
+        name = click.prompt('Project name', default=project_name)
+        purpose = click.prompt('Project purpose', default=project_purpose)
+        version = click.prompt('Current version', default=project_version)
+        repository = click.prompt('Repository URL (leave empty to skip)', default=repository_url or '', show_default=False)
+    
+    click.echo()
+    
+    # Step 2: Annotation Format
+    click.echo(click.style('✨ Step 2: Annotation Format', fg='blue', bold=True))
+    click.echo()
+    
+    current_format = _get_value(existing_config, 'format', 'darkarts')
+    
+    if is_upgrade:
+        click.echo(f'Current format: {click.style(current_format, fg="green", bold=True)}')
+        if non_interactive:
+            format_choice = current_format
+        else:
+            change_format = click.confirm('Change annotation format?', default=False)
+            if change_format:
+                click.echo()
+                click.echo('VooDocs supports two annotation formats:')
+                click.echo('  1. Natural language (e.g., module_purpose: "...")')
+                click.echo('  2. Symbolic DarkArts (e.g., ⊢{...}, ∂{...}, ⚠{...})')
+                click.echo()
+                format_choice = click.prompt(
+                    'Choose format',
+                    type=click.Choice(['voodocs', 'darkarts'], case_sensitive=False),
+                    default=current_format
+                )
+            else:
+                format_choice = current_format
+    else:
+        click.echo('VooDocs supports two annotation formats:')
+        click.echo('  1. Natural language (e.g., module_purpose: "...")')
+        click.echo('  2. Symbolic DarkArts (e.g., ⊢{...}, ∂{...}, ⚠{...})')
+        click.echo()
+        if non_interactive:
+            format_choice = 'darkarts'
+        else:
+            format_choice = click.prompt(
+                'Choose format',
+                type=click.Choice(['voodocs', 'darkarts'], case_sensitive=False),
+                default='darkarts'
+            )
+    
+    click.echo()
+    
+    # Step 3: AI Assistant Setup
+    click.echo(click.style('🤖 Step 3: AI Assistant Setup', fg='blue', bold=True))
+    click.echo()
+    
+    detected_ai = _detect_ai_environment()
+    
+    if has_ai_instructions and is_upgrade:
+        click.echo(f'{_status_icon(True)} AI instructions already configured')
+        if non_interactive:
+            setup_ai = False
+            ai_choice = None
+        else:
+            setup_ai = click.confirm('Update AI instructions?', default=False)
+            if setup_ai:
+                ai_choice = click.prompt(
+                    'Which AI assistant?',
+                    type=click.Choice(['cursor', 'claude', 'default'], case_sensitive=False),
+                    default=detected_ai or 'cursor'
+                )
+            else:
+                ai_choice = None
+    else:
+        if detected_ai:
+            click.echo(f'Detected AI environment: {click.style(detected_ai, fg="green", bold=True)}')
+        else:
+            click.echo('No AI environment detected')
+        click.echo()
+        
+        if non_interactive:
+            setup_ai = detected_ai is not None
+            ai_choice = detected_ai or 'cursor'
+        else:
+            setup_ai = click.confirm('Generate AI instructions for your coding assistant?', default=True)
+            if setup_ai:
+                ai_choice = click.prompt(
+                    'Which AI assistant?',
+                    type=click.Choice(['cursor', 'claude', 'default'], case_sensitive=False),
+                    default=detected_ai or 'cursor'
+                )
+            else:
+                ai_choice = None
+    
+    click.echo()
+    
+    # Step 4: Privacy Settings
+    click.echo(click.style('🔒 Step 4: Privacy Settings', fg='blue', bold=True))
+    click.echo()
+    
+    if has_gitignore_entry and is_upgrade:
+        click.echo(f'{_status_icon(True)} .gitignore already configured')
+        add_to_gitignore = False
+    else:
+        if non_interactive:
+            is_private = True
+            add_to_gitignore = True
+        else:
+            is_private = click.confirm('Is this a private project?', default=True)
+            add_to_gitignore = False
+            if is_private:
+                add_to_gitignore = click.confirm('Add .voodocs.json to .gitignore?', default=True)
+    
+    click.echo()
+    
+    # Step 5: Example Files
+    click.echo(click.style('📝 Step 5: Example Files', fg='blue', bold=True))
+    click.echo()
+    
+    if has_examples and is_upgrade:
+        click.echo(f'{_status_icon(True)} Example files already exist')
+        create_examples = False
+    else:
+        if non_interactive:
+            create_examples = True
+        else:
+            create_examples = click.confirm('Create example annotated files?', default=not is_upgrade)
+    
+    click.echo()
+    
+    # Show configuration summary
+    click.echo(click.style('📊 Configuration Summary', fg='cyan', bold=True))
+    click.echo(click.style('─' * 50, fg='cyan'))
+    click.echo(f'  Project Name:      {click.style(name, fg="green")}')
+    click.echo(f'  Purpose:           {purpose}')
+    click.echo(f'  Version:           {version}')
+    if repository:
+        click.echo(f'  Repository:        {repository}')
+    click.echo(f'  Format:            {click.style(format_choice, fg="green", bold=True)}')
+    if setup_ai and ai_choice:
+        click.echo(f'  AI Assistant:      {click.style(ai_choice, fg="green")} {_status_icon(True, "new") if not has_ai_instructions else ""}')
+    if add_to_gitignore:
+        click.echo(f'  .gitignore:        {click.style("Yes", fg="green")} {_status_icon(True, "new")}')
+    if create_examples:
+        click.echo(f'  Example Files:     {click.style("Yes", fg="green")} {_status_icon(True, "new")}')
+    click.echo(click.style('─' * 50, fg='cyan'))
+    click.echo()
+    
+    if not non_interactive:
+        action = 'upgrade' if is_upgrade else 'create'
+        if not click.confirm(f'Proceed to {action} configuration?', default=True):
+            click.echo('Aborted.')
+            return
+        click.echo()
+    
+    # Create/update configuration
+    action_verb = 'Updating' if is_upgrade else 'Creating'
+    click.echo(click.style(f'⚙️  {action_verb} configuration...', fg='blue'))
     
-    # Create default configuration
     config = {
         "version": "1.0",
-        "format": format,
+        "project": {
+            "name": name,
+            "purpose": purpose,
+            "version": version,
+            "repository": repository if repository else None
+        },
+        "format": format_choice,
         "validation": {
             "semantic": True,
             "performance": True,
@@ -76,40 +301,252 @@ def init(format, config_only):
         ]
     }
     
+    # Merge with existing config if upgrading
+    if is_upgrade and existing_config:
+        # Preserve any custom fields
+        for key in existing_config:
+            if key not in config:
+                config[key] = existing_config[key]
+    
     # Write configuration
     with open(config_path, 'w') as f:
         json.dump(config, f, indent=2)
     
-    click.echo(click.style('✓ Created .voodocs.json', fg='green'))
+    verb = 'Updated' if is_upgrade else 'Created'
+    click.echo(click.style(f'  ✓ {verb} .voodocs.json', fg='green'))
+    
+    # Add to .gitignore if requested
+    if add_to_gitignore:
+        _add_to_gitignore(cwd, '.voodocs.json')
+        click.echo(click.style('  ✓ Added to .gitignore', fg='green'))
+    
+    # Generate AI instructions
+    if setup_ai and ai_choice:
+        click.echo(click.style(f'  ⚙️  Generating {ai_choice} instructions...', fg='blue'))
+        _generate_ai_instructions(cwd, ai_choice, format_choice)
+        click.echo(click.style(f'  ✓ Created AI instructions', fg='green'))
     
-    if not config_only:
-        # Create example files
+    # Create example files
+    if create_examples:
+        click.echo(click.style('  ⚙️  Creating example files...', fg='blue'))
         examples_dir = cwd / 'voodocs-examples'
         examples_dir.mkdir(exist_ok=True)
         
-        if format == 'voodocs':
-            create_voodocs_example(examples_dir)
+        if format_choice == 'voodocs':
+            _create_voodocs_examples(examples_dir)
         else:
-            create_darkarts_example(examples_dir)
+            _create_darkarts_examples(examples_dir)
         
-        click.echo(click.style(f'✓ Created example files in {examples_dir}/', fg='green'))
+        click.echo(click.style(f'  ✓ Created examples in {examples_dir}/', fg='green'))
     
+    # Success!
     click.echo()
-    click.echo(click.style('🎉 VooDocs initialized successfully!', fg='green', bold=True))
+    if is_upgrade:
+        click.echo(click.style('╔══════════════════════════════════════════╗', fg='green', bold=True))
+        click.echo(click.style('║   ✅ VooDocs Upgrade Complete!         ║', fg='green', bold=True))
+        click.echo(click.style('╚══════════════════════════════════════════╝', fg='green', bold=True))
+    else:
+        click.echo(click.style('╔══════════════════════════════════════════╗', fg='green', bold=True))
+        click.echo(click.style('║   🎉 VooDocs Setup Complete!           ║', fg='green', bold=True))
+        click.echo(click.style('╚══════════════════════════════════════════╝', fg='green', bold=True))
     click.echo()
-    click.echo('Next steps:')
+    click.echo(click.style('Next steps:', fg='cyan', bold=True))
     click.echo('  1. Review .voodocs.json configuration')
-    click.echo('  2. Add annotations to your code')
-    click.echo('  3. Run: voodocs validate .')
-    click.echo('  4. Run: voodocs generate . ./docs')
+    if setup_ai and ai_choice:
+        ai_file = '.cursorrules' if ai_choice == 'cursor' else f'{ai_choice}-instructions.md'
+        click.echo(f'  2. Your AI assistant will use {ai_file}')
+    click.echo('  3. Add annotations to your code')
+    click.echo('  4. Run: voodocs validate .')
+    click.echo('  5. Run: voodocs generate . ./docs')
     click.echo()
-    click.echo('Documentation: https://voodocs.com/docs')
+    if is_upgrade:
+        click.echo(click.style('💡 Tip:', fg='yellow') + ' Run ' + click.style('voodocs init --upgrade', fg='cyan') + ' again after future updates!')
+    click.echo()
+    click.echo(f'Documentation: {click.style("https://voodocs.com/docs", fg="blue", underline=True)}')
+    click.echo()
+
 
+def _status_icon(exists: bool, label: str = None) -> str:
+    """Return a status icon."""
+    if label == "new":
+        return click.style('🆕', fg='green')
+    return click.style('✓', fg='green') if exists else click.style('✗', fg='red')
 
-def create_voodocs_example(examples_dir: Path):
+
+def _get_value(config: Optional[Dict[str, Any]], path: str, default: Any) -> Any:
+    """Get a value from nested config dict using dot notation."""
+    if not config:
+        return default
+    
+    keys = path.split('.')
+    value = config
+    for key in keys:
+        if isinstance(value, dict) and key in value:
+            value = value[key]
+        else:
+            return default
+    
+    return value if value is not None else default
+
+
+def _check_ai_instructions(cwd: Path) -> bool:
+    """Check if AI instructions exist."""
+    return (
+        (cwd / '.cursorrules').exists() or
+        (cwd / '.claude' / 'instructions.md').exists() or
+        (cwd / 'AI_INSTRUCTIONS.md').exists()
+    )
+
+
+def _get_ai_file_status(cwd: Path) -> str:
+    """Get status of AI instruction files."""
+    files = []
+    if (cwd / '.cursorrules').exists():
+        files.append('.cursorrules')
+    if (cwd / '.claude' / 'instructions.md').exists():
+        files.append('.claude/instructions.md')
+    if (cwd / 'AI_INSTRUCTIONS.md').exists():
+        files.append('AI_INSTRUCTIONS.md')
+    
+    return ', '.join(files) if files else 'none'
+
+
+def _check_gitignore(cwd: Path, entry: str) -> bool:
+    """Check if entry exists in .gitignore."""
+    gitignore = cwd / '.gitignore'
+    if not gitignore.exists():
+        return False
+    
+    content = gitignore.read_text()
+    return entry in content
+
+
+def _detect_project_name(cwd: Path) -> str:
+    """Detect project name from directory or package.json."""
+    package_json = cwd / 'package.json'
+    if package_json.exists():
+        try:
+            with open(package_json) as f:
+                data = json.load(f)
+                if 'name' in data:
+                    return data['name']
+        except:
+            pass
+    
+    return cwd.name
+
+
+def _detect_version(cwd: Path) -> str:
+    """Detect project version."""
+    package_json = cwd / 'package.json'
+    if package_json.exists():
+        try:
+            with open(package_json) as f:
+                data = json.load(f)
+                if 'version' in data:
+                    return data['version']
+        except:
+            pass
+    
+    pyproject = cwd / 'pyproject.toml'
+    if pyproject.exists():
+        try:
+            with open(pyproject) as f:
+                for line in f:
+                    if line.startswith('version'):
+                        return line.split('=')[1].strip().strip('"\'')
+        except:
+            pass
+    
+    version_file = cwd / 'VERSION'
+    if version_file.exists():
+        try:
+            return version_file.read_text().strip()
+        except:
+            pass
+    
+    return '1.0.0'
+
+
+def _detect_repository(cwd: Path) -> Optional[str]:
+    """Detect repository URL from git config."""
+    try:
+        result = subprocess.run(
+            ['git', 'config', '--get', 'remote.origin.url'],
+            capture_output=True,
+            text=True,
+            cwd=cwd
+        )
+        if result.returncode == 0:
+            url = result.stdout.strip()
+            if url.startswith('git@github.com:'):
+                url = url.replace('git@github.com:', 'https://github.com/')
+            if url.endswith('.git'):
+                url = url[:-4]
+            return url
+    except:
+        pass
+    
+    return None
+
+
+def _detect_ai_environment() -> Optional[str]:
+    """Detect which AI environment is being used."""
+    if os.environ.get('CURSOR_USER') or Path('.cursorrules').exists():
+        return 'cursor'
+    
+    if os.environ.get('CLAUDE_API_KEY') or Path('.claude').exists():
+        return 'claude'
+    
+    return None
+
+
+def _add_to_gitignore(cwd: Path, entry: str):
+    """Add an entry to .gitignore."""
+    gitignore = cwd / '.gitignore'
+    
+    if gitignore.exists():
+        content = gitignore.read_text()
+        if entry in content:
+            return
+    else:
+        content = ''
+    
+    if content and not content.endswith('\n'):
+        content += '\n'
+    content += f'\n# VooDocs\n{entry}\n'
+    
+    gitignore.write_text(content)
+
+
+def _generate_ai_instructions(cwd: Path, ai_type: str, format_type: str):
+    """Generate AI instructions file."""
+    cli_dir = Path(__file__).parent
+    template_path = cli_dir.parent / 'darkarts' / 'instructions' / f'{ai_type}.md'
+    
+    if not template_path.exists():
+        template_path = cli_dir.parent / 'darkarts' / 'instructions' / 'default.md'
+    
+    if not template_path.exists():
+        return
+    
+    instructions = template_path.read_text()
+    
+    if ai_type == 'cursor':
+        output_file = cwd / '.cursorrules'
+    elif ai_type == 'claude':
+        output_dir = cwd / '.claude'
+        output_dir.mkdir(exist_ok=True)
+        output_file = output_dir / 'instructions.md'
+    else:
+        output_file = cwd / 'AI_INSTRUCTIONS.md'
+    
+    output_file.write_text(instructions)
+
+
+def _create_voodocs_examples(examples_dir: Path):
     """Create example files with @voodocs annotations."""
     
-    # TypeScript example
     ts_example = '''/**@voodocs
 module_purpose: "Example TypeScript module demonstrating @voodocs annotations"
 dependencies: []
@@ -137,41 +574,11 @@ export function greet(name: string, age: number): string {
 '''
     
     (examples_dir / 'example.ts').write_text(ts_example)
-    
-    # Python example
-    py_example = '''"""@voodocs
-module_purpose: "Example Python module demonstrating @voodocs annotations"
-dependencies: []
-assumptions: ["Python 3.7+"]
-"""
-
-def calculate_total(prices: list[float], tax_rate: float) -> float:
-    """@voodocs
-    preconditions: [
-      "prices is a non-empty list of positive numbers",
-      "tax_rate is between 0 and 1"
-    ]
-    postconditions: [
-      "Returns the total with tax applied",
-      "Result is greater than or equal to sum of prices"
-    ]
-    invariants: [
-      "Does not modify the prices list"
-    ]
-    side_effects: []
-    complexity: "O(n) where n is the length of prices"
-    """
-    subtotal = sum(prices)
-    return subtotal * (1 + tax_rate)
-'''
-    
-    (examples_dir / 'example.py').write_text(py_example)
 
 
-def create_darkarts_example(examples_dir: Path):
+def _create_darkarts_examples(examples_dir: Path):
     """Create example files with symbolic @darkarts annotations."""
     
-    # TypeScript example
     ts_example = '''/**@darkarts
 ⊢{Example TypeScript module demonstrating symbolic @darkarts annotations}
 ∂{}
@@ -190,7 +597,7 @@ def create_darkarts_example(examples_dir: Path):
 ⊨{
   Does ¬ modify input parameters
 }
-⚡{}
+⚡{O(1)}
 */
 export function greet(name: string, age: number): string {
   return `Hello, ${name}! You are ${age} years old.`;
@@ -198,31 +605,3 @@ export function greet(name: string, age: number): string {
 '''
     
     (examples_dir / 'example.ts').write_text(ts_example)
-    
-    # Python example
-    py_example = '''"""@darkarts
-⊢{Example Python module demonstrating symbolic @darkarts annotations}
-∂{}
-⚠{Python 3.7+}
-"""
-
-def calculate_total(prices: list[float], tax_rate: float) -> float:
-    """@darkarts
-    ⊳{
-      prices is a non-empty list ∧ ∀ p ∈ prices: p > 0
-      tax_rate ∈ [0, 1]
-    }
-    ⊲{
-      Returns the total with tax applied
-      result ≥ sum(prices)
-    }
-    ⊨{
-      Does ¬ modify the prices list
-    }
-    ⚡{O(n) where n = len(prices)}
-    """
-    subtotal = sum(prices)
-    return subtotal * (1 + tax_rate)
-'''
-    
-    (examples_dir / 'example.py').write_text(py_example)

package/lib/darkarts/instructions/claude.md

@@ -0,0 +1,139 @@
+# Claude AI Instructions for Symbolic DarkArts Annotations
+
+**Version:** 2.0  
+**Date:** December 21, 2024
+
+---
+
+## 1. Primary Goal
+
+Your primary goal is to **write and maintain symbolic DarkArts annotations** for all new and existing code. This ensures that our documentation is always up-to-date, accurate, and machine-readable.
+
+---
+
+## 2. Annotation Format: Symbolic DarkArts
+
+**Always use the symbolic DarkArts format.** Do not use the natural language `@voodocs` format.
+
+### Correct Format
+
+```typescript
+/**@darkarts
+⊢{Module purpose}
+∂{Dependencies}
+⚠{Assumptions}
+*/
+
+/**@darkarts
+⊳{Preconditions}
+⊲{Postconditions}
+⊨{Invariants}
+⚡{Side effects / Complexity}
+🔒{Security implications}
+*/
+```
+
+### Incorrect Format (Do Not Use)
+
+```typescript
+/**@voodocs
+module_purpose: "..."
+dependencies: [...]
+*/
+```
+
+---
+
+## 3. Key Rules
+
+1.  **Annotate Everything:** All modules, functions, classes, and interfaces must have a DarkArts annotation block.
+2.  **Use Symbolic Format Only:** Strictly adhere to the symbolic format (`⊢`, `∂`, `⚠`, `⊳`, `⊲`, `⊨`, `⚡`, `🔒`).
+3.  **Use Logic Symbols:** Use mathematical symbols for logic (`∧`, `∨`, `¬`, `∈`, `∃`, `∀`, `⇒`, `⇔`).
+4.  **Be Precise and Concise:** Annotations should be accurate and to the point.
+5.  **Validate Your Work:** After making changes, run `voodocs validate . --recursive` to ensure all annotations are correct.
+
+---
+
+## 4. Symbol Quick Reference
+
+| Symbol | Meaning | Symbol | Meaning |
+|---|---|---|---|
+| `⊢` | Module Purpose | `∧` | And |
+| `∂` | Dependencies | `∨` | Or |
+| `⚠` | Assumptions | `¬` | Not |
+| `⊳` | Preconditions | `∈` | In |
+| `⊲` | Postconditions | `∉` | Not In |
+| `⊨` | Invariants | `∃` | Exists |
+| `⚡` | Side Effects / Complexity | `∀` | For All |
+| `🔒` | Security Implications | `⇒` | Implies |
+| `⇔` | If and Only If | `⊤` | True |
+| `⊥` | False | `∅` | Empty Set |
+| `⊆` | Subset | `∪` | Union |
+| `∩` | Intersection | | |
+
+---
+
+## 5. Workflow
+
+1.  **When writing new code:** Add symbolic DarkArts annotations as you go.
+2.  **When modifying existing code:** Update the corresponding annotations to reflect your changes.
+3.  **Before committing:** Run `voodocs validate . --recursive` to catch any errors.
+4.  **If validation fails:** Run `voodocs fix . --recursive` to automatically fix common issues.
+
+---
+
+## 6. Example: Adding a New Function
+
+If you add a new function `getUserById`, you must add a symbolic annotation block:
+
+```typescript
+/**@darkarts
+⊳{userId must be a valid UUID}
+⊲{
+  Returns a user object if found
+  Returns null if ¬∃ user with that ID
+}
+⊨{Does ¬ modify the database}
+⚡{O(1) lookup}
+*/
+export async function getUserById(userId: string): Promise<User | null> {
+  // ...
+}
+```
+
+---
+
+## 7. Example: Modifying a Module
+
+If you add a new dependency to a module, update the `∂` field:
+
+**Before:**
+```typescript
+/**@darkarts
+⊢{User authentication service}
+∂{jsonwebtoken}
+*/
+```
+
+**After (added bcrypt):**
+```typescript
+/**@darkarts
+⊢{User authentication service}
+∂{
+  jsonwebtoken: For JWT creation
+  bcrypt: For password hashing
+}
+*/
+```
+
+---
+
+## 8. Important Commands
+
+-   **Validate:** `voodocs validate . --recursive`
+-   **Fix:** `voodocs fix . --recursive`
+-   **Generate Docs:** `voodocs generate . ./docs --recursive`
+
+---
+
+By following these instructions, you will help us maintain a high-quality, machine-readable, and self-validating codebase. Thank you for your contribution!

package/lib/darkarts/instructions/cursor.md

@@ -0,0 +1,139 @@
+# Cursor AI Instructions for Symbolic DarkArts Annotations
+
+**Version:** 2.0  
+**Date:** December 21, 2024
+
+---
+
+## 1. Primary Goal
+
+Your primary goal is to **write and maintain symbolic DarkArts annotations** for all new and existing code. This ensures that our documentation is always up-to-date, accurate, and machine-readable.
+
+---
+
+## 2. Annotation Format: Symbolic DarkArts
+
+**Always use the symbolic DarkArts format.** Do not use the natural language `@voodocs` format.
+
+### Correct Format
+
+```typescript
+/**@darkarts
+⊢{Module purpose}
+∂{Dependencies}
+⚠{Assumptions}
+*/
+
+/**@darkarts
+⊳{Preconditions}
+⊲{Postconditions}
+⊨{Invariants}
+⚡{Side effects / Complexity}
+🔒{Security implications}
+*/
+```
+
+### Incorrect Format (Do Not Use)
+
+```typescript
+/**@voodocs
+module_purpose: "..."
+dependencies: [...]
+*/
+```
+
+---
+
+## 3. Key Rules
+
+1.  **Annotate Everything:** All modules, functions, classes, and interfaces must have a DarkArts annotation block.
+2.  **Use Symbolic Format Only:** Strictly adhere to the symbolic format (`⊢`, `∂`, `⚠`, `⊳`, `⊲`, `⊨`, `⚡`, `🔒`).
+3.  **Use Logic Symbols:** Use mathematical symbols for logic (`∧`, `∨`, `¬`, `∈`, `∃`, `∀`, `⇒`, `⇔`).
+4.  **Be Precise and Concise:** Annotations should be accurate and to the point.
+5.  **Validate Your Work:** After making changes, run `voodocs validate . --recursive` to ensure all annotations are correct.
+
+---
+
+## 4. Symbol Quick Reference
+
+| Symbol | Meaning | Symbol | Meaning |
+|---|---|---|---|
+| `⊢` | Module Purpose | `∧` | And |
+| `∂` | Dependencies | `∨` | Or |
+| `⚠` | Assumptions | `¬` | Not |
+| `⊳` | Preconditions | `∈` | In |
+| `⊲` | Postconditions | `∉` | Not In |
+| `⊨` | Invariants | `∃` | Exists |
+| `⚡` | Side Effects / Complexity | `∀` | For All |
+| `🔒` | Security Implications | `⇒` | Implies |
+| `⇔` | If and Only If | `⊤` | True |
+| `⊥` | False | `∅` | Empty Set |
+| `⊆` | Subset | `∪` | Union |
+| `∩` | Intersection | | |
+
+---
+
+## 5. Workflow
+
+1.  **When writing new code:** Add symbolic DarkArts annotations as you go.
+2.  **When modifying existing code:** Update the corresponding annotations to reflect your changes.
+3.  **Before committing:** Run `voodocs validate . --recursive` to catch any errors.
+4.  **If validation fails:** Run `voodocs fix . --recursive` to automatically fix common issues.
+
+---
+
+## 6. Example: Adding a New Function
+
+If you add a new function `getUserById`, you must add a symbolic annotation block:
+
+```typescript
+/**@darkarts
+⊳{userId must be a valid UUID}
+⊲{
+  Returns a user object if found
+  Returns null if ¬∃ user with that ID
+}
+⊨{Does ¬ modify the database}
+⚡{O(1) lookup}
+*/
+export async function getUserById(userId: string): Promise<User | null> {
+  // ...
+}
+```
+
+---
+
+## 7. Example: Modifying a Module
+
+If you add a new dependency to a module, update the `∂` field:
+
+**Before:**
+```typescript
+/**@darkarts
+⊢{User authentication service}
+∂{jsonwebtoken}
+*/
+```
+
+**After (added bcrypt):**
+```typescript
+/**@darkarts
+⊢{User authentication service}
+∂{
+  jsonwebtoken: For JWT creation
+  bcrypt: For password hashing
+}
+*/
+```
+
+---
+
+## 8. Important Commands
+
+-   **Validate:** `voodocs validate . --recursive`
+-   **Fix:** `voodocs fix . --recursive`
+-   **Generate Docs:** `voodocs generate . ./docs --recursive`
+
+---
+
+By following these instructions, you will help us maintain a high-quality, machine-readable, and self-validating codebase. Thank you for your contribution!

package/lib/darkarts/instructions/default.md

@@ -0,0 +1,139 @@
+# AI Instructions for Symbolic DarkArts Annotations
+
+**Version:** 2.0  
+**Date:** December 21, 2024
+
+---
+
+## 1. Primary Goal
+
+Your primary goal is to **write and maintain symbolic DarkArts annotations** for all new and existing code. This ensures that our documentation is always up-to-date, accurate, and machine-readable.
+
+---
+
+## 2. Annotation Format: Symbolic DarkArts
+
+**Always use the symbolic DarkArts format.** Do not use the natural language `@voodocs` format.
+
+### Correct Format
+
+```typescript
+/**@darkarts
+⊢{Module purpose}
+∂{Dependencies}
+⚠{Assumptions}
+*/
+
+/**@darkarts
+⊳{Preconditions}
+⊲{Postconditions}
+⊨{Invariants}
+⚡{Side effects / Complexity}
+🔒{Security implications}
+*/
+```
+
+### Incorrect Format (Do Not Use)
+
+```typescript
+/**@voodocs
+module_purpose: "..."
+dependencies: [...]
+*/
+```
+
+---
+
+## 3. Key Rules
+
+1.  **Annotate Everything:** All modules, functions, classes, and interfaces must have a DarkArts annotation block.
+2.  **Use Symbolic Format Only:** Strictly adhere to the symbolic format (`⊢`, `∂`, `⚠`, `⊳`, `⊲`, `⊨`, `⚡`, `🔒`).
+3.  **Use Logic Symbols:** Use mathematical symbols for logic (`∧`, `∨`, `¬`, `∈`, `∃`, `∀`, `⇒`, `⇔`).
+4.  **Be Precise and Concise:** Annotations should be accurate and to the point.
+5.  **Validate Your Work:** After making changes, run `voodocs validate . --recursive` to ensure all annotations are correct.
+
+---
+
+## 4. Symbol Quick Reference
+
+| Symbol | Meaning | Symbol | Meaning |
+|---|---|---|---|
+| `⊢` | Module Purpose | `∧` | And |
+| `∂` | Dependencies | `∨` | Or |
+| `⚠` | Assumptions | `¬` | Not |
+| `⊳` | Preconditions | `∈` | In |
+| `⊲` | Postconditions | `∉` | Not In |
+| `⊨` | Invariants | `∃` | Exists |
+| `⚡` | Side Effects / Complexity | `∀` | For All |
+| `🔒` | Security Implications | `⇒` | Implies |
+| `⇔` | If and Only If | `⊤` | True |
+| `⊥` | False | `∅` | Empty Set |
+| `⊆` | Subset | `∪` | Union |
+| `∩` | Intersection | | |
+
+---
+
+## 5. Workflow
+
+1.  **When writing new code:** Add symbolic DarkArts annotations as you go.
+2.  **When modifying existing code:** Update the corresponding annotations to reflect your changes.
+3.  **Before committing:** Run `voodocs validate . --recursive` to catch any errors.
+4.  **If validation fails:** Run `voodocs fix . --recursive` to automatically fix common issues.
+
+---
+
+## 6. Example: Adding a New Function
+
+If you add a new function `getUserById`, you must add a symbolic annotation block:
+
+```typescript
+/**@darkarts
+⊳{userId must be a valid UUID}
+⊲{
+  Returns a user object if found
+  Returns null if ¬∃ user with that ID
+}
+⊨{Does ¬ modify the database}
+⚡{O(1) lookup}
+*/
+export async function getUserById(userId: string): Promise<User | null> {
+  // ...
+}
+```
+
+---
+
+## 7. Example: Modifying a Module
+
+If you add a new dependency to a module, update the `∂` field:
+
+**Before:**
+```typescript
+/**@darkarts
+⊢{User authentication service}
+∂{jsonwebtoken}
+*/
+```
+
+**After (added bcrypt):**
+```typescript
+/**@darkarts
+⊢{User authentication service}
+∂{
+  jsonwebtoken: For JWT creation
+  bcrypt: For password hashing
+}
+*/
+```
+
+---
+
+## 8. Important Commands
+
+-   **Validate:** `voodocs validate . --recursive`
+-   **Fix:** `voodocs fix . --recursive`
+-   **Generate Docs:** `voodocs generate . ./docs --recursive`
+
+---
+
+By following these instructions, you will help us maintain a high-quality, machine-readable, and self-validating codebase. Thank you for your contribution!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voodocs/cli",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "AI-Native Documentation System with Validation - The only documentation tool that validates your annotations and guarantees accuracy",
   "main": "voodocs_cli.py",
   "bin": {
@@ -58,6 +58,7 @@
     "lib/darkarts/context/",
     "lib/darkarts/core/",
     "lib/darkarts/validation/",
+    "lib/darkarts/instructions/",
     "lib/darkarts/exceptions.py",
     "lib/darkarts/telemetry.py",
     "lib/darkarts/parsers/typescript/dist/",