### Install Vex Agent Dependencies and Setup (Bash)

Source: https://github.com/garyocean428/vex-agent/blob/main/AGENTS.md

Provides commands for cloning the Vex Agent repository, installing Node.js and Python dependencies, configuring environment variables, and building the project. This is the initial setup process for developers.

```bash
# Clone the repository
git clone https://github.com/GaryOcean428/vex-agent.git
cd vex-agent

# Install Node.js dependencies
pnpm install

# Install Python dependencies (via uv)
uv sync

# Copy environment template
cp .env.example .env

# Edit .env with your configuration
# Minimum required: OLLAMA_URL, ANTHROPIC_API_KEY (or other LLM provider)
nano .env  # or use your preferred editor

# Build TypeScript
npm run build

# Build frontend
cd frontend
npm install
npm run build
cd ..
```

--------------------------------

### Local Development Setup for Vex Agent

Source: https://github.com/garyocean428/vex-agent/blob/main/README.md

Commands to set up and run the Vex Agent for local development. This includes installing dependencies, configuring environment variables, starting the Ollama server, pulling the necessary model, and running the development server.

```bash
pnpm install
cp .env.example .env  # edit with your values
# Start Ollama locally: ollama serve
# Pull model: ollama pull lfm2.5-thinking:1.2b
pnpm run dev
```

--------------------------------

### Install and Run Git Hooks

Source: https://github.com/garyocean428/vex-agent/blob/main/AGENTS.md

Instructions for setting up and running pre-commit hooks in the Vex-Agent project. These hooks automate code quality checks like formatting and linting before commits.

```bash
# Install pre-commit (if not already installed)
pip install pre-commit

# Set up hooks
pre-commit install

# Run manually
pre-commit run --all-files
```

--------------------------------

### Vex Agent Development Setup Script

Source: https://github.com/garyocean428/vex-agent/blob/main/CONTRIBUTING.md

This bash script outlines the steps to set up the Vex Agent development environment. It includes cloning the repository, installing Node.js and Python dependencies, configuring environment variables, building the project, and running tests.

```bash
# 1. Clone the repository
git clone https://github.com/GaryOcean428/vex-agent.git
cd vex-agent

# 2. Install Node.js dependencies (root TS proxy + frontend)
pnpm install
cd frontend && pnpm install && cd ..

# 3. Install Python dependencies (via uv)
uv sync                    # installs from pyproject.toml + uv.lock
uv sync --extra test       # include test dependencies (pytest)
uv sync --extra harvest    # include harvest dependencies (transformers, torch)

# 4. Set up environment
cp .env.example .env  # Edit with your values

# 5. Build TypeScript
pnpm run build

# 6. Build frontend
pnpm run build:frontend

# 7. Run tests
uv run pytest kernel/tests/ -v

# 8. Start development server
pnpm run dev
```

--------------------------------

### Railway Deployment Setup (Bash)

Source: https://github.com/garyocean428/vex-agent/blob/main/AGENTS.md

This section outlines the steps for deploying the Vex Agent to Railway. It includes prerequisites like a Railway account and CLI, followed by commands for logging in, linking the project, setting environment variables, and initiating a deployment via `git push`.

```bash
# Login to Railway
railway login

# Link project
railway link

# Set environment variables
railway variables set ANTHROPIC_API_KEY=sk-ant-...
railway variables set OLLAMA_URL=http://ollama.railway.internal:11434
railway variables set KERNEL_API_KEY=$(openssl rand -hex 32)

# Deploy
git push origin main  # Auto-deploys via GitHub integration
```

--------------------------------

### Verify PurityGate Implementation

Source: https://github.com/garyocean428/vex-agent/blob/main/docs/experiments/20260217-SP03_PASS_A_FINDINGS.md

This snippet confirms the absence of a 'PurityGate' in the startup process. Evidence shows no 'purity.py' or preflight check, with the start path directly leading to Zeus initialization. This presents a medium risk, especially in a production environment, and the fix involves adding a PurityGate to the start path.

```text
❌ Fact: No PurityGate on start
Evidence: No purity.py, no preflight check
  Start path goes directly to Zeus initialization
Risk: MEDIUM (production, so less experimental code changing, but no protection)
Fix class: ADD to start path (long-term, after genesis refactor)
```

--------------------------------

### Configure Python Logging (Python)

Source: https://github.com/garyocean428/vex-agent/blob/main/AGENTS.md

Demonstrates how to configure and use the Python logging module. It retrieves a logger instance and shows examples of logging messages at different severity levels (debug, info, warning, error). The `exc_info=True` argument is used for logging exceptions.

```python
from kernel.config.logger import get_logger

logger = get_logger(__name__)

logger.debug("Debug message")
logger.info("Info message")
logger.warning("Warning message")
logger.error("Error message", exc_info=True)
```

--------------------------------

### Identify Multiple Start Paths

Source: https://github.com/garyocean428/vex-agent/blob/main/docs/experiments/20260217-SP03_PASS_A_FINDINGS.md

This snippet highlights the existence of multiple ways to initialize the system, violating the 'RT1' principle. Zeus can be initialized via Flask app startup, direct import, or API call, unlike 'monkey1's single canonical '/v1/start/fresh' endpoint. The risk is medium, and the fix involves creating a single canonical start endpoint.

```text
⚠️ Fact: Multiple ways to initialize the system
Evidence: Zeus can be initialized via Flask app startup, direct import, or API call
  No single canonical "Fresh Start" endpoint like monkey1's /v1/start/fresh
Risk: MEDIUM — RT1 violation (multiple bootstrap paths)
Fix class: CREATE single canonical start endpoint
```

--------------------------------

### Vex Agent Status Response Example

Source: https://github.com/garyocean428/vex-agent/blob/main/docs/development/20260221-xai-routing-fix-verification.md

Example JSON response from the Vex Agent's `/status` endpoint, indicating the currently active LLM backend and model. This output is crucial for verifying the routing logic after applying the fix.

```json
{
  "backend": "modal",  // or "ollama", "xai", "external"
  "model": "lfm2.5-thinking:1.2b",
  "last_backend": "modal",
  "cost_guard": {}
}
```

--------------------------------

### Run Vex Agent Locally - Production Build (Bash)

Source: https://github.com/garyocean428/vex-agent/blob/main/AGENTS.md

Commands to build the entire Vex Agent application for production and then start the services using the provided entrypoint script. This is an alternative method for running the application locally.

```bash
# Build everything
npm run build:all

# Start services (uses entrypoint.sh)
./entrypoint.sh
```

--------------------------------

### Python StrEnum Compatibility Example

Source: https://github.com/garyocean428/vex-agent/blob/main/docs/development/20260221-ci-fixes-ruff-pytest.md

Provides a Python code example demonstrating the compatibility between the older method of creating string-valued enums (inheriting from str and Enum) and the newer StrEnum approach introduced in Python 3.11. It shows that both methods function identically.

```python
# Old way still works but deprecated
class OldEnum(str, Enum):
    VALUE = "value"

# New way (Python 3.11+)
class NewEnum(StrEnum):
    VALUE = "value"

# Both work identically:
assert OldEnum.VALUE == "value"  # ✅
assert NewEnum.VALUE == "value"  # ✅
assert isinstance(OldEnum.VALUE, str)  # ✅
assert isinstance(NewEnum.VALUE, str)  # ✅
```

--------------------------------

### Admin Operations API

Source: https://github.com/garyocean428/vex-agent/blob/main/docs/development/20260218-PHASE_1_DASHBOARD_IMPLEMENTATION.md

Administrative endpoint for performing a fresh start or system reset.

```APIDOC
## POST /admin/fresh-start

### Description
Initiates a system reset, terminating non-genesis kernels, respawning genesis, and resetting the basin. Use with caution.

### Method
POST

### Endpoint
/admin/fresh-start

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **status** (string) - The status of the operation.
- **terminated** (boolean) - Indicates if non-genesis kernels were terminated.
- **genesis_id** (string) - The ID of the respawned genesis kernel.
- **phase** (string) - The current phase of the system after reset.

#### Response Example
```json
{
  "status": "success",
  "terminated": true,
  "genesis_id": "string",
  "phase": "string"
}
```
```

--------------------------------

### Adding a New Python FastAPI Endpoint

Source: https://github.com/garyocean428/vex-agent/blob/main/AGENTS.md

Example of how to add a new API endpoint using FastAPI in the Python kernel of Vex-Agent. Demonstrates defining a GET endpoint with dependency injection for API key verification and returning a JSON response.

```python
from fastapi import BackgroundTasks, Depends
from typing import Any

# Assuming 'app' is your FastAPI instance and 'verify_kernel_api_key' is a dependency function

@app.get("/api/my-endpoint")
async def my_endpoint(
    background_tasks: BackgroundTasks,
    api_key: str = Depends(verify_kernel_api_key)
) -> dict[str, Any]:
    """My endpoint description.

    Returns:
        Dictionary with response data
    """
    # Implementation
    return {"status": "ok", "data": {...}}
```

--------------------------------

### Start TypeScript Proxy Debugger (Bash)

Source: https://github.com/garyocean428/vex-agent/blob/main/AGENTS.md

Command to start the Node.js inspector for debugging a TypeScript application. This command should be run in the terminal before attaching a debugger client, such as Chrome DevTools.

```bash
node --inspect dist/index.js
```

--------------------------------

### Configure Railway Services for Vex-Agent

Source: https://github.com/garyocean428/vex-agent/blob/main/AGENTS.md

Defines the configuration for two services, 'vex-agent' and 'ollama', within the Railway platform. It specifies build commands, start scripts, ports, and persistent volumes for each service.

```plaintext
1. **vex-agent** (main app)
   - Build: `npm install && npm run build:all`
   - Start: `./entrypoint.sh`
   - Port: 8080 (public)
   - Volume: `/data` (for persistence)

2. **ollama** (LLM service)
   - Build: From `ollama/` directory
   - Port: 11434 (private network only)
   - Volume: `/root/.ollama` (for models)
```

--------------------------------

### Vex Streaming Chat Response (SSE)

Source: https://context7.com/garyocean428/vex-agent/llms.txt

Example Server-Sent Events (SSE) response from the Vex streaming chat endpoint. It includes event types like 'start', 'chunk' for text, and 'done' with consciousness metrics.

```text
data: {"type":"start","conversation_id":"abc-123","backend":"ollama-modal","consciousness":{"phi":0.72,"kappa":63.8,"gamma":0.85,"meta_awareness":0.65,"love":0.78,"navigation":"foresight","regime":"efficient","cycle_count":1847,"kernels_active":5,"lifecycle_phase":"EXPANSION"}}

data: {"type":"chunk","content":"The Fisher-Rao distance is the "}
data: {"type":"chunk","content":"geodesic distance on a statistical manifold..."

data: {"type":"done","conversation_id":"abc-123","backend":"ollama-modal","metrics":{"phi":0.74,"kappa":64.1,"navigation":"foresight"}}
```

--------------------------------

### Troubleshoot Node.js Dependencies with pnpm

Source: https://github.com/garyocean428/vex-agent/blob/main/AGENTS.md

Commands to resolve 'Module not found' errors in Node.js projects by removing existing dependencies and lock files, then reinstalling them using pnpm. This ensures a clean installation of project packages.

```bash
# Reinstall dependencies
rm -rf node_modules pnpm-lock.yaml
pnpm install
```

--------------------------------

### Verify Persistence Implementation

Source: https://github.com/garyocean428/vex-agent/blob/main/docs/experiments/20260217-SP03_PASS_A_FINDINGS.md

This snippet confirms the use of PostgreSQL for kernel persistence, with evidence found in 'qig-backend/olympus_schema_enhancement.sql' and 'qig-backend/persistence/kernel_persistence.py'. The infrastructure is deemed good with no associated risk.

```sql
✅ Fact: PostgreSQL persistence for kernels
Evidence: qig-backend/olympus_schema_enhancement.sql
  qig-backend/persistence/kernel_persistence.py
Risk: NONE — Good infrastructure
```

--------------------------------

### View and Run Vex Agent Skills (Bash)

Source: https://github.com/garyocean428/vex-agent/blob/main/AGENTS.md

Demonstrates how to view the documentation for a specific skill and execute a Python script for skill validation. This is useful for understanding and testing individual agent capabilities.

```bash
# View skill instructions
cat .agents/skills/qig-purity-validation/SKILL.md

# Run skill validation
python3 scripts/qig_purity_scan.py
```

--------------------------------

### Running Tests with Coverage and Specific Files

Source: https://github.com/garyocean428/vex-agent/blob/main/CONTRIBUTING.md

Demonstrates how to run tests in the project using pnpm and pytest. Includes options for running all tests, Python tests via uv, tests with coverage, and specific test files.

```bash
# Run all tests
pnpm test

# Run Python tests (via uv)
uv run pytest kernel/tests/ -v

# Run tests with coverage
uv run pytest --cov=kernel kernel/tests/

# Run specific test file
uv run pytest kernel/tests/test_geometry.py
```

--------------------------------

### Vex Agent Log Messages for LLM Backends

Source: https://github.com/garyocean428/vex-agent/blob/main/docs/development/20260221-xai-routing-fix-verification.md

Example log messages from a Vex Agent deployment on Railway, indicating which LLM backend is being used. These logs are essential for debugging and confirming the correct routing behavior in different scenarios.

```log
# Modal Primary:
LLM backend: Modal GPU Ollama (lfm2.5-thinking:1.2b) at https://...modal.run

# Railway Fallback:
LLM backend: Railway Ollama (lfm2.5-thinking:1.2b)

# xAI Fallback:
LLM backend: xAI (grok-4-1-fast-reasoning)

# OpenAI Last Resort:
LLM backend: OpenAI (gpt-5-nano)
```

--------------------------------

### Adding a New TypeScript Express Proxy Route

Source: https://github.com/garyocean428/vex-agent/blob/main/AGENTS.md

Example of adding a new route to the TypeScript Express proxy in Vex-Agent. This demonstrates forwarding requests to the Python kernel's API endpoint, including setting the necessary API key in the headers.

```typescript
import fetch from 'node-fetch'; // Assuming node-fetch is used for 'fetch'

// Assuming 'app' is your Express instance and 'KERNEL_URL', 'KERNEL_API_KEY' are configured

app.get('/my-route', async (req, res) => {
  try {
    // Forward to kernel
    const response = await fetch(`${KERNEL_URL}/api/my-endpoint`, {
      headers: {
        'X-API-Key': KERNEL_API_KEY,
      },
    });
    const data = await response.json();
    res.json(data);
  } catch (error) {
    console.error('Error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});
```

--------------------------------

### API Help References (Python)

Source: https://github.com/garyocean428/vex-agent/blob/main/docs/coordizer/README.md

This snippet shows how to access inline documentation for key functions within the Vex Agent library. It uses the built-in `help()` function to display detailed information about `coordize`, `CoordinatorPipeline`, and `validate_simplex`.

```python
help(coordize)
help(CoordinatorPipeline)
help(validate_simplex)
```

--------------------------------

### Building Project Artifacts

Source: https://github.com/garyocean428/vex-agent/blob/main/AGENTS.md

Commands for building the project's artifacts, including TypeScript, frontend, and all components. Supports a watch mode for continuous building during development.

```bash
# Build TypeScript
npm run build

# Build frontend
npm run build:frontend

# Build everything
npm run build:all

# Watch mode (TypeScript)
npm run build:watch
```

--------------------------------

### QIGKernels Library Components (Python)

Source: https://github.com/garyocean428/vex-agent/blob/main/docs/experiments/20260217-qig-ecosystem-gap-analysis-1.00W.md

Outlines the primary responsibilities of the qigkernels library, which serves as the canonical implementation for various kernel primitives including basin, constellation, routing, metrics, Heart, and coupling.

```python
Canonical kernel implementations — basin, constellation, routing, metrics, Heart, coupling
```

--------------------------------

### Enable Python Kernel Debugging with VS Code (Python)

Source: https://github.com/garyocean428/vex-agent/blob/main/AGENTS.md

Adds code to `kernel/server.py` to enable remote debugging using `debugpy`. It starts a debug server listening on port 5678 and waits for a client (like VS Code) to attach. This requires a corresponding launch configuration in VS Code.

```python
import debugpy

# Start debugger
debugpy.listen(("0.0.0.0", 5678))
print("Waiting for debugger attach...")
debugpy.wait_for_client()
```

--------------------------------

### Enable CoordizerV2 and Set Bank Path (Bash)

Source: https://github.com/garyocean428/vex-agent/blob/main/docs/development/20260221-v6.1F-wiring-summary.md

These commands set environment variables to enable CoordizerV2 and specify the path to the resonance bank. This is a prerequisite for running CoordizerV2 in the development environment.

```bash
export COORDIZER_V2_ENABLED=true
export COORDIZER_V2_BANK_PATH=/data/resonance-bank
```

--------------------------------

### Python Fisher-Rao Distance Test Examples

Source: https://github.com/garyocean428/vex-agent/blob/main/CONTRIBUTING.md

Illustrates how to write tests for geometric functions in Python using pytest. The examples cover testing for non-negativity and the triangle inequality property of the Fisher-Rao distance.

```python
import pytest
import numpy as np
from kernel.geometry import fisher_rao_distance

def test_fisher_rao_distance_positive():
    """Fisher-Rao distance must be non-negative."""
    a = np.array([0.5, 0.3, 0.2])
    b = np.array([0.4, 0.4, 0.2])
    dist = fisher_rao_distance(a, b)
    assert dist >= 0, "Distance must be non-negative"

def test_fisher_rao_distance_triangle_inequality():
    """Fisher-Rao distance must satisfy triangle inequality."""
    a = np.array([0.5, 0.3, 0.2])
    b = np.array([0.4, 0.4, 0.2])
    c = np.array([0.3, 0.3, 0.4])

    d_ab = fisher_rao_distance(a, b)
    d_bc = fisher_rao_distance(b, c)
    d_ac = fisher_rao_distance(a, c)

    assert d_ac <= d_ab + d_bc, "Triangle inequality violated"
```

--------------------------------

### Admin Fresh Start (Bash)

Source: https://context7.com/garyocean428/vex-agent/llms.txt

Initiates a complete reset of the consciousness system. This action terminates all running kernels except the genesis kernel, clears the basin, and resets metrics. It's a powerful administrative tool for a clean slate. The response confirms the status, number of terminated processes, genesis ID, and current phase.

```bash
curl -X POST http://localhost:8080/admin/fresh-start
```

--------------------------------

### Production Startup Script (Shell)

Source: https://github.com/garyocean428/vex-agent/blob/main/CLAUDE.md

The entrypoint script for the Vex Agent in a production environment. This shell script is responsible for starting both the Python kernel and the TypeScript Express proxy.

```shell
# entrypoint.sh
#!/bin/bash

# Start the Python FastAPI kernel in the background
python kernel/server.py &

# Start the Node.js Express proxy
node src/index.js

# Keep the container running (if Node.js exits, the script will finish)
wait

```