Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

release: 1.3.0 — Mercury Bots

Salman Qureshi88a77fef5eff
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2fc3c944..2bb258fe 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,72 @@
# Changelog
+## 1.3.0 — Mercury Bots
+
+Persistent, persona-scoped agents that run **outside your conversation** — each with its own persona, workspace, skills, permissions, and durable queue. Onboard specialists, chain them into multi-level fleets, and let them work 24/7 while you keep talking to Mercury.
+
+### New
+
+- **Persistent bot runtime (P0)** — Bots are long-lived agents with a persistent persona (`bot.yaml` + `permissions.yaml`), their own private sandbox at `~/.mercury/bots/<id>/`, and journals that survive restarts. A wake turns them on; they work through a durable job queue; results land **in the bot's own thread** — never dumped back into the session that dispatched work.
+- **Durable queue + HTTP API (P1)** — Jobs survive restarts and lease-expire when a worker dies (`timed out` classification, non-destructive DLQ replay via `/bots replay`). Fleet health is one command away: `mercury bots doctor` (exit 1 = actionable), `mercury bots list`, `mercury bots storage`. Telegram `/pair`-style ingress: every bot reachable through the channel you already use.
+- **Fleets — lead bots + crews** — Promote a bot to **fleet lead**; it recruits and organizes its own crew (imperative self-organization). Multi-level hierarchies supported. Crew results bubble up through the lead. Fleet onboarding walks tiers: **solo → lead auto-build → lead manual**.
+- **Web cockpit — Mercury Bots section** — The local web dashboard gained a fleet section: roster with live states, per-bot threads, needs-you escalation badges, and a fleet step view that mirrors the TUI.
+- **Persona system** — Two-pass persona builder keeps big personas big; hand-edited `bot.yaml`/`permissions.yaml` apply live. Persona file declares access scopes (read/write/execute per directory), so each bot gets exactly the surface it needs — no more.
+- **Sandbox + `bot_deliver`** — Every bot gets an isolated workspace; final artifacts go out through `bot_deliver`. Sandbox retention janitor caps per-bot disk usage; fleet-shared folder at `~/.mercury/bots/_shared` for cross-bot files with implicit grants.
+- **Bundles** — `/bots export` produces a shareable bundle (manifests + personas + permissions + skills; a lead's bundle carries its whole crew, whole-fleet export supported). `/bots import` recreates them — imported bots start disabled by design. Sandbox, journals, and `.env` never travel.
+- **Bot-facing tools** — `dispatch_bot`, `bot_schedule` (bots schedule their own future runs), `bot_deliver` (finalize artifacts), `fleet_status`, `journal_append`. Skill access for bots: native skill library + per-bot skill libraries with auto-synthesis.
+- **Lifecycle + observability** — Full create/edit/budget/delete lifecycle, stop/start/run with held-queue semantics (stop holds, never kills), needs-you alerts to your active channel, journal hydration restores per-bot threads on open, live activity bus feeds the roster and cockpit, per-bot token budgets, mtime-cached manifests, tail-read journals, `mercury bots storage` for disk usage.
+- **Permission tiers at onboarding** — Bots get `ask` / `allow` tiers per capability, set explicitly — nothing defaults silently. Per-bot shell allow-lists flow from `permissions.yaml autoApproveCommands`; malformed scope entries skip + warn, never crash turns.
+
+### Fixed
+
+- Fleet duplication on reopen; `/bots` stays inside the bot thread it opened.
+- Bot thinking streams into its thread live; fleet speed fixes (single-provider lease wait, batched roster fetches).
+- Web fleet step mirrors the TUI step view exactly (solo / auto-build / manual tiers).
+- Results no longer sliced at 800 chars in bot threads; delivery-contract gaps closed with durable retries + durable mailboxes.
+- Windows hardening: queue teardown EBUSY on SQLite backend, EBUSY on heartbeat test backends, EINVAL on retention backdating, separator-agnostic traversal guard; post-close queue ops degrade to no-ops, not crashes.
+- JSON backend lease-expiry race closed; SQLite queue handle released on teardown; doctor closes its queue.
+- Telegram member installs blocked `install_skill` — tool surfaced only where it's safe.
+- `mercury bots doctor` scheduler linkage: routines registered in schedules but missing from `bot.yaml` are flagged before they silently never fire.
+
+### Internal
+
+- New `src/bots/` module: `store.ts`, `queue.ts` (SQLite + JSON backends), `bot-manager.ts`, `bot-turn.ts`, `journal.ts`, `bundle.ts`, `doctor.ts`, `persona-template.ts`, `fleet-*`, `skill-synthesis.ts`, `retention.ts`, `tools/` (`dispatch-bot`, `bot_schedule`, `bot_deliver`, `fleet_status`, `journal_append`).
+- `mercury bots` — new CLI command group (`doctor` / `list` / `storage`) mirroring the in-chat `/bots` surface.
+- PRs #131–#139 + PR #117's RevShare integration carry this release.
+
+### Migration from 1.2.7
+
+No breaking changes. Bots are **opt-in** — onboard your first bot with `/bots create <id> "Name" "Description"`; the doctor and fleet surface appear as soon as you have a fleet. Existing config, memory, and channels are untouched.
+
+## 1.2.7 — Polished Mercury
+
+UX-polish on the Mercury Code surface: every command in autocomplete, honest completion stats, and status verbs that describe what's happening without an extra model call.
+
+### New
+
+- **50/50 RevShare Integration: Mercury & AIML API** (#117) — revenue-share program integration.
+- **Dynamic status verbs** (#119) — one LLM call per session generates live status verbs ("Compiling", "Sweeping"), chat stays static.
+- **"Did you know?" tips** (#120) — surface-categorized, rare, system-voice tips about features you haven't used.
+
+### Fixed
+
+- Step narrations render as separate blocks in the live tail; the `│` rule stays on settled messages, only the live tail drops it.
+- Slash autocomplete + `/help` cover every recent command, on every surface.
+- File-change stats in the completion banner are smart-conditional (no noise for prose-only turns).
+- CLI uninstall discovery works on machines with no real install.
+
+## 1.2.6 — Command Surface Fixes
+
+Hotfix on 1.2.5: slash autocomplete and `/help` now list every recent command on every surface; the live tail renders step narrations as separate blocks with the `│` rule behavior corrected.
+
+## 1.2.5 — Restore & Republish
+
+Recovery release: restores the Release/1.23 work dropped by a bad merge (40f5aea), rebuilds Pages output without merge-conflict markers, and re-publishes the 1.2.4 line cleanly.
+
+## 1.2.4 — Landing & Cards
+
+Website/branding release: richer per-page OG social-card generator with sections and breadcrumbs, inline SVG icons replace emojis on the landing page, and the v1.2.3 release page fix ships in the built docs bundle.
+
## 1.2.3 — Unstoppable Mercury
The release where **Mercury Code stops dying and starts telling the truth.** The completion pipeline was rebuilt around a completion contract: every task ends in a verdict — verified completion, or an honest pause that names its blocker and resumes. Tasks can no longer fake success, die silently, or loop forever.
diff --git a/README.md b/README.md
index ea5403b3..ce6ed706 100644
--- a/README.md
+++ b/README.md
@@ -21,7 +21,7 @@
</p>
<p align="center">
- <strong>🔖 Current Stable: v1.2.7</strong>
+ <strong>🔖 Current Stable: v1.3.0 — Mercury Bots</strong>
</p>
<p align="center">
@@ -434,7 +434,7 @@ Output is **versioned** so older builds are never overwritten:
```
release/
├── latest → symlink to most-recent version
-├── v1.2.7/
+├── v1.3.0/
│ ├── mercury-macos-arm64
│ ├── mercury-macos-x64
│ ├── mercury-linux-x64
diff --git a/RELEASE.md b/RELEASE.md
index 68eb4e5e..600f6636 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -1,67 +1,47 @@
-# Release v1.1.13
+# Release v1.3.0
-## ☿ Mercury Agent v1.1.13 — Chatty Mercury
+## ☿ Mercury Agent v1.3.0 — Mercury Bots
-Three new channels — Discord, Slack, and Signal — bring Mercury to where you already are. Every new channel has its own access model (pairing codes, admin roles, member approval), streaming responses, and real-time task progress. Signal adds end-to-end encryption for the privacy-first crowd.
-
-Beyond channels, this release fixes the long-running cycle problem — the silent task failures that could make Mercury disappear mid-task. The CLI now updates heartbeats in-place instead of stacking new messages, step logs collapse to 3 lines (Ctrl+D for full history), and a crash flag system means Mercury tells you what happened when it restarts after an ungraceful exit.
+Mercury stops being one agent and becomes **a fleet**. This release introduces **Mercury Bots** — persistent, persona-scoped agents that run *outside your conversation*: each with its own persona, private sandbox workspace, skill library, permission scopes, token budget, and a durable job queue. Onboard a researcher, a writer, a watchtower — chain them into multi-level fleets where a lead bot recruits and manages its own crew. They work 24/7, stream their thinking into their own threads, and escalate only what truly needs you.
### What's New
-- **Discord** — Full bot integration with slash commands, streaming responses, rich embeds, organization access with admin roles and pairing codes, DM + channel support, and rate limiting.
-- **Slack** — Socket Mode bot (no public endpoint needed) with slash commands, streaming edits, organization access with admin/member roles, channel + DM support, and @mention awareness.
-- **Signal** — End-to-end encrypted via signal-cli bridge. Group and private modes. Auto-managed signal-cli binary. Pairing-code access control. Phone number redaction in CLI.
-- **Crash recovery** — Crash flag system writes to `~/.mercury/.crash-flag` on ungraceful exit; next startup reports what happened.
+- **Persistent bot runtime** — Bots are long-lived persona agents, not temp sub-agents: `bot.yaml` manifest + `permissions.yaml`, private sandbox at `~/.mercury/bots/<id>/`, journal-backed thread history that hydrates on reopen. A wake turns them on; they work through a durable job queue that survives restarts.
+- **Fleets — leads + crews** — Promote any bot to **fleet lead**; it recruits, organizes, and manages its own crew (imperative self-organization). Multi-level hierarchies supported; crew results bubble up through the lead. Onboarding tiers: solo → lead auto-build → lead manual.
+- **Durable queue + DLQ** — Jobs survive restarts, lease-heartbeat while running, classify to `timed out` on worker death, and replay non-destructively from the DLQ (`/bots replay`). Nothing dies silently.
+- **Web cockpit** — The local dashboard gained a **Mercury Bots section**: live roster states, per-bot threads, needs-you escalation badges, and a fleet step view that mirrors the TUI.
+- **Sandbox + deliverables** — Per-bot isolated workspace; final artifacts go out via `bot_deliver`; retention janitor caps disk; fleet-shared folder for cross-bot files with implicit grants.
+- **Bundles** — `/bots export` produces a shareable bundle (manifests + personas + permissions + skills; a lead's bundle carries its whole crew). `/bots import` recreates bots — imported bots start **disabled** by design; sandbox, journals, and `.env` never travel.
+- **Permission tiers at onboarding** — `ask` / `allow` per capability, set explicitly. Per-bot shell allow-lists flow from `permissions.yaml autoApproveCommands`; malformed scopes skip + warn, never crash turns.
+- **Bot-facing tools** — `dispatch_bot`, `bot_schedule`, `bot_deliver`, `fleet_status`, `journal_append` + native/per-bot skill libraries with auto-synthesis. Bots can schedule their own future runs.
+- **`mercury bots` CLI** — `doctor` (exit 1 when actionable), `list`, `storage`.
### Fixed
-- **CLI heartbeat updates in place** — No more wall-of-progress messages during long tasks.
-- **All 12 silent task failure paths eliminated** — Every loop condition, tool limit, and stall now sends an explicit error message.
-- **Step log collapse** — Max 3 visible steps during active tasks; Ctrl+D for full history.
-- **Ollama Local routed through OpenAI compat** — Fixes AI SDK v1 specification error.
-- **Daemon graceful shutdown** — SIGTERM → wait → SIGKILL; stale signal-cli cleanup on stop.
-- **Channel send errors logged** — No more silently swallowed send failures.
-
-### Dependencies
-
-- `discord.js` v14.26.4
-- `@slack/bolt` v4.7.3
+- Fleet duplication on reopen; `/bots` stays inside the bot thread it opened.
+- Bot thinking streams live into its thread; fleet speed fixes (single-provider lease wait, batched roster fetches).
+- Bot-thread results no longer sliced at 800 chars; durable retries + durable mailboxes close delivery-contract gaps.
+- Windows hardening: SQLite queue teardown EBUSY, heartbeat-test EBUSY, retention EINVAL, separator-agnostic traversal guard; post-close queue ops degrade to no-ops.
+- JSON backend lease-expiry race closed; doctor flags routines registered in schedules but missing from `bot.yaml` (the silently-never-fires failure).
+- Telegram member installs no longer surface `install_skill`.
### Upgrade
**npm:**
```
-npm install -g @cosmicstack/[email protected]
+npm install -g @cosmicstack/[email protected]
mercury restart
```
-**Standalone binary:** re-run the one-line installer from [mercuryagent.sh](https://mercuryagent.sh), then:
-```
-mercury restart
-```
+**Standalone binary:** re-run the one-line installer from mercuryagent.sh, then `mercury restart`.
-No config migrations needed. All new channels are off by default.
+No config migrations. Bots are opt-in: `/bots create <id> "Name" "Description"` onboards your first bot.
-### Files Touched
+### Files Touched (highlights)
-- `src/channels/discord.ts` — Discord channel (new)
-- `src/channels/signal.ts` — Signal channel (new)
-- `src/channels/slack.ts` — Slack channel (new)
-- `src/signal/binary.ts` — signal-cli binary management (new)
-- `src/signal/jsonrpc.ts` — JSON-RPC client (new)
-- `src/signal/process.ts` — Process lifecycle (new)
-- `src/signal/setup.ts` — Signal registration (new)
-- `src/core/crash-flag.ts` — Crash flag system (new)
-- `src/core/agent.ts` — Channel registration, heartbeat in-place, silent failure elimination
-- `src/channels/registry.ts` — Discord/Slack/Signal registration
-- `src/channels/cli.ts` — sendHeartbeat method
-- `src/types/channel.ts` — Signal/Discord/Slack access types
-- `src/utils/config.ts` — Config sections and access management for new channels
-- `src/index.ts` — CLI commands for new channels, onboarding flows
-- `src/cli/daemon.ts` — Graceful shutdown, signal-cli cleanup
-- `src/cli/watchdog.ts` — Crash flag on max-restart
-- `src/providers/registry.ts` — ollamaLocal → OpenAI compat
-- `src/ui/App.tsx` — Step collapse, Ctrl+D, Processing indicator
-- `package.json` — v1.1.13, discord.js, @slack/bolt
+- `src/bots/*` — the entire fleet module (new): store, queue (SQLite+JSON), bot-manager, bot-turn, journal, bundle, doctor, persona-template, fleet-*, skill-synthesis, retention, tools/.
+- `src/core/agent.ts`, `src/cli/*`, `src/channels/cli.ts` — /bots chat surface, CLI command group, bot-thread region, thinking streams.
+- `src/web/*` — Mercury Bots cockpit section on the dashboard.
+- PRs: #131–#139, #117 (RevShare).
-**Full Changelog**: https://github.com/cosmicstack-labs/mercury-agent/compare/v1.1.12...v1.1.13
\ No newline at end of file
+**Full Changelog**: https://github.com/cosmicstack-labs/mercury-agent/compare/v1.2.7...v1.3.0
\ No newline at end of file
diff --git a/package-lock.json b/package-lock.json
index c8b3c1ca..ae8bf46f 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "@cosmicstack/mercury-agent",
- "version": "1.2.7",
+ "version": "1.3.0",
"lockfileVersion": 2,
"requires": true,
"packages": {
"": {
"name": "@cosmicstack/mercury-agent",
- "version": "1.2.7",
+ "version": "1.3.0",
"hasInstallScript": true,
"license": "MIT",
"dependencies": {
diff --git a/package.json b/package.json
index d7230bc5..c676baca 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "@cosmicstack/mercury-agent",
- "version": "1.2.7",
+ "version": "1.3.0",
"description": "Soul-driven AI agent with Second Brain memory, permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI or Telegram.",
"type": "module",
"main": "dist/index.js",
diff --git a/website/docs/cli-commands/in-chat-commands.mdx b/website/docs/cli-commands/in-chat-commands.mdx
index d7b41820..01bf3b78 100644
--- a/website/docs/cli-commands/in-chat-commands.mdx
+++ b/website/docs/cli-commands/in-chat-commands.mdx
@@ -91,6 +91,29 @@ When saver auto-engages, Mercury sends a one-time notification so you know respo
| `/agents config` | Show sub-agent resource allocation |
| `/agents set max <n>` | Set max concurrent sub-agents |
+## Mercury Bots
+
+Persistent persona-scoped agents that run outside your conversation — each with its own persona, sandbox, skills, and durable queue. See the [Mercury Bots guide](../integrations/mercury-bots) for the full surface.
+
+| Command | Description |
+|---------|-------------|
+| `/bots` | Roster with live fleet states |
+| `/bots create <id> "Name" "Description"` | Onboard a bot |
+| `/bots open <id>` | Open the bot's own thread |
+| `/bot <id> <message>` or `@<id> <message>` | Dispatch a task to a bot (result lands in the bot's thread) |
+| `/bots persona <id> <text>` | Set the bot's character |
+| `/bots edit <id>` | Edit name, description, model, budget |
+| `/bots delete <id>` | Delete the bot |
+| `/bots promote <id>` / `demote <id>` | Fleet lead ↔ solo bot |
+| `/bots stop <id>` / `start <id>` | Stop (holds jobs) / start (resumes subtree for leads) |
+| `/bots enable <id>` / `disable <id>` | Reactivate a disabled (e.g. imported) bot |
+| `/bots run <id> [routine]` | Fire a routine or bare wake now |
+| `/bots journal <id>` | Recent runs for a bot |
+| `/bots dlq` | Failed jobs (replayable) |
+| `/bots replay <id> <jobId>` | Non-destructive DLQ replay |
+| `/bots export <id> [path]` | Export a shareable bundle (leads carry their crew) |
+| `/bots import <path>` | Recreate bots from a bundle (imports start disabled) |
+
## Background Tasks
| Command | Description |
diff --git a/website/docs/integrations/mercury-bots.mdx b/website/docs/integrations/mercury-bots.mdx
new file mode 100644
index 00000000..4d47b830
--- /dev/null
+++ b/website/docs/integrations/mercury-bots.mdx
@@ -0,0 +1,113 @@
+---
+id: mercury-bots
+title: Mercury Bots — The Fleet
+description: "Persistent, persona-scoped agents that run outside your conversation — each with its own persona, sandbox, skills, permission scopes, and durable queue. Build fleets with lead bots and crews."
+keywords: [bots, fleet, persona, mercury bots, fleet lead, crew, dispatch, dlq, bundles]
+---
+
+# Mercury Bots — The Fleet
+
+Mercury Bots are **persistent, persona-scoped agents** that run *outside your conversation*. Unlike sub-agents (which die with their task) or channels (which answer as one persona), bots are long-lived specialists: each has a name, a character, its own private workspace, its own skill library and permission scopes, a per-bot token budget, and a durable job queue. Dispatch work and keep talking — the bot works in the background and delivers results in **its own thread**.
+
+## Concepts
+
+| Concept | What it is |
+|---|---|
+| **Bot** | A persistent persona agent: `bot.yaml` manifest + `permissions.yaml`, sandbox at `~/.mercury/bots/<id>/`, journal-backed history |
+| **Wake** | Turning a bot on for a turn (`/bots run <id> [routine]` or a dispatched task) |
+| **Thread** | The bot's own chat — results, thinking streams, and journal history land here, never in your active chat |
+| **Fleet lead** | A bot promoted to organize its own crew (`/bots promote <id>`) — tell it *what*, it decides *how* and who |
+| **Crew** | The bots under a lead; results bubble up through the lead; multi-level hierarchies supported |
+| **Bundle** | Shareable export of a bot (or whole fleet): manifests + personas + permissions + skills |
+| **DLQ** | Dead-letter queue for failed/timed-out jobs, replayable non-destructively |
+| **Needs-you alert** | Escalation to your active channel when a bot is blocked (failed job, permission wall, stopped bot) |
+
+## Bot vs sub-agent vs channel
+
+| | Sub-agent | Mercury Bot |
+|---|---|---|
+| Lifetime | dies with its task | persists across restarts |
+| Identity | anonymous | named persona with editable character |
+| Workspace | session workspace | private sandbox `~/.mercury/bots/<id>/` + shared folder |
+| Results | your chat | the bot's own thread |
+| Memory | none | journal history hydrates on reopen |
+| Skills | session skills | native library + per-bot libraries |
+| Schedule | — | `bot_schedule` — bots own their routines |
+
+## Quick start
+
+```
+/bots # roster with live states
+/bots create researcher "Researcher" "Web research specialist"
+/bots persona researcher "Meticulous researcher who cites sources."
+/bots promote researcher # make it a fleet lead (optional)
+/dispatch_bot bot=researcher task="Compare X vs Y, cite sources"
+/bots open researcher # open its thread
+```
+
+The result lands in the researcher's thread — your chat stays clean. Check on it with `/bots` or open its thread and reply directly.
+
+## Commands
+
+Run these inside a conversation with Mercury (CLI, Telegram, Discord, Slack, or Web):
+
+| Command | Description |
+|---------|-------------|
+| `/bots` | Roster with live states |
+| `/bots create <id> "Name" "Description"` | Onboard a bot (walks persona, workspace, budget, permission tiers) |
+| `/bots open <id>` | Open the bot's own thread |
+| `/bot <id> <message>` or `@<id> <message>` | Dispatch a task; the result lands only in the bot's thread |
+| `/bots persona <id> <text>` | Replace the bot's character |
+| `/bots edit <id>` | Change name, description, model, budget |
+| `/bots delete <id>` | Remove the bot and its sandbox |
+| `/bots promote <id>` / `/bots demote <id>` | Make lead / return to solo |
+| `/bots stop <id>` / `/bots start <id>` | Stop holds jobs (resumable); start resumes the whole subtree for leads |
+| `/bots enable <id>` / `/bots disable <id>` | Suspend/reactivate (imported bots start disabled) |
+| `/bots run <id> [routine]` | Fire a routine now, or a bare wake |
+| `/bots journal <id>` | Recent runs |
+| `/bots dlq` | Failed jobs (replayable) |
+| `/bots replay <id> <jobId>` | Re-run a DLQ job non-destructively |
+| `/bots export <id> [path]` | Bundle export (a lead's carries its crew) |
+| `/bots import <path>` | Recreate from a bundle (starts disabled) |
+
+CLI mirrors the read-only surface — `mercury bots doctor` (fleet health check, exit 1 when actionable), `mercury bots list`, `mercury bots storage`.
+
+## Workspaces & file access
+
+- Every bot gets a **private sandbox**: `~/.mercury/bots/<id>/`. Work stays isolated; other bots can't wander into it.
+- The fleet-shared folder `~/.mercury/bots/_shared/` is for cross-bot files — implicit grants for crew members, explicit for leads.
+- Access scopes (**read / write / execute** per directory) are declared in the bot's `permissions.yaml`; hand-edits apply live; malformed entries skip + warn rather than crash.
+- Shell approval follows the bot's own allow-list (`permissions.yaml autoApproveCommands`).
+- Final artifacts must exit via **`bot_deliver`** (platform folder or download) — nothing lives only inside a sandbox.
+- The **retention janitor** enforces per-bot disk caps (journal rotation, DLQ cap), so a forgotten fleet can't fill your disk.
+
+## Scheduling & autonomy
+
+Bots own routines through `bot_schedule` — schedule their own future runs and recurring jobs, visible in `/tasks` and the fleet doctor. Leads additionally self-organize: give a lead a goal and it recruits crew, splits work, and synthesizes results upward.
+
+## Bundles
+
+```
+/bots export <id> # single bot (or whole crew if lead / whole fleet)
+/bots import <path> # recreate bots — starts disabled by design
+```
+
+Bundles contain manifests, personas, permissions, and skill libraries so a recreated fleet works identically. What never travels: `~/.mercury/bots/<id>/` sandbox state, journals, and `.env` secrets. Import locally, review, `/bots enable`.
+
+## Web cockpit
+
+The local dashboard ('Mercury Bots' section) shows the live roster, per-bot threads with streamed thinking, needs-you badges, and a fleet step view that mirrors the TUI (solo / lead auto-build / lead manual).
+
+## Observability
+
+- **`/bots` roster** — live per-bot states (running / waiting / stopped / needs-you).
+- **Journals** — per-bot run history, tail-read and mtime-cached for speed.
+- **DLQ + replay** — failures classify honestly (`failed`, `timed out`) and replay non-destructively.
+- **`mercury bots doctor`** — storage health, queue depth, journal rotation, and scheduler linkage (routines registered but never wired are flagged before they silently never fire).
+
+## Security notes
+
+- Bots are persona-scoped: tools, skills, and scopes come from the bot's own manifests, not from your session.
+- Permission tiers (`ask` / `allow`) are chosen explicitly at onboarding — nothing defaults silently.
+- Bots stopped with `/bots stop` hold their queued jobs; nothing sneaks back in via the due-sweep until you `/bots start`.
+- Imported bundles start disabled — inspect before enabling.
\ No newline at end of file
diff --git a/website/docs/releases/1.3.0.mdx b/website/docs/releases/1.3.0.mdx
new file mode 100644
index 00000000..d1c8354f
--- /dev/null
+++ b/website/docs/releases/1.3.0.mdx
@@ -0,0 +1,131 @@
+---
+title: "v1.3.0 — Mercury Bots"
+sidebar_label: "v1.3.0"
+description: "Mercury stops being one agent and becomes a fleet. Persistent persona-scoped bots with private sandboxes, durable queues, multi-level fleets with self-organizing leads, bundles, a web cockpit, and honest observability."
+keywords: [mercury, mercury-agent, mercury-bots, bots, fleet, persona, agent-fleet, release, 1.3.0]
+---
+
+import Head from '@docusaurus/Head';
+
+<Head>
+ <meta property="og:title" content="Mercury Agent v1.3.0 — Mercury Bots" />
+ <meta property="og:description" content="Mercury becomes a fleet: persistent persona-scoped bots, durable queues, self-organizing crews, bundles, a web cockpit, and honest observability." />
+ <meta property="og:type" content="article" />
+ <meta property="og:url" content="https://mercuryagent.sh/docs/releases/1.3.0" />
+ <meta property="og:site_name" content="Mercury Agent — Soul-driven" />
+ <meta name="twitter:card" content="summary_large_image" />
+ <meta name="twitter:site" content="@mercuryagent" />
+ <meta name="twitter:title" content="Mercury Agent v1.3.0 — Mercury Bots" />
+ <meta name="twitter:description" content="Persistent persona bots · Durable queue · Fleets with crews · Bundles · Web cockpit · Sandbox retention." />
+ <link rel="canonical" href="https://mercuryagent.sh/docs/releases/1.3.0" />
+</Head>
+
+# v1.3.0 — Mercury Bots
+
+> **Mercury stops being one agent and becomes a fleet.**
+
+`1.3.0` is the biggest capability shift since the Second Brain: **Mercury Bots** — persistent, persona-scoped agents that live *outside your conversation*. Each bot has its own persona (`bot.yaml` + `permissions.yaml`), a private sandbox workspace under `~/.mercury/bots/<id>/`, its own skill library and permission scopes, a per-bot token budget, and a journal-backed thread history that survives restarts. Dispatch work and keep talking to Mercury — the bot works in the background and delivers results in **its own thread**, never in the middle of your chat.
+
+And because one bot is never enough: promote a bot to **fleet lead** and it recruits and organizes its own crew — multi-level hierarchies with results bubbling up through the lead. Ship the whole fleet to a teammate as a single bundle. Watch it all live from the web cockpit.
+
+> **Why "Mercury Bots"?** Sub-agents die with their task; channels answer one persona at a time. Bots are neither: they are persistent specialists with identities, workspaces, and queues — the difference between hiring a contractor for the afternoon and employing a small team.
+
+## At a glance
+
+| Area | What changed |
+|---|---|
+| **Persistent runtime** | Persona manifests (`bot.yaml`/`permissions.yaml`), private sandbox per bot, journal-hydrated threads, wakes + durable queue |
+| **Fleet hierarchy** | Fleet leads recruit/manage their own crew (imperative self-organization); multi-level fleets; results bubble up through leads |
+| **Durable queue + DLQ** | Jobs survive restarts; lease-heartbeat; `timed out` classification; non-destructive `/bots replay` |
+| **Web cockpit** | Mercury Bots section on the local dashboard: live roster, per-bot threads, needs-you badges, fleet step view mirroring the TUI |
+| **Sandbox + `bot_deliver`** | Isolated per-bot workspaces; final artifacts via `bot_deliver`; retention janitor caps disk; `_shared` folder for cross-bot files |
+| **Bundles** | `/bots export` / `/bots import` — portable fleets; imported bots start disabled; sandbox/journals/`.env` never travel |
+| **Permissions** | Explicit tiers at onboarding (`ask`/`allow`), per-bot shell allow-lists, malformed scopes warn instead of crashing |
+| **CLI** | `mercury bots doctor` / `list` / `storage` mirroring the in-chat surface |
+
+## The bot model
+
+A bot is **not** a sub-agent and **not** a channel — it's a third way to run intelligence:
+
+| | Sub-agent | Bot |
+|---|---|---|
+| Lifetime | dies with its task | persistent across restarts |
+| Identity | anonymous worker | named persona (name, description, character) |
+| Workspace | inherits your session | private sandbox at `~/.mercury/bots/<id>/` (+ fleet-shared folder) |
+| Results | land in your chat | land in **the bot's own thread** |
+| Continuity | none | journal history hydrates on reopen |
+| Permissions | your session's | its own scopes, declared in the persona |
+
+The wake lifecycle: dispatch a task → the bot's thread shows live state and streamed thinking → it works through the durable queue → results land in its thread → if something genuinely needs you (failed job, blocked permission, stopped bot), a **needs-you alert** reaches your active channel.
+
+## Fleets — leads and crews
+
+Any bot can be promoted to a **fleet lead** (`/bots promote <id>`). Leads are different:
+
+- **Imperative self-organization** — tell the lead *what* to achieve, not how; it recruits crew, delegates, and synthesizes results (multi-level hierarchies supported).
+- **Crew management** — `fleet-delegation`, `fleet-layout`, and `fleet-stop/start` semantics: stopping a lead holds its whole subtree; `/bots start` on the lead resumes it.
+- **Onboarding tiers** — solo bot → **lead auto-build** (lead designs its own crew from your brief) → **lead manual** (you hand-pick every member).
+- **Bundle portability** — exporting a lead ships the whole crew as one bundle.
+
+## Durable queue — honest about failure
+
+The fleet runs on a durable job queue (SQLite-backed with a JSON fallback), hardened through eight Windows/teardown cycles:
+
+- Jobs **survive restarts**; workers take leases with heartbeats.
+- Deaths classify honestly: `timed out` (worker died), `failed` (permanent) — both land in the DLQ, replayable **non-destructively** via `/bots replay <id> <jobId>`.
+- Post-close queue operations degrade to no-ops, never crashes; traversal guards are separator-agnostic.
+- `mercury bots doctor` cross-checks schedules: routines that exist in the scheduler but never got registered (the *silently never fires* failure) are flagged before they bite.
+
+## The web cockpit
+
+The local web dashboard now has a **Mercury Bots section**:
+
+- Live fleet roster with per-bot states (running / waiting / stopped / needs-you).
+- Per-bot **thread view** — chat with any bot from the browser, thinking streamed live.
+- **Fleet step view** mirroring Mercury Code TUI steps — solo, lead auto-build, lead manual tiers all render identically.
+- Needs-you escalation badges surface bots that are blocked and waiting on you.
+
+## Sandbox, retention, deliverables
+
+- Every bot works inside `~/.mercury/bots/<id>/` — its own workspace with per-directory **read/write/execute scopes declared in the persona**.
+- Final artifacts exit through **`bot_deliver`** (platform or download format), so nothing lives only inside a sandbox.
+- The **retention janitor** enforces per-bot disk caps (journal rotation, DLQ cap) — a forgotten fleet can't eat your disk.
+- `~/.mercury/bots/_shared/` is the fleet-shared folder: implicit grants between crew members, explicit grants for leads.
+
+## Bundles — portable fleets
+
+```
+/bots export <id> [path] # manifest + persona + permissions + skills (+ crew if lead)
+/bots import <path> # recreate bots — imported bots start disabled
+```
+
+A lead's bundle carries its entire crew. Whole-fleet export is supported. Imported bots start **disabled by design** — you inspect them, then `/bots enable` when you trust them. Sandboxed state, journals, and `.env` secrets never travel.
+
+## Permissions — explicit, not silent
+
+Onboarding walks through capability tiers (`ask` / `allow`) — nothing defaults silently in the dark. Hand-edited `bot.yaml` / `permissions.yaml` apply **live**; malformed scope entries skip with a warning instead of crashing turns. Telegram member installs no longer surface `install_skill`.
+
+## Also in this release
+
+- **Live thinking streams** — bot reasoning streams into its thread as a quoted preview; fleet speedups from a single-provider lease wait and batched roster fetches.
+- **`mercury bots` CLI** — `doctor` (exit 1 = actionable), `list`, `storage` for disk usage.
+- **Windows/teardown hardening** — eight cycles of EBUSY/EINVAL/traversal fixes across the queue, heartbeat tests, and retention backdating.
+- **v1.2.4 → v1.2.7 carried in** — dynamic status verbs, "Did you know?" tips, slash-autocomplete coverage everywhere, smart-conditional completion stats, and the RevShare integration (#117). See the [changelog](https://github.com/cosmicstack-labs/mercury-agent/blob/main/CHANGELOG.md) for the full per-version detail.
+
+## Upgrade
+
+```bash
+npm install -g @cosmicstack/[email protected]
+mercury restart
+```
+
+Standalone-binary users: re-run the one-line installer from [mercuryagent.sh](https://mercuryagent.sh), then `mercury restart`.
+
+No config migrations. Bots are opt-in — nothing changes until you create one:
+
+```
+/bots create researcher "Researcher" "Web research specialist"
+/bots persona researcher "You are a meticulous researcher who cites sources."
+```
+
+**Full Changelog**: https://github.com/cosmicstack-labs/mercury-agent/compare/v1.2.7...v1.3.0
\ No newline at end of file
diff --git a/website/docs/releases/releases.mdx b/website/docs/releases/releases.mdx
index 4aa8681d..33bb7ccc 100644
--- a/website/docs/releases/releases.mdx
+++ b/website/docs/releases/releases.mdx
@@ -9,6 +9,7 @@ This section tracks Mercury release notes by version.
## Available release notes
+- [**v1.3.0 — Mercury Bots**](/docs/releases/1.3.0) — Mercury becomes a fleet: persistent persona-scoped bots with private sandboxes and durable queues, lead bots that recruit their own crews, portable bundles, a web cockpit, and honest failure observability.
- [**v1.2.3 — Unstoppable Mercury**](/docs/releases/1.2.3) — Mercury Code stops dying and starts telling the truth: completion contract, AUTO mode, the mechanical escalation harness, compact-on-pressure, live plan checklist, wheel scrolling, and security hardening.
- [**v1.2.0 — Cloudy Mercury**](/docs/releases/1.2.0) — Mercury Cloud: terminal pairing, JWT auth with self-recovery, Cloud WebSocket, shared memory pool search. Cross-platform fixes for Windows and Termux. Patch set 1.2.0 → 1.2.1 → 1.2.2.
- [v1.1.13 — Chatty Mercury](/docs/releases/1.1.13) — Discord, Slack, and Signal channels. Long-running loop fixes. CLI heartbeat in-place. Crash recovery.
diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts
index bafd3e5c..9f51270a 100644
--- a/website/docusaurus.config.ts
+++ b/website/docusaurus.config.ts
@@ -92,7 +92,7 @@ const config: Config = {
items: [
{to: '/docs', label: 'Docs', position: 'left'},
{to: '/cloud', label: 'Mercury Cloud', position: 'left'},
- {to: '/docs/releases/1.2.0', label: 'Releases', position: 'left'},
+ {to: '/docs/releases/1.3.0', label: 'Releases', position: 'left'},
{
href: 'https://github.com/cosmicstack-labs/mercury-agent',
label: 'GitHub',
diff --git a/website/sidebars.ts b/website/sidebars.ts
index c3359d16..e79c3050 100644
--- a/website/sidebars.ts
+++ b/website/sidebars.ts
@@ -45,6 +45,7 @@ const sidebars: SidebarsConfig = {
collapsed: false,
items: [
'integrations/web-dashboard',
+ 'integrations/mercury-bots',
'integrations/kanban-boards',
'integrations/github-companion',
'integrations/telegram',
@@ -78,6 +79,7 @@ const sidebars: SidebarsConfig = {
collapsed: false,
items: [
'releases/releases',
+ 'releases/1.3.0',
'releases/1.2.3',
'releases/1.2.0',
'releases/1.1.13',