AI-Native Symbolic Documentation System - The world's first documentation tool using mathematical notation with semantic validation
npm install @voodocs/cliThe world's first documentation system designed exclusively for AI.
DarkArts is a mathematical notation system for documenting code that is optimized for AI understanding, not human reading. It achieves 79% token reduction compared to traditional comments while providing more precise semantic information.
DarkArts is for AI, not humans.
- AI writes it - Using assistants like Claude, Cursor, GitHub Copilot
- AI reads it - LLMs parse it instantly with mathematical precision
- Humans don't touch it - Use generated docs or companion files instead
DarkArts uses Unicode mathematical symbols for maximum precision and token efficiency:
| Symbol | Meaning | Example |
|--------|---------|---------|
| ⊢ | Purpose | ⊢{u auth svc} |
| ∂ | Dependencies | ∂{bcrypt,db} |
| ⚠ | Assumptions | ⚠{u exists in db} |
| ⊳ | Preconditions | ⊳{id:uuid,pw≥8} |
| ⊲ | Postconditions | ⊲{ret tok\|null} |
| ⊨ | Invariants | ⊨{no db mod} |
| ⚡ | Complexity | ⚡{O(1)} |
| 🔒 | Security | 🔒{pw:hash} |
| Symbol | Meaning | Example |
|--------|---------|---------|
| ⇄ | Bidirectional | ⇄{enc↔dec} |
| ⊕ | Side Effects | ⊕{writes db} |
| ⊗ | Forbidden | ⊗{no pw log} |
| ≈ | Approximation | ≈{±0.001} |
| ∴ | Consequence | ∴{fail→null} |
| ∀ | Universal | ∀{users have email} |
| ∃ | Existential | ∃{admin required} |
79% reduction compared to traditional comments:
``typescript
// Traditional (140 tokens)
/**
* User authentication service with JWT token generation.
* Dependencies: bcrypt, jsonwebtoken, database
* Preconditions: identifier must be valid UUID, password ≥8 chars
* Postconditions: returns JWT token or null
* Invariants: does not modify database
* Security: password hashed, token encrypted
*/
// DarkArts v3.0.0 (30 tokens)
/**@darkarts
⊢{u auth svc w/ JWT tok gen}
∂{bcrypt,jsonwebtoken,db}
⊳{id:uuid,pw≥8}
⊲{ret JWT tok|null}
⊨{no db mod}
🔒{pw:hash,tok:enc}
*/
`
`bash`
npm install -g @voodocs/cli@3.0.0
`bash`
voodocs init
Use your AI assistant (Claude, Cursor, etc.) to generate DarkArts annotations:
`
Prompt: "Add DarkArts v3.0.0 annotations to this function"
`bash`
voodocs validate src/ -r
`bash`
voodocs generate src/
Use shorthand for common validations:
`typescript`
/**@darkarts
⊳{id:uuid, email:email, pw≥8, age[18,65]}
*/
Available patterns:
- :uuid - valid UUID:email
- - valid email format:url
- - valid URL:json
- - valid JSON:jwt
- - valid JWT token:hash
- - hashed value:enc
- - encrypted value≥N
- , ≤N, >N,
- [N,M] - range notation∈{...}
- - set membership
200+ abbreviations for maximum compression:
Core:
- u = user, pw = password, auth = authenticationtok
- = token, sess = session, svc = service
Web/API:
- ep = endpoint, rt = route, mw = middlewarereq
- = request, res = response, hdl = handler
Security:
- enc = encryption, dec = decryption, sig = signaturecert
- = certificate, perm = permission
Data:
- db = database, tbl = table, rec = recordidx
- = index, sch = schema, coll = collection
[See full list in documentation]
Seven new symbols for richer semantics:
`typescript`
/**@darkarts
⊢{data enc/dec svc}
⇄{enc↔dec} // Bidirectional operations
⊕{writes cache} // Side effects
⊗{no pw log} // Forbidden operations
≈{±0.001 precision} // Approximation
∴{if fail→retry 3x} // Logical consequences
∀{all data:enc} // Universal properties
∃{valid key required} // Existential properties
*/
Enhanced parser with semantic validation:
`bash
$ voodocs validate src/auth.ts
Error in @darkarts annotation at line 42:
⊳{id:uuuid}
^^^^^
Unknown pattern ':uuuid'. Did you mean ':uuid'?
Available patterns: :uuid, :email, :url, :json, :jwt, :hash, :enc
Error at line 45:
Contradiction - invariant says no db modification,
but side effect writes to database
`
`bashInitialize project
voodocs init
🔧 Context System
DarkArts integrates with AI context management:
bash
Initialize context
voodocs context initGenerate context from annotations
voodocs generate src/ -rView context
voodocs context view
`Context files (
) provide structured information for AI assistants.📄 Companion Files
For compiled languages (Solidity, Rust, etc.), use companion files:
`bash
Create .voodocs.md files alongside source
voodocs companion contracts/ -r
`Example:
contracts/
Registry.sol
Registry.sol.voodocs.md ← Human-readable documentation
🎓 For Humans
Humans should never manually write or read DarkArts annotations. Instead:
1. Use AI to generate annotations
2. Read generated docs (HTML, Markdown)
3. Use companion files for human-readable documentation
🔬 Research & Patents
DarkArts is based on peer-reviewed research and protected by patents:
- Patent 1: Context-Augmented AI Systems
- Patent 2: Multi-Dimensional Quality Categorization
- Patent 3: Invariant-Guided Code Generation
- Patent 4: Token-Efficient Context Management
Portfolio Value: $50M-180M
📊 Benchmarks
Real-world performance validation:
| Metric | Improvement |
|--------|-------------|
| Token Reduction | 79% |
| Quality Score | +42% |
| Time Reduction | 43% |
| Bug Detection | +67% |
| Cost Savings | $12.2K/year per developer |
🌐 Ecosystem
- ESLint Plugin:
- TypeScript Support: Built-in parser
- Python Support: Built-in parser
- Solidity Support: Via companion files📖 Documentation
- User Guide
- API Reference
- Tutorials
- Examples
🤝 Contributing
DarkArts is commercial software. For enterprise licensing:
- Email: contact@3vil.enterprises
- Website: https://voodocs.com
📜 License
Commercial License - © 2025 3vilEnterprises
🆕 What's New in v3.0.0
$3
- Removed
- Only mathematical notation supported
- New symbols - Old parsers won't recognize ⇄, ⊕, ⊗, ≈, ∴, ∀, ∃$3
- ✅ Pattern shortcuts (
:uuid, :email, ≥N`, etc.)No migration needed! v3.0.0 is backward compatible with v2.x annotations. New features are optional enhancements.
---
DarkArts v3.0.0 - The AI-Native Mathematical Language for Code