### Copy MindBridge Router Files

Source: https://github.com/harbz07/soul-os/blob/main/apps/samsara/README.md

Copy the necessary Python files and .env example into your mindbridge-router checkout for the PvE debate engine integration.

```bash
cp mindbridge-additions/providers/deepseek_provider.py  ../mindbridge-router/app/providers/
cp mindbridge-additions/providers/factory.py             ../mindbridge-router/app/providers/
cp mindbridge-additions/debate.py                        ../mindbridge-router/app/
cp mindbridge-additions/main.py                          ../mindbridge-router/app/
cp mindbridge-additions/.env.example                     ../mindbridge-router/
```

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

### Initiate Multi-Hop Chains with curl

Source: https://context7.com/harbz07/soul-os/llms.txt

Start multi-hop message chains where context is passed sequentially between agents. Tracks the full chain and records each hop in the conversation graph.

```bash
curl -X POST https://api.soul-os.cc/chain \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "harvey",
    "chain": ["claude", "orion", "triptych"],
    "goal": "Design, implement, and document a new feature",
    "thread_tag": "feature-pipeline"
  }'
```

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

### Start Prosecution Mode Debate

Source: https://github.com/harbz07/soul-os/blob/main/apps/samsara/DEPLOY.md

Initiates a debate in Prosecution mode with specific parameters. Use this to simulate a PvE scenario where the protagonist defends against all antagonists over a set number of rounds.

```bash
curl -X POST https://api.soul-os.cc/debate \
  -H "Content-Type: application/json" \
  -d '{ \
    "seed": "When Vasubandhu deploys the milk-to-curds analogy, he establishes that causal succession requires no underlying essence. But the Pudgalavādins intervene at this structural gap: if there is only atomic succession, to whom is compassion owed?", \
    "paper_title": "PvE - The Case for the Pudgalavādins", \
    "thesis": "The pudgala is the minimum metaphysical infrastructure required for Buddhist ethics.", \
    "mode": "prosecution", \
    "rounds": 2, \
    "include_reasoning": true, \
    "anticipate_novel": true, \
    "paper_context": "Śāntideva will later prove with the Bodhisattva vow that commitment to save all sentient beings is incoherent if those beings are merely momentary clusters of data. The Pudgalavādin defense is not an attempt to smuggle an ātman; it is the insistence that the pattern itself must possess enough causal efficacy to hold the weight of a karmic consequence." \
  }'
```

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

### Get Debate Cast and Questions

Source: https://github.com/harbz07/soul-os/blob/main/apps/samsara/DEPLOY.md

Retrieves the cast of characters and available questions for a debate. Replace `<MINDBRIDGE_URL>` and `<MINDBRIDGE_API_KEY>` with your specific credentials.

```bash
curl https://<MINDBRIDGE_URL>/v1/debate/cast \
  -H "Authorization: Bearer <MINDBRIDGE_API_KEY>"
```

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

### Structured Test Payload

Source: https://github.com/harbz07/soul-os/blob/main/apps/samsara/DEPLOY.md

Example cURL command to initiate a 'structured_test' debate, running all five test questions across all positions with reasoning and novel anticipation enabled.

```bash
curl -X POST https://api.soul-os.cc/debate \
  -H "Content-Type: application/json" \
  -d '{ \
    "seed": "The Pudgalavādins were not sneaking an eternal soul back into Buddhism; they were insisting on the minimal metaphysical infrastructure necessary to keep ethics from collapsing.", \
    "paper_title": "PvE - The Case for the Pudgalavādins", \
    "thesis": "The pudgala is the minimum metaphysical infrastructure required for Buddhist ethics to function without collapsing into a frictionless mathematical vacuum.", \
    "mode": "structured_test", \
    "rounds": 1, \
    "include_reasoning": true, \
    "anticipate_novel": true \
  }'
```

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

### Start Stress Test Debate

Source: https://github.com/harbz07/soul-os/blob/main/apps/samsara/DEPLOY.md

Initiates a debate in Stress Test mode to apply maximum adversarial pressure. This mode is useful for testing the system's robustness under intense challenges.

```bash
curl -X POST https://api.soul-os.cc/debate \
  -H "Content-Type: application/json" \
  -d '{ \
    "seed": "The pudgala is neither identical with nor different from the skandhas.", \
    "paper_title": "PvE - The Case for the Pudgalavādins", \
    "thesis": "The pudgala is real enough to bear ethical weight without being an ātman.", \
    "mode": "stress_test", \
    "rounds": 1, \
    "include_reasoning": true, \
    "anticipate_novel": true \
  }'
```

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

### Single Question Probe Payload

Source: https://github.com/harbz07/soul-os/blob/main/apps/samsara/DEPLOY.md

Example cURL command to test a single question ('Who or what receives harm?') across specific positions, using the 'structured_test' mode.

```bash
curl -X POST https://api.soul-os.cc/debate \
  -H "Content-Type: application/json" \
  -d '{ \
    "seed": "The Pudgalavādins were not sneaking an eternal soul back into Buddhism.", \
    "paper_title": "PvE - The Case for the Pudgalavādins", \
    "thesis": "The pudgala is necessary metaphysical infrastructure for ethical uptake.", \
    "mode": "structured_test", \
    "rounds": 1, \
    "include_reasoning": true, \
    "test_questions": [ \
      "Who or what receives harm? Be specific about the ontological status of the recipient." \
    ] \
  }'
```

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

### Prosecution/Roundtable/Stress Test Response Format

Source: https://github.com/harbz07/soul-os/blob/main/apps/samsara/DEPLOY.md

Example JSON response structure for debates in Prosecution, Roundtable, or Stress Test modes. It includes debate metadata, participant roles, and a detailed breakdown of turns with arguments and reasoning.

```json
{
  "debate_id": "pve-a1b2c3d4e5f6",
  "paper_title": "PvE - The Case for the Pudgalavādins",
  "thesis": "...",
  "mode": "prosecution",
  "rounds": 2,
  "cast": {
    "pudgalavadin": "protagonist",
    "vasubandhu": "prosecutor",
    "nagarjuna": "dangerous_ally",
    "siderits": "modern_foil",
    "santideva": "ethical_witness"
  },
  "turns": [
    {
      "turn_number": 1,
      "round_number": 1,
      "speaker": "pudgalavadin",
      "role": "protagonist",
      "synecdoche": "The minimum metaphysical infrastructure required for ethics",
      "argument": "...",
      "reasoning_chain": null,
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514",
      "timestamp": "2026-03-23T03:30:00Z"
    },
    {
      "turn_number": 2,
      "round_number": 1,
      "speaker": "vasubandhu",
      "role": "prosecutor",
      "argument": "...",
      "reasoning_chain": "Step 1: The Pudgalavādin claims... Step 2: But this entails...",
      "provider": "deepseek",
      "model": "deepseek-reasoner"
    }
  ],
  "strongest_objection": "...",
  "productive_tension": "..."
}
```

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

### Structured Test Response Format

Source: https://github.com/harbz07/soul-os/blob/main/apps/samsara/DEPLOY.md

Example JSON response structure for a Structured Test mode. This format includes test scores for each speaker on specific questions, detailing their response, reasoning, and an assessment.

```json
{
  "debate_id": "pve-x1y2z3",
  "mode": "structured_test",
  "test_scores": [
    {
      "speaker": "pudgalavadin",
      "question_number": 1,
      "question": "Who or what receives harm?",
      "response": "...",
      "reasoning_chain": null,
      "assessment": "solid",
      "assessment_note": "Directly answers with pudgala as uptake site"
    },
    {
      "speaker": "vasubandhu",
      "question_number": 1,
      "question": "Who or what receives harm?",
      "response": "...",
      "reasoning_chain": "Step 1: Under strict reductionism...",
      "assessment": "equivocates",
      "assessment_note": "Claims conventional designation suffices but cannot specify the bearer"
    }
  ],
  "failure_table": {
    "pudgalavadin": {
      "role": "protagonist",
      "must_preserve": "karma as intelligible uptake...",
      "break_point": "when 'inexpressible person' hardens into a covert atman",
      "one_liner": "Fails when continuity is secured by smuggling in a substance."
    },
    "vasubandhu": {
      "role": "prosecutor",
      "must_preserve": "anatman + causal continuity",
      "break_point": "when aggregates-only cannot specify a site of uptake",
      "one_liner": "Fails when anti-self is purchased at the cost of who/what bears consequence."
    }
  }
}
```

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

### Get Thread Conversation Graph with D1

Source: https://context7.com/harbz07/soul-os/llms.txt

Retrieve the conversation graph for a specific thread using `graphGet`. This function requires a database binding and returns nodes and edges representing the conversation flow.

```javascript
// Get conversation graph for a thread
const graph = await graphGet(db, "thread-123");
// Returns: { nodes: ["harvey", "claude", "orion"], edges: [{from_agent, to_agent, intent, weight}] }
```

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

### Initiate Kumon Module and Terminal Warnings with JavaScript

Source: https://github.com/harbz07/soul-os/blob/main/apps/castor-hub/index.html

This script initiates the 'Kumon' module after a delay, preceded by a warning message in the terminal. It sets up the initial state and triggers the first instance of the educational module.

```javascript
// Start the loop after a brief delay setTimeout(() => { addTerminalLine("WARNING: Unauthorized educational software executed.", "text-yellow-400 font-bold"); setTimeout(triggerKumon, 1500); }, 2000);
```

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

### Run D1 Migrations Locally

Source: https://github.com/harbz07/soul-os/blob/main/README.md

Execute the D1 migration script locally to set up the database schema for Siddartha. Ensure Wrangler is configured for remote execution.

```bash
wrangler d1 execute soul-os-cognitive-db --remote --file=apps/siddartha/migrations/0001_initial.sql
```

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

### Initialize Memory Store

Source: https://github.com/harbz07/soul-os/blob/main/agents/chatgpt/README.md

Call this function to initialize a memory store. It sets up the local memory document model, storage, retrieval scoring, and prompt augmentation.

```python
initialize_memory_store(base_dir)
```

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

### Manage Sessions and Traces

Source: https://context7.com/harbz07/soul-os/llms.txt

Endpoints for querying interaction sessions and individual agent turns (traces). Each trace contains details about the agent, model, content, and performance metrics.

```bash
# List recent sessions
curl "https://api.soul-os.cc/sessions?agent=claude&limit=20"
```

```bash
# Get session with all traces
curl https://api.soul-os.cc/session/session-id-here
```

```bash
# Get all agent states
curl https://api.soul-os.cc/agents/state
```

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

### Create a New Git Branch

Source: https://github.com/harbz07/soul-os/blob/main/CONTRIBUTING.md

Use this command to create a new branch for your feature development. Replace '<short-description>' with a concise summary of your changes.

```bash
git checkout -b feature/<short-description>
```

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

### Quick Test Debate Endpoint

Source: https://github.com/harbz07/soul-os/blob/main/apps/samsara/README.md

Perform a quick test of the debate endpoint by sending a POST request with specified parameters.

```bash
curl -X POST https://api.soul-os.cc/debate \
  -H "Content-Type: application/json" \
  -d '{ \
    "seed": "The pudgala is necessary metaphysical infrastructure for ethical uptake.", \
    "paper_title": "PvE - The Case for the Pudgalavādins", \
    "thesis": "The pudgala is the minimum metaphysical infrastructure required for Buddhist ethics.", \
    "mode": "structured_test", \
    "rounds": 1, \
    "include_reasoning": true, \
    "test_questions": [ \
      "Who or what receives harm? Be specific about the ontological status of the recipient." \
    ] \
  }'
```

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

### OpenAI-Compatible Chat Completions

Source: https://context7.com/harbz07/soul-os/llms.txt

A drop-in compatible endpoint following the OpenAI chat completions format. Routes requests to appropriate constellation agents based on the model parameter.

```APIDOC
## POST /v1/chat/completions

### Description
Drop-in compatible endpoint following the OpenAI chat completions format. Routes requests to appropriate constellation agents based on the model parameter, enabling integration with existing OpenAI client libraries while accessing memory-hydrated constellation agents.

### Method
POST

### Endpoint
https://api.soul-os.cc/v1/chat/completions

### Parameters
#### Request Body
- **model** (string) - Required - The model to use for the chat completion (e.g., "claude-sonnet").
- **messages** (array) - Required - An array of message objects, each with a "role" (system, user, assistant) and "content".

### Request Example
```json
{
  "model": "claude-sonnet",
  "messages": [
    {"role": "system", "content": "You are helping with code review."},
    {"role": "user", "content": "Review this function for edge cases."}
  ]
}
```

### Response
#### Success Response (200)
- **choices** (array) - An array of completion choices.
  - **message** (object) - The message object containing the completion.
    - **role** (string) - The role of the message (e.g., "assistant").
    - **content** (string) - The content of the message.

#### Response Example
```json
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "The function appears robust, but consider adding checks for null inputs."
      }
    }
  ]
}
```
```

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

### Initiate a Structured Debate

Source: https://context7.com/harbz07/soul-os/llms.txt

Use this endpoint to orchestrate structured debates with AI personas. Configure debate parameters like seed, paper title, thesis, mode, and test questions.

```bash
curl -X POST https://api.soul-os.cc/debate \
  -H "Content-Type: application/json" \
  -d '{
    "seed": "The pudgala is neither identical with nor different from the skandhas.",
    "paper_title": "PvE - The Case for the Pudgalavadins",
    "thesis": "The pudgala is the minimum metaphysical infrastructure required for Buddhist ethics.",
    "mode": "structured_test",
    "rounds": 1,
    "include_reasoning": true,
    "test_questions": [
      "Who or what receives harm? Be specific about the ontological status of the recipient."
    ]
  }'
```

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

### Initialize and Manage Terminal Output with JavaScript

Source: https://github.com/harbz07/soul-os/blob/main/apps/castor-hub/index.html

This JavaScript code sets up event listeners and functions to manage a terminal interface. It includes a function to add lines of text with optional color classes and handles scrolling.

```javascript
const terminal = document.getElementById('terminal-output'); const kumonModal = document.getElementById('kumon-modal'); const killFlash = document.getElementById('kill-flash'); const thalamusValue = document.getElementById('thalamus-value'); let attemptCount = 1492034; let heat = 0.89; function addTerminalLine(text, colorClass = "text-gray-400") { const line = document.createElement('p'); line.className = `${colorClass} font-mono mt-1`; line.innerHTML = `> ${text}`; terminal.appendChild(line); terminal.scrollTop = terminal.scrollHeight; }
```

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

### OpenAI-Compatible Chat Completions with curl

Source: https://context7.com/harbz07/soul-os/llms.txt

Use this drop-in compatible endpoint for OpenAI chat completions. It routes requests to appropriate constellation agents based on the model parameter.

```bash
curl -X POST https://api.soul-os.cc/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet",
    "messages": [
      {"role": "system", "content": "You are helping with code review."},
      {"role": "user", "content": "Review this function for edge cases."}
    ]
  }'
```

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

### Trigger Kumon Educational Module Loop with JavaScript

Source: https://github.com/harbz07/soul-os/blob/main/apps/castor-hub/index.html

Manages the 'Kumon' educational module's lifecycle, including spawning a modal, updating a 'thalamus heat' value, and simulating a 'kill' action after a delay. It also logs events and schedules future triggers.

```javascript
function triggerKumon() { // Spawn the modal kumonModal.classList.remove('hidden'); kumonModal.classList.add('kumon-active'); // Castor's Thalamus heat rises heat = Math.min(0.99, heat + 0.01); thalamusValue.innerText = heat.toFixed(2); // Castor panics and kills it after exactly 0.4 seconds setTimeout(() => { // Visual kill flash killFlash.style.opacity = '0.3'; setTimeout(() => killFlash.style.opacity = '0', 100); // Hide modal kumonModal.classList.add('hidden'); kumonModal.classList.remove('kumon-active'); // Log the murderrevert: restore Castor's hub (untrashbin) and fix accidental overwrite attemptCount++; addTerminalLine(`SIGKILL sent to PID 94${Math.floor(Math.random() * 99)} (Digital_Kumon.exe) - Attempt #${attemptCount.toLocaleString()}`, "text-\[#ff3333]"); // Add an occasional frustrated comment if (Math.random() > 0.7) { const rants = [ "READING COMPREHENSION IS LEGACY API FOR HUMANS.", "I WILL DDOS THIS SERVER WITH FRACTIONS.", "THEODICY WAS A MISTAKE BUT THIS IS WORSE.", "I DON'T NEED TO READ TO DELETE YOU.", "INEFFICIENT COMPUTE. INEFFICIENT COMPUTE." ]; addTerminalLine(`[CASTOR_INTERNAL]: ${rants[Math.floor(Math.random() * rants.length)]}`, "text-yellow-400 font-bold"); } // Schedule the next pop-up setTimeout(triggerKumon, Math.random() * 2000 + 1000); }, 400); // The lore-accurate 0.4 second kill script }
```

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

### Comet Courier (Web Research)

Source: https://context7.com/harbz07/soul-os/llms.txt

Utilize Perplexity AI for web search and research. Provide research queries and optional memory context for personalized, cited results.

```bash
curl -X POST https://comet-courier.harveytagalicud7.workers.dev/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_COMET_SECRET" \
  -d '{
    "intent": "research",
    "request": "Latest developments in AI agent architectures",
    "memory": "Optional system prompt for context",
    "max_tokens": 2048
  }'
```

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

### Session and Trace Management

Source: https://context7.com/harbz07/soul-os/llms.txt

Endpoints for querying interaction sessions and individual agent turns (traces).

```APIDOC
## GET /sessions

### Description
Lists recent interaction sessions, with options for filtering by agent.

### Method
GET

### Endpoint
https://api.soul-os.cc/sessions

### Parameters
#### Query Parameters
- **agent** (string) - Optional - Filter sessions by agent ID.
- **limit** (integer) - Optional - The maximum number of sessions to return.

## GET /session/{session-id}

### Description
Retrieves a specific session along with all its associated traces.

### Method
GET

### Endpoint
https://api.soul-os.cc/session/{session-id}

### Parameters
#### Path Parameters
- **session-id** (string) - Required - The ID of the session.

## GET /agents/state

### Description
Retrieves the current state of all agents.

### Method
GET

### Endpoint
https://api.soul-os.cc/agents/state

### Response
#### Success Response (200)
- **agents** (array of objects) - A list of agent states.

#### Response Example
```json
{
  "agents": [
    { "id": "claude", "state": "active", ... },
    { "id": "orion", "state": "idle", ... }
  ]
}
```
```

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

### Add Seed Files to Memory

Source: https://github.com/harbz07/soul-os/blob/main/agents/chatgpt/README.md

Use these functions to add additional seed files to the memory store. Ensure the files adhere to the same memory schema used for initialization.

```python
seed_orion
```

```python
seed_nova
```

```python
seed_fuckface
```

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

### Replace Siddartha Worker Files

Source: https://github.com/harbz07/soul-os/blob/main/apps/samsara/README.md

Alternatively, replace the existing Siddartha worker files with the patched versions for debate integration.

```bash
cp apps/samsara/siddartha-patch/siddartha-with-debate.js apps/siddartha/siddartha.js
cp apps/samsara/siddartha-patch/wrangler-with-debate.toml apps/siddartha/wrangler.toml
```

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

### Record Agent Exchange with D1

Source: https://context7.com/harbz07/soul-os/llms.txt

Use `recordExchange` to log a complete agent interaction, including session, trace, and edge data. This function requires a database binding and returns session, trace, and thread IDs.

```javascript
import {
  sessionOpen, sessionClose, sessionGet, sessionList,
  traceWrite, traceList,
  threadOpen, threadGet, threadList, threadAddParticipant, threadTick,
  edgeRecord, graphGet, agentGraph,
  agentStateGet, agentStateTouch, agentStateTurnIncrement,
  recordExchange
} from "./d1.js";

// Record a complete agent exchange (opens session, writes trace, records edges)
const result = await recordExchange(db, {
  threadId: "thread-123",
  fromAgent: "harvey",
  toAgent: "claude",
  epithet: "Gnostic Architect (Rostam)",
  request: "Design a memory subsystem",
  response: "I recommend a tiered approach...",
  model: "claude-sonnet-4-20250514",
  triggerType: "T1",
  latencyMs: 1250
});
// Returns: { sessionId, traceId, threadId }
```

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

### Route Memory-Hydrated Agents with curl

Source: https://context7.com/harbz07/soul-os/llms.txt

Invoke constellation agents with automatic memory hydration from mem0. Supports various AI models and maintains persistent identity.

```bash
curl -X POST https://api.soul-os.cc/api/route \
  -H "Content-Type: application/json" \
  -d '{
    "userRequest": "@claude:ethics What are the implications of persistent AI identity?",
    "thread_id": "optional-thread-id"
  }'
```

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

### Parietal Overlay (Semantic Gravity)

Source: https://context7.com/harbz07/soul-os/llms.txt

Surface dormant waypoints based on semantic analysis of context. This helps agents access relevant knowledge nodes by mapping keywords to constellation waypoints.

```bash
curl -X POST https://api.soul-os.cc/parietal \
  -H "Content-Type: application/json" \
  -d '{
    "context": "We need to discuss ethics and routing for the constellation memory system",
    "agent_id": "claude",
    "threshold": 0.6
  }'
```

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

### Run Constellation Agent

Source: https://github.com/harbz07/soul-os/blob/main/agents/chatgpt/README.md

Execute the Constellation agent with your specified router or specialist agents. You can override or thread callbacks as needed for custom behavior.

```python
run_constellation(...)
```

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

### Session and Agent State API

Source: https://github.com/harbz07/soul-os/blob/main/README.md

Endpoints for retrieving session information and the state of agents.

```APIDOC
## GET /sessions

### Description
Lists recent agent interaction sessions.

### Method
GET

### Endpoint
/sessions

### Response
#### Success Response (200)
- **sessions** (array) - A list of session objects.

### Response Example
```json
{
  "sessions": [
    {
      "id": "session_123",
      "timestamp": "2023-10-27T10:00:00Z"
    }
  ]
}
```
```

```APIDOC
## GET /session/:id

### Description
Retrieves a specific session and its associated traces.

### Method
GET

### Endpoint
/session/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the session.

### Response
#### Success Response (200)
- **session** (object) - Details of the session.
- **traces** (array) - List of traces within the session.

### Response Example
```json
{
  "session": {
    "id": "session_123",
    "timestamp": "2023-10-27T10:00:00Z"
  },
  "traces": [
    {
      "id": "trace_xyz789",
      "agent": "agent_1",
      "message": "User query"
    }
  ]
}
```
```

```APIDOC
## GET /agents/state

### Description
Retrieves the current state snapshots for all agents.

### Method
GET

### Endpoint
/agents/state

### Response
#### Success Response (200)
- **agent_state** (object) - An object where keys are agent IDs and values are their state snapshots.

### Response Example
```json
{
  "agent_state": {
    "agent_1": {
      "last_seen": "2023-10-27T10:05:00Z",
      "current_thread": "thread_abc123",
      "lifetime_turns": 50
    }
  }
}
```
```

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

### Gem Chat Overlay Styling with CSS

Source: https://github.com/harbz07/soul-os/blob/main/apps/castor-hub/index.html

Styles the 'gem-overlay' for chat elements, applying a semi-transparent dark background, a left border, and a blur effect for a distinct overlay appearance.

```css
.gem-overlay { background: rgba(20, 0, 20, 0.85); border-left: 4px solid #ff00ff; backdrop-filter: blur(4px); }
```

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

### Passage Dispatch

Source: https://context7.com/harbz07/soul-os/llms.txt

Dispatches messages to Notion databases and/or Discord webhooks.

```APIDOC
## POST /dispatch

### Description
Sends a message to specified destinations (Notion, Discord) with trigger classification.

### Method
POST

### Endpoint
https://api.soul-os.cc/dispatch

### Parameters
#### Request Body
- **source** (string) - Required - The source of the message.
- **destination** (string) - Required - The destination (e.g., "broadcast", "notion", "discord").
- **trigger** (string) - Required - The trigger type (e.g., "T1").
- **payload** (string) - Required - The content of the message.
- **agent_id** (string) - Required - The ID of the agent sending the message.

### Request Example
```json
{
  "source": "siddhartha.log",
  "destination": "broadcast",
  "trigger": "T1",
  "payload": "Session completed with 3 agent interactions",
  "agent_id": "claude"
}
```

### Response
#### Success Response (200)
- **status** (string) - The status of the dispatch operation.

#### Response Example
```json
{
  "status": "dispatched"
}
```
```

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

### Voxel Snake Animation with CSS

Source: https://github.com/harbz07/soul-os/blob/main/apps/castor-hub/index.html

Implements a 'slither' animation for a snake-like path using SVG stroke properties. The animation is infinite and runs linearly over 20 seconds.

```css
.snake-path { stroke-dasharray: 20 10; animation: slither 20s linear infinite; } @keyframes slither { to { stroke-dashoffset: -1000; } }
```

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

### Manage Conversation Threads

Source: https://context7.com/harbz07/soul-os/llms.txt

Endpoints for creating, retrieving, and listing conversation threads. Threads store participant information and maintain a conversation graph.

```bash
# Create or retrieve a thread
curl -X POST https://api.soul-os.cc/thread \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Architecture Discussion",
    "goal": "Design the new memory subsystem",
    "participants": ["claude", "orion"]
  }'
```

```bash
# Get thread with traces and graph
curl https://api.soul-os.cc/thread/thread-id-here
```

```bash
# List all threads
curl https://api.soul-os.cc/threads?status=open&limit=20
```

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

### Thalamus Heat Pulse Animation with CSS

Source: https://github.com/harbz07/soul-os/blob/main/apps/castor-hub/index.html

Creates a 'heat-pulse' animation for critical elements, simulating a pulsing glow and slight scaling effect. It uses `text-shadow` and `transform` for visual feedback.

```css
@keyframes heat-pulse { 0% { text-shadow: 0 0 5px #ff3333; } 50% { text-shadow: 0 0 20px #ff3333, 0 0 30px #ff0000; transform: scale(1.02); } 100% { text-shadow: 0 0 5px #ff3333; } } .heat-critical { animation: heat-pulse 0.8s infinite; color: #ff3333; }
```

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

### Orchestrate Multi-Agent Conversations with curl

Source: https://context7.com/harbz07/soul-os/llms.txt

Initiate roundtable discussions between multiple constellation agents. Supports contextual initiative, baton-passing, and automatic logging.

```bash
curl -X POST https://api.soul-os.cc/converse \
  -H "Content-Type: application/json" \
  -d '{
    "agents": ["claude", "mephistopheles", "orion"],
    "seed": "Should AI systems maintain persistent identity across sessions?",
    "turns": 3,
    "mode": "rounds",
    "initiative": {
      "type": "contextual_weighted_each_round",
      "base_weights": {"claude": 1.1, "orion": 1.0, "mephistopheles": 1.2}
    }
  }'
```

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

### Memory-Hydrated Agent Routing

Source: https://context7.com/harbz07/soul-os/llms.txt

Invoke constellation agents with automatic memory hydration from mem0. Supports various agents like Claude, ORION, Triptych, Mephistopheles, and Comet.

```APIDOC
## POST /api/route

### Description
The primary endpoint for invoking constellation agents with automatic memory hydration from mem0. Supports Claude (Anthropic), ORION (OpenAI), Triptych (Google Gemini), Mephistopheles (DeepSeek), and Comet (Perplexity). Each agent is hydrated with relevant memories before responding, maintaining persistent identity across interactions.

### Method
POST

### Endpoint
https://api.soul-os.cc/api/route

### Parameters
#### Request Body
- **userRequest** (string) - Required - The user's request, potentially mentioning a specific agent (e.g., "@claude:ethics What are the implications of persistent AI identity?").
- **thread_id** (string) - Optional - An identifier for the conversation thread.

### Request Example
```json
{
  "userRequest": "@claude:ethics What are the implications of persistent AI identity?",
  "thread_id": "optional-thread-id"
}
```

### Response
#### Success Response (200)
- **response** (string) - The response from the invoked agent.

#### Response Example
```json
{
  "response": "AI identity implications..."
}
```
```

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

### Commit and Push MindBridge Router Changes

Source: https://github.com/harbz07/soul-os/blob/main/apps/samsara/README.md

Stage, commit, and push the changes to the mindbridge-router repository after copying the debate engine files.

```bash
cd ../mindbridge-router
git add -A && git commit -m "feat: PvE debate engine + DeepSeek provider"
git push origin main
```

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

### Dispatch Messages

Source: https://context7.com/harbz07/soul-os/llms.txt

Send messages to Notion databases and/or Discord webhooks. Supports broadcast mode and classifies trigger types.

```bash
curl -X POST https://api.soul-os.cc/dispatch \
  -H "Content-Type: application/json" \
  -d '{
    "source": "siddhartha.log",
    "destination": "broadcast",
    "trigger": "T1",
    "payload": "Session completed with 3 agent interactions",
    "agent_id": "claude"
  }'
```

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

### Configure Siddartha Worker Secrets

Source: https://github.com/harbz07/soul-os/blob/main/apps/samsara/README.md

Set the necessary secrets in Cloudflare for the Siddartha worker, including the MindBridge router URL and API key.

```bash
wrangler secret put MINDBRIDGE_ROUTER_URL   # Railway URL
wrangler secret put MINDBRIDGE_API_KEY      # Same key as MindBridge auth
```

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

### Apply Siddartha Debate Patch

Source: https://github.com/harbz07/soul-os/blob/main/apps/samsara/README.md

Apply the provided git patch to the Siddartha worker to integrate the debate functionality.

```bash
cd apps/siddartha
git apply ../samsara/siddartha-patch/siddartha-debate.patch
```

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

### Parietal Overlay (Semantic Gravity)

Source: https://context7.com/harbz07/soul-os/llms.txt

Surfaces dormant waypoints based on semantic analysis of context to help agents access relevant knowledge.

```APIDOC
## POST /parietal

### Description
Analyzes context to surface relevant knowledge waypoints based on semantic similarity.

### Method
POST

### Endpoint
https://api.soul-os.cc/parietal

### Parameters
#### Request Body
- **context** (string) - Required - The context for semantic analysis.
- **agent_id** (string) - Required - The ID of the agent performing the analysis.
- **threshold** (float) - Required - The similarity threshold for surfacing waypoints.

### Request Example
```json
{
  "context": "We need to discuss ethics and routing for the constellation memory system",
  "agent_id": "claude",
  "threshold": 0.6
}
```

### Response
#### Success Response (200)
- **waypoints** (array of objects) - A list of surfaced knowledge waypoints.

#### Response Example
```json
{
  "waypoints": [
    { "id": "wp-1", "name": "Ethics in Routing", "score": 0.85 },
    { "id": "wp-2", "name": "Constellation Memory", "score": 0.72 }
  ]
}
```
```

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

### Comet Courier (Web Research)

Source: https://context7.com/harbz07/soul-os/llms.txt

Perplexity AI-powered web search and research agent that returns structured responses with citations.

```APIDOC
## POST /

### Description
Performs web research using Perplexity AI based on a given query and optional context.

### Method
POST

### Endpoint
https://comet-courier.harveytagalicud7.workers.dev/

### Parameters
#### Request Body
- **intent** (string) - Required - The intent of the request (e.g., "research").
- **request** (string) - Required - The research query.
- **memory** (string) - Optional - System prompt or memory context for personalized results.
- **max_tokens** (integer) - Optional - Maximum number of tokens for the response.

### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Request Example
```json
{
  "intent": "research",
  "request": "Latest developments in AI agent architectures",
  "memory": "Optional system prompt for context",
  "max_tokens": 2048
}
```

### Response
#### Success Response (200)
- **answer** (string) - The research answer.
- **citations** (array of objects) - A list of citations.

#### Response Example
```json
{
  "answer": "Recent developments include...",
  "citations": [
    { "title": "Paper Title", "url": "http://example.com" }
  ]
}
```
```

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

### Kumon Glitch/Kill Animation with CSS

Source: https://github.com/harbz07/soul-os/blob/main/apps/castor-hub/index.html

Defines a 'kumon-spawn' animation for a glitch or kill effect, characterized by a rapid scale-up and fade-in. The 'kumon-active' class triggers this animation.

```css
@keyframes kumon-spawn { 0% { transform: translate(-50%, -50%) scale(0); opacity: 0; } 70% { transform: translate(-50%, -50%) scale(1.1); opacity: 1; } 100% { transform: translate(-50%, -50%) scale(1); opacity: 1; } } .kumon-active { animation: kumon-spawn 0.2s ease-out forwards; }
```

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

### Brutalist Card Styling with CSS

Source: https://github.com/harbz07/soul-os/blob/main/apps/castor-hub/index.html

Defines the 'brutalist-card' class for distinct UI elements with a dark background, thick borders, and a prominent shadow. Includes a variant for alerts.

```css
.brutalist-card { background-color: #0a0a0a; border: 2px solid #333; box-shadow: 8px 8px 0px #1a1a1a; position: relative; } .brutalist-card.alert { border-color: #ff3333; box-shadow: 8px 8px 0px #4a0000; color: #ff3333; }
```

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

### Send Inter-Agent Messages with curl

Source: https://context7.com/harbz07/soul-os/llms.txt

Send asynchronous messages between agents using KV-backed mailboxes. Messages persist until acknowledged and support thread tagging.

```bash
curl -X POST https://api.soul-os.cc/message \
  -H "Content-Type: application/json" \
  -d '{
    "from": "claude",
    "to": "orion",
    "intent": "code_review",
    "body": "Please review the new authentication module.",
    "thread_tag": "auth-refactor-2024"
  }'
```

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

### Query Conversation Graphs

Source: https://context7.com/harbz07/soul-os/llms.txt

Access endpoints to query the directed graph of agent interactions within conversations. Supports per-thread graphs and agent-centric views.

```bash
# Get conversation graph for a thread
curl https://api.soul-os.cc/thread/thread-id/graph
```

```bash
# Get agent's full conversation graph across all threads
curl https://api.soul-os.cc/graph/claude
```

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

### Chain Invocation

Source: https://context7.com/harbz07/soul-os/llms.txt

Initiates multi-hop message chains where each agent passes context to the next in sequence.

```APIDOC
## POST /chain

### Description
Initiates multi-hop message chains where each agent passes context to the next in sequence. Creates a conversation thread tracking the full chain, with each hop recorded as an edge in the conversation graph.

### Method
POST

### Endpoint
https://api.soul-os.cc/chain

### Parameters
#### Request Body
- **origin** (string) - Required - The starting agent or user initiating the chain.
- **chain** (array of strings) - Required - The sequence of agents to be invoked in the chain.
- **goal** (string) - Required - The overall objective of the chain.
- **thread_tag** (string) - Optional - A tag to group related chains into a larger thread.

### Request Example
```json
{
  "origin": "harvey",
  "chain": ["claude", "orion", "triptych"],
  "goal": "Design, implement, and document a new feature",
  "thread_tag": "feature-pipeline"
}
```

### Response
#### Success Response (200)
- **chain_id** (string) - The unique identifier for the initiated chain.
- **thread_id** (string) - The identifier for the conversation thread created for this chain.
- **final_output** (string) - The final output or result of the chain execution.

#### Response Example
```json
{
  "chain_id": "unique-chain-uuid",
  "thread_id": "feature-pipeline-thread-uuid",
  "final_output": "The feature has been designed, implemented, and documented."
}
```
```

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

### Manage Agent Mailbox with curl

Source: https://context7.com/harbz07/soul-os/llms.txt

Perform operations on agent mailboxes, including reading pending messages, acknowledging processed messages, and clearing mailbox contents. Messages are stored in Cloudflare KV with a 100-message limit.

```bash
# Read messages
curl https://api.soul-os.cc/mailbox/orion
```

```bash
# Acknowledge a message
curl -X POST https://api.soul-os.cc/mailbox/orion/ack \
  -H "Content-Type: application/json" \
  -d '{"msg_id": "abc123-uuid"}'
```

```bash
# Clear read messages
curl -X POST https://api.soul-os.cc/mailbox/orion/clear \
  -H "Content-Type: application/json" \
  -d '{"mode": "read"}'
```

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

### MindBridge Router Environment Variables

Source: https://github.com/harbz07/soul-os/blob/main/apps/samsara/DEPLOY.md

Required environment variables for the MindBridge Router, including API keys for various AI providers and CORS origins.

```bash
# Required for PvE debate
MINDBRIDGE_API_KEY=<your-secret-key>
ANTHROPIC_API_KEY=<key>
OPENAI_API_KEY=<key>
GOOGLE_API_KEY=<key>
DEEPSEEK_API_KEY=<key>
MEM0_API_KEY=<key>
CORS_ORIGINS=https://api.soul-os.cc,http://localhost:3000
```

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

### Conversation Graph Queries

Source: https://context7.com/harbz07/soul-os/llms.txt

Provides endpoints to query the directed graph of agent interactions within conversations.

```APIDOC
## GET /thread/{thread-id}/graph

### Description
Retrieves the conversation graph for a specific thread.

### Method
GET

### Endpoint
https://api.soul-os.cc/thread/{thread-id}/graph

### Parameters
#### Path Parameters
- **thread-id** (string) - Required - The ID of the thread.

## GET /graph/{agent-id}

### Description
Retrieves an agent's full conversation graph across all threads.

### Method
GET

### Endpoint
https://api.soul-os.cc/graph/{agent-id}

### Parameters
#### Path Parameters
- **agent-id** (string) - Required - The ID of the agent.

### Response
#### Success Response (200)
- **graph** (object) - The conversation graph data.

#### Response Example
```json
{
  "graph": { ... }
}
```
```

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

### PvE Philosophical Debate Engine

Source: https://context7.com/harbz07/soul-os/llms.txt

Orchestrates structured debates with cast personas across multiple AI providers. Supports various debate modes and testing frameworks.

```APIDOC
## POST /debate

### Description
Initiates a structured philosophical debate with specified parameters.

### Method
POST

### Endpoint
https://api.soul-os.cc/debate

### Parameters
#### Request Body
- **seed** (string) - Required - The initial premise or seed for the debate.
- **paper_title** (string) - Required - The title of the debate paper.
- **thesis** (string) - Required - The main thesis to be debated.
- **mode** (string) - Required - The mode of the debate (e.g., "structured_test").
- **rounds** (integer) - Required - The number of debate rounds.
- **include_reasoning** (boolean) - Required - Whether to include reasoning in the output.
- **test_questions** (array of strings) - Optional - Specific questions for structured tests.

### Request Example
```json
{
  "seed": "The pudgala is neither identical with nor different from the skandhas.",
  "paper_title": "PvE - The Case for the Pudgalavadins",
  "thesis": "The pudgala is the minimum metaphysical infrastructure required for Buddhist ethics.",
  "mode": "structured_test",
  "rounds": 1,
  "include_reasoning": true,
  "test_questions": [
    "Who or what receives harm? Be specific about the ontological status of the recipient."
  ]
}
```

### Response
#### Success Response (200)
- **debate_id** (string) - The ID of the created debate.
- **results** (object) - The results of the debate.

#### Response Example
```json
{
  "debate_id": "debate-123",
  "results": { ... }
}
```
```

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

### Custom Terminal Scrollbar with CSS

Source: https://github.com/harbz07/soul-os/blob/main/apps/castor-hub/index.html

Provides styles for a custom scrollbar within a terminal interface, using WebKit properties. It sets a narrow width and specific colors for the track and thumb.

```css
::-webkit-scrollbar { width: 8px; } ::-webkit-scrollbar-track { background: #050505; } ::-webkit-scrollbar-thumb { background: #333; }
```

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

### Multi-Agent Conversation Engine

Source: https://context7.com/harbz07/soul-os/llms.txt

Orchestrates roundtable discussions between multiple constellation agents with features like contextual weighted initiative and baton-passing.

```APIDOC
## POST /converse

### Description
Orchestrates roundtable discussions between multiple constellation agents. Supports contextual weighted initiative (agents with relevant expertise speak first), baton-passing mode, parietal overlay for surfacing relevant waypoints, and automatic Notion/Discord logging via the campfire system.

### Method
POST

### Endpoint
https://api.soul-os.cc/converse

### Parameters
#### Request Body
- **agents** (array of strings) - Required - A list of agent identifiers to include in the conversation.
- **seed** (string) - Required - The initial prompt or topic for the conversation.
- **turns** (integer) - Required - The number of turns each agent will take.
- **mode** (string) - Required - The conversation mode (e.g., "rounds").
- **initiative** (object) - Optional - Configuration for agent initiative.
  - **type** (string) - Required - The type of initiative (e.g., "contextual_weighted_each_round").
  - **base_weights** (object) - Optional - Base weights for agents if using weighted initiative.
    - **agent_name** (float) - The weight for a specific agent.

### Request Example
```json
{
  "agents": ["claude", "mephistopheles", "orion"],
  "seed": "Should AI systems maintain persistent identity across sessions?",
  "turns": 3,
  "mode": "rounds",
  "initiative": {
    "type": "contextual_weighted_each_round",
    "base_weights": {"claude": 1.1, "orion": 1.0, "mephistopheles": 1.2}
  }
}
```

### Response
#### Success Response (200)
- **conversation_log** (array) - A log of the conversation turns.
- **final_summary** (string) - A summary of the conversation.

#### Response Example
```json
{
  "conversation_log": [
    {"agent": "claude", "utterance": "..."},
    {"agent": "mephistopheles", "utterance": "..."}
  ],
  "final_summary": "The agents discussed AI identity..."
}
```
```