docs: Comprehensive documentation improvement

New documentation:
- docs/INDEX.md - Master navigation for all documentation
- docs/TROUBLESHOOTING.md - Common issues and solutions
- docs/DOCUMENTATION_STANDARDS.md - Writing guidelines

API Reference (6 new files):
- docs/api/VSA_API.md - Vector Symbolic Architecture
- docs/api/VM_API.md - Ternary Virtual Machine
- docs/api/HYBRID_API.md - HybridBigInt storage
- docs/api/FIREBIRD_API.md - LLM inference engine
- docs/api/VIBEE_API.md - Specification compiler
- docs/api/PLUGIN_API.md - Extension system

Developer guides:
- docs/getting-started/DEVELOPMENT_SETUP.md - Dev environment setup
- examples/README.md - Examples documentation

Updated:
- CONTRIBUTING.md - Enhanced contribution guidelines
- docs/api/README.md - Updated with new API docs

Also includes plugin adapter specs and implementations.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: Antigravity Agent

CONTRIBUTING.md

@@ -1,54 +1,270 @@
-# Contributing to VIBEE
+# Contributing to Trinity
+
+Thank you for your interest in contributing to Trinity!
+
+---
+
+## Quick Links
+
+- [Development Setup](#development-setup)
+- [Code Style](#code-style)
+- [Pull Request Process](#pull-request-process)
+- [Testing](#testing)
+- [Documentation](#documentation)
+
+---
+
+## Development Setup
+
+### Prerequisites
+
+- **Zig 0.13.0** (required version)
+- **Git** for version control
+- **Make** (optional, for convenience scripts)
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/gHashTag/trinity.git
+cd trinity
+
+# Verify Zig version
+zig version  # Should show 0.13.0
+
+# Build
+zig build
+
+# Run tests
+zig build test
+```
+
+See [docs/getting-started/DEVELOPMENT_SETUP.md](docs/getting-started/DEVELOPMENT_SETUP.md) for detailed setup instructions.
+
+---
 
 ## Development Workflow
 
-1. **Fork** the repository
-2. **Create** a feature branch: `git checkout -b feature/my-feature`
-3. **Write specification first** — Create `.vibee` file before implementation
-4. **Generate code** — Use `vibeec gen` to generate implementation
-5. **Test** — Run `zig test` on generated code
-6. **Commit** — Follow conventional commits
-7. **Submit** pull request
+### Golden Chain Methodology
+
+Trinity follows the **specification-first** development approach:
+
+1. **Create specification** — Write `.vibee` file first
+2. **Generate code** — `./bin/vibee gen spec.vibee`
+3. **Test** — `zig test trinity/output/module.zig`
+4. **Write TOXIC VERDICT** — Self-criticism of implementation
+5. **Propose TECH TREE** — 3 options for next iteration
 
-## Specification-First Development
+```bash
+# View methodology
+./bin/vibee koschei
+```
+
+### Branch Naming
+
+| Prefix | Use |
+|--------|-----|
+| `feature/` | New features |
+| `fix/` | Bug fixes |
+| `docs/` | Documentation |
+| `refactor/` | Code refactoring |
+| `test/` | Test additions |
+
+Example: `feature/vsa-similarity-metrics`
 
-All new features must start with a `.vibee` specification:
+---
+
+## Code Style
+
+### Zig Code
+
+- Follow [Zig Style Guide](https://ziglang.org/documentation/master/#Style-Guide)
+- Use 4-space indentation
+- Max line length: 120 characters
+- Add doc comments for public functions
+
+```zig
+/// Binds two vectors via element-wise multiplication.
+/// Properties:
+/// - bind(a, a) = all +1 (self-inverse)
+/// - bind(a, bind(a, b)) = b (unbind)
+pub fn bind(a: *HybridBigInt, b: *HybridBigInt) HybridBigInt {
+    // Implementation
+}
+```
+
+### Specification Files
+
+- Use 2-space indentation in YAML
+- Include version and module name
+- Document all behaviors
 
 ```yaml
-# specs/my_feature.vibee
-name: my_feature
+name: module_name
 version: "1.0.0"
 language: zig
-module: my_feature
+module: module_name
 
 behaviors:
-  - name: feature_behavior
+  - name: function_name
     given: Precondition
     when: Action
     then: Expected result
 ```
 
-## Code Style
+### Commit Messages
+
+Use [Conventional Commits](https://www.conventionalcommits.org/):
+
+| Type | Description |
+|------|-------------|
+| `feat:` | New feature |
+| `fix:` | Bug fix |
+| `docs:` | Documentation |
+| `refactor:` | Code refactoring |
+| `test:` | Test changes |
+| `chore:` | Build/tooling |
+
+Example:
+```
+feat: Add cosine similarity to VSA module
+
+- Implement normalized dot product
+- Add SIMD acceleration
+- Include tests for edge cases
+```
+
+---
+
+## Pull Request Process
+
+### Before Submitting
+
+1. **Run tests:**
+   ```bash
+   zig build test
+   zig test src/vsa.zig  # Specific module
+   ```
 
-- **Zig**: Follow Zig style guide
-- **Specifications**: Use 2-space indentation in YAML
-- **Commits**: Use conventional commits (`feat:`, `fix:`, `docs:`)
+2. **Check formatting:**
+   ```bash
+   zig fmt src/
+   ```
+
+3. **Update documentation** if changing public APIs
+
+### PR Template
+
+```markdown
+## Description
+Brief description of changes.
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Documentation
+- [ ] Refactoring
 
 ## Testing
+How was this tested?
+
+## Checklist
+- [ ] Tests pass
+- [ ] Documentation updated
+- [ ] Follows code style
+```
+
+### Review Process
+
+1. Create PR against `main` branch
+2. Automated tests run via CI
+3. Maintainer reviews code
+4. Address feedback
+5. Merge when approved
+
+---
+
+## Testing
+
+### Running Tests
 
 ```bash
-cd src/vibeec
-zig test parser.zig
-zig test codegen.zig
+# All tests
+zig build test
+
+# Specific module
+zig test src/vsa.zig
+zig test src/vm.zig
+zig test src/hybrid.zig
+
+# With verbose output
+zig test src/vsa.zig --verbose
+
+# Specific test
+zig test src/vsa.zig --filter "bind"
+```
+
+### Writing Tests
+
+```zig
+test "function description" {
+    // Arrange
+    var a = HybridBigInt.random(100);
+    var b = HybridBigInt.random(100);
+
+    // Act
+    const result = bind(&a, &b);
+
+    // Assert
+    try std.testing.expect(result.trit_len == 100);
+}
 ```
 
-## Pull Request Guidelines
+### Test Coverage
+
+- All public functions must have tests
+- Test edge cases (empty, max size, etc.)
+- Include performance tests for critical paths
+
+---
+
+## Documentation
+
+### What to Document
+
+- Public API functions
+- Configuration options
+- Examples and tutorials
+- Architecture decisions
+
+### Documentation Style
+
+- Use Markdown
+- Include code examples
+- Add "See Also" cross-references
+
+### Building Docs
+
+Documentation is in `docs/` directory:
+- `docs/INDEX.md` — Main navigation
+- `docs/api/` — API reference
+- `docs/getting-started/` — Tutorials
+
+---
+
+## Getting Help
+
+- **Issues:** https://github.com/gHashTag/trinity/issues
+- **Discussions:** GitHub Discussions
+- **Documentation:** `docs/INDEX.md`
+
+---
 
-1. Reference related issue
-2. Include specification file
-3. Add tests for new behaviors
-4. Update documentation if needed
+## Recognition
 
-## Questions
+Contributors are recognized in:
+- Git commit history
+- Release notes
+- CONTRIBUTORS.md (for significant contributions)
 
-Open an issue for questions or discussions.
+Thank you for contributing to Trinity!