feat: Add Docusaurus documentation site with GitHub Pages deployment

- Create Docusaurus site in docsite/ with Trinity branding
- Add documentation: intro, getting-started, API reference, architecture
- Configure GitHub Actions workflow for automated deployment
- Custom homepage with VSA, BitNet, and VIBEE features
- Purple/gradient theme matching Trinity brand

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

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

Author: Antigravity Agent

.github/workflows/deploy-docs.yml

@@ -0,0 +1,59 @@
+name: Deploy Documentation to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docsite/**'
+      - '.github/workflows/deploy-docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docsite
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build website
+        run: npm run build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docsite/build
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docsite/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docsite/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+## Installation
+
+```bash
+yarn
+```
+
+## Local Development
+
+```bash
+yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+## Build
+
+```bash
+yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+## Deployment
+
+Using SSH:
+
+```bash
+USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```bash
+GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docsite/docs/api/firebird.md

@@ -0,0 +1,45 @@
+---
+sidebar_position: 5
+---
+
+# Firebird API
+
+LLM Inference Engine with BitNet Support.
+
+**Module:** `src/firebird/`
+
+## CLI Commands
+
+### Chat Mode
+
+```bash
+./bin/firebird chat --model path/to/model.gguf
+```
+
+### Server Mode
+
+```bash
+./bin/firebird serve --port 8080 --model model.gguf
+```
+
+## HTTP API
+
+### POST /v1/chat/completions
+
+OpenAI-compatible chat endpoint.
+
+```json
+{
+  "model": "bitnet-3b",
+  "messages": [{"role": "user", "content": "Hello!"}],
+  "temperature": 0.7
+}
+```
+
+## Performance
+
+| Model Size | Memory | Tokens/sec |
+|------------|--------|------------|
+| 1.5B | ~1GB | 15-20 |
+| 3B | ~2GB | 8-12 |
+| 7B | ~4GB | 4-6 |

docsite/docs/api/hybrid.md

@@ -0,0 +1,44 @@
+---
+sidebar_position: 4
+---
+
+# Hybrid API
+
+HybridBigInt — Optimal Memory/Speed Trade-off.
+
+**Module:** `src/hybrid.zig`
+
+## Storage Modes
+
+| Mode | Storage | Speed | Use Case |
+|------|---------|-------|----------|
+| Packed | 1.58 bits/trit | Slower | Storage |
+| Unpacked | 8 bits/trit | Fast | Computation |
+
+## Core Functions
+
+### zero() → HybridBigInt
+
+```zig
+var v = HybridBigInt.zero();
+```
+
+### random(len) → HybridBigInt
+
+```zig
+var v = HybridBigInt.random(1000);
+```
+
+### pack() / ensureUnpacked()
+
+```zig
+vector.pack();           // Memory efficient
+vector.ensureUnpacked(); // Compute efficient
+```
+
+## Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `MAX_TRITS` | 59049 | Maximum dimension |
+| `SIMD_WIDTH` | 32 | Parallel trits |

docsite/docs/api/index.md

@@ -0,0 +1,50 @@
+---
+sidebar_position: 1
+sidebar_label: Overview
+---
+
+# API Reference
+
+Complete API documentation for Trinity modules.
+
+## Core Modules
+
+| Module | Description |
+|--------|-------------|
+| [VSA](/docs/api/vsa) | Vector Symbolic Architecture |
+| [VM](/docs/api/vm) | Ternary Virtual Machine |
+| [Hybrid](/docs/api/hybrid) | HybridBigInt storage |
+| [Firebird](/docs/api/firebird) | LLM inference engine |
+| [VIBEE](/docs/api/vibee) | Specification compiler |
+| [Plugin](/docs/api/plugin) | Extension system |
+
+## Quick Reference
+
+### VSA Operations
+
+```zig
+vsa.bind(a, b)              // Create association
+vsa.unbind(bound, key)      // Retrieve from binding
+vsa.bundle2(a, b)           // Combine 2 vectors
+vsa.cosineSimilarity(a, b)  // Compare vectors [-1, 1]
+vsa.hammingDistance(a, b)   // Count differences
+vsa.permute(v, count)       // Cyclic shift
+```
+
+### HybridBigInt
+
+```zig
+var v = HybridBigInt.zero();       // Zero vector
+var v = HybridBigInt.random(1000); // Random vector
+v.pack();                          // Memory efficient
+v.ensureUnpacked();                // Compute efficient
+```
+
+### CLI Commands
+
+```bash
+./bin/vibee gen <spec.vibee>      # Generate code
+./bin/vibee run <program.999>     # Execute program
+./bin/vibee chat --model <path>   # Interactive chat
+./bin/vibee serve --port 8080     # HTTP server
+```

docsite/docs/api/plugin.md

@@ -0,0 +1,38 @@
+---
+sidebar_position: 7
+---
+
+# Plugin API
+
+Extensible Plugin System for Trinity.
+
+**Module:** `src/vibeec/plugin/`
+
+## Plugin Types
+
+| Type | Loading | Use Case |
+|------|---------|----------|
+| `comptime_import` | @import | Core |
+| `wasm_runtime` | WASM | Community |
+| `native_ffi` | .so/.dylib | Performance |
+
+## Creating a Plugin
+
+1. Create `plugin.vibee` specification
+2. Implement required exports
+3. Build to WASM
+
+## Loading Plugins
+
+```zig
+var loader = PluginLoader.init(allocator, &registry, .{});
+const result = try loader.loadFromPath("plugin.wasm");
+```
+
+## CLI Commands
+
+```bash
+vibee plugin list          # List installed
+vibee plugin install <url> # Install
+vibee plugin init <name>   # Create new
+```

docsite/docs/api/vibee.md

@@ -0,0 +1,49 @@
+---
+sidebar_position: 6
+---
+
+# VIBEE API
+
+Specification-Driven Code Generator.
+
+**Module:** `src/vibeec/`
+
+## CLI Commands
+
+```bash
+./bin/vibee gen <spec.vibee>       # Generate Zig
+./bin/vibee run <program.999>      # Execute via VM
+./bin/vibee koschei                # Development cycle
+```
+
+## Specification Format
+
+```yaml
+name: module_name
+version: "1.0.0"
+language: zig
+module: module_name
+
+types:
+  TypeName:
+    fields:
+      field1: String
+      field2: Int
+
+behaviors:
+  - name: function_name
+    given: Precondition
+    when: Action
+    then: Expected result
+```
+
+## Supported Types
+
+| Type | Description |
+|------|-------------|
+| `String` | Text string |
+| `Int` | Integer |
+| `Float` | Floating point |
+| `Bool` | Boolean |
+| `List<T>` | Array |
+| `Option<T>` | Nullable |