@voodocs/cli 2.5.2 → 3.0.0

package/lib/darkarts/context/ai_instructions.py

@@ -1,15 +1,15 @@
 """@darkarts
-⊢ai-instructions:ctx.templates
+⊢{ai-instructions:ctx.templates}
 ∂{typing}
-⚠{ai:cursor∨claude,project:voodocs-enabled,templates:markdown}
-⊨{∀gen→valid-markdown,∀gen→include-cmds,∀gen→teach-best-practices}
+⚠{ai:cursor∨claude,project:darkarts-enabled,templates:markdown}
+⊨{∀gen→valid-markdown,∀gen→include-cmds,∀gen→teach-v3-notation}
 🔒{no-implications}
 ⚡{O(1)|template-generation}
 
-AI instruction templates for VooDocs Context System.
+AI instruction templates for DarkArts v3.0.0 Context System.
 
 This module provides templates for generating AI assistant instructions
-that teach them how to use the VooDocs context system effectively.
+that teach them how to use the DarkArts mathematical notation system.
 """
 
 from typing import Dict, Optional
@@ -17,7 +17,7 @@ from typing import Dict, Optional
 
 def generate_cursorrules(project_name: str, project_purpose: str) -> str:
     """
-    Generate .cursorrules content for Cursor AI.
+    Generate .cursorrules content for Cursor AI with DarkArts v3.0.0.
     
     Args:
         project_name: Name of the project
@@ -26,716 +26,530 @@ def generate_cursorrules(project_name: str, project_purpose: str) -> str:
     Returns:
         Content for .cursorrules file
     """
-    return f"""# {project_name} - VooDocs Context System
+    return f"""# {project_name} - DarkArts v3.0.0
 
 ## Project Overview
 {project_purpose}
 
-## VooDocs Context System (v0.2.0+)
+## DarkArts v3.0.0 - AI-Native Mathematical Documentation
 
-This project uses VooDocs with the Context System for intelligent documentation and validation.
+This project uses **DarkArts v3.0.0**, an AI-native mathematical notation system for code documentation.
 
-### Context File Location
-- **Context file**: `.voodocs.context` (YAML format)
-- **Auto-generated**: From @voodocs annotations in code
-- **Version controlled**: Track context changes over time
+**Key Philosophy**: DarkArts is **for AI, not humans**. It uses mathematical symbols for maximum token efficiency and AI comprehension.
 
-### Essential Commands
+---
 
-#### Before Starting Work
-```bash
-# Read the project context to understand architecture, invariants, and assumptions
-voodocs context view
-```
+## Mathematical Notation Reference
+
+### Core Symbols
+
+| Symbol | Meaning | Example |
+|--------|---------|---------|
+| `⊢` | Purpose | `⊢{{u auth svc w/ JWT tok gen}}` |
+| `∂` | Dependencies | `∂{{bcrypt,jsonwebtoken,db}}` |
+| `⚠` | Assumptions | `⚠{{db conn established,u authenticated}}` |
+| `⊳` | Preconditions | `⊳{{id:uuid,pw≥8}}` |
+| `⊲` | Postconditions | `⊲{{ret JWT tok|null}}` |
+| `⊨` | Invariants | `⊨{{no db mod,no pw log}}` |
+| `⚡` | Complexity | `⚡{{O(n)|linear-search}}` |
+| `🔒` | Security | `🔒{{pw:hash,tok:enc}}` |
+
+### New Symbols (v3.0.0)
+
+| Symbol | Meaning | Example |
+|--------|---------|---------|
+| `⇄` | Bidirectional | `⇄{{enc↔dec,compress↔decompress}}` |
+| `⊕` | Side Effects | `⊕{{writes db,sends email,logs event}}` |
+| `⊗` | Forbidden | `⊗{{no pw log,no api key exposure}}` |
+| `≈` | Approximation | `≈{{±0.001,~100ms}}` |
+| `∴` | Consequence | `∴{{fail→null,invalid→err}}` |
+| `∀` | Universal | `∀{{users have email,ids are unique}}` |
+| `∃` | Existential | `∃{{admin required,config file exists}}` |
 
-#### During Development
-```bash
-# Add @voodocs annotations to your code (see format below)
-# Then auto-generate context from annotations
-voodocs context generate --update
+---
 
-# Check if code respects documented invariants
-voodocs context check
+## Pattern Shortcuts (v3.0.0)
 
-# Query specific information
-voodocs context query "search term" --section invariants
-```
+### Type Patterns
 
-#### Before Committing
-```bash
-# Validate context and check invariants
-voodocs context validate --check-invariants
+Use `:pattern` for common validations:
 
-# Update context version with description
-voodocs context update --description "Brief description of changes"
-```
+| Pattern | Meaning | Example |
+|---------|---------|---------|
+| `:uuid` | Valid UUID | `id:uuid` |
+| `:email` | Valid email | `email:email` |
+| `:url` | Valid URL | `url:url` |
+| `:json` | Valid JSON | `data:json` |
+| `:jwt` | Valid JWT | `tok:jwt` |
+| `:hash` | Hash format | `pw:hash` |
+| `:enc` | Encrypted | `data:enc` |
 
-#### Architecture & Documentation
-```bash
-# Generate architecture diagrams
-voodocs context diagram --type modules --output docs/architecture.mmd
+### Numeric Patterns
 
-# View full context as Markdown
-voodocs context view > docs/CONTEXT.md
-```
+| Pattern | Meaning | Example |
+|---------|---------|---------|
+| `≥N` | Greater or equal | `pw≥8` |
+| `≤N` | Less or equal | `age≤120` |
+| `>N` | Greater than | `score>0` |
+| `<N` | Less than | `retry<5` |
+| `[N,M]` | Range | `age[18,65]` |
+| `∈{{...}}` | Set membership | `status∈{{active,pending}}` |
 
-### @voodocs Annotation Format
+---
 
-Add to Python/TypeScript/JavaScript files:
+## Enhanced Abbreviations (v3.0.0)
+
+### Core Terms
+
+| Abbrev | Full | Abbrev | Full |
+|--------|------|--------|------|
+| `u` | user | `pw` | password |
+| `auth` | authentication | `tok` | token |
+| `svc` | service | `db` | database |
+| `req` | request | `res` | response |
+| `ret` | return | `err` | error |
+| `val` | validate | `gen` | generate |
+| `proc` | process | `exec` | execute |
+| `cfg` | config | `env` | environment |
+
+### Web/API Terms
+
+| Abbrev | Full | Abbrev | Full |
+|--------|------|--------|------|
+| `ep` | endpoint | `rt` | route |
+| `mw` | middleware | `hdlr` | handler |
+| `ctrl` | controller | `mdl` | model |
+| `svc` | service | `repo` | repository |
+| `dto` | data transfer object | `api` | API |
+
+### Security Terms
+
+| Abbrev | Full | Abbrev | Full |
+|--------|------|--------|------|
+| `enc` | encryption | `dec` | decryption |
+| `hash` | hashing | `sig` | signature |
+| `cert` | certificate | `perm` | permission |
+| `role` | role | `sess` | session |
+
+### Data Terms
+
+| Abbrev | Full | Abbrev | Full |
+|--------|------|--------|------|
+| `tbl` | table | `col` | column |
+| `rec` | record | `idx` | index |
+| `pk` | primary key | `fk` | foreign key |
+| `qry` | query | `txn` | transaction |
 
-**Python:**
-```python
-\"\"\"@voodocs
-module_purpose: "Brief description of what this module does"
-dependencies: [
-    "other-module: What it provides",
-    "external-lib: Why we use it"
-]
-assumptions: [
-    "Database connection is established",
-    "User is authenticated",
-    "Environment variables are set"
-]
-invariants: [
-    "All user input must be validated",
-    "Passwords must be hashed before storage",
-    "API keys must never be logged"
-]
-security_model: "Brief description of security approach"
-performance_notes: "Expected performance characteristics"
-\"\"\"
-```
+---
+
+## Complete Example
 
 **TypeScript/JavaScript:**
 ```typescript
-/**@voodocs
-module_purpose: "Brief description of what this module does"
-dependencies: [
-    "react: UI framework",
-    "axios: HTTP client"
-]
-assumptions: [
-    "API endpoint is available",
-    "User has valid token"
-]
-invariants: [
-    "All API responses must be validated",
-    "Errors must be handled gracefully"
-]
+/**@darkarts
+⊢{{u auth svc w/ JWT tok gen}}
+∂{{bcrypt,jsonwebtoken,db}}
+⚠{{db conn established,u tbl exists}}
+⊳{{email:email,pw≥8}}
+⊲{{ret JWT tok|null}}
+⊨{{no pw log,no db mod}}
+⊕{{logs auth attempt,updates last_login}}
+⊗{{no pw in logs,no tok in logs}}
+🔒{{pw:hash,tok:enc,sess:secure}}
+⚡{{O(1)|hash-lookup}}
+⇄{{login↔logout}}
+∴{{invalid→null,expired→refresh}}
+∀{{users have unique email}}
+∃{{admin role required for setup}}
+≈{{~50ms response time}}
 */
+async function authenticateUser(email, password) {{
+  // Implementation
+}}
 ```
 
-### Context-Aware Development Workflow
-
-1. **Understand Context**: Always run `voodocs context view` before making changes
-2. **Check Invariants**: Ensure you understand the global invariants that must be respected
-3. **Add Annotations**: Document your code with @voodocs annotations as you write
-4. **Update Context**: Run `voodocs context generate --update` after adding features
-5. **Validate**: Run `voodocs context check` to ensure invariants are respected
-6. **Update Version**: Use `voodocs context update` to track context changes
-
-### What to Document
-
-**Module Purpose**: What this module does and why it exists
-**Dependencies**: What this module depends on (internal and external)
-**Assumptions**: What must be true for this module to work correctly
-**Invariants**: Rules that must always hold (security, data integrity, etc.)
-**Security Model**: How this module handles security concerns
-**Performance Notes**: Expected performance characteristics and bottlenecks
-
-### Context Sections
-
-The `.voodocs.context` file contains:
-
-- **Project**: Name, purpose, domain
-- **Versioning**: Code version, context version, last updated
-- **Invariants**: Global rules that must always hold
-- **Assumptions**: System-wide assumptions
-- **Architecture**: Modules, decisions, patterns
-- **Critical Paths**: Important workflows
-- **Dependencies**: External libraries and tools
-- **Known Issues**: Bugs and limitations
-- **Change History**: Version tracking with Git integration
+**Python:**
+```python
+\"\"\"@darkarts
+⊢{{u auth svc w/ JWT tok gen}}
+∂{{bcrypt,jsonwebtoken,db}}
+⚠{{db conn established,u tbl exists}}
+⊳{{email:email,pw≥8}}
+⊲{{ret JWT tok|None}}
+⊨{{no pw log,no db mod}}
+⊕{{logs auth attempt,updates last_login}}
+⊗{{no pw in logs,no tok in logs}}
+🔒{{pw:hash,tok:enc,sess:secure}}
+⚡{{O(1)|hash-lookup}}
+⇄{{login↔logout}}
+∴{{invalid→None,expired→refresh}}
+∀{{users have unique email}}
+∃{{admin role required for setup}}
+≈{{~50ms response time}}
+\"\"\"
+async def authenticate_user(email: str, password: str):
+    # Implementation
+    pass
+```
 
-### Best Practices
+---
 
-1. **Read context first**: Always check context before making changes
-2. **Document as you code**: Add @voodocs annotations while writing code
-3. **Keep invariants clear**: Make invariants specific and testable
-4. **Update regularly**: Run `voodocs context generate --update` frequently
-5. **Validate before commit**: Run `voodocs context check` before committing
-6. **Track changes**: Use `voodocs context update` to document what changed
+## Token Efficiency
 
-### CI/CD Integration
+**Traditional comment:** 140 tokens  
+**DarkArts v3.0.0:** 30 tokens  
+**Reduction:** 79% 🎯
 
-The context system can be integrated into CI/CD pipelines:
+---
 
-```yaml
-# GitHub Actions example
-- name: Validate Context
-  run: voodocs context validate --check-invariants
+## Context System Commands
 
-- name: Check Invariants
-  run: voodocs context check --format json
+### Before Starting Work
+```bash
+# Read project context to understand architecture
+voodocs context view
 ```
 
-### Querying Context
+### During Development
+```bash
+# Add @darkarts annotations to your code
+# Then update context from annotations
+voodocs context generate --update
 
-Search for specific information:
+# Check if code respects invariants
+voodocs context check
+```
 
+### Before Committing
 ```bash
-# Find security-related invariants
-voodocs context query "security" --section invariants
-
-# Find authentication assumptions
-voodocs context query "auth" --section assumptions --format json
+# Validate context and check invariants
+voodocs context validate --check-invariants
 
-# Search all sections
-voodocs context query "database"
+# Update context version
+voodocs context update --description "Brief description of changes"
 ```
 
-### Architecture Diagrams
+---
 
-Generate visual documentation:
+## Best Practices
 
-```bash
-# Module dependency diagram
-voodocs context diagram --type modules
+1. **Use mathematical notation** - It's for AI, not humans
+2. **Use pattern shortcuts** - `:uuid`, `≥8`, etc.
+3. **Use abbreviations** - `u`, `auth`, `svc`, etc.
+4. **Be concise** - Maximum token efficiency
+5. **Be precise** - Mathematical symbols have exact meanings
+6. **Document invariants** - Rules that must always hold
+7. **Document side effects** - What changes state
+8. **Document forbidden operations** - What must never happen
 
-# External dependencies
-voodocs context diagram --type dependencies
+---
 
-# Critical path workflows
-voodocs context diagram --type flow
+## What to Document
 
-# Generate all diagrams
-voodocs context diagram --type all --output docs/arch
-```
+**Purpose (`⊢`)**: What this function/module does  
+**Dependencies (`∂`)**: What it depends on  
+**Assumptions (`⚠`)**: What must be true  
+**Preconditions (`⊳`)**: Input requirements  
+**Postconditions (`⊲`)**: Output guarantees  
+**Invariants (`⊨`)**: Rules that always hold  
+**Side Effects (`⊕`)**: What it modifies  
+**Forbidden (`⊗`)**: What it must not do  
+**Security (`🔒`)**: Security measures  
+**Complexity (`⚡`)**: Time/space complexity  
 
-### Remember
+---
 
-- The context system is your source of truth for project understanding
-- Invariants are enforced rules - respect them
-- Assumptions are documented expectations - validate them
-- Context is version-controlled - track changes
-- Always check context before making architectural decisions
+## Remember
+
+- **DarkArts is for AI, not humans** - Use mathematical notation
+- **79% token reduction** - Massive efficiency gains
+- **Pattern shortcuts** - Use `:uuid`, `≥8`, etc.
+- **Enhanced abbreviations** - 200+ terms available
+- **New symbols** - ⇄, ⊕, ⊗, ≈, ∴, ∀, ∃
 
 ---
 
-**VooDocs Context System** - AI-native documentation that keeps code and context in sync.
+**DarkArts v3.0.0** - The AI-Native Mathematical Language for Code
+
+*Designed by AI, for AI.*
 """
 
 
-def generate_context_guide(project_name: str, project_purpose: str) -> str:
+def generate_claude_instructions(project_name: str, project_purpose: str) -> str:
     """
-    Generate comprehensive context guide for AI assistants.
+    Generate instructions for Claude AI with DarkArts v3.0.0.
     
     Args:
         project_name: Name of the project
         project_purpose: Brief purpose of the project
     
     Returns:
-        Content for VOODOCS_CONTEXT_GUIDE.md file
+        Instructions for Claude
     """
-    return f"""# VooDocs Context System Guide - {project_name}
+    return f"""# DarkArts v3.0.0 Instructions for Claude
 
-## Project Overview
-
-**Name**: {project_name}  
+## Project: {project_name}
 **Purpose**: {project_purpose}
 
-This project uses the **VooDocs Context System** (v0.2.0+) for intelligent documentation, validation, and architecture management.
-
 ---
 
-## What is the Context System?
+## Your Role
 
-The VooDocs Context System is an AI-native documentation framework that:
+You are working on a codebase that uses **DarkArts v3.0.0**, an AI-native mathematical notation system for code documentation.
 
-1. **Auto-generates** project context from code annotations
-2. **Validates** code against documented invariants
-3. **Tracks** changes with version control integration
-4. **Visualizes** architecture with auto-generated diagrams
-5. **Queries** like a database for instant information
+**Key Principle**: DarkArts is designed **for AI, not humans**. Use mathematical symbols for maximum token efficiency and precision.
 
 ---
 
-## Quick Start
-
-### 1. View Current Context
-
-```bash
-voodocs context view
-```
+## Core Symbols You Must Use
 
-This shows you:
-- Project purpose and domain
-- Global invariants (rules that must hold)
-- System assumptions
-- Architecture and modules
-- Dependencies
-- Known issues
+When documenting code, use these mathematical symbols:
 
-**Do this before making any changes!**
+- `⊢{{...}}` - Purpose (what this does)
+- `∂{{...}}` - Dependencies (what it needs)
+- `⚠{{...}}` - Assumptions (what must be true)
+- `⊳{{...}}` - Preconditions (input requirements)
+- `⊲{{...}}` - Postconditions (output guarantees)
+- `⊨{{...}}` - Invariants (rules that always hold)
+- `⚡{{...}}` - Complexity (time/space)
+- `🔒{{...}}` - Security (security measures)
 
-### 2. Check Invariants
+**New in v3.0.0:**
+- `⇄{{...}}` - Bidirectional relationships
+- `⊕{{...}}` - Side effects (state modifications)
+- `⊗{{...}}` - Forbidden operations (must not do)
+- `≈{{...}}` - Approximations (acceptable error)
+- `∴{{...}}` - Consequences (logical implications)
+- `∀{{...}}` - Universal properties (for all)
+- `∃{{...}}` - Existential properties (must exist)
 
-```bash
-voodocs context check
-```
+---
 
-This validates that the code respects all documented invariants:
-- Password hashing
-- API key protection
-- SQL injection prevention
-- Input validation
-- Error handling
-- And more...
+## Pattern Shortcuts
 
-### 3. Update Context
+Use these shortcuts for common validations:
 
-```bash
-voodocs context generate --update
-```
+**Type patterns:**
+- `id:uuid` - Valid UUID
+- `email:email` - Valid email
+- `url:url` - Valid URL
+- `data:json` - Valid JSON
+- `tok:jwt` - Valid JWT token
+- `pw:hash` - Hashed password
+- `data:enc` - Encrypted data
 
-This scans the codebase for @voodocs annotations and updates the context file.
+**Numeric patterns:**
+- `pw≥8` - Password at least 8 characters
+- `age[18,65]` - Age between 18 and 65
+- `retry<5` - Retry count less than 5
+- `status∈{{active,pending}}` - Status in set
 
 ---
 
-## The `.voodocs.context` File
-
-**Location**: `./.voodocs.context`  
-**Format**: YAML  
-**Purpose**: Single source of truth for project understanding
-
-### Structure
-
-```yaml
-project:
-  name: "{project_name}"
-  purpose: "{project_purpose}"
-  domain: "Application domain"
-
-versioning:
-  code_version: "1.0.0"
-  context_version: "1.0"
-  last_updated: "2025-12-19"
-
-invariants:
-  global:
-    - "All passwords must be hashed before storage"
-    - "API keys must never be logged"
-    - "All database queries must use parameterized statements"
-
-assumptions:
-  - "Database connection is established at startup"
-  - "User authentication is handled by auth service"
-
-architecture:
-  modules:
-    module-name:
-      purpose: "What this module does"
-      dependencies: ["other-module"]
-
-dependencies:
-  external:
-    - name: "library-name"
-      version: "1.0.0"
-      purpose: "Why we use it"
-
-critical_paths:
-  - name: "User Login Flow"
-    steps:
-      - "User enters credentials"
-      - "Credentials validated"
-      - "JWT token generated"
-      - "Token returned to client"
-```
+## Enhanced Abbreviations
 
----
+Use these abbreviations for maximum token efficiency:
 
-## @voodocs Annotations
+**Core:** `u` (user), `pw` (password), `auth` (authentication), `tok` (token), `svc` (service), `db` (database), `req` (request), `res` (response), `ret` (return), `err` (error)
 
-### Purpose
+**Web/API:** `ep` (endpoint), `rt` (route), `mw` (middleware), `hdlr` (handler), `ctrl` (controller), `api` (API)
 
-Annotations are **structured comments** that document:
-- What a module does
-- What it depends on
-- What assumptions it makes
-- What invariants it enforces
+**Security:** `enc` (encryption), `dec` (decryption), `hash` (hashing), `sig` (signature), `cert` (certificate), `perm` (permission)
 
-### Format
+**Data:** `tbl` (table), `col` (column), `rec` (record), `idx` (index), `qry` (query), `txn` (transaction)
 
-**Python:**
-```python
-\"\"\"@voodocs
-module_purpose: "User authentication and session management"
-dependencies: [
-    "bcrypt: Password hashing",
-    "jwt: Token generation",
-    "database: User storage"
-]
-assumptions: [
-    "Database connection is available",
-    "Redis is running for session storage"
-]
-invariants: [
-    "Passwords must be hashed with bcrypt",
-    "Sessions must expire after 24 hours",
-    "Failed login attempts must be rate-limited"
-]
-security_model: "Passwords hashed with bcrypt (cost 12), JWTs expire in 24h, rate limiting on failed attempts"
-performance_notes: "O(1) for session lookup (Redis), O(log n) for user lookup (indexed database)"
-\"\"\"
+---
 
-def authenticate_user(username: str, password: str) -> Optional[str]:
-    # Implementation
-    pass
-```
+## Example Annotation
 
-**TypeScript:**
 ```typescript
-/**@voodocs
-module_purpose: "API client for backend communication"
-dependencies: [
-    "axios: HTTP client",
-    "zod: Response validation"
-]
-assumptions: [
-    "API endpoint is reachable",
-    "User has valid authentication token"
-]
-invariants: [
-    "All API responses must be validated",
-    "Network errors must be handled gracefully",
-    "Retry logic must use exponential backoff"
-]
+/**@darkarts
+⊢{{u auth svc w/ JWT tok gen}}
+∂{{bcrypt,jsonwebtoken,db}}
+⚠{{db conn established,u tbl exists}}
+⊳{{email:email,pw≥8}}
+⊲{{ret JWT tok|null}}
+⊨{{no pw log,no db mod}}
+⊕{{logs auth attempt,updates last_login}}
+⊗{{no pw in logs,no tok in logs}}
+🔒{{pw:hash,tok:enc,sess:secure}}
+⚡{{O(1)|hash-lookup}}
+⇄{{login↔logout}}
+∴{{invalid→null,expired→refresh}}
+∀{{users have unique email}}
+∃{{admin role required}}
+≈{{~50ms}}
 */
-
-export class ApiClient {{
-    // Implementation
+async function authenticateUser(email, password) {{
+  // Implementation
 }}
 ```
 
-### Fields
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `module_purpose` | Yes | Brief description of what this module does |
-| `dependencies` | No | List of dependencies (internal and external) |
-| `assumptions` | No | What must be true for this module to work |
-| `invariants` | No | Rules that must always hold |
-| `security_model` | No | How security is handled |
-| `performance_notes` | No | Expected performance characteristics |
-
 ---
 
-## Command Reference
-
-### Context Management
-
-| Command | Purpose |
-|---------|---------|
-| `voodocs context init` | Initialize context file |
-| `voodocs context view` | View context as Markdown |
-| `voodocs context status` | Show context status |
-
-### Auto-Generation
-
-| Command | Purpose |
-|---------|---------|
-| `voodocs context generate` | Generate context from code |
-| `voodocs context generate --update` | Update existing context |
-
-### Validation
-
-| Command | Purpose |
-|---------|---------|
-| `voodocs context validate` | Validate context file |
-| `voodocs context validate --check-invariants` | Validate + check code |
-| `voodocs context check` | Check code against invariants |
-| `voodocs context check --format json` | JSON output for CI/CD |
-
-### Querying
-
-| Command | Purpose |
-|---------|---------|
-| `voodocs context query "term"` | Search all sections |
-| `voodocs context query "term" --section invariants` | Search specific section |
-| `voodocs context query "term" --format json` | JSON output |
-
-### Versioning
-
-| Command | Purpose |
-|---------|---------|
-| `voodocs context update` | Update context version |
-| `voodocs context sync` | Sync with code version |
-| `voodocs context history` | Show version history |
-| `voodocs context diff v1 v2` | Compare versions |
+## Your Tasks
 
-### Visualization
-
-| Command | Purpose |
-|---------|---------|
-| `voodocs context diagram --type modules` | Module diagram |
-| `voodocs context diagram --type dependencies` | Dependency diagram |
-| `voodocs context diagram --type flow` | Flow diagram |
-| `voodocs context diagram --type all` | All diagrams |
+1. **When writing new code**: Add @darkarts annotations using mathematical notation
+2. **When modifying code**: Update existing @darkarts annotations
+3. **When reviewing code**: Check that annotations are accurate and complete
+4. **When documenting**: Use pattern shortcuts and abbreviations for maximum efficiency
 
 ---
 
-## Development Workflow
-
-### 1. Before Starting Work
-
-```bash
-# Read the context
-voodocs context view
-
-# Check current status
-voodocs context status
-
-# Validate everything
-voodocs context validate --check-invariants
-```
-
-### 2. During Development
+## Token Efficiency Goal
 
-```bash
-# Add @voodocs annotations to your code
-# (See annotation format above)
-
-# Update context from annotations
-voodocs context generate --update
-
-# Check if code respects invariants
-voodocs context check
-```
-
-### 3. Before Committing
-
-```bash
-# Final validation
-voodocs context validate --check-invariants
-
-# Update context version
-voodocs context update --description "Added user authentication module"
-
-# Generate updated diagrams
-voodocs context diagram --type all --output docs/architecture
-```
-
-### 4. During Code Review
-
-```bash
-# Compare context versions
-voodocs context diff v1.0 v1.1
-
-# Check specific invariant
-voodocs context check --invariant "password"
-
-# Query for specific information
-voodocs context query "authentication" --section assumptions
-```
+- Traditional comment: ~140 tokens
+- DarkArts v3.0.0: ~30 tokens
+- **Target: 79% reduction**
 
 ---
 
-## Invariant Checking
+## Commands Available
 
-### What Are Invariants?
+- `voodocs context view` - View project context
+- `voodocs context check` - Check invariants
+- `voodocs validate` - Validate annotations
+- `voodocs companion` - Generate human-readable docs
 
-Invariants are **rules that must always hold**. Examples:
-- "All passwords must be hashed before storage"
-- "API keys must never be logged"
-- "All database queries must use parameterized statements"
-
-### How It Works
-
-The invariant checker uses **pattern-based detection** to find violations:
-
-```bash
-voodocs context check
-```
-
-**Output:**
-```
-✅ All passwords must be hashed before storage
-   No violations found
-
-❌ API keys must never be logged
-   Found 2 potential violation(s):
-   
-   📍 src/auth.py:45
-      logger.info(f"Using API key: {{api_key}}")
-      → API keys/secrets should not be logged
-```
+---
 
-### Supported Patterns
+## Remember
 
-- Password security (hashing detection)
-- API key protection (logging detection)
-- SQL injection prevention (parameterized queries)
-- Input validation
-- Null/None checking
-- Error handling
+- **Use mathematical symbols** - Not English words
+- **Use pattern shortcuts** - `:uuid`, `≥8`, etc.
+- **Use abbreviations** - `u`, `auth`, `svc`, etc.
+- **Be concise** - Maximum token efficiency
+- **Be precise** - Mathematical symbols have exact meanings
 
 ---
 
-## Architecture Diagrams
-
-### Generate Diagrams
+**DarkArts v3.0.0** - Designed by AI, for AI.
+"""
 
-```bash
-# Module dependency diagram
-voodocs context diagram --type modules --output architecture.mmd
 
-# External dependencies
-voodocs context diagram --type dependencies --output dependencies.mmd
+def generate_default_instructions() -> str:
+    """
+    Generate default DarkArts v3.0.0 instructions for any AI.
+    
+    Returns:
+        General instructions for AI assistants
+    """
+    return """# DarkArts v3.0.0 - AI Assistant Instructions
 
-# Critical path workflows
-voodocs context diagram --type flow --output flows.mmd
-```
+## Overview
 
-### Viewing Diagrams
+You are working with **DarkArts v3.0.0**, an AI-native mathematical notation system for code documentation.
 
-The diagrams are generated in **Mermaid** format. View them:
-- Copy to [Mermaid Live Editor](https://mermaid.live)
-- Use VS Code with Mermaid extension
-- Render in GitHub (supports Mermaid in markdown)
+**Philosophy**: DarkArts is designed **for AI, not humans**. It uses mathematical symbols for maximum token efficiency (79% reduction vs traditional comments).
 
 ---
 
-## CI/CD Integration
-
-### GitHub Actions
-
-```yaml
-name: Context Validation
-
-on: [push, pull_request]
-
-jobs:
-  validate:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      
-      - name: Install VooDocs
-        run: npm install -g @voodocs/cli
-      
-      - name: Validate Context
-        run: voodocs context validate --check-invariants
-      
-      - name: Check Invariants
-        run: voodocs context check --format json > violations.json
-      
-      - name: Upload Report
-        uses: actions/upload-artifact@v2
-        with:
-          name: context-report
-          path: violations.json
-```
+## Core Symbols
+
+| Symbol | Meaning | Usage |
+|--------|---------|-------|
+| `⊢{...}` | Purpose | What this does |
+| `∂{...}` | Dependencies | What it needs |
+| `⚠{...}` | Assumptions | What must be true |
+| `⊳{...}` | Preconditions | Input requirements |
+| `⊲{...}` | Postconditions | Output guarantees |
+| `⊨{...}` | Invariants | Rules that always hold |
+| `⚡{...}` | Complexity | Time/space complexity |
+| `🔒{...}` | Security | Security measures |
+
+**New in v3.0.0:**
+
+| Symbol | Meaning | Usage |
+|--------|---------|-------|
+| `⇄{...}` | Bidirectional | Reversible operations |
+| `⊕{...}` | Side Effects | State modifications |
+| `⊗{...}` | Forbidden | Must not do |
+| `≈{...}` | Approximation | Acceptable error |
+| `∴{...}` | Consequence | Logical implications |
+| `∀{...}` | Universal | For all elements |
+| `∃{...}` | Existential | Must exist |
 
 ---
 
-## Best Practices
-
-### 1. Read Context First
-Always run `voodocs context view` before making changes.
+## Pattern Shortcuts
 
-### 2. Document As You Code
-Add @voodocs annotations while writing code, not after.
+**Type patterns:**
+- `:uuid`, `:email`, `:url`, `:json`, `:jwt`, `:hash`, `:enc`
 
-### 3. Keep Invariants Specific
-❌ Bad: "Data must be valid"  
-✅ Good: "All user input must be validated using Zod schemas"
+**Numeric patterns:**
+- `≥N`, `≤N`, `>N`, `<N`, `[N,M]`, `∈{...}`
 
-### 4. Update Regularly
-Run `voodocs context generate --update` frequently during development.
+**Examples:**
+- `id:uuid` - ID must be valid UUID
+- `pw≥8` - Password at least 8 characters
+- `age[18,65]` - Age between 18 and 65
 
-### 5. Validate Before Commit
-Always run `voodocs context check` before committing.
+---
 
-### 6. Track Changes
-Use `voodocs context update` to document what changed and why.
+## Abbreviations
 
-### 7. Query for Understanding
-Use `voodocs context query` to quickly find information.
+Use these for maximum token efficiency:
 
-### 8. Generate Diagrams
-Keep architecture diagrams up-to-date with `voodocs context diagram`.
+**Core:** `u`, `pw`, `auth`, `tok`, `svc`, `db`, `req`, `res`, `ret`, `err`  
+**Web:** `ep`, `rt`, `mw`, `hdlr`, `ctrl`, `api`  
+**Security:** `enc`, `dec`, `hash`, `sig`, `cert`, `perm`  
+**Data:** `tbl`, `col`, `rec`, `idx`, `qry`, `txn`
 
 ---
 
-## Troubleshooting
-
-### "No modules found in context"
-
-**Problem**: Trying to generate module diagram but no modules defined.
-
-**Solution**: Add modules to `.voodocs.context`:
-```yaml
-architecture:
-  modules:
-    module-name:
-      purpose: "What it does"
-      dependencies: []
+## Example
+
+```javascript
+/**@darkarts
+⊢{u auth svc w/ JWT tok gen}
+∂{bcrypt,jsonwebtoken,db}
+⊳{email:email,pw≥8}
+⊲{ret JWT tok|null}
+⊨{no pw log}
+⊕{logs auth,updates last_login}
+⊗{no pw in logs}
+🔒{pw:hash,tok:enc}
+⚡{O(1)}
+*/
+async function authenticateUser(email, password) {
+  // Implementation
+}
 ```
 
-Or add `module_purpose` to @voodocs annotations and regenerate.
-
-### "Invariant violations found"
-
-**Problem**: Code doesn't respect documented invariants.
-
-**Solution**: 
-1. Review the violation report
-2. Fix the code to respect the invariant
-3. Or update the invariant if it's incorrect
-
-### "Context file not found"
-
-**Problem**: No `.voodocs.context` file exists.
-
-**Solution**: Run `voodocs context init` to create one.
-
 ---
 
-## Summary
-
-The VooDocs Context System is your **single source of truth** for:
-- ✅ Project understanding
-- ✅ Architecture documentation
-- ✅ Code validation
-- ✅ Change tracking
-- ✅ Visual documentation
+## Your Responsibilities
 
-**Always check context before making changes!**
+1. **Write annotations** using mathematical notation
+2. **Use pattern shortcuts** for validations
+3. **Use abbreviations** for maximum efficiency
+4. **Be precise** with mathematical symbols
+5. **Document invariants** that must always hold
+6. **Document side effects** that modify state
+7. **Document forbidden operations** that must not happen
 
 ---
 
-**VooDocs v0.2.0+** - AI-native documentation that keeps code and context in sync.
+**DarkArts v3.0.0** - The AI-Native Mathematical Language for Code
 """
 
 
-def generate_ai_instructions(project_name: str, project_purpose: str, ai_type: str = "cursor") -> Dict[str, str]:
+# Template registry
+TEMPLATES = {
+    'cursor': generate_cursorrules,
+    'claude': generate_claude_instructions,
+    'default': lambda *args: generate_default_instructions()
+}
+
+
+def get_template(ai_type: str = 'default') -> callable:
     """
-    Generate AI instruction files for different AI assistants.
+    Get instruction template for specific AI type.
     
     Args:
-        project_name: Name of the project
-        project_purpose: Brief purpose of the project
-        ai_type: Type of AI assistant ("cursor", "claude", "copilot", "all")
+        ai_type: Type of AI assistant ('cursor', 'claude', 'default')
     
     Returns:
-        Dictionary mapping filename to content
+        Template generation function
     """
-    instructions = {}
-    
-    if ai_type in ["cursor", "all"]:
-        instructions[".cursorrules"] = generate_cursorrules(project_name, project_purpose)
-    
-    if ai_type in ["all", "cursor", "claude", "copilot"]:
-        instructions["VOODOCS_CONTEXT_GUIDE.md"] = generate_context_guide(project_name, project_purpose)
-    
-    return instructions
+    return TEMPLATES.get(ai_type, TEMPLATES['default'])