slackhive 0.1.37 → 0.1.39

package/docs/features/history.mdx

@@ -0,0 +1,60 @@
+---
+title: "Version History"
+description: "Auto-snapshot every change to an agent's configuration, browse diffs, and restore any previous version."
+---
+
+## Overview
+
+Every time you save changes to an agent — skills, CLAUDE.md, tool permissions, or MCP assignments — SlackHive automatically creates a snapshot of the agent's full state. The **History** tab on each agent's detail page lets you browse these snapshots, view line-level diffs, and restore any previous version.
+
+This gives you a safety net for experimentation: try a new persona, restructure skills, or tighten permissions, and roll back immediately if something breaks.
+
+## What gets snapshotted
+
+Each snapshot captures the full agent state at the time of save:
+
+- `CLAUDE.md` content
+- All skill files (content and metadata)
+- Tool permissions (allowlist and denylist)
+- Assigned MCP servers
+
+Slack credentials, agent name, slug, and description are not included in snapshots (they are managed separately as live fields).
+
+## Viewing history
+
+1. Open an agent from the dashboard
+2. Click the **History** tab
+
+You'll see a chronological list of snapshots with timestamps. Click any snapshot to expand it.
+
+## Reading a diff
+
+Each snapshot shows a line-level diff against the previous version. Lines are color-coded:
+
+- **Green** (additions) — lines added in this snapshot
+- **Red** (deletions) — lines removed compared to the previous snapshot
+- Unchanged lines are shown for context
+
+## Restoring a version
+
+To restore an agent to a previous state:
+
+1. Open the snapshot you want to restore
+2. Click **Restore this version**
+3. Confirm the restore
+
+The runner hot-reloads the agent within seconds of the restore. The restored state becomes the current agent configuration and is itself snapshotted as a new entry in the history (so the restore is reversible).
+
+## Snapshot retention
+
+SlackHive keeps up to **10 snapshots per agent**. When a new snapshot would exceed the cap, the oldest snapshot is automatically deleted.
+
+If you need to preserve a specific version permanently, export the agent configuration (copy the CLAUDE.md and skill content) before it ages out of the snapshot cap.
+
+## Conversation history
+
+In addition to configuration history, each Slack thread maintains its own conversation context. Each Slack thread (identified by `userId + channelId + threadTs`) maps to a persistent Claude Code session.
+
+Session context survives runner restarts: the Claude session ID is stored in Postgres and reloaded when the runner starts. When an agent receives a message in an existing thread, it resumes the same Claude session — maintaining full conversation context including tool results, intermediate outputs, and prior exchanges.
+
+Sessions expire after **30 minutes of inactivity**. The runner runs a cleanup job every 10 minutes that removes stale sessions from both the in-memory cache and the database. After expiry, the next message in that thread starts a fresh session (though the agent still has all memories from previous conversations).

package/docs/features/import-export.mdx

@@ -0,0 +1,77 @@
+---
+title: "Import & Export"
+description: "Export an agent's configuration as a JSON file and import it into any other agent."
+---
+
+## What gets exported
+
+The export captures the full agent configuration:
+
+- **CLAUDE.md** — identity, instructions, and behavior rules
+- **Skills** — all Markdown skill files (slash commands)
+
+Slack credentials, memories, and scheduled jobs are **not** included in the export. This keeps exports portable — you can import a config into any agent without overwriting live credentials or accumulated memory.
+
+---
+
+## Exporting an agent
+
+1. Open the agent in the dashboard
+2. Click the **Download** icon in the top-right of the agent page
+3. A JSON file named `{agent-slug}-export.json` downloads immediately
+
+The file looks like:
+
+```json
+{
+  "claudeMd": "# DataBot\n\nYou are a data analyst...",
+  "skills": [
+    { "name": "sql-rules", "content": "## SQL Rules\n..." }
+  ],
+  "exportedAt": "2026-04-09T10:00:00.000Z"
+}
+```
+
+---
+
+## Importing a config
+
+Import applies an exported config to an **existing** agent — it overwrites that agent's CLAUDE.md and upserts its skills.
+
+1. Open the target agent in the dashboard
+2. Click the **Upload** icon in the top-right
+3. Select the `.json` export file
+4. A confirmation modal shows what will be applied:
+   - The new CLAUDE.md content
+   - How many skills will be upserted
+   - When the config was exported
+5. Click **Apply Import** to confirm
+
+<Note>
+  Import **overwrites** the agent's current CLAUDE.md. Skills are upserted — existing skills with the same name are updated, new ones are added, and skills not in the import are left untouched.
+</Note>
+
+---
+
+## Common use cases
+
+| Use case | How |
+|----------|-----|
+| **Clone an agent** | Export agent A → create agent B → import into B |
+| **Promote staging → prod** | Export from a test agent, import into the live one |
+| **Backup before a big edit** | Export before making large changes to CLAUDE.md |
+| **Share agent templates** | Export and send the JSON to a teammate to import |
+| **Roll back instructions** | Use [Version History](/features/history) for full snapshots, or re-import an old export |
+
+---
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Version History" icon="clock-rotate-left" href="/features/history">
+    Auto-snapshots on every save — browse diffs and restore any version.
+  </Card>
+  <Card title="Creating Agents" icon="robot" href="/agents/creating-agents">
+    Set up a new agent to import a config into.
+  </Card>
+</CardGroup>

package/docs/features/logs.mdx

@@ -0,0 +1,131 @@
+---
+title: "Live Logs"
+description: "Real-time log streaming for debugging agents and monitoring activity."
+---
+
+## Overview
+
+The **Live Logs** feature streams Docker container log output directly to your browser using server-sent events (SSE). Each agent's logs are available from its detail page.
+
+Logs capture everything the runner produces for a given agent: startup events, incoming Slack messages, Claude SDK calls, MCP tool invocations, memory writes, and errors.
+
+## Accessing logs
+
+1. Open an agent from the dashboard
+2. Click the **Logs** tab on the agent detail page
+
+Logs begin streaming immediately. New log lines appear in real time as the agent processes messages.
+
+## Log levels
+
+SlackHive uses structured logging (Winston) with four levels:
+
+| Level | Color | When it appears |
+|-------|-------|----------------|
+| `error` | Red | Unrecoverable failures: Slack auth errors, Claude SDK exceptions, DB connection failures |
+| `warn` | Yellow | Recoverable issues: stale session retries, MCP server startup failures, malformed memory files |
+| `info` | Default | Normal operation: agent started, message received, memory synced, session created |
+| `debug` | Dimmed | Verbose detail: SDK options, session directory paths, MCP server config |
+
+Use the **level filter** in the log viewer to show only the levels you care about. In production, `info` and above is usually sufficient. Enable `debug` when diagnosing unexpected behavior.
+
+## Log search
+
+The log viewer includes a search bar. Type any string to filter log lines to those containing that text. Useful for finding:
+- Log lines for a specific user ID (`U012AB3CD`)
+- Log lines for a specific session (`session_key`)
+- All memory sync events (`memory synced`)
+- All MCP-related activity (`mcp__`)
+
+## What you'll see in logs
+
+### Agent startup
+
+```
+[info] Agent started { mcpServers: ['redshift', 'filesystem'] }
+[info] Memory watcher started { memoryDir: '/tmp/agents/data-bot/memory' }
+[debug] MCP servers configured { servers: ['redshift'] }
+```
+
+### Incoming message
+
+```
+[info] Streaming query { sessionKey: 'U012-C456-1234.5678', resume: 'new', cwd: '...' }
+[debug] Session work dir created { sessionKey: '...', sessionDir: '...' }
+[debug] Session created { sessionKey: '...', sessionId: 'sess_...' }
+```
+
+### Memory write
+
+```
+[info] Memory synced to DB { filePath: '...', name: 'kai_preferences', type: 'user' }
+[info] Memory synced from session { file: 'user_kai_preferences.md', name: 'kai_preferences', type: 'user' }
+```
+
+### MCP tool use
+
+MCP tool invocations appear in the Claude SDK output stream and are rendered in the Slack response as tool-use labels. In logs, you'll see the MCP proxy management:
+
+```
+[info] MCP proxy started { server: 'redshift', port: 14050 }
+```
+
+### Session cleanup
+
+```
+[info] Cleaned up stale sessions { count: 2 }
+```
+
+### Errors
+
+```
+[error] Claude query failed { sessionKey: '...', error: 'No conversation found' }
+[warn] Stale session, retrying as new { sessionKey: '...', staleSessionId: 'sess_...' }
+[error] MCP proxy start failed { server: 'broken-mcp', error: 'Command not found' }
+```
+
+## Debugging common issues
+
+### Agent not responding in Slack
+
+Check for:
+- `[error]` lines mentioning Slack token or connection errors
+- `[warn]` lines about missing or invalid credentials
+- Whether the agent shows **Active** status in the dashboard
+
+### MCP tools not working
+
+Check for:
+- `[error] MCP proxy start failed` — the server binary is not found or not executable
+- `[warn] MCP envRef not found` — the referenced env var key doesn't exist in the encrypted store
+- `[warn] Memory dir watcher error` — filesystem permission issues
+
+### Memory not persisting
+
+Check for:
+- `[warn] Could not parse memory file` — the agent wrote a memory file with invalid frontmatter
+- Absence of `[info] Memory synced to DB` lines — the watcher may not have detected the file
+
+### Stale session errors
+
+Stale sessions occur when a Claude session ID stored in the database no longer corresponds to an active SDK session (e.g. after a runner restart). SlackHive retries automatically as a new session. You'll see:
+
+```
+[warn] Stale session, retrying as new
+```
+
+This is normal after restarts and resolves itself automatically.
+
+## Tailing logs from the CLI
+
+For shell access to runner logs, use the CLI:
+
+```bash
+slackhive logs
+```
+
+This tails the Docker container logs for the runner service. Add `--no-follow` to print without following:
+
+```bash
+docker compose logs runner --tail 100
+```

package/docs/features/multi-workspace.mdx

@@ -0,0 +1,90 @@
+---
+title: "Multi-Workspace"
+description: "Connect agents across multiple Slack workspaces — all managed from a single SlackHive instance."
+---
+
+## One platform, many workspaces
+
+SlackHive lets you deploy agents into multiple Slack workspaces from a single installation. Each agent carries its own Slack credentials, so agents in different workspaces run completely independently — while you manage everything from one dashboard.
+
+Common setups:
+
+| Setup | Example |
+|-------|---------|
+| **Single workspace** | All agents live in `company.slack.com` |
+| **Multi-team** | Engineering agents in one workspace, support agents in another |
+| **Client workspaces** | Agency deploying agents into each client's Slack |
+| **Staging + production** | Same agent config, separate workspaces for testing |
+
+---
+
+## How it works
+
+Each agent stores its own Slack credentials:
+
+- `slack_bot_token` — the bot's OAuth token (`xoxb-...`)
+- `slack_app_token` — for Socket Mode (`xapp-...`)
+- `slack_signing_secret` — to verify incoming events
+
+When the runner starts, it creates a separate Slack Bolt connection for each agent using that agent's credentials. Agents in different workspaces don't share connections or interfere with each other.
+
+---
+
+## Setting up agents across workspaces
+
+Each workspace needs its own Slack app. For each workspace:
+
+<Steps>
+  <Step title="Create a Slack app for that workspace">
+    During agent creation, the onboarding wizard generates a manifest. Install that manifest into the target workspace — **not** your main workspace.
+
+    → See [Slack App Setup](/configuration/slack-app) for the full manifest install steps.
+  </Step>
+  <Step title="Collect the credentials">
+    From the installed app, copy:
+    - **Bot Token** (`xoxb-...`) — from OAuth & Permissions
+    - **App Token** (`xapp-...`) — from Basic Information → App-Level Tokens
+    - **Signing Secret** — from Basic Information
+
+    These are workspace-specific. An app installed in workspace A cannot connect to workspace B.
+  </Step>
+  <Step title="Create the agent in SlackHive">
+    Paste the credentials into the agent wizard. The runner will connect to that workspace automatically on the next start (or within seconds if already running).
+  </Step>
+</Steps>
+
+Repeat for each workspace. You can have any number of agents per workspace.
+
+---
+
+## User management across workspaces
+
+Users and roles in SlackHive are platform-wide — there's no per-workspace access control.
+
+| What's shared | What's isolated |
+|---------------|-----------------|
+| User accounts and roles | Agent Slack connections |
+| Admin dashboard | Agent memories |
+| Platform settings | Agent skills and tools |
+| | Slack thread sessions |
+
+An admin can see and manage agents in all workspaces from the same dashboard. Use [per-agent write access grants](/features/users#per-agent-write-access-for-editors) if you need to restrict editors to specific workspaces' agents.
+
+---
+
+## Boss agents across workspaces
+
+A Boss and all its specialists **must be in the same Slack workspace**. Boss delegates by @mentioning specialists in the same thread — this only works when they share a workspace. If you need Boss orchestration in multiple workspaces, create a separate Boss and specialist set for each workspace.
+
+---
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Slack App Setup" icon="slack" href="/configuration/slack-app">
+    How to create and install a Slack app for each workspace.
+  </Card>
+  <Card title="Creating Agents" icon="robot" href="/agents/creating-agents">
+    Walk through the full agent creation wizard.
+  </Card>
+</CardGroup>

package/docs/features/scheduled-jobs.mdx

@@ -0,0 +1,231 @@
+---
+title: "Scheduled Jobs"
+description: "Trigger any agent on a schedule — get proactive alerts, reports, and monitoring delivered to Slack automatically."
+---
+
+## Your agents don't just wait to be asked
+
+Most AI tools are reactive — you ask, they answer. Scheduled Jobs make your agents **proactive**. Set a schedule, point it at any agent, and it fires automatically — running queries, checking metrics, scanning for anomalies, and posting results directly to a Slack channel or DM.
+
+No dashboards to check. No reports to pull. The insight comes to you.
+
+---
+
+## What you can build
+
+<CardGroup cols={2}>
+  <Card title="GMV & Revenue Alerts" icon="chart-line">
+    If GMV drops more than 10% hour-over-hour, DM the CEO immediately with a breakdown by channel and cohort.
+  </Card>
+  <Card title="Fraud Monitoring" icon="shield-halved">
+    Run a fraud check every hour. If anomalies are detected, post a summary to `#fraud-alerts` with transaction IDs and risk scores.
+  </Card>
+  <Card title="Daily Business Digest" icon="newspaper">
+    Every morning at 8 AM, post yesterday's key metrics — bookings, revenue, churn, NPS — to `#analytics`.
+  </Card>
+  <Card title="Weekly Engineering Report" icon="code">
+    Every Monday, summarize last week's PRs, incidents, and deploy count. Post to `#engineering`.
+  </Card>
+  <Card title="Inventory Alerts" icon="boxes-stacked">
+    Check stock levels every 4 hours. DM the ops lead if any SKU drops below threshold.
+  </Card>
+  <Card title="Support Queue Health" icon="headset">
+    Every 30 minutes during business hours, check ticket queue depth. Alert `#support-ops` if SLA is at risk.
+  </Card>
+</CardGroup>
+
+---
+
+## How it works
+
+<Steps>
+  <Step title="You set up a job">
+    Pick an agent, write a prompt, set a schedule (cron), and choose where results go — a Slack channel or a direct message.
+  </Step>
+  <Step title="The schedule fires">
+    At the configured time, SlackHive sends your prompt to the agent — exactly like a Slack message, but automated.
+  </Step>
+  <Step title="The agent runs">
+    The agent executes fully — it can run queries, call APIs, check metrics, compare against thresholds, and reason about the results.
+  </Step>
+  <Step title="Results posted to Slack">
+    The response is posted to the channel or DM you configured. If nothing notable happened, the agent can say so. If something needs attention, it flags it.
+  </Step>
+</Steps>
+
+---
+
+## Any agent, any schedule
+
+Jobs are not limited to boss agents. Assign a job to any agent:
+
+| Agent | Job example |
+|-------|------------|
+| `@data-analyst` | Run revenue query every morning, post to `#finance` |
+| `@devops` | Check error rates every 15 min, DM on-call if spiking |
+| `@fraud-bot` | Hourly transaction anomaly scan, post to `#fraud-alerts` |
+| `@support-agent` | Check ticket backlog every 30 min, alert if queue > 50 |
+| `@boss` | Daily summary across all teams, post to `#general` |
+
+---
+
+## Creating a job
+
+Go to **Jobs** in the sidebar → **New Job**.
+
+<Steps>
+  <Step title="Name the job">
+    Give it a clear name — e.g. `Daily Revenue Digest` or `Hourly Fraud Check`.
+  </Step>
+  <Step title="Choose an agent">
+    Select which agent should run this job. Pick the specialist best suited for the task.
+  </Step>
+  <Step title="Write the prompt">
+    Write exactly what you'd say to the agent in Slack. Be specific about what to check, what thresholds matter, and what to include in the response.
+
+    ```
+    Check GMV for the last hour vs the same hour yesterday.
+    If it's down more than 10%, flag it as urgent and include
+    a breakdown by acquisition channel. Otherwise just post
+    a one-line summary.
+    ```
+  </Step>
+  <Step title="Set the schedule">
+    Use a cron expression or pick a preset:
+
+    | Preset | Cron |
+    |--------|------|
+    | Every hour | `0 * * * *` |
+    | Every 15 minutes | `*/15 * * * *` |
+    | Daily at 8 AM | `0 8 * * *` |
+    | Weekdays at 9 AM | `0 9 * * 1-5` |
+    | Weekly on Monday | `0 9 * * 1` |
+
+    <Tip>The UI shows cron expressions in plain English so you can verify the schedule before saving.</Tip>
+  </Step>
+  <Step title="Set the target — Channel or DM">
+    Choose where the agent posts its results.
+
+    <Tabs>
+      <Tab title="Post to a Channel">
+        Post results publicly to any Slack channel — `#analytics`, `#fraud-alerts`, `#engineering`, etc.
+
+        **How to get the channel ID:**
+        1. Open Slack and right-click the channel name in the sidebar
+        2. Click **Copy link**
+        3. The link looks like: `https://app.slack.com/client/T.../C08ABCD1234`
+        4. The channel ID is the part starting with `C` — e.g. `C08ABCD1234`
+
+        Paste it into the **Target** field and select **Channel**.
+
+        <Note>Make sure the agent's Slack bot has been invited to the channel first. If not, invite it with `/invite @agent-name`.</Note>
+      </Tab>
+      <Tab title="Send a DM">
+        Send results as a direct message to any individual — CEO, on-call engineer, finance lead, or yourself.
+
+        **How to get the user ID:**
+        1. In Slack, click on the person's name or profile picture
+        2. Click **View full profile**
+        3. Click the **⋯ More** button (three dots)
+        4. Click **Copy member ID**
+        5. It looks like: `U012AB3CD45`
+
+        Paste it into the **Target** field and select **DM**.
+
+        The message arrives as a direct message from the agent's Slack bot — clean and personal.
+      </Tab>
+    </Tabs>
+  </Step>
+</Steps>
+
+---
+
+## Channel vs DM — when to use which
+
+| Use case | Channel | DM |
+|----------|---------|-----|
+| Team-wide reports (daily digest, weekly summary) | ✅ | |
+| Public monitoring dashboards (`#fraud-alerts`, `#ops`) | ✅ | |
+| Personal alerts (CEO wants GMV drop notification) | | ✅ |
+| On-call paging (engineer gets error spike alert) | | ✅ |
+| Sensitive metrics (revenue, churn — exec-only) | | ✅ |
+| Cross-team awareness (PM, data, eng all need to know) | ✅ | |
+
+<Tip>You can create multiple jobs for the same agent — one that posts to a channel for team visibility, and another that DMs the team lead for immediate personal attention.</Tip>
+
+---
+
+## Writing effective job prompts
+
+The prompt is the most important part. A few principles:
+
+**Be specific about what to check**
+```
+❌ Check the data
+✅ Query bookings for the last 24 hours and compare to the 7-day average
+```
+
+**Define what "notable" means**
+```
+❌ Let me know if anything is wrong
+✅ Flag if conversion rate drops below 3% or if any single channel
+   drops more than 20% week-over-week
+```
+
+**Tell it what to do in each case**
+```
+✅ If everything looks normal, post a one-line summary.
+   If something needs attention, include the specific numbers,
+   what changed, and your best hypothesis for why.
+```
+
+**Give it context it might need**
+```
+✅ Note: Tuesday is always lower due to our weekly maintenance window.
+   Don't flag Tuesday dips unless they exceed 30%.
+```
+
+---
+
+## Monitoring job runs
+
+Every job run is logged — status, output, duration, and timestamp — visible in **Jobs → [job name] → Run History**.
+
+| Status | Meaning |
+|--------|---------|
+| ✅ Success | Agent ran and posted to Slack |
+| ❌ Error | Agent not running, Claude error, or Slack API failure |
+| ⏭ Skipped | Agent was offline when the job fired |
+
+<Note>
+  If a job fails, the error is logged in run history. Common causes: the agent's Slack app token expired, the agent wasn't running, or the MCP server the agent needed was down.
+</Note>
+
+---
+
+## Example: GMV drop alert
+
+Here's a complete setup for a GMV monitoring job:
+
+| Field | Value |
+|-------|-------|
+| **Name** | Hourly GMV Alert |
+| **Agent** | `@data-analyst` |
+| **Schedule** | `0 * * * *` (every hour) |
+| **Target** | DM → CEO's Slack user ID |
+| **Prompt** | Compare GMV for the last hour vs the same hour last week. If it's down more than 15%, send an urgent alert with a breakdown by channel, device type, and acquisition source. If it's within normal range, send a single line: "GMV on track — $X this hour vs $Y last week." |
+
+The CEO gets a DM every hour. 99% of the time it's one line. When something breaks, they know immediately — with the breakdown already in their pocket.
+
+---
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Creating Agents" icon="robot" href="/agents/creating-agents">
+    Build the specialist agents that power your jobs.
+  </Card>
+  <Card title="MCP Servers" icon="plug" href="/configuration/mcp-servers">
+    Connect agents to your data sources so jobs can query real data.
+  </Card>
+</CardGroup>

package/docs/features/users.mdx

@@ -0,0 +1,92 @@
+---
+title: "User Management"
+description: "Create users, assign roles, and control per-agent write access."
+---
+
+## Authentication overview
+
+SlackHive uses a simple built-in auth system — no external provider required.
+
+- **Superadmin** is configured via environment variables (`ADMIN_USERNAME` / `ADMIN_PASSWORD`) — never stored in the database
+- **Sessions** use HMAC-signed cookies. The signing key is `AUTH_SECRET` in your `.env`
+- All routes are protected — unauthenticated requests redirect to `/login`
+
+## Roles
+
+SlackHive has four roles with escalating permissions:
+
+| Role | View agents | Edit agents | Manage jobs | Settings | Manage users |
+|------|-------------|-------------|-------------|----------|-------------|
+| **Superadmin** | All | All | Yes | Yes | Yes |
+| **Admin** | All | All | Yes | Yes | Yes |
+| **Editor** | All | Own + granted | Yes | Yes | No |
+| **Viewer** | All | No | No | No | No |
+
+### Superadmin
+
+Configured via `ADMIN_USERNAME` and `ADMIN_PASSWORD` in `.env`. This account is never stored in the database — it exists only in environment configuration. The superadmin has all permissions and cannot be deleted or demoted.
+
+### Admin
+
+Full access equivalent to superadmin, but stored in the database and manageable via the Users page. Admins can create other users, change roles, and grant per-agent write access to editors.
+
+### Editor
+
+Read access to all agents by default. Write access on:
+- Agents they created themselves
+- Any agents an admin has explicitly granted them access to
+
+Editors can create and manage scheduled jobs. They cannot manage users or change platform settings.
+
+### Viewer
+
+Read-only access to everything. Can see all agents, memories, and history, but cannot make changes.
+
+## Creating users
+
+Only superadmins and admins can create users.
+
+1. Go to **Settings → Users** in the sidebar
+2. Click **Add User**
+3. Enter a username and password
+4. Select a role
+5. Click **Create**
+
+Users can log in immediately at the `/login` page.
+
+## Changing a user's role
+
+1. Go to **Settings → Users**
+2. Find the user in the list
+3. Use the role dropdown to select a new role
+4. Changes take effect on the user's next page load (their active session remains valid)
+
+## Per-agent write access for editors
+
+Admins can grant editors write access to specific agents beyond what they created themselves:
+
+1. Go to **Settings → Users**
+2. Click a user with the **Editor** role
+3. Under **Agent Access**, you'll see a checklist of all agents
+4. Check the agents this editor should have full write access to
+5. Save
+
+Checked agents grant the editor full edit rights: skills, CLAUDE.md, tool permissions, MCP assignments, and history restore.
+
+## Permissions enforcement
+
+All permissions are enforced **server-side** in API route guards — not just hidden in the UI. A viewer who manually calls an API endpoint to edit an agent will receive a 403 response.
+
+The permission model:
+- Read operations require any authenticated session
+- Write operations on an agent require: admin, superadmin, or (editor + agent ownership/grant)
+- Settings mutations require: admin or superadmin
+- User management requires: admin or superadmin
+
+## Session behavior
+
+Sessions use HMAC-signed cookies with no expiry by default (persistent sessions). Sessions are invalidated when:
+- The user logs out explicitly
+- `AUTH_SECRET` is rotated in `.env` (invalidates all sessions immediately)
+
+There is no session table — sessions are stateless HMAC tokens, which means there's no way to invalidate individual sessions without rotating the `AUTH_SECRET`.