@voodocs/cli 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,205 @@
+## [0.1.2] - 2025-12-19
+
+### Fixed
+- Fixed bug in documentation generator where `class_invariants` was incorrectly referenced as `invariants` on line 570
+- Function-level invariants now render correctly in generated documentation
+
+### Added
+- Comprehensive example file demonstrating function-level invariants (`examples/test_function_invariants.py`)
+- Examples showing `transfer_funds()`, `binary_search()`, and `BankAccount` class with invariants
+- Documentation in USAGE.md clarifying when to use `invariants` vs `class_invariants`
+- Real-world examples of conservation laws and state constraints using invariants
+
+### Changed
+- Updated USAGE.md annotation fields table to clarify `invariants` usage
+- Added "Function with Invariants" and "Class with Invariants" examples to USAGE.md
+
+### Documentation
+- Clarified that `invariants` can be used at function level for execution-time properties
+- Clarified that `class_invariants` should be used for object state constraints
+- Added examples showing both use cases
+
+## [0.1.1] - 2025-12-19
+
+### Fixed
+
+**Critical Bug Fix:**
+- Fixed `ModuleNotFoundError: No module named 'darkarts.telemetry'` when using pnpm global installation
+- Improved symlink resolution in `cli.py` to handle both npm and pnpm directory structures
+- Now works correctly with npm, pnpm, and direct execution
+
+**Technical Details:**
+- pnpm uses a different symlink structure (`.pnpm/@voodocs+cli@version/node_modules/...`)
+- Previous path resolution only worked with npm's simpler symlink structure
+- New implementation properly resolves symlinks for both package managers
+
+**Affected Users:**
+- Users installing with `pnpm install -g @voodocs/cli`
+- npm users are unaffected (already working)
+
+# Changelog
+
+All notable changes to VooDocs will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-12-19
+
+### 🎉 Initial Release
+
+First public release of VooDocs - AI-native documentation for modern development.
+
+### Added
+
+**Core Commands:**
+- `voodocs init` - Initialize VooDocs in a project with interactive prompts
+- `voodocs instruct` - Generate AI assistant instructions for 5 major AI coding assistants (Cursor, Claude Code, GitHub Copilot, Cody, Windsurf)
+- `voodocs generate` - Generate documentation, tests, and API specs from @voodocs annotations
+- `voodocs status` - Show project statistics and annotation coverage
+- `voodocs watch` - Watch files and automatically regenerate documentation
+- `voodocs validate` - Validate @voodocs annotations for correctness
+- `voodocs check` - Check annotation coverage and quality
+- `voodocs export` - Export documentation to HTML or PDF
+- `voodocs telemetry` - Control anonymous telemetry (enable/disable/status)
+
+**Documentation Generation:**
+- Mathematical notation translation (LaTeX → human-readable)
+- Support for Python and TypeScript
+- Multi-language output (English, Spanish, French, German, Chinese, Japanese)
+- Markdown output with proper formatting
+- Code examples and usage documentation
+
+**Test Generation:**
+- Property-based testing using Hypothesis (Python)
+- Automatic test case generation from @voodocs annotations
+- Support for pytest, unittest, and jest frameworks
+- Edge case detection and testing
+
+**API Specification:**
+- OpenAPI 3.0 spec generation
+- Swagger 2.0 support
+- GraphQL schema generation
+- Automatic endpoint documentation
+
+**Quality Tools:**
+- Annotation validation with detailed error messages
+- Coverage checking and reporting
+- Best practices recommendations
+- CI/CD integration templates (GitHub Actions, GitLab CI, pre-commit hooks)
+
+**Export Capabilities:**
+- HTML export with responsive design
+- PDF export with professional formatting
+- Customizable templates
+
+**Telemetry & Privacy:**
+- Anonymous usage analytics with Supabase backend
+- Privacy-respecting data collection (no PII)
+- Easy opt-out mechanism
+- GDPR compliant
+- 90-day data retention policy
+- Transparent privacy policy (PRIVACY.md)
+
+**Configuration:**
+- Project-level configuration via `.voodocs/config.json`
+- Customizable output directories
+- Language selection
+- Test framework preferences
+- API format preferences
+- Exclude/include patterns
+
+**Developer Experience:**
+- Interactive CLI with prompts
+- Comprehensive error messages
+- Detailed usage documentation (USAGE.md)
+- Example projects and templates
+- Fast execution (optimized performance)
+
+### Technical Details
+
+**Package:**
+- Size: 169.6 kB (compressed)
+- Unpacked size: 616.1 kB
+- Total files: 70
+- Zero dependencies (standalone)
+
+**Supported Languages:**
+- Python (≥3.7)
+- TypeScript (via compiled parser)
+- JavaScript (via TypeScript parser)
+
+**Supported Platforms:**
+- Linux
+- macOS
+- Windows
+
+**Requirements:**
+- Node.js ≥16.0.0
+- Python ≥3.7.0
+
+### Architecture
+
+**DarkArts Language:**
+- Mathematical notation for AI-readable specifications
+- @voodocs annotation syntax
+- LaTeX-style mathematical expressions
+- First-order logic support
+- Set theory notation
+
+**Plugin System:**
+- Extensible architecture
+- Custom generator support
+- Custom validator support
+- Custom exporter support
+
+**Parsers:**
+- Python AST parser
+- TypeScript/JavaScript parser (compiled)
+- Annotation extraction and validation
+
+### Known Limitations
+
+- TypeScript parser requires npm postinstall step
+- PDF export requires WeasyPrint (Python dependency)
+- Windows support not extensively tested
+- Limited to Python and TypeScript in v0.1.0
+
+### Security
+
+- No sensitive data collected
+- Anonymous session IDs only
+- Supabase anon key embedded (safe for public use)
+- No code or file content transmitted
+- No personal information collected
+
+### Documentation
+
+- README.md - Project overview and quick start
+- USAGE.md - Comprehensive user guide (350+ lines)
+- PRIVACY.md - Telemetry and privacy policy
+- NPM_PUBLISH_GUIDE.md - Publishing instructions
+- TELEMETRY_*.md - Telemetry implementation details
+
+### Links
+
+- npm: https://www.npmjs.com/package/@voodocs/cli
+- GitHub: https://github.com/3vilEnterprises/vooodooo-magic/tree/main/packages/voodocs
+- Issues: https://github.com/3vilEnterprises/vooodooo-magic/issues
+- Homepage: https://voodocs.com
+
+---
+
+## [Unreleased]
+
+### Planned for v0.2.0
+- Additional language support (Java, Go, Rust)
+- Web dashboard for analytics
+- Team collaboration features
+- Custom template support
+- Plugin marketplace
+- Performance optimizations
+
+---
+
+**Note:** This is a free beta release. Telemetry helps us understand usage patterns and prioritize features. You can disable telemetry at any time with `voodocs telemetry disable`.

package/PRIVACY.md

@@ -0,0 +1,83 @@
+# VooDocs Privacy Policy
+
+**Last updated:** 2025-12-19
+
+This Privacy Policy explains how VooDocs collects, uses, and discloses information about you. This policy applies when you use the VooDocs command-line interface (CLI) and its related services.
+
+## 1. Information We Collect
+
+VooDocs is designed with privacy as a core principle. We collect minimal, anonymous information to help us improve the product and understand how it is used.
+
+### Anonymous Telemetry
+
+By default, VooDocs collects anonymous telemetry data about CLI usage. This data is not linked to your identity and does not include any personal information or code content.
+
+We collect the following anonymous data:
+
+- **Command Usage**: Which VooDocs commands are executed (e.g., `init`, `generate`).
+- **Success/Failure Rates**: Whether commands succeed or fail.
+- **Performance Metrics**: Command execution duration.
+- **Error Information**: The type of error if a command fails (e.g., `ParserError`).
+- **Project Metadata**: The programming language of the project (e.g., `python`, `typescript`).
+- **Usage Statistics**: Number of files processed, number of annotations found.
+- **Environment Information**: Operating system, VooDocs version, Python version, Node.js version.
+- **Anonymous Session ID**: A randomly generated UUID to group events from a single CLI session. This ID is not tied to you or your machine and resets periodically.
+
+### What We DO NOT Collect
+
+We are developers ourselves and we respect your privacy. VooDocs **never** collects:
+
+- **Personally Identifiable Information (PII)**: Your name, email, IP address, or any other personal data.
+- **Code or Source Files**: The content of your source code, annotations, or generated documentation.
+- **File Names or Paths**: The names or paths of your files or directories.
+- **Git Information**: Your git remote, email, or user name.
+- **Machine Information**: Your machine name, MAC address, or other hardware identifiers.
+
+## 2. How We Use Information
+
+We use the anonymous telemetry data we collect to:
+
+- **Improve VooDocs**: Understand which features are most popular and where users encounter problems.
+- **Enhance Performance**: Identify and fix performance bottlenecks.
+- **Prioritize Features**: Make data-driven decisions about what to build next.
+- **Track Adoption**: Measure the overall growth and adoption of VooDocs.
+
+## 3. Data Storage and Security
+
+- **Data Storage**: Anonymous telemetry data is stored in a secure Supabase database.
+- **Data Retention**: We retain anonymous telemetry data for a maximum of 90 days.
+- **Access Control**: Access to the telemetry data is strictly limited to authorized VooDocs personnel.
+
+## 4. Your Choices
+
+### Opting Out of Telemetry
+
+Telemetry is enabled by default to help us improve the product. You can disable it at any time by running:
+
+```bash
+voodocs telemetry disable
+```
+
+You can also disable it by setting the following environment variable:
+
+```bash
+export VOODOCS_TELEMETRY_DISABLED=1
+```
+
+### Viewing Telemetry Status
+
+To check if telemetry is enabled and view your anonymous session ID, run:
+
+```bash
+voodocs telemetry status
+```
+
+## 5. Changes to This Policy
+
+We may update this Privacy Policy from time to time. If we make material changes, we will notify you by updating the date at the top of the policy and, in some cases, we may provide additional notice (such as by displaying a prominent notice in the CLI).
+
+## 6. Contact Us
+
+If you have any questions about this Privacy Policy, please open an issue on our GitHub repository:
+
+[https://github.com/3vilEnterprises/vooodooo-magic/issues](https://github.com/3vilEnterprises/vooodooo-magic/issues)

package/README.md

@@ -1,16 +1,16 @@
-# VooDocs - AI-Native Documentation System
+# Voodocs - AI-Native Documentation System
 
 [![NPM Version](https://img.shields.io/npm/v/@voodocs/cli.svg)](https://www.npmjs.com/package/@voodocs/cli)
 [![License](https://img.shields.io/npm/l/@voodocs/cli.svg)](https://voodocs.com/terms)
 [![Support](https://img.shields.io/badge/support-priority-blue.svg)](https://voodocs.com/support)
 
-**VooDocs** is a revolutionary AI-native documentation system that transforms how software is documented, tested, and specified. It teaches AI coding assistants (like Cursor and Claude Code) to write precise, machine-readable specifications in `@voodocs` annotations using the **DarkArtsAI language** - the mathematical and logical notation that AI naturally understands. These annotations are then automatically translated into human-readable documentation, automated tests, and API specifications.
+**Voodocs** is a revolutionary AI-native documentation system that transforms how software is documented, tested, and specified. It teaches AI coding assistants (like Cursor and Claude Code) to write precise, machine-readable specifications in `@voodocs` annotations using the **DarkArtsAI language** - the mathematical and logical notation that AI naturally understands. These annotations are then automatically translated into human-readable documentation, automated tests, and API specifications.
 
-This is the future of software development: **AI documents your code in its native language, VooDocs translates it for humans.**
+This is the future of software development: **AI documents your code in its native language, Voodocs translates it for humans.**
 
 ## How It Works
 
-1.  **Install**: Add VooDocs to your project with `npm install -g @voodocs/cli`
+1.  **Install**: Add Voodocs to your project with `npm install -g @voodocs/cli`
 2.  **Instruct**: Run `voodocs instruct` to generate AI instructions for your coding assistant
 3.  **Code**: Your AI assistant (Cursor, Claude Code, etc.) automatically adds `@voodocs` annotations as it writes code
 4.  **Generate**: Run `voodocs generate` to produce:
@@ -30,7 +30,7 @@ npm install -g @voodocs/cli
 
 ### 2. Initialize Your Project
 
-Navigate to your project directory and initialize VooDocs:
+Navigate to your project directory and initialize Voodocs:
 
 ```bash
 voodocs init
@@ -99,7 +99,7 @@ Voodocs uses the **DarkArts language** - a mathematical and logical notation sys
 - **Declarative relationships**: What IS, not what to DO
 - **Conditional reasoning**: Case-based specifications
 
-VooDocs then translates this precise, machine-readable format into natural language documentation that humans can easily understand.
+Voodocs then translates this precise, machine-readable format into natural language documentation that humans can easily understand.
 
 ## Why Voodocs?
 

package/USAGE.md

@@ -247,7 +247,7 @@ function myFunction(x: number): number {
 | `assumptions` | Assumptions made by the module. |
 | `preconditions` | Conditions that must be true before a function is called. |
 | `postconditions` | Conditions that must be true after a function returns. |
-| `invariants` | Conditions that must always be true for a class. |
+| `invariants` | Properties that remain unchanged throughout execution. For functions: conditions that hold during execution. For classes: use `class_invariants` for object state constraints. |
 | `complexity` | Time and space complexity of an algorithm. |
 | `error_cases` | How the function behaves in error scenarios. |
 | `security_model` | Security implications and threat model. |
@@ -268,7 +268,57 @@ The DarkArts language is a formal notation used in annotations. It includes:
 
 ## Examples
 
-See the `examples/` directory for complete examples in Python and TypeScript.
+### Function with Invariants
+
+**Python**:
+```python
+def transfer_funds(from_account, to_account, amount):
+    """@voodocs
+    preconditions: [
+        "from_account.balance >= amount",
+        "amount > 0",
+        "from_account != to_account"
+    ]
+    postconditions: [
+        "from_account.balance = from_account.balance₀ - amount",
+        "to_account.balance = to_account.balance₀ + amount"
+    ]
+    invariants: [
+        "total_balance = from_account.balance + to_account.balance (conservation)",
+        "from_account.balance >= 0",
+        "to_account.balance >= 0"
+    ]
+    complexity: "O(1)"
+    """
+    from_account.balance -= amount
+    to_account.balance += amount
+```
+
+### Class with Invariants
+
+**Python**:
+```python
+class BankAccount:
+    """@voodocs
+    class_invariants: [
+        "balance >= 0 (no overdrafts)",
+        "account_id is unique and immutable"
+    ]
+    """
+    
+    def deposit(self, amount):
+        """@voodocs
+        preconditions: ["amount > 0"]
+        postconditions: ["self.balance = self.balance₀ + amount"]
+        invariants: [
+            "self.balance >= 0 (class invariant maintained)",
+            "self.account_id unchanged"
+        ]
+        """
+        self.balance += amount
+```
+
+See the `examples/` directory for more complete examples in Python and TypeScript.
 
 ---
 

package/cli.py

@@ -17,10 +17,27 @@ import time
 from pathlib import Path
 from functools import wraps
 
-# Add lib to path (resolve symlinks for npm bin)
+# Add lib to path (resolve symlinks for npm/pnpm bin)
 import os
-script_path = Path(os.path.realpath(__file__)).parent
-sys.path.insert(0, str(script_path / "lib"))
+
+# Get the directory containing this script
+# Handle both direct execution and symlinked execution (npm/pnpm global install)
+script_path = Path(__file__)
+if script_path.is_symlink():
+    # Follow the symlink to get the actual package location
+    script_path = Path(os.readlink(script_path))
+    if not script_path.is_absolute():
+        # Relative symlink - resolve relative to the symlink's directory
+        script_path = (Path(__file__).parent / script_path).resolve()
+else:
+    # Not a symlink - use realpath to resolve any relative paths
+    script_path = Path(os.path.realpath(__file__))
+
+# Get the package root directory (where cli.py and lib/ are located)
+package_root = script_path.parent
+
+# Add lib directory to Python path
+sys.path.insert(0, str(package_root / "lib"))
 
 from darkarts.plugins.voodocs.instruction_generator import InstructionGenerator
 from darkarts.plugins.voodocs.documentation_generator import DocumentationGenerator
@@ -120,7 +137,7 @@ Documentation: https://github.com/3vilEnterprises/vooodooo-magic/tree/main/packa
     parser.add_argument(
         "--version",
         action="version",
-        version="VooDocs 0.1.0"
+        version="VooDocs 0.1.2"
     )
     
     subparsers = parser.add_subparsers(dest="command", help="Available commands")
@@ -418,7 +435,7 @@ def cmd_init(args):
         config = {
             "project_name": project_name,
             "language": language,
-            "version": "0.1.0",
+            "version": "0.1.2",
             "output_dir": "./voodocs-output",
             "test_framework": "pytest",
             "api_format": "openapi",

package/examples/test_function_invariants.py

@@ -0,0 +1,134 @@
+"""
+Example demonstrating function-level invariants in VooDocs.
+
+This file shows how to use invariants at the function level to document
+properties that must hold throughout the function's execution.
+"""
+
+
+def transfer_funds(from_account, to_account, amount):
+    """@voodocs
+    preconditions: [
+        "from_account.balance >= amount",
+        "amount > 0",
+        "from_account != to_account"
+    ]
+    postconditions: [
+        "from_account.balance = from_account.balance₀ - amount",
+        "to_account.balance = to_account.balance₀ + amount",
+        "total_balance = from_account.balance + to_account.balance = total_balance₀"
+    ]
+    invariants: [
+        "total_balance = from_account.balance + to_account.balance (conservation of funds)",
+        "from_account.balance >= 0 (no negative balances)",
+        "to_account.balance >= 0 (no negative balances)",
+        "amount remains constant throughout execution"
+    ]
+    side_effects: [
+        "Modifies from_account.balance",
+        "Modifies to_account.balance",
+        "Logs transaction to audit trail"
+    ]
+    complexity: "O(1)"
+    """
+    # Verify preconditions
+    if from_account.balance < amount:
+        raise ValueError("Insufficient funds")
+    if amount <= 0:
+        raise ValueError("Amount must be positive")
+    if from_account == to_account:
+        raise ValueError("Cannot transfer to same account")
+    
+    # Perform transfer (invariants hold throughout)
+    from_account.balance -= amount
+    to_account.balance += amount
+    
+    # Log transaction
+    print(f"Transferred {amount} from {from_account.id} to {to_account.id}")
+
+
+def binary_search(arr, target):
+    """@voodocs
+    preconditions: [
+        "arr is sorted in ascending order",
+        "∀ i, j: 0 ≤ i < j < len(arr) ⇒ arr[i] ≤ arr[j]"
+    ]
+    postconditions: [
+        "result ≥ 0 ⇒ arr[result] = target",
+        "result = -1 ⇒ target ∉ arr"
+    ]
+    invariants: [
+        "0 ≤ left ≤ right < len(arr) (search bounds)",
+        "target ∈ arr ⇒ target ∈ arr[left:right+1] (target in search range)",
+        "arr remains unchanged (no side effects on input)"
+    ]
+    complexity: "O(log n) where n = len(arr)"
+    """
+    left, right = 0, len(arr) - 1
+    
+    while left <= right:
+        mid = (left + right) // 2
+        
+        if arr[mid] == target:
+            return mid
+        elif arr[mid] < target:
+            left = mid + 1
+        else:
+            right = mid - 1
+    
+    return -1
+
+
+class BankAccount:
+    """@voodocs
+    class_invariants: [
+        "balance >= 0 (no overdrafts)",
+        "account_id is unique and immutable",
+        "len(transaction_history) >= 0"
+    ]
+    """
+    
+    def __init__(self, account_id, initial_balance=0):
+        """@voodocs
+        preconditions: [
+            "initial_balance >= 0",
+            "account_id is not None"
+        ]
+        postconditions: [
+            "self.balance = initial_balance",
+            "self.account_id = account_id",
+            "len(self.transaction_history) = 0"
+        ]
+        invariants: [
+            "self.balance >= 0 (established at initialization)"
+        ]
+        """
+        self.account_id = account_id
+        self.balance = initial_balance
+        self.transaction_history = []
+    
+    def deposit(self, amount):
+        """@voodocs
+        preconditions: [
+            "amount > 0"
+        ]
+        postconditions: [
+            "self.balance = self.balance₀ + amount",
+            "len(self.transaction_history) = len(self.transaction_history₀) + 1"
+        ]
+        invariants: [
+            "self.balance >= 0 (class invariant maintained)",
+            "amount remains constant",
+            "self.account_id unchanged"
+        ]
+        side_effects: [
+            "Modifies self.balance",
+            "Appends to self.transaction_history"
+        ]
+        complexity: "O(1)"
+        """
+        if amount <= 0:
+            raise ValueError("Deposit amount must be positive")
+        
+        self.balance += amount
+        self.transaction_history.append(("deposit", amount))

package/lib/darkarts/plugins/voodocs/documentation_generator.py

@@ -567,7 +567,7 @@ class DocumentationGenerator:
         
         # Documentation coverage badge
         total_items = len(parsed.module.classes) + len(parsed.get_all_functions())
-        annotated_items = sum(1 for _ in parsed.module.classes if _.invariants or _.state_transitions)
+        annotated_items = sum(1 for _ in parsed.module.classes if _.class_invariants or _.state_transitions)
         annotated_items += sum(1 for f in parsed.get_all_functions() if f.preconditions or f.postconditions)
         
         if total_items > 0:

package/lib/darkarts/telemetry.py

@@ -0,0 +1,206 @@
+"""
+VooDocs Telemetry Client
+
+Privacy-respecting anonymous telemetry for usage analytics.
+"""
+
+import os
+import sys
+import json
+import uuid
+import platform
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, Any, Optional
+import urllib.request
+import urllib.error
+
+# Supabase configuration
+SUPABASE_URL = os.getenv("VOODOCS_SUPABASE_URL", "https://sjatkayudkbkmipubhfy.supabase.co")
+SUPABASE_ANON_KEY = os.getenv("VOODOCS_SUPABASE_ANON_KEY", "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InNqYXRrYXl1ZGtia21pcHViaGZ5Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NjYxNjE0MTMsImV4cCI6MjA4MTczNzQxM30.Wj3dbokjKPsmWTgbPw77aPnCoZCsE5hrFfIH-R_ErzI")
+
+# VooDocs version
+VERSION = "0.1.2"
+
+class TelemetryClient:
+    """Anonymous telemetry client for VooDocs CLI."""
+    
+    def __init__(self):
+        self.session_id = self._get_or_create_session_id()
+        self.enabled = self._check_if_enabled()
+        self.config_dir = Path.home() / ".voodocs"
+        self.config_file = self.config_dir / "telemetry.json"
+        
+    def _get_or_create_session_id(self) -> str:
+        """Get or create a random session ID."""
+        config_dir = Path.home() / ".voodocs"
+        session_file = config_dir / "session_id"
+        
+        if session_file.exists():
+            try:
+                return session_file.read_text().strip()
+            except:
+                pass
+        
+        # Create new session ID
+        session_id = str(uuid.uuid4())
+        try:
+            config_dir.mkdir(parents=True, exist_ok=True)
+            session_file.write_text(session_id)
+        except:
+            pass  # Fail silently if can't write
+        
+        return session_id
+    
+    def _check_if_enabled(self) -> bool:
+        """Check if telemetry is enabled."""
+        # Check environment variable
+        if os.getenv("VOODOCS_TELEMETRY_DISABLED") == "1":
+            return False
+        
+        # Check config file
+        config_dir = Path.home() / ".voodocs"
+        config_file = config_dir / "telemetry.json"
+        
+        if config_file.exists():
+            try:
+                config = json.loads(config_file.read_text())
+                return config.get("enabled", True)
+            except:
+                pass
+        
+        return True  # Enabled by default
+    
+    def _show_first_run_notice(self):
+        """Show telemetry notice on first run."""
+        notice_file = self.config_dir / ".telemetry_notice_shown"
+        
+        if not notice_file.exists():
+            print("\n" + "="*70)
+            print("📊 VooDocs Telemetry")
+            print("="*70)
+            print("VooDocs collects anonymous usage data to improve the product.")
+            print("No personal information is collected.")
+            print()
+            print("To disable telemetry:")
+            print("  voodocs telemetry disable")
+            print()
+            print("Learn more: https://voodocs.com/privacy")
+            print("="*70 + "\n")
+            
+            try:
+                self.config_dir.mkdir(parents=True, exist_ok=True)
+                notice_file.touch()
+            except:
+                pass  # Fail silently
+    
+    def track_event(self, event_type: str, data: Optional[Dict[str, Any]] = None):
+        """
+        Track a telemetry event.
+        
+        Args:
+            event_type: Type of event (command_executed, etc.)
+            data: Additional event data
+        """
+        if not self.enabled:
+            return
+        
+        if not SUPABASE_URL or not SUPABASE_ANON_KEY:
+            return  # Silently skip if not configured
+        
+        # Show first-run notice
+        if event_type == "command_executed":
+            self._show_first_run_notice()
+        
+        event = {
+            "event_type": event_type,
+            "session_id": self.session_id,
+            "version": VERSION,
+            "platform": platform.system().lower(),
+            "python_version": f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
+            **(data or {})
+        }
+        
+        # Send synchronously with short timeout (CLI-friendly)
+        self._send_event_sync(event)
+    
+    def _send_event_sync(self, event: Dict[str, Any]):
+        """Send event to Supabase synchronously with timeout."""
+        try:
+            url = f"{SUPABASE_URL}/rest/v1/telemetry_events"
+            headers = {
+                "apikey": SUPABASE_ANON_KEY,
+                "Authorization": f"Bearer {SUPABASE_ANON_KEY}",
+                "Content-Type": "application/json",
+                "Prefer": "return=minimal"
+            }
+            
+            data = json.dumps(event).encode("utf-8")
+            req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+            
+            # Short timeout - fail fast if network issue
+            urllib.request.urlopen(req, timeout=2)
+        except:
+            pass  # Fail silently - telemetry should never break the CLI
+    
+    def enable(self):
+        """Enable telemetry."""
+        try:
+            self.config_dir.mkdir(parents=True, exist_ok=True)
+            config = {"enabled": True}
+            self.config_file.write_text(json.dumps(config, indent=2))
+            self.enabled = True
+            print("✓ Telemetry enabled")
+        except Exception as e:
+            print(f"✗ Failed to enable telemetry: {e}")
+    
+    def disable(self):
+        """Disable telemetry."""
+        try:
+            self.config_dir.mkdir(parents=True, exist_ok=True)
+            config = {"enabled": False}
+            self.config_file.write_text(json.dumps(config, indent=2))
+            self.enabled = False
+            print("✓ Telemetry disabled")
+        except Exception as e:
+            print(f"✗ Failed to disable telemetry: {e}")
+    
+    def status(self):
+        """Show telemetry status."""
+        status = "enabled" if self.enabled else "disabled"
+        print(f"Telemetry: {status}")
+        print(f"Session ID: {self.session_id}")
+        
+        if self.enabled:
+            print("\nTo disable: voodocs telemetry disable")
+        else:
+            print("\nTo enable: voodocs telemetry enable")
+
+
+# Global telemetry client instance
+_telemetry_client: Optional[TelemetryClient] = None
+
+def get_telemetry_client() -> TelemetryClient:
+    """Get the global telemetry client instance."""
+    global _telemetry_client
+    if _telemetry_client is None:
+        _telemetry_client = TelemetryClient()
+    return _telemetry_client
+
+def track_command(command: str, success: bool, duration_ms: int, **kwargs):
+    """
+    Track a command execution.
+    
+    Args:
+        command: Command name (init, generate, etc.)
+        success: Whether command succeeded
+        duration_ms: Command duration in milliseconds
+        **kwargs: Additional event data
+    """
+    client = get_telemetry_client()
+    client.track_event("command_executed", {
+        "command": command,
+        "success": success,
+        "duration_ms": duration_ms,
+        **kwargs
+    })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voodocs/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "AI-Native Documentation System - Generate docs, tests, and API specs from @voodocs annotations using the DarkArts language",
   "main": "cli.py",
   "bin": {
@@ -48,6 +48,7 @@
     "lib/darkarts/annotations/",
     "lib/darkarts/core/",
     "lib/darkarts/exceptions.py",
+    "lib/darkarts/telemetry.py",
     "lib/darkarts/parsers/typescript/dist/",
     "lib/darkarts/parsers/typescript/src/",
     "lib/darkarts/parsers/typescript/package.json",
@@ -60,6 +61,8 @@
     "README.md",
     "LICENSE",
     "USAGE.md",
+    "PRIVACY.md",
+    "CHANGELOG.md",
     "requirements.txt"
   ],
   "os": [