### Quick Start SKILL.md Example

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(features)/skills.mdx

A minimal SKILL.md file for a new skill, demonstrating the required frontmatter and basic instructions.

```markdown
---
name: my-skill
description: Does something useful.
---

# My Skill

When the user asks for X, do Y.

Use curl to fetch data:

```bash
curl https://api.example.com/data
```

Parse the JSON response and format it as a table.
```

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

### Reference Files Example

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(features)/skills.mdx

Examples of documentation files that can be placed in a skill's 'references' directory for on-demand loading.

```bash
references/api_docs.md
references/schema.md
references/examples.md
```

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

### Asset Files Example

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(features)/skills.mdx

Examples of asset files that can be included in a skill's 'assets' directory for use in output.

```bash
assets/template.html
assets/logo.png
assets/boilerplate/
```

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

### Install Skill from File (CLI)

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(features)/skills.mdx

Install a skill directly from a local `.skill` file using the `spacebot skill install` command.

```bash
spacebot skill install path/to/skill.skill
```

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

### Development Setup for Desktop App

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(getting-started)/desktop.mdx

Starts the spacebot server and the desktop app with hot-reloading. The Tauri window loads from the Vite dev server, which proxies API requests to the running Spacebot instance.

```bash
# Start spacebot server (from source or installed) -- needed for the API
cargo run -- start -f -d

# In another terminal: start the desktop app
just desktop-dev
# or: cd desktop && bun run tauri:dev
```

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

### List Installed Binaries

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(configuration)/sandbox.mdx

The GET /agents/tools API endpoint returns a JSON object listing installed binaries, their sizes, and modification times. This is useful for dashboard observability.

```json
{
  "tools_bin": "/data/tools/bin",
  "binaries": [
    { "name": "gh", "size": 1234567, "modified": "2026-02-20T14:15:00Z" },
    { "name": "ripgrep", "size": 3456789, "modified": "2026-02-15T10:30:00Z" }
  ]
}
```

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

### List Installed Skills for an Agent

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(features)/skills.mdx

Use this GET request to retrieve a list of all skills currently installed for a specific agent. The response includes details like skill name, description, and file path.

```json
{
  "skills": [
    {
      "name": "pdf",
      "description": "Create, edit, and extract content from PDF files",
      "file_path": "/path/to/skills/pdf/SKILL.md",
      "base_dir": "/path/to/skills/pdf",
      "source": "instance"
    }
  ]
}
```

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

### Discord Rich Help Output Example

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/design-docs/slash-commands.md

Example of how the `/help` command output is formatted for rich platforms like Discord, grouped by category with command names and descriptions.

```text
Session
  /new          Start a new conversation
  /retry        Resend the last message
  /stop         Cancel active workers

Memory
  /memory       Search or list memories
  /remember     Save something to memory
...
```

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

### Install Skill

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(features)/skills.mdx

Installs a skill from a GitHub repository for a specified agent.

```APIDOC
## POST /api/agents/skills/install

### Description
Install a skill from GitHub.

### Method
POST

### Endpoint
/api/agents/skills/install

### Parameters
#### Request Body
- **agent_id** (string) - Required - The ID of the agent to install the skill for.
- **spec** (string) - Required - The GitHub repository path of the skill (e.g., "vercel-labs/agent-skills").
- **instance** (boolean) - Optional - Whether to install as an instance skill.

### Request Example
```json
{
  "agent_id": "my-agent",
  "spec": "vercel-labs/agent-skills",
  "instance": false
}
```

### Response
#### Success Response (200)
- **installed** (array) - A list of the names of the skills successfully installed.

### Response Example
```json
{
  "installed": [
    "vercel-react-best-practices",
    "web-design-guidelines",
    "composition-patterns"
  ]
}
```
```

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

### Install Skill Response

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(features)/skills.mdx

The response to a successful skill installation request lists the names of the skills that were installed.

```json
{
  "installed": [
    "vercel-react-best-practices",
    "web-design-guidelines",
    "composition-patterns"
  ]
}
```

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

### Executable Scripts Example

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(features)/skills.mdx

Examples of executable scripts that can be included within a skill's 'scripts' directory.

```bash
scripts/rotate_pdf.py
scripts/merge_pdfs.sh
scripts/extract_images.py
```

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

### Worker System Prompt Instruction for Persistent Binaries

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/design-docs/sandbox-hardening.md

This instruction is added to the worker's system prompt to guide agents on installing tools durably. It clarifies that binaries installed via package managers on the root filesystem are ephemeral, and to ensure persistence, binaries should be downloaded or copied into `/data/tools/bin`.

```text
Persistent binary directory: /data/tools/bin (on PATH, survives restarts and rollouts)
Binaries installed via package managers (apt, brew, etc.) land on the root filesystem
which is ephemeral on hosted instances — they disappear on rollouts. To install a tool
durably, download or copy the binary into /data/tools/bin.
```

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

### Telegram Compact Help Output Example

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/design-docs/slash-commands.md

Example of how the `/help` command output is formatted for text-based platforms like Telegram, providing a compact list of commands and their brief descriptions.

```text
/new — new conversation
/retry — resend last message
/memory [query] — search memories
/tasks [status] — list tasks
/help — show this
```

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

### Run Development Server

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/README.md

Commands to start the Next.js development server using npm, pnpm, or yarn.

```bash
npm run dev
# or
pnpm dev
# or
yarn dev
```

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

### Install Skills from Repository (CLI)

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(features)/skills.mdx

Install skills from a GitHub repository using the `spacebot skill add` command. Supports installing all skills or specific ones.

```bash
# Install all skills from a repo
spacebot skill add vercel-labs/agent-skills

# Install a specific skill from a repo
spacebot skill add anthropics/skills/pdf

# Install to instance-level (shared across all agents)
spacebot skill add vercel-labs/agent-skills --instance

# Install to a specific agent
spacebot skill add remotion-dev/skills --agent my-agent
```

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

### Screenshot File Path Example

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(features)/browser.mdx

Example of a screenshot file path. The actual path is returned in the tool output and can be configured via `screenshot_dir`.

```shell
~/.spacebot/agents/main/data/screenshots/screenshot_20260212_143052_123.png
```

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

### Start Spacebot Development Server

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(getting-started)/quickstart.mdx

Navigate to the interface directory and run the Vite development server. This starts the UI and proxies API requests to the Spacebot development instance.

```bash
cd interface && bun run dev
```

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

### Install Spacebot Binary

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(getting-started)/quickstart.mdx

Installs the Spacebot binary from a local source directory after cloning the repository and optionally building the web UI.

```bash
cargo install --path .
```

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

### Install a Skill from GitHub

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(features)/skills.mdx

Send a POST request to this endpoint to install a skill from a GitHub repository. Specify the agent ID and the skill's spec (e.g., 'vercel-labs/agent-skills'). The 'instance' field determines if it's an instance-level skill.

```json
{
  "agent_id": "my-agent",
  "spec": "vercel-labs/agent-skills",
  "instance": false
}
```

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

### Development Dependencies Installation (Bun)

Source: https://github.com/spacedriveapp/spacebot/blob/main/interface/PLAN.md

Install development-specific dependencies for Tailwind CSS, TypeScript, Vite, and related plugins.

```bash
4. Install dev deps: `tailwindcss@3`, `postcss`, `autoprefixer`, `@tailwindcss/forms`, `@tailwindcss/typography`, `tailwindcss-animate`, `tailwindcss-radix`, `sass`, `typescript`, `@types/react`, `@types/react-dom`, `@vitejs/plugin-react`, `vite`
```

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

### Channel Prompt Assembly Example

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(core)/prompts.mdx

An example of how various Jinja components are assembled to form the complex channel system prompt. It includes conditional sections for context and skills.

```jinja
{%- if identity_context %}
{{ identity_context }}
{%- endif %}

{%- if memory_bulletin %}
## Memory Context

{{ memory_bulletin }}
{%- endif %}

[Base channel instructions...]

{%- if skills_prompt %}
{{ skills_prompt }}
{%- endif %}

{{ worker_capabilities }}

{%- if conversation_context %}
## Conversation Context

{{ conversation_context }}
{%- endif %}

{%- if status_text %}
## Current Status

{{ status_text }}
{%- endif %}
```

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

### UI Dependencies Installation (Bun)

Source: https://github.com/spacedriveapp/spacebot/blob/main/interface/PLAN.md

Install UI component library dependencies, ensuring compatibility with Spacedrive's design system.

```bash
3. Install UI deps (matching Spacedrive): `@radix-ui/*`, `@react-spring/web`, `class-variance-authority`, `clsx`, `sonner`, `@phosphor-icons/react`, `react-hook-form`, `@hookform/resolvers`, `zod`, `framer-motion`, `valtio`, `use-debounce`, `react-resizable-layout`, `react-loading-icons`, `rooks`, `@fontsource/ibm-plex-sans`
```

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

### Core Dependencies Installation (Bun)

Source: https://github.com/spacedriveapp/spacebot/blob/main/interface/PLAN.md

Install essential dependencies for a React application using Bun, including state management and data fetching libraries.

```bash
2. Install core deps: `react`, `react-dom`, `@tanstack/react-query`, `@tanstack/react-router` (or `react-router-dom`), `openapi-fetch`, `openapi-typescript`
```

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

### Slack Platform Metadata Example

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(core)/channels.mdx

Example JSON structure for storing Slack-specific metadata within the `platform_meta` column.

```json
{
  "slack_workspace_id": "T01ABC",
  "slack_channel_id": "C02DEF",
  "slack_thread_ts": "1234567890.123456"
}
```

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

### Manual Single-Instance Deploy with Fly.io

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(getting-started)/docker.mdx

Example commands for deploying Spacebot as a single instance using Fly.io.

```APIDOC
## Manual Single-Instance Deploy with Fly.io

```bash
fly launch --image ghcr.io/spacedriveapp/spacebot:latest
fly volumes create spacebot_data --size 5
fly secrets set ANTHROPIC_API_KEY="sk-ant-..."
fly deploy
```
```

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

### Bun Initialization in Interface Directory

Source: https://github.com/spacedriveapp/spacebot/blob/main/interface/PLAN.md

Initialize a new project in the `interface/` directory using Bun.

```bash
1. `bun init` in `interface/`
```

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

### Create and Render Prompts with PromptEngine

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(core)/prompts.mdx

Demonstrates how to initialize the PromptEngine and render static or variable-populated prompts. Ensure the engine is created once at startup.

```rust
let engine = PromptEngine::new("en")?;

// Render a static template
let worker_prompt = engine.render_static("worker")?;

// Render with variables
let channel_prompt = engine.render_channel_prompt(
    Some(identity_context),      // Option<String>
    Some(memory_bulletin),       // Option<String>
    Some(skills_prompt),         // Option<String>
    worker_capabilities,         // String
    conversation_context,        // Option<String>
    status_text                  // Option<String>
)?;
```

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

### API Response for /api/logs

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/design-docs/live-logs.md

Example JSON structure for the response of the GET /api/logs endpoint, which returns a list of recent log entries.

```json
{
  "entries": [
    {
      "timestamp": "2026-02-19T10:30:45.123Z",
      "level": "INFO",
      "target": "spacebot::agent::channel",
      "message": "processing inbound message"
    }
  ]
}
```

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

### API Response for Aggregated Usage

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/design-docs/token-usage-tracking.md

Example JSON response structure for the GET /api/usage endpoint, showing total aggregated token usage and breakdowns by agent, model, or day.

```json
{
  "total": {
    "input_tokens": 1240000,
    "output_tokens": 380000,
    "cache_read_tokens": 890000,
    "cache_write_tokens": 120000,
    "reasoning_tokens": 45000,
    "request_count": 1840,
    "estimated_cost_usd": 4.82,
    "cost_status": "estimated"
  },
  "by_agent": [...],
  "by_model": [...],
  "by_day": [...] 
}
```

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

### Agent Creation Flow Example

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/design-docs/agent-factory.md

Illustrates a typical user interaction for creating a new agent, showing the conversational steps and the structured content presented to the user for choices.

```text
User: "I need an agent that handles customer support tickets from email"

Agent: [branch → factory_search_context("company info", "support process")]
       [branch → factory_list_presets()]

Agent: "Found context about your company. Here are starting points:"
       [structured: SelectCards — Customer Support, Community Manager,
        Executive Assistant, with relevance tags]

User: [clicks Customer Support]

Agent: [branch → factory_load_preset("customer-support")]
       "How should this agent communicate?"
       [structured: Buttons — "Professional & formal", "Friendly & warm",
        "Match the customer's tone", "Same as {main_agent}"]

User: "Friendly but professional. We're a dev tools company."

Agent: "Should it handle everything or escalate some things?"
       [structured: Buttons — "Handle everything", "Escalate billing/refunds",
        "Escalate complex issues", "Custom rules"]

User: "Escalate billing, refunds, and anything legal."

Agent: "Where does it fit in the org?"
       [structured: Buttons — "Reports to main", "Peer of main",
        "Independent"]

User: [clicks "Reports to main"]

Agent: [factory_create_agent with synthesized identity files]
       [structured: Summary — ID, role, personality, escalation rules,
        model, org position, with "Refine" and "Looks good" buttons]

User: "Looks good!"

Agent: "support is live. Route email to it from Settings > Bindings."
```

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

### Spacebot Startup Sequence

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(core)/architecture.mdx

Illustrates the step-by-step process from command-line argument parsing to the main event loop, including initialization of various managers and agent-specific setups. Long-running loops respect shutdown signals.

```text
CLI (clap) → parse args
  → Load config.toml
  → Optionally daemonize (Unix socket for IPC)
  → Build tokio runtime
  → Initialize tracing + OpenTelemetry (optional)
  → run()
    → Start IPC server (stop/status commands)
    → Start Axum API server
    → Initialize shared resources:
        LlmManager, EmbeddingModel, PromptEngine, agent links
    → For each agent:
        → Run SQLite migrations
        → Initialize MemoryStore, LanceDB tables
        → Load RuntimeConfig + identity + skills
    → Best-effort startup warmup pass (bounded wait)
    → Initialize MessagingManager (start all platform adapters)
    → Initialize CronScheduler
    → Start Cortex loops (warmup, bulletin fallback, association, ready-task)
        → Register agent in active agents map
    → Enter main event loop (tokio::select!)
        → Inbound messages → route to Channel instances
        → Agent registration/removal
        → Provider setup events
        → Shutdown signal → graceful shutdown
```

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

### Fire-and-Forget Worker Example

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(features)/workers.mdx

Illustrates the lifecycle of a fire-and-forget worker. The channel spawns the worker, receives a unique ID, and later gets a `WorkerComplete` event with the task's result.

```text
Channel: "spawn_worker: run the test suite"
  → Worker starts, runs tests
  → Worker returns: "12 passed, 0 failed"
  → Channel sees result, replies to user
```

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

### Rust API Module Setup

Source: https://github.com/spacedriveapp/spacebot/blob/main/interface/PLAN.md

Set up the axum Router, state management, and middleware for the API module. This includes starting the HTTP server and handling embedded static files.

```rust
- `src/api.rs` (new module root) — axum Router, state, middleware
  - `src/api/server.rs` — `start_http_server()` returns a shutdown handle, serves on configurable port (default `19898`)
  - `src/api/static_files.rs` — serve embedded frontend assets with SPA fallback (all non-API routes return `index.html`)
```

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

### Recursive Investigation Loop Example

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/design-docs/production-worker-failures.md

This log demonstrates a worker getting stuck in a loop, continuously gathering more data without synthesizing findings or reporting progress, eventually leading to a context limit error.

```text
[0] User: Search for SQL in ~/app that uses @limit
[1] Assistant: Tool: find ~/app -name "*.ts" | head -20
[2] User: Result: 10,666 files found  
[3] Assistant: Tool: grep -r "@limit" ~/app --include="*.ts"
[4] User: Result: 50KB of matches across node_modules and .next/
[5] Assistant: Tool: grep -r "@limit" ~/app/src --include="*.ts"
[6] User: Result: 20 matches
[7] Assistant: Tool: read file ~/app/src/backend/db/query.ts
[8] User: Result: 200 lines of code
[9] Assistant: Tool: read file ~/app/src/backend/db/index.ts  
[10] User: Result: 150 lines of code
[11] Assistant: Tool: shell: grep -n "LIMIT" ~/app/src/backend/db/*.ts
[12] User: Result: 100 lines of grep output
[13] Assistant: Tool: file: read ~/app/src/data/schema.ts
[14] User: Result: 300 lines of schema
[15] Assistant: [Context limit exceeded error]
```

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

### Project Directory Structure Example

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/design-docs/projects.md

Illustrates a typical project root directory containing multiple repositories and worktrees.

```treeview
~/Projects/spacebot/            ← project root
├── spacebot/                   ← repo (core agent)
├── spacebot-platform/          ← repo (control plane)
├── spacebot-dash/              ← repo (dashboard)
├── spacebot-web/               ← repo (marketing site)
├── feat-projects/              ← worktree of spacebot/ for this feature
└── fix-auth-bug/               ← worktree of spacebot-platform/
```

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

### Initializing McpManager and Connecting

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/design-docs/mcp.md

Demonstrates the initialization of McpManager and the initiation of connections to all configured MCP servers during agent startup. This occurs after configuration resolution and before spawning communication channels.

```rust
let mcp_manager = McpManager::new(resolved_config.mcp.clone());
mcp_manager.connect_all().await;
```

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

### Example Context Injection Formatting

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(core)/memory.mdx

Illustrates how memories are formatted and injected into the system prompt for channels, grouping them by type for clarity.

```markdown
## Identity
- My name is Spacebot
- James is a software engineer who works on SpaceDrive

## Recent Context
- We decided to use SQLite for the prototype (2 days ago)
- James prefers short, direct responses (preference)
```

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

### Instance Database Structure

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/design-docs/multi-agent-communication-graph.md

Illustrates the file structure of the instance directory, highlighting the location of the new shared `instance.db` and existing per-agent databases.

```text
{instance_dir}/
    instance.db              ← new: agent_links, shared_notes (future)
    agents/
        agent-a/
            data/spacebot.db ← existing per-agent database
        agent-b/
            data/spacebot.db
```

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

### List Installed Skills

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(features)/skills.mdx

Retrieves a list of all skills currently installed for a specific agent.

```APIDOC
## GET /api/agents/skills?agent_id={id}

### Description
List all installed skills for an agent.

### Method
GET

### Endpoint
/api/agents/skills?agent_id={id}

### Parameters
#### Query Parameters
- **agent_id** (string) - Required - The ID of the agent whose skills are to be listed.

### Response
#### Success Response (200)
- **skills** (array) - A list of installed skills, each with name, description, file_path, base_dir, and source.
  - **name** (string) - The name of the skill.
  - **description** (string) - A brief description of the skill.
  - **file_path** (string) - The file path to the skill's main documentation.
  - **base_dir** (string) - The base directory of the skill.
  - **source** (string) - The source of the skill (e.g., "instance").

### Response Example
```json
{
  "skills": [
    {
      "name": "pdf",
      "description": "Create, edit, and extract content from PDF files",
      "file_path": "/path/to/skills/pdf/SKILL.md",
      "base_dir": "/path/to/skills/pdf",
      "source": "instance"
    }
  ]
}
```
```

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

### Verify Frontend Build with Nix

Source: https://github.com/spacedriveapp/spacebot/blob/main/AGENTS.md

Confirm that the frontend build works after updating dependencies and the Nix hash by running 'nix build .#frontend'.

```bash
nix build .#frontend
```

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

### Built-in Skill Example

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(features)/skills.mdx

An example of a built-in skill, 'wiki-writing', with its description, as it might appear in documentation.

```markdown
| Skill | Description |
|---|---|
| `wiki-writing` | Encyclopedic writing standards for the wiki system — page types, tone, structure, wiki-link syntax, editing discipline |
```

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

### List Installed Skills

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(features)/skills.mdx

List all skills currently installed for the agent, indicating whether they are workspace or instance-level.

```bash
spacebot skill list
```

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

### Interface Configuration Files

Source: https://github.com/spacedriveapp/spacebot/blob/main/interface/PLAN.md

Create essential configuration files for Vite, Tailwind CSS, PostCSS, and TypeScript.

```bash
5. Create config files: `vite.config.ts`, `tailwind.config.ts`, `postcss.config.js`, `tsconfig.json`, `index.html`
```

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

### Fly.io Deployment Example

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(getting-started)/docker.mdx

Commands to deploy Spacebot on Fly.io, including launching with a specific image, creating persistent volumes, setting secrets, and deploying.

```bash
# Manual single-instance deploy
fly launch --image ghcr.io/spacedriveapp/spacebot:latest
fly volumes create spacebot_data --size 5
fly secrets set ANTHROPIC_API_KEY="sk-ant-..."
fly deploy
```

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

### Cron Job Workflow Example

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(features)/cron.mdx

Illustrates the lifecycle of a cron job, from firing to delivery and shutdown. Shows how a fresh channel is created for each job and how results are delivered.

```text
Cron job "check-email" fires (every 30m, active 09:00-17:00)
    → Scheduler creates a fresh Channel
    → Channel receives the cron job prompt as a synthetic message
    → Channel runs the LLM loop (can branch, spawn workers, use tools)
    → Channel produces the first user-visible OutboundResponse
    → Scheduler treats that response as the terminal delivery payload
    → Scheduler delivers the OutboundResponse via MessagingManager::broadcast_proactive(...)
    → Scheduler records execution status and delivery outcome in the log
    → Channel shuts down

Cron job "daily-summary" fires (every 24h)
    → Same flow, different prompt, different target
    → Runs independently even if "check-email" is still in-flight
```

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

### ProjectStore Initialization

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/design-docs/projects.md

This indicates the integration of the `ProjectStore` into the agent's dependencies, making its CRUD operations and Git helper functions available for project management tasks.

```go
Add `ProjectStore` to `AgentDeps`
```

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

### Telegram Platform Metadata Example

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(core)/channels.mdx

Example JSON structure for storing Telegram-specific metadata within the `platform_meta` column.

```json
{
  "telegram_chat_id": 551234,
  "telegram_chat_type": "private"
}
```

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

### Discord Platform Metadata Example

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(core)/channels.mdx

Example JSON structure for storing Discord-specific metadata within the `platform_meta` column.

```json
{
  "discord_guild_id": "1323900500600422472",
  "discord_guild_name": "My Server",
  "discord_channel_id": "1471388652562284626",
  "discord_is_thread": false,
  "discord_parent_channel_id": null
}
```

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

### Configure Local LLM Server (OpenAI Completions)

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(configuration)/config.mdx

Set up a provider for a local LLM server using the OpenAI Completions API. Note that `/v1` should not be included in the `base_url`.

```toml
[llm.provider.local_llm]
api_type = "openai_completions"
base_url = "http://localhost:8080" # no /v1 in base_url
api_key = "env:LOCAL_LLM_KEY"
name = "Local LLaMA Server"
```

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

### Start Spacebot Daemon

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(getting-started)/quickstart.mdx

Starts the Spacebot application as a background daemon. This is the default behavior when running the `spacebot` command.

```bash
spacebot
```

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

### Remove Installed Skill

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(features)/skills.mdx

Remove an installed skill from the agent's configuration using the `spacebot skill remove` command.

```bash
spacebot skill remove pdf
```

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

### Legacy to Provider Key Migration Example

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(configuration)/config.mdx

Shows how legacy LLM API keys are automatically converted into internal provider configurations. Custom provider configurations with the same ID will take precedence.

```toml
[llm]
anthropic_key = "env:ANTHROPIC_API_KEY"
openai_key = "env:OPENAI_API_KEY"
```

```toml
[llm.provider.anthropic]
api_type = "anthropic"
base_url = "https://api.anthropic.com"
api_key = "env:ANTHROPIC_API_KEY"

[llm.provider.openai]
api_type = "openai_completions"
base_url = "https://api.openai.com"
api_key = "env:OPENAI_API_KEY"
```

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

### Install Git Hooks

Source: https://github.com/spacedriveapp/spacebot/blob/main/CONTRIBUTING.md

Installs a pre-commit hook that automatically runs `cargo fmt` to ensure code formatting consistency.

```bash
./scripts/install-git-hooks.sh
```

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

### Development Server Configuration

Source: https://github.com/spacedriveapp/spacebot/blob/main/interface/PLAN.md

Instructions for running the development environment. This involves starting the Vite development server for the interface and the Rust application separately.

```bash
# In interface/ directory:
bun run dev

# In the project root:
cargo run -- start -f -d

```

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

### Install GitHub Skill

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(features)/skills.mdx

Install a GitHub skill to enable workers to use the `gh` CLI. This integrates domain-specific knowledge for GitHub operations.

```bash
spacebot skill add anthropics/skills/github
```

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

### Connecting to SQLite Database with `sqlx`

Source: https://github.com/spacedriveapp/spacebot/blob/main/RUST_STYLE_GUIDE.md

This code demonstrates connecting to a SQLite database using `sqlx` and running migrations. Ensure the `migrations` directory exists and contains your SQL migration files.

```rust
pub struct MemoryStore {
    pool: SqlitePool,
}

impl MemoryStore {
    pub async fn connect(path: &Path) -> Result<Self> {
        let pool = SqlitePool::connect(&format!("sqlite:{}", path.display()))
            .await
            .context("failed to connect to memory database")?;
        sqlx::migrate!("./migrations").run(&pool).await?;
        Ok(Self { pool })
    }

    pub async fn save(&self, memory: &Memory) -> Result<()> {
        sqlx::query!(
            r#" 
            INSERT INTO memories (id, content, memory_type, importance, created_at)
            VALUES (?, ?, ?, ?, ?)
            "#,
            memory.id,
            memory.content,
            memory.memory_type,
            memory.importance,
            memory.created_at,
        )
        .execute(&self.pool)
        .await?;
        Ok(())
    }
}
```

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

### Get Default Conversation Settings

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/design-docs/conversation-settings.md

The GET /api/conversation-defaults endpoint returns the default settings for new conversations, replacing hardcoded UI values.

```json
{
    "model": "anthropic/claude-sonnet-4",
    "memory": "full",
    "delegation": "standard",
    "worker_context": {
        "history": "none",
        "memory": "none"
    },
    "available_models": ["anthropic/claude-sonnet-4", "anthropic/claude-opus-4", "anthropic/claude-haiku-4.5"],
    "memory_modes": ["full", "ambient", "off"],
    "delegation_modes": ["standard", "direct"],
    "worker_history_modes": ["none", "summary", "recent", "full"],
    "worker_memory_modes": ["none", "ambient", "tools", "full"]
}
```

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

### Get Agent Warmup Status

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(core)/cortex.mdx

Retrieves the warmup status for a specific agent or all agents. Use when `agent_id` is omitted to get statuses for all agents.

```json
{
  "statuses": [
    {
      "agent_id": "main",
      "status": {
        "state": "warm",
        "embedding_ready": true,
        "last_refresh_unix_ms": 1763935800123,
        "last_error": null,
        "bulletin_age_secs": 42
      }
    }
  ]
}

```

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

### Agent Refinement Flow Example

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/design-docs/agent-factory.md

Demonstrates how a user can refine an existing agent's behavior through a conversational update, showing the process of modifying identity files.

```text
User: "make the support agent more casual"
Agent: [reads current SOUL.md → rewrites with casual voice → factory_update_identity]
       "Updated. More relaxed tone, still precise on technical stuff."
```

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

### Create Project

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(features)/projects.mdx

Registers a new project by specifying its root path.

```APIDOC
## POST /api/projects

### Description
Create a project (registers a root path)

### Method
POST

### Endpoint
/api/projects
```

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

### Cortex Signal Mapping Example

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/content/docs/(core)/cortex.mdx

Illustrates how the Cortex maps system events to high-level signals for pattern detection. This is a conceptual example of event-to-signal translation.

```text
Channel A emits: WorkerComplete { result: "...", ... }   → cortex maps to WorkerCompleted signal
Worker 7 emits: StatusUpdate { status: "stuck on..." }   → cortex maps to WorkerStatusUpdate signal
Branch 3 emits: ToolCompleted { tool: "memory_save" }    → cortex maps to MemorySaved signal
```

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

### Spacebot Skill Management Commands

Source: https://github.com/spacedriveapp/spacebot/blob/main/README.md

Provides commands for adding skills from the public registry and listing installed skills. Ensure the 'spacebot' CLI is installed and configured.

```bash
spacebot skill add vercel-labs/agent-skills
```

```bash
spacebot skill add anthropics/skills/pdf
```

```bash
spacebot skill list
```

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

### MCP Server Configuration Example (TOML)

Source: https://github.com/spacedriveapp/spacebot/blob/main/docs/design-docs/mcp.md

Defines default and per-agent MCP server configurations using TOML. Supports environment variable interpolation for sensitive values.

```toml
[defaults]
# MCP servers inherited by all agents

[[defaults.mcp]]
name = "filesystem"
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]

[[defaults.mcp]]
name = "sentry"
transport = "http"
url = "https://mcp.sentry.io"
headers = { "Authorization" = "Bearer ${SENTRY_TOKEN}" }

# Per-agent override
[[agents]]
id = "main"

[[agents.mcp]]
name = "postgres"
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres", "postgresql://..."]
```