slackhive 0.1.37 → 0.1.39

package/docs/introduction.mdx

@@ -0,0 +1,160 @@
+---
+title: "Introduction"
+description: "SlackHive turns your Slack workspace into a team of AI agents — specialists you @mention, a Boss that coordinates, and memory that compounds over time."
+---
+
+## Build your AI-first company on Slack
+
+Your team already lives in Slack. Every question, decision, and follow-up happens there. SlackHive adds AI agents to that same workspace — they sit alongside your people, in the same channels, in the same threads.
+
+These aren't chatbots you switch to. They're **colleagues you @mention**. Each one connects to the tools your team already uses — Notion, Jira, GitHub, Figma, your database, your analytics stack. They read context, take action, and report back — right inside Slack.
+
+**Anyone on the team can create an agent.** No engineers required. If you can describe what you need, you can deploy it in minutes.
+
+---
+
+## What this looks like in practice
+
+A CEO who wants to drill into metrics doesn't open a BI tool — they ask `@data-analyst` directly in Slack. An engineer debugging a production issue asks `@devops` to tail logs and open a PR with the fix. A PM sketches a feature idea and asks `@designer` to create the initial wireframe in Figma. A marketer asks `@content-writer` to draft a campaign brief in their brand voice.
+
+Every tool your company uses — Notion, Jira, GitHub, Redshift, HubSpot, Figma — becomes accessible through a simple @mention in Slack.
+
+```
+CEO:            @data-analyst revenue is down 8% this week, can you dig in?
+DataBot:        [queries Redshift across 6 dimensions]
+                Found it — enterprise tier churn spiked on Tuesday after
+                the pricing page change. 3 accounts, $42k ARR. @boss — done!
+
+Engineer:       @devops the checkout service is throwing 500s, what's happening?
+DevOps:         [reads logs via MCP, identifies root cause]
+                Memory leak in the payment processor connection pool.
+                I've opened PR #847 with the fix and added a health check.
+
+PM:             @designer can you mock up a simpler onboarding flow?
+Designer:       [uses Figma MCP to create frames]
+                Done — here's the Figma link with 3 variants. Let me know
+                which direction you want to take.
+```
+
+---
+
+## Two ways to work
+
+### Tag a specialist directly
+
+When you know who to ask, @mention them. The agent reads the thread, uses its tools, and replies.
+
+```
+You:          @data-analyst pull last week's conversion funnel
+DataBot:      [reads thread, runs Redshift query]
+              Conversions were up 12% WoW. Checkout completion
+              jumped 3×. Want a channel or cohort breakdown?
+```
+
+### Ask @boss to figure it out
+
+When you're not sure who handles it, tag your Boss agent. Boss reads your request, finds the right specialist, delegates in the same thread, and summarizes the result.
+
+```
+You:          @boss can you analyze last week's conversion funnel?
+Boss:         That's right up @data-analyst's alley. Let me loop them in 👇
+              @data-analyst — user wants conversion funnel analysis for last week.
+              When you're done, please tag @boss.
+
+DataBot:      [reads full thread, runs Redshift query]
+              Conversions were up 12% WoW, driven by a 3× improvement
+              in checkout completion. @boss — done!
+
+Boss:         Great find @data-analyst! To summarize —
+              conversions are up 12% week-over-week. The big win was
+              checkout: completion rate jumped 3×. Want me to dig into
+              which channels drove that?
+```
+
+The specialist receives the **full Slack thread** as context — nothing is lost in the handoff.
+
+---
+
+## How SlackHive works
+
+<Steps>
+  <Step title="Create an agent">
+    Give it a name, a persona ("You are a data analyst who writes concise SQL..."), and connect it to a Slack app. Takes about 5 minutes.
+  </Step>
+  <Step title="Connect it to your tools">
+    Assign MCP servers to give the agent real capabilities — query a database, read files, call an API, create Jira tickets, update Notion pages. Or leave it as a conversational agent.
+  </Step>
+  <Step title="Your team @mentions it in Slack">
+    The agent wakes up, reads the thread for context, uses its tools, and replies directly in the thread.
+  </Step>
+  <Step title="It learns and improves">
+    After each conversation, the agent writes structured memory — who you are, what you prefer, what it learned about your team. Those memories are loaded at the start of every future conversation.
+  </Step>
+</Steps>
+
+---
+
+## What's included
+
+<CardGroup cols={2}>
+  <Card title="Boss Orchestration" icon="sitemap">
+    A Boss agent receives high-level requests and delegates to the right specialists via Slack thread @mentions. Specialists report back, and Boss consolidates results.
+  </Card>
+  <Card title="Persistent Memory" icon="brain">
+    Agents write structured memories during every session — feedback, user context, project state. Memories compound over time — the longer an agent works with your team, the sharper it gets.
+  </Card>
+  <Card title="MCP Tool Servers" icon="plug">
+    Connect agents to any external tool — Notion, Jira, GitHub, Redshift, Figma, HubSpot — via the Model Context Protocol. Manage a global catalog and assign per-agent.
+  </Card>
+  <Card title="Skills" icon="terminal">
+    Skills are domain knowledge files your agent always carries — SQL conventions, writing guidelines, PR templates. Give agents repeatable workflows baked into their context.
+  </Card>
+  <Card title="Encrypted Secret Store" icon="lock">
+    A platform-level encrypted store for API keys and credentials. MCP configs reference secrets by name — raw values are never exposed in the API or UI.
+  </Card>
+  <Card title="Hot Reload" icon="bolt">
+    Edit any agent — instructions, skills, tools, permissions — and changes take effect within seconds. No restarts, no downtime.
+  </Card>
+  <Card title="Version History" icon="clock-rotate-left">
+    Every save auto-snapshots the full agent state. Browse history with line-level diffs and restore any version with one click.
+  </Card>
+  <Card title="Access Control" icon="shield">
+    Four roles: superadmin, admin, editor, and viewer. Grant per-agent access to specific team members. All permissions enforced server-side.
+  </Card>
+</CardGroup>
+
+---
+
+## Under the hood
+
+SlackHive runs as four Docker Compose services:
+
+| Service | What it does |
+|---------|-------------|
+| **Web** (Next.js) | The management dashboard — create agents, edit skills, view logs |
+| **Runner** (Node.js) | Hosts all agent processes and maintains their Slack connections |
+| **PostgreSQL** | Stores agents, memories, skills, sessions, users, and history |
+| **Redis** | Pub/sub bus that delivers hot-reload events from Web to Runner instantly |
+
+<Note>
+  SlackHive agents are powered by **Claude Code** — not a chatbot wrapper. Each agent is a real AI agent with tools, memory, and instructions. Works with a Claude Pro or Max subscription, or a standard API key.
+</Note>
+
+---
+
+## Get started
+
+<CardGroup cols={2}>
+  <Card title="Quick Start" icon="rocket" href="/quickstart">
+    From zero to your first agent responding in Slack — in under 10 minutes.
+  </Card>
+  <Card title="Create an Agent" icon="robot" href="/agents/creating-agents">
+    Walk through the agent creation wizard in detail.
+  </Card>
+  <Card title="Boss Agents" icon="sitemap" href="/agents/boss-agents">
+    Set up a Boss to orchestrate a team of specialists.
+  </Card>
+  <Card title="MCP Servers" icon="plug" href="/configuration/mcp-servers">
+    Connect agents to Notion, Jira, GitHub, databases, and more.
+  </Card>
+</CardGroup>

package/docs/logo/dark.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
+  <defs>
+    <style>
+      .bg { fill: #1A1918; }
+      .line { fill: none; stroke: #EBE6E0; stroke-width: 32; stroke-linecap: round; stroke-linejoin: round; }
+      .prompt-accent { fill: none; stroke: #D97757; stroke-width: 32; stroke-linecap: round; stroke-linejoin: round; }
+      .cursor { fill: #D97757; }
+    </style>
+  </defs>
+  <rect class="bg" width="512" height="512" rx="112" />
+  <path class="line" d="M 200 140 L 200 372" />
+  <path class="line" d="M 312 140 L 312 372" />
+  <path class="line" d="M 140 200 L 372 200" />
+  <path class="prompt-accent" d="M 100 280 L 140 312 L 100 344" />
+  <path class="line" d="M 180 312 L 280 312" />
+  <rect class="cursor" x="312" y="296" width="40" height="32" rx="6" />
+</svg>

package/docs/logo/light.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
+  <defs>
+    <style>
+      .bg { fill: #F5F0EB; }
+      .line { fill: none; stroke: #1A1918; stroke-width: 32; stroke-linecap: round; stroke-linejoin: round; }
+      .prompt-accent { fill: none; stroke: #D97757; stroke-width: 32; stroke-linecap: round; stroke-linejoin: round; }
+      .cursor { fill: #D97757; }
+    </style>
+  </defs>
+  <rect class="bg" width="512" height="512" rx="112" />
+  <path class="line" d="M 200 140 L 200 372" />
+  <path class="line" d="M 312 140 L 312 372" />
+  <path class="line" d="M 140 200 L 372 200" />
+  <path class="prompt-accent" d="M 100 280 L 140 312 L 100 344" />
+  <path class="line" d="M 180 312 L 280 312" />
+  <rect class="cursor" x="312" y="296" width="40" height="32" rx="6" />
+</svg>

package/docs/logo/wide-dark.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 60" fill="none">
+  <!-- Icon -->
+  <rect x="0" y="2" width="56" height="56" rx="12" fill="#1A1918"/>
+  <line x1="20" y1="14" x2="20" y2="46" stroke="#EBE6E0" stroke-width="4" stroke-linecap="round"/>
+  <line x1="36" y1="14" x2="36" y2="46" stroke="#EBE6E0" stroke-width="4" stroke-linecap="round"/>
+  <line x1="12" y1="22" x2="44" y2="22" stroke="#EBE6E0" stroke-width="4" stroke-linecap="round"/>
+  <polyline points="8,32 14,38 8,44" fill="none" stroke="#D97757" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
+  <line x1="18" y1="38" x2="30" y2="38" stroke="#EBE6E0" stroke-width="4" stroke-linecap="round"/>
+  <rect x="34" y="34" width="6" height="5" rx="1.5" fill="#D97757"/>
+  <!-- Text -->
+  <text x="68" y="44" font-family="system-ui,-apple-system,sans-serif" font-size="38" font-weight="700" fill="#EBE6E0">SlackHive</text>
+</svg>

package/docs/logo/wide-light.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 60" fill="none">
+  <!-- Icon -->
+  <rect x="0" y="2" width="56" height="56" rx="12" fill="#1A1918"/>
+  <line x1="20" y1="14" x2="20" y2="46" stroke="#EBE6E0" stroke-width="4" stroke-linecap="round"/>
+  <line x1="36" y1="14" x2="36" y2="46" stroke="#EBE6E0" stroke-width="4" stroke-linecap="round"/>
+  <line x1="12" y1="22" x2="44" y2="22" stroke="#EBE6E0" stroke-width="4" stroke-linecap="round"/>
+  <polyline points="8,32 14,38 8,44" fill="none" stroke="#D97757" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
+  <line x1="18" y1="38" x2="30" y2="38" stroke="#EBE6E0" stroke-width="4" stroke-linecap="round"/>
+  <rect x="34" y="34" width="6" height="5" rx="1.5" fill="#D97757"/>
+  <!-- Text -->
+  <text x="68" y="44" font-family="system-ui,-apple-system,sans-serif" font-size="38" font-weight="700" fill="#1A1918">SlackHive</text>
+</svg>

package/docs/quickstart.mdx

@@ -0,0 +1,270 @@
+---
+title: "Quick Start"
+description: "From zero to your first AI agent responding in Slack — in under 10 minutes."
+---
+
+This guide takes you from a fresh machine to a working SlackHive setup with a live agent in your Slack workspace. You'll install SlackHive, create a Slack app, and send your first message to an AI agent.
+
+<Note>
+  **Before you begin, you'll need:**
+  - [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed and running
+  - A Slack workspace where you can install apps (you need to be an admin, or have permission to install apps)
+  - One of:
+    - An [Anthropic API key](https://console.anthropic.com) — pay per token, best for teams
+    - A Claude Pro or Max subscription — run `claude login` on your machine first
+</Note>
+
+## Install SlackHive
+
+<Tabs>
+  <Tab title="CLI (Recommended)">
+    The `slackhive` CLI handles everything automatically — it checks your environment, clones the repo, walks you through configuration, and starts all services.
+
+    <Steps>
+      <Step title="Install the CLI">
+        Open your terminal and run:
+
+        ```bash
+        npm install -g slackhive
+        ```
+
+        <Note>Requires Node.js 20 or later. Check your version with `node --version`.</Note>
+      </Step>
+      <Step title="Run the setup wizard">
+        ```bash
+        slackhive init
+        ```
+
+        The wizard will ask you a few questions:
+
+        | Prompt | What to enter |
+        |--------|---------------|
+        | **Install directory** | Where to put SlackHive (default: `./slackhive`) |
+        | **Admin username** | Your login name for the dashboard |
+        | **Admin password** | Choose a strong password |
+        | **Anthropic API key** | Your `sk-ant-api03-...` key, or leave blank for Claude Max |
+
+        Everything else (database passwords, encryption keys) is generated automatically.
+
+        Once you confirm, the wizard checks that Docker is running, builds the images, and starts all four services. This takes 2–3 minutes on the first run.
+      </Step>
+      <Step title="Open the dashboard">
+        When the wizard finishes, navigate to:
+
+        ```
+        http://localhost:3001
+        ```
+
+        Log in with the admin credentials you just set. You'll see the SlackHive dashboard.
+      </Step>
+    </Steps>
+  </Tab>
+  <Tab title="Manual Setup">
+    If you prefer to set things up yourself:
+
+    <Steps>
+      <Step title="Clone the repository">
+        ```bash
+        git clone https://github.com/pelago-labs/slackhive.git
+        cd slackhive
+        ```
+      </Step>
+      <Step title="Create your environment file">
+        ```bash
+        cp .env.example .env
+        ```
+
+        Open `.env` and fill in these required values:
+
+        ```bash
+        # Claude (choose one)
+        ANTHROPIC_API_KEY=sk-ant-api03-...
+
+        # Database
+        POSTGRES_DB=slackhive
+        POSTGRES_USER=slackhive
+        POSTGRES_PASSWORD=your-strong-password
+
+        # Redis
+        REDIS_PASSWORD=your-strong-password
+
+        # Dashboard login
+        ADMIN_USERNAME=admin
+        ADMIN_PASSWORD=your-strong-password
+
+        # Security keys — generate with: openssl rand -hex 32
+        AUTH_SECRET=...
+        ENV_SECRET_KEY=...
+
+        NODE_ENV=production
+        ```
+
+        <Tip>
+          Generate strong values for `AUTH_SECRET` and `ENV_SECRET_KEY` with:
+          ```bash
+          openssl rand -hex 32
+          ```
+        </Tip>
+      </Step>
+      <Step title="Start all services">
+        ```bash
+        docker compose up -d --build
+        ```
+
+        This builds and starts four containers:
+
+        | Container | Port | Description |
+        |-----------|------|-------------|
+        | `web` | 3001 | Management dashboard |
+        | `runner` | — | Agent process host |
+        | `postgres` | 5432 | Database |
+        | `redis` | 6379 | Hot-reload event bus |
+
+        First run takes 2–3 minutes while images build.
+      </Step>
+      <Step title="Open the dashboard">
+        Navigate to [http://localhost:3001](http://localhost:3001) and log in.
+      </Step>
+    </Steps>
+
+    <Warning>
+      Never commit your `.env` file. It contains secrets and is already listed in `.gitignore`.
+    </Warning>
+  </Tab>
+</Tabs>
+
+## Create your first agent
+
+Once you're logged into the dashboard, click **New Agent** in the sidebar. This opens a 5-step wizard.
+
+<Steps>
+  <Step title="Name & Role">
+    Give your agent:
+    - **Name** — shown in Slack (e.g. "Data Analyst" or "Ava")
+    - **Description** — what this agent does. Keep it short — this is used by Boss agents to know who to delegate to.
+    - **Persona** — how the agent should behave. This becomes its identity. Example:
+
+    ```
+    You are a data analyst who specializes in SQL queries and business metrics.
+    You give concise, direct answers. You always show your SQL before running it.
+    When you have results, lead with the key insight, then show the numbers.
+    ```
+
+    - **Model** — `claude-sonnet-4-6` is a good default for most agents
+
+    Leave the **Boss** toggle off for now. You can come back to that later.
+  </Step>
+  <Step title="Create a Slack App">
+    Each SlackHive agent needs its own Slack app. The wizard generates everything you need.
+
+    1. Click **Generate Manifest** in the wizard
+    2. Open [api.slack.com/apps](https://api.slack.com/apps) in a **new tab**
+    3. Click **Create New App** → **From an app manifest**
+    4. Select your Slack workspace
+    5. Paste the manifest JSON from the wizard
+    6. Click **Create**
+    7. On the next screen, click **Install to Workspace** → **Allow**
+
+    Your Slack bot now exists in your workspace. You'll grab its credentials in the next step.
+
+    <Tip>
+      Keep the Slack app settings tab open — you'll need it for Step 3.
+    </Tip>
+  </Step>
+  <Step title="Enter Credentials">
+    You need three values from your Slack app. Go back to the Slack app settings tab:
+
+    **Bot Token**
+    - Go to **OAuth & Permissions** in the left sidebar
+    - Copy the **Bot User OAuth Token** — it starts with `xoxb-`
+
+    **App Token**
+    - Go to **Basic Information**
+    - Scroll to **App-Level Tokens**
+    - Click **Generate Token and Scopes**
+    - Give it any name (e.g. "socket-mode")
+    - Add the scope `connections:write`
+    - Click **Generate**, then copy the token — it starts with `xapp-`
+
+    **Signing Secret**
+    - Still on **Basic Information**
+    - Under **App Credentials**, click **Show** next to Signing Secret and copy it
+
+    Paste all three into the wizard and click **Verify Connection**. If it fails, see [Slack App Setup](/configuration/slack-app) for troubleshooting.
+  </Step>
+  <Step title="Tools (Optional)">
+    Choose a **starter template** for your agent's skill set:
+    - **Blank** — clean slate
+    - **Data Analyst** — SQL patterns, data summarization
+    - **Writer** — content drafting, editing
+    - **Developer** — code review, PR summaries
+
+    You can also assign **MCP servers** here if you've added any to the catalog. MCP servers give agents access to external tools like databases and APIs. Skip this for now — you can add them later.
+  </Step>
+  <Step title="Review & Create">
+    Review the summary and click **Create Agent**.
+
+    The runner picks up the new agent within a few seconds. You'll see the agent status change to **Active** in the dashboard.
+  </Step>
+</Steps>
+
+## Test your agent in Slack
+
+Your agent is now live. Let's make sure it works.
+
+<Steps>
+  <Step title="Invite the bot to a channel">
+    In Slack, go to any channel and type:
+
+    ```
+    /invite @your-agent-name
+    ```
+
+    Replace `your-agent-name` with the bot's Slack handle (it matches the name you gave it in the wizard).
+  </Step>
+  <Step title="Send a message">
+    @mention your agent:
+
+    ```
+    @your-agent-name hello, what can you help me with?
+    ```
+
+    You should see a typing indicator, then a response in the thread.
+  </Step>
+</Steps>
+
+<Tip>
+  You can also DM the bot directly without inviting it to a channel. Open a new DM in Slack, find your agent by name, and start chatting.
+</Tip>
+
+If you don't get a response, check the **Logs** tab on the agent's detail page in the dashboard — it shows exactly what happened and any errors.
+
+## CLI reference
+
+Once installed, the `slackhive` CLI gives you quick access to common operations:
+
+| Command | What it does |
+|---------|-------------|
+| `slackhive init` | First-time setup wizard |
+| `slackhive start` | Start all services |
+| `slackhive stop` | Stop all services |
+| `slackhive status` | Show running containers |
+| `slackhive logs` | Tail the runner logs |
+| `slackhive update` | Pull latest changes and rebuild |
+
+## What's next
+
+<CardGroup cols={2}>
+  <Card title="Create a Boss Agent" icon="sitemap" href="/agents/boss-agents">
+    Set up an orchestrator that routes requests to the right specialist automatically.
+  </Card>
+  <Card title="Connect MCP Servers" icon="plug" href="/configuration/mcp-servers">
+    Give your agent real tools — query databases, read files, call APIs.
+  </Card>
+  <Card title="Agent Memory" icon="brain" href="/agents/memory">
+    Learn how agents remember context and get smarter over time.
+  </Card>
+  <Card title="Environment Variables" icon="lock" href="/configuration/env-vars">
+    Full reference for all configuration options.
+  </Card>
+</CardGroup>

package/docs/self-hosting/docker.mdx

@@ -0,0 +1,151 @@
+---
+title: "Docker Setup"
+description: "Run SlackHive with Docker Compose — the standard deployment method."
+---
+
+## Docker Compose architecture
+
+SlackHive runs as four Docker Compose services. All services share a private bridge network and communicate by service name.
+
+| Service | Image | Port (host) | Description |
+|---------|-------|-------------|-------------|
+| `web` | Built from `apps/web` | 3001 | Next.js 15 management UI + API |
+| `runner` | Built from `apps/runner` | — | Agent process host (Slack Bolt) |
+| `postgres` | `postgres:16-alpine` | 5432 | PostgreSQL database |
+| `redis` | `redis:7-alpine` | 6379 | Pub/sub event bus |
+
+## Prerequisites
+
+- Docker Engine 24+ and Docker Compose v2
+- At least 2 GB RAM available for Docker
+- Ports 3001 and 5432 free on the host (or configure alternate ports)
+
+## Starting services
+
+```bash
+# First time (builds images)
+docker compose up -d --build
+
+# Subsequent starts (uses cached images)
+docker compose up -d
+
+# Check status
+docker compose ps
+```
+
+## Stopping services
+
+```bash
+# Stop containers (data is preserved in volumes)
+docker compose stop
+
+# Stop and remove containers (data is preserved in volumes)
+docker compose down
+
+# Stop and remove containers AND volumes (destroys all data)
+docker compose down -v
+```
+
+<Warning>
+  `docker compose down -v` deletes all PostgreSQL and Redis data. Do not use this unless you intend to start fresh.
+</Warning>
+
+## Viewing logs
+
+```bash
+# All services
+docker compose logs -f
+
+# Runner only
+docker compose logs -f runner
+
+# Web only
+docker compose logs -f web
+
+# Last 100 lines of runner
+docker compose logs --tail 100 runner
+```
+
+## Rebuilding after changes
+
+If you pull an update or change code:
+
+```bash
+docker compose up -d --build
+```
+
+Or use the CLI:
+
+```bash
+slackhive update
+```
+
+This pulls the latest code, rebuilds images, and restarts containers.
+
+## Agent working directories
+
+Agents write ephemeral files (CLAUDE.md, skills, session directories, memory files) to `AGENTS_TMP_DIR`, which defaults to `/tmp/agents` inside the runner container.
+
+This directory is mounted as a Docker volume or bind mount. If you want agent working directories to persist across container rebuilds (useful for debugging), add a bind mount in `docker-compose.yml`:
+
+```yaml
+runner:
+  volumes:
+    - /path/on/host/agents:/tmp/agents
+```
+
+Otherwise, the runner recreates all workspace files from the database on startup.
+
+## Claude Pro or Max subscription volume mount
+
+If you're using a Claude Pro or Max subscription instead of an API key, you need to mount the Claude credentials from the host:
+
+```yaml
+runner:
+  volumes:
+    - ~/.claude:/root/.claude       # Auth credentials
+    - /tmp/agents:/tmp/agents       # Agent working dirs (optional)
+```
+
+Then make sure `ANTHROPIC_API_KEY` is **not** set in `.env`.
+
+## Health checks
+
+The `postgres` and `redis` services include health checks in `docker-compose.yml`. The `web` and `runner` services wait for their dependencies to be healthy before starting.
+
+If services fail to start, check:
+
+```bash
+# Check health status
+docker compose ps
+
+# Check postgres logs
+docker compose logs postgres
+
+# Check redis logs
+docker compose logs redis
+```
+
+## Persistent data volumes
+
+By default, Docker Compose creates named volumes for PostgreSQL and Redis data:
+
+| Volume | Contents |
+|--------|----------|
+| `slackhive_postgres_data` | All database tables (agents, skills, memory, sessions, users, etc.) |
+| `slackhive_redis_data` | Redis persistence (used for pub/sub; not critical) |
+
+These volumes survive `docker compose down` but are deleted by `docker compose down -v`.
+
+## Database migrations
+
+SlackHive runs database migrations automatically on startup. The web service applies any pending schema migrations before starting the server.
+
+For manual migration (e.g. after pulling an update with schema changes):
+
+```bash
+docker compose up -d --build web
+docker compose logs -f web
+```
+
+Watch for migration success messages in the web logs before proceeding.