+ 
-
+
@@ -52,6 +52,11 @@ moltbot onboard --install-daemon
The wizard installs the Gateway daemon (launchd/systemd user service) so it stays running.
Legacy note: `clawdbot` remains available as a compatibility shim.
+
+
+
+
+
## Quick start (TL;DR)
Runtime: **Node ≥22**.
diff --git a/docs/automation/cron-jobs.md b/docs/automation/cron-jobs.md
index 4924fb7c1..fd2d15659 100644
--- a/docs/automation/cron-jobs.md
+++ b/docs/automation/cron-jobs.md
@@ -15,6 +15,11 @@ the right time, and can optionally deliver output back to a chat.
If you want *“run this every morning”* or *“poke the agent in 20 minutes”*,
cron is the mechanism.
+
+
+Diagram source (Mermaid)
+
```mermaid
graph LR
subgraph Channels [Messaging Channels]
@@ -87,6 +92,8 @@ graph LR
GW -->|outbound| Channels
```
+
+
+
## TL;DR
- Cron runs **inside the Gateway** (not inside the model).
- Jobs persist under `~/.clawdbot/cron/` so restarts don’t lose schedules.
diff --git a/docs/automation/webhook.md b/docs/automation/webhook.md
index 5ed883976..e11e5d4f5 100644
--- a/docs/automation/webhook.md
+++ b/docs/automation/webhook.md
@@ -9,6 +9,11 @@ read_when:
Gateway can expose a small HTTP webhook endpoint for external triggers.
+
+
+Diagram source (Mermaid)
+
```mermaid
flowchart TD
subgraph MainSession [Main Session Job]
@@ -36,6 +41,8 @@ flowchart TD
end
```
+
+
+
## Enable
```json5
diff --git a/docs/broadcast-groups.md b/docs/broadcast-groups.md
index 91ba86c01..ae63b8ee1 100644
--- a/docs/broadcast-groups.md
+++ b/docs/broadcast-groups.md
@@ -17,6 +17,11 @@ Broadcast Groups enable multiple agents to process and respond to the same messa
Current scope: **WhatsApp only** (web channel).
+
+
+Diagram source (Mermaid)
+
```mermaid
sequenceDiagram
participant EXT as External System
@@ -38,6 +43,8 @@ sequenceDiagram
end
```
+
+
+
Broadcast groups are evaluated after channel allowlists and group activation rules. In WhatsApp groups, this means broadcasts happen when Moltbot would normally reply (for example: on mention, depending on your group settings).
## Use Cases
diff --git a/docs/concepts/agent-loop.md b/docs/concepts/agent-loop.md
index 70871cc50..96e149472 100644
--- a/docs/concepts/agent-loop.md
+++ b/docs/concepts/agent-loop.md
@@ -13,6 +13,11 @@ In Moltbot, a loop is a single, serialized run per session that emits lifecycle
as the model thinks, calls tools, and streams output. This doc explains how that authentic loop is
wired end-to-end.
+
+
+Diagram source (Mermaid)
+
```mermaid
flowchart TD
MSG[Incoming Message] --> ALLOW{Channel Allowlist\n+ Group Activation?}
@@ -36,6 +41,8 @@ flowchart TD
ISO1 & ISO2 & ISO3 --> DELIVER[Deliver Replies\nto Same Chat]
```
+
+
+
## Entry points
- Gateway RPC: `agent` and `agent.wait`.
- CLI: `agent` command.
@@ -96,6 +103,11 @@ These run inside the agent loop or gateway pipeline:
See [Plugins](/plugin#plugin-hooks) for the hook API and registration details.
+
+
+Diagram source (Mermaid)
+
```mermaid
stateDiagram-v2
[*] --> Intake: Inbound message / RPC
@@ -29,6 +34,8 @@ stateDiagram-v2
Compaction --> ModelInference: Retry with compacted context
```
+
+
+
## Streaming + partial replies
- Assistant deltas are streamed from pi-agent-core and emitted as `assistant` events.
- Block streaming can emit partial replies either on `text_end` or `message_end`.
diff --git a/docs/concepts/agent-workspace.md b/docs/concepts/agent-workspace.md
index 471cc04d3..43b0a15a5 100644
--- a/docs/concepts/agent-workspace.md
+++ b/docs/concepts/agent-workspace.md
@@ -9,6 +9,11 @@ read_when:
The workspace is the agent's home. It is the only working directory used for
file tools and for workspace context. Keep it private and treat it as memory.
+
+
+Diagram source (Mermaid)
+
```mermaid
sequenceDiagram
participant GW as Gateway
@@ -131,6 +143,8 @@ sequenceDiagram
GW->>HOOK: session_end
```
+
+
+
This is separate from `~/.clawdbot/`, which stores config, credentials, and
sessions.
diff --git a/docs/concepts/architecture.md b/docs/concepts/architecture.md
index 37d3583e2..3ebe4c94d 100644
--- a/docs/concepts/architecture.md
+++ b/docs/concepts/architecture.md
@@ -21,6 +21,11 @@ Last updated: 2026-01-22
## Components and flows
+
+
+Diagram source (Mermaid)
+
```mermaid
graph TD
subgraph Workspace ["Agent Workspace (~/clawd)"]
@@ -44,6 +49,8 @@ graph TD
end
```
+
+
+
### Gateway (daemon)
- Maintains provider connections.
- Exposes a typed WS API (requests, responses, server‑push events).
diff --git a/docs/concepts/channel-routing.md b/docs/concepts/channel-routing.md
index 62ad8af6c..474f548cc 100644
--- a/docs/concepts/channel-routing.md
+++ b/docs/concepts/channel-routing.md
@@ -51,6 +51,11 @@ Routing picks **one agent** for each inbound message:
The matched agent determines which workspace and session store are used.
+
+
+Diagram source (Mermaid)
+
```mermaid
graph TD
subgraph Channels
@@ -60,6 +65,8 @@ graph TD
GW -.-> CANVAS
```
+
+
+
## Broadcast groups (run multiple agents)
Broadcast groups let you run **multiple agents** for the same peer **when Moltbot would normally reply** (for example: in WhatsApp groups, after mention/activation gating).
@@ -86,6 +93,11 @@ Config:
See: [Broadcast Groups](/broadcast-groups).
+
+
+Diagram source (Mermaid)
+
```mermaid
flowchart TD
MSG[Inbound Message] --> P1{Exact Peer Match?}
@@ -68,6 +73,8 @@ flowchart TD
FOUND --> WS[Workspace + Session Store]
```
+
+
+
## Config overview
- `agents.list`: named agent definitions (workspace, model, etc.).
diff --git a/docs/concepts/compaction.md b/docs/concepts/compaction.md
index ef2539228..5ed349a11 100644
--- a/docs/concepts/compaction.md
+++ b/docs/concepts/compaction.md
@@ -8,6 +8,11 @@ read_when:
Every model has a **context window** (max tokens it can see). Long-running chats accumulate messages and tool results; once the window is tight, Moltbot **compacts** older history to stay within limits.
+
+
+Diagram source (Mermaid)
+
```mermaid
flowchart TD
MSG[Inbound Message\nfrom peer] --> BC{Peer in\nBroadcast Config?}
@@ -99,6 +111,8 @@ flowchart TD
DEFAULT --> REPLY_S
```
+
+
+
## What compaction is
Compaction **summarizes older conversation** into a compact summary entry and keeps recent messages intact. The summary is stored in the session history, so future requests use:
- The compaction summary
diff --git a/docs/concepts/memory.md b/docs/concepts/memory.md
index 44cb91375..79f124fd8 100644
--- a/docs/concepts/memory.md
+++ b/docs/concepts/memory.md
@@ -9,6 +9,11 @@ read_when:
Moltbot memory is **plain Markdown in the agent workspace**. The files are the
source of truth; the model only "remembers" what gets written to disk.
+
+
+Diagram source (Mermaid)
+
```mermaid
flowchart TD
A[Session Messages Accumulate] --> B{Near Context Limit?}
@@ -24,6 +29,8 @@ flowchart TD
K --> C
```
+
+
+
Memory search tools are provided by the active memory plugin (default:
`memory-core`). Disable memory plugins with `plugins.slots.memory = "none"`.
diff --git a/docs/concepts/messages.md b/docs/concepts/messages.md
index 2c66ee63a..ad35eaaf0 100644
--- a/docs/concepts/messages.md
+++ b/docs/concepts/messages.md
@@ -20,6 +20,11 @@ Inbound message
-> outbound replies (channel limits + chunking)
```
+
+
+Diagram source (Mermaid)
+
```mermaid
flowchart TD
subgraph WorkspaceFiles [Workspace Memory Files]
@@ -37,6 +42,8 @@ flowchart TD
DAILY --> READ
```
+
+
+
Key knobs live in configuration:
- `messages.*` for prefixes, queueing, and group behavior.
- `agents.defaults.*` for block streaming and chunking defaults.
diff --git a/docs/concepts/model-failover.md b/docs/concepts/model-failover.md
index efcc5aa06..6ecaf5a12 100644
--- a/docs/concepts/model-failover.md
+++ b/docs/concepts/model-failover.md
@@ -13,6 +13,11 @@ Moltbot handles failures in two stages:
This doc explains the runtime rules and the data that backs them.
+
+
+Diagram source (Mermaid)
+
```mermaid
flowchart TD
A[Inbound Message] --> B{Dedupe Cache}
@@ -44,6 +49,8 @@ flowchart TD
O --> P[Delivered]
```
+
+
+
## Auth storage (keys + OAuth)
Moltbot uses **auth profiles** for both API keys and OAuth tokens.
diff --git a/docs/concepts/multi-agent.md b/docs/concepts/multi-agent.md
index 3bbda0e47..661270542 100644
--- a/docs/concepts/multi-agent.md
+++ b/docs/concepts/multi-agent.md
@@ -9,6 +9,11 @@ status: active
Goal: multiple *isolated* agents (separate workspace + `agentDir` + sessions), plus multiple channel accounts (e.g. two WhatsApps) in one running Gateway. Inbound is routed to an agent via bindings.
+
+
+Diagram source (Mermaid)
+
```mermaid
flowchart TD
REQ[Agent Run Request] --> PROF[Select Auth Profile\nSession-pinned or round-robin]
@@ -32,6 +37,8 @@ flowchart TD
SWITCH --> PROF
```
+
+
+
## What is "one agent"?
An **agent** is a fully scoped brain with its own:
diff --git a/docs/concepts/queue.md b/docs/concepts/queue.md
index 8c6ff7283..e78dd5d3e 100644
--- a/docs/concepts/queue.md
+++ b/docs/concepts/queue.md
@@ -7,6 +7,11 @@ read_when:
We serialize inbound auto-reply runs (all channels) through a tiny in-process queue to prevent multiple agent runs from colliding, while still allowing safe parallelism across sessions.
+
+
+Diagram source (Mermaid)
+
```mermaid
graph TD
GW[Gateway Process] --> A1[Agent: home]
@@ -33,6 +38,8 @@ graph TD
B3[Binding: Telegram] --> A2
```
+
+
+
## Why
- Auto-reply runs can be expensive (LLM calls) and can collide when multiple inbound messages arrive close together.
- Serializing avoids competing for shared resources (session files, logs, CLI stdin) and reduces the chance of upstream rate limits.
@@ -48,6 +55,11 @@ Inbound messages can steer the current run, wait for a followup turn, or do both
- `interrupt` (legacy): abort the active run for that session, then run the newest message.
- `queue` (legacy alias): same as `steer`.
+
+
+Diagram source (Mermaid)
+
```mermaid
flowchart LR
subgraph SessionLanes [Session Lanes\none run per session]
@@ -28,6 +33,8 @@ flowchart LR
CL -.->|parallel| ML
```
+
+
+
Steer-backlog means you can get a followup response after the steered run, so
streaming surfaces can look like duplicates. Prefer `collect`/`steer` if you want
one response per inbound message.
diff --git a/docs/concepts/session.md b/docs/concepts/session.md
index a648ddf91..112562a75 100644
--- a/docs/concepts/session.md
+++ b/docs/concepts/session.md
@@ -7,6 +7,11 @@ read_when:
Moltbot treats **one direct-chat session per agent** as primary. Direct chats collapse to `agent:Diagram source (Mermaid)
+
```mermaid
stateDiagram-v2
[*] --> Idle: No active run
@@ -69,6 +81,8 @@ stateDiagram-v2
SteerBacklog --> Running: Steer now + preserve for followup
```
+
+
+
Use `session.dmScope` to control how **direct messages** are grouped:
- `main` (default): all DMs share the main session for continuity.
- `per-peer`: isolate by sender id across channels.
diff --git a/docs/concepts/streaming.md b/docs/concepts/streaming.md
index 0575229a6..da63fcf16 100644
--- a/docs/concepts/streaming.md
+++ b/docs/concepts/streaming.md
@@ -13,6 +13,11 @@ Moltbot has two separate “streaming” layers:
There is **no real token streaming** to external channel messages today. Telegram draft streaming is the only partial-stream surface.
+
+
+Diagram source (Mermaid)
+
```mermaid
flowchart TD
CREATE[Session Created\nNew inbound message] --> LOAD[Load Session\nfrom sessions.json + JSONL]
@@ -22,6 +27,8 @@ flowchart TD
ARCHIVE --> CREATE
```
+
+
+
## Block streaming (channel messages)
Block streaming sends assistant output in coarse chunks as it becomes available.
diff --git a/docs/gateway/index.md b/docs/gateway/index.md
index 7f9d8bedb..52ca5083f 100644
--- a/docs/gateway/index.md
+++ b/docs/gateway/index.md
@@ -10,6 +10,11 @@ Last updated: 2025-12-09
## What it is
- The always-on process that owns the single Baileys/Telegram connection and the control/event plane.
+
+
+Diagram source (Mermaid)
+
```mermaid
flowchart TD
MODEL[Model Output\ntext_delta events] --> BS{Block Streaming\nEnabled?}
@@ -36,6 +41,8 @@ flowchart TD
TG -->|No| BS
```
+
+
+
- Replaces the legacy `gateway` command. CLI entry point: `moltbot gateway`.
- Runs until stopped; exits non-zero on fatal errors so the supervisor restarts it.
@@ -36,6 +43,11 @@ moltbot gateway --force
# dev loop (auto-reload on TS changes):
pnpm gateway:watch
```
+
+
+Diagram source (Mermaid)
+
```mermaid
stateDiagram-v2
[*] --> NotInstalled
@@ -23,6 +28,8 @@ stateDiagram-v2
Error --> Running: Supervisor auto-restart\nRestartSec=5
```
+
+
+
- Config hot reload watches `~/.clawdbot/moltbot.json` (or `CLAWDBOT_CONFIG_PATH`).
- Default mode: `gateway.reload.mode="hybrid"` (hot-apply safe changes, restart on critical).
- Hot reload uses in-process restart via **SIGUSR1** when needed.
diff --git a/docs/gateway/protocol.md b/docs/gateway/protocol.md
index 744e0deba..d4a4ff0b9 100644
--- a/docs/gateway/protocol.md
+++ b/docs/gateway/protocol.md
@@ -18,6 +18,11 @@ handshake time.
- WebSocket, text frames with JSON payloads.
- First frame **must** be a `connect` request.
+
+
+Diagram source (Mermaid)
+
```mermaid
flowchart LR
WATCH[File Watcher\n~/.clawdbot/moltbot.json] --> DEBOUNCE[Debounce]
@@ -45,6 +57,8 @@ flowchart LR
ANALYZE -->|reload.mode=off| IGNORE[Ignored]
```
+
+
+
## Handshake (connect)
Gateway → Client (pre-connect challenge):
diff --git a/docs/gateway/security/index.md b/docs/gateway/security/index.md
index b6a2daf7f..4e3559d12 100644
--- a/docs/gateway/security/index.md
+++ b/docs/gateway/security/index.md
@@ -5,6 +5,8 @@ read_when:
---
# Security 🔒
+
+
## Quick check: `moltbot security audit` (formerly `clawdbot security audit`)
See also: [Formal Verification (Security Models)](/security/formal-verification/)
@@ -35,6 +37,11 @@ Moltbot is both a product and an experiment: you’re wiring frontier-model beha
Start with the smallest access that still works, then widen it as you gain confidence.
+
+
+Diagram source (Mermaid)
+
```mermaid
sequenceDiagram
participant C as Client
@@ -43,6 +48,8 @@ sequenceDiagram
end
```
+
+
+
### What the audit checks (high level)
- **Inbound access** (DM policies, group policies, allowlists): can strangers trigger the bot?
diff --git a/docs/images/diagrams/01-architecture.png b/docs/images/diagrams/01-architecture.png
new file mode 100644
index 000000000..df88113d5
Binary files /dev/null and b/docs/images/diagrams/01-architecture.png differ
diff --git a/docs/images/diagrams/02-agent-loop.png b/docs/images/diagrams/02-agent-loop.png
new file mode 100644
index 000000000..c0e7356ab
Binary files /dev/null and b/docs/images/diagrams/02-agent-loop.png differ
diff --git a/docs/images/diagrams/03-message-flow.png b/docs/images/diagrams/03-message-flow.png
new file mode 100644
index 000000000..346d33a4b
Binary files /dev/null and b/docs/images/diagrams/03-message-flow.png differ
diff --git a/docs/images/diagrams/04-ws-protocol.png b/docs/images/diagrams/04-ws-protocol.png
new file mode 100644
index 000000000..c73d123ac
Binary files /dev/null and b/docs/images/diagrams/04-ws-protocol.png differ
diff --git a/docs/images/diagrams/05-channel-routing.png b/docs/images/diagrams/05-channel-routing.png
new file mode 100644
index 000000000..be129bebf
Binary files /dev/null and b/docs/images/diagrams/05-channel-routing.png differ
diff --git a/docs/images/diagrams/06-multi-agent.png b/docs/images/diagrams/06-multi-agent.png
new file mode 100644
index 000000000..f9976979b
Binary files /dev/null and b/docs/images/diagrams/06-multi-agent.png differ
diff --git a/docs/images/diagrams/07-queue-lanes.png b/docs/images/diagrams/07-queue-lanes.png
new file mode 100644
index 000000000..4d096a10b
Binary files /dev/null and b/docs/images/diagrams/07-queue-lanes.png differ
diff --git a/docs/images/diagrams/08-queue-modes.png b/docs/images/diagrams/08-queue-modes.png
new file mode 100644
index 000000000..41047ab18
Binary files /dev/null and b/docs/images/diagrams/08-queue-modes.png differ
diff --git a/docs/images/diagrams/09-cron-jobs.png b/docs/images/diagrams/09-cron-jobs.png
new file mode 100644
index 000000000..959700792
Binary files /dev/null and b/docs/images/diagrams/09-cron-jobs.png differ
diff --git a/docs/images/diagrams/10-webhook.png b/docs/images/diagrams/10-webhook.png
new file mode 100644
index 000000000..f7417c37b
Binary files /dev/null and b/docs/images/diagrams/10-webhook.png differ
diff --git a/docs/images/diagrams/11-compaction.png b/docs/images/diagrams/11-compaction.png
new file mode 100644
index 000000000..44a065591
Binary files /dev/null and b/docs/images/diagrams/11-compaction.png differ
diff --git a/docs/images/diagrams/12-memory.png b/docs/images/diagrams/12-memory.png
new file mode 100644
index 000000000..d7ad4ea85
Binary files /dev/null and b/docs/images/diagrams/12-memory.png differ
diff --git a/docs/images/diagrams/13-streaming.png b/docs/images/diagrams/13-streaming.png
new file mode 100644
index 000000000..16cb442a0
Binary files /dev/null and b/docs/images/diagrams/13-streaming.png differ
diff --git a/docs/images/diagrams/14-broadcast.png b/docs/images/diagrams/14-broadcast.png
new file mode 100644
index 000000000..ba4102e22
Binary files /dev/null and b/docs/images/diagrams/14-broadcast.png differ
diff --git a/docs/images/diagrams/15-security.png b/docs/images/diagrams/15-security.png
new file mode 100644
index 000000000..9c7e47978
Binary files /dev/null and b/docs/images/diagrams/15-security.png differ
diff --git a/docs/images/diagrams/16-pairing.png b/docs/images/diagrams/16-pairing.png
new file mode 100644
index 000000000..1241fb603
Binary files /dev/null and b/docs/images/diagrams/16-pairing.png differ
diff --git a/docs/images/diagrams/17-model-failover.png b/docs/images/diagrams/17-model-failover.png
new file mode 100644
index 000000000..d643ff7c4
Binary files /dev/null and b/docs/images/diagrams/17-model-failover.png differ
diff --git a/docs/images/diagrams/18-tool-groups.png b/docs/images/diagrams/18-tool-groups.png
new file mode 100644
index 000000000..21cb3b340
Binary files /dev/null and b/docs/images/diagrams/18-tool-groups.png differ
diff --git a/docs/images/diagrams/19-plugin-discovery.png b/docs/images/diagrams/19-plugin-discovery.png
new file mode 100644
index 000000000..4874f7650
Binary files /dev/null and b/docs/images/diagrams/19-plugin-discovery.png differ
diff --git a/docs/images/diagrams/20-plugin-hooks.png b/docs/images/diagrams/20-plugin-hooks.png
new file mode 100644
index 000000000..efa3a4663
Binary files /dev/null and b/docs/images/diagrams/20-plugin-hooks.png differ
diff --git a/docs/images/diagrams/21-browser.png b/docs/images/diagrams/21-browser.png
new file mode 100644
index 000000000..0551a038e
Binary files /dev/null and b/docs/images/diagrams/21-browser.png differ
diff --git a/docs/images/diagrams/22-onboarding.png b/docs/images/diagrams/22-onboarding.png
new file mode 100644
index 000000000..26c57d20c
Binary files /dev/null and b/docs/images/diagrams/22-onboarding.png differ
diff --git a/docs/images/diagrams/23-gateway-lifecycle.png b/docs/images/diagrams/23-gateway-lifecycle.png
new file mode 100644
index 000000000..b7067eced
Binary files /dev/null and b/docs/images/diagrams/23-gateway-lifecycle.png differ
diff --git a/docs/images/diagrams/24-hot-reload.png b/docs/images/diagrams/24-hot-reload.png
new file mode 100644
index 000000000..d7af741cb
Binary files /dev/null and b/docs/images/diagrams/24-hot-reload.png differ
diff --git a/docs/images/diagrams/25-install.png b/docs/images/diagrams/25-install.png
new file mode 100644
index 000000000..c65e66560
Binary files /dev/null and b/docs/images/diagrams/25-install.png differ
diff --git a/docs/images/diagrams/26-workspace.png b/docs/images/diagrams/26-workspace.png
new file mode 100644
index 000000000..4c9828ee2
Binary files /dev/null and b/docs/images/diagrams/26-workspace.png differ
diff --git a/docs/images/diagrams/27-readme-architecture.png b/docs/images/diagrams/27-readme-architecture.png
new file mode 100644
index 000000000..79489fc0e
Binary files /dev/null and b/docs/images/diagrams/27-readme-architecture.png differ
diff --git a/docs/images/diagrams/28-session-lifecycle.png b/docs/images/diagrams/28-session-lifecycle.png
new file mode 100644
index 000000000..81d76e9e8
Binary files /dev/null and b/docs/images/diagrams/28-session-lifecycle.png differ
diff --git a/docs/images/diagrams/29-broadcast-vs-normal.png b/docs/images/diagrams/29-broadcast-vs-normal.png
new file mode 100644
index 000000000..a6ba1e312
Binary files /dev/null and b/docs/images/diagrams/29-broadcast-vs-normal.png differ
diff --git a/docs/images/diagrams/30-hero-banner.png b/docs/images/diagrams/30-hero-banner.png
new file mode 100644
index 000000000..c25d86849
Binary files /dev/null and b/docs/images/diagrams/30-hero-banner.png differ
diff --git a/docs/images/diagrams/31-security-threat-model.png b/docs/images/diagrams/31-security-threat-model.png
new file mode 100644
index 000000000..06f7b3133
Binary files /dev/null and b/docs/images/diagrams/31-security-threat-model.png differ
diff --git a/docs/images/diagrams/32-getting-started-timeline.png b/docs/images/diagrams/32-getting-started-timeline.png
new file mode 100644
index 000000000..b37243d97
Binary files /dev/null and b/docs/images/diagrams/32-getting-started-timeline.png differ
diff --git a/docs/install/index.md b/docs/install/index.md
index cb845c617..576f47eb1 100644
--- a/docs/install/index.md
+++ b/docs/install/index.md
@@ -9,6 +9,11 @@ read_when:
Use the installer unless you have a reason not to. It sets up the CLI and runs onboarding.
+
+
+Diagram source (Mermaid)
+
```mermaid
graph TD
subgraph Layer1 [Layer 1: Inbound Access Control]
@@ -63,6 +70,8 @@ graph TD
Layer3 --> AGENT[Agent Executes]
```
+
+
+
## Quick install (recommended)
```bash
diff --git a/docs/plugin.md b/docs/plugin.md
index f1adae913..79ab735e5 100644
--- a/docs/plugin.md
+++ b/docs/plugin.md
@@ -112,6 +112,11 @@ manifest.
If multiple plugins resolve to the same id, the first match in the order above
wins and lower-precedence copies are ignored.
+
+
+Diagram source (Mermaid)
+
```mermaid
flowchart TD
START[Install Moltbot] --> OS{Operating System?}
@@ -28,6 +33,8 @@ flowchart TD
GIT --> ONBOARD
```
+
+
+
### Package packs
A plugin directory may include a `package.json` with `moltbot.extensions`:
diff --git a/docs/start/getting-started.md b/docs/start/getting-started.md
index bdda03347..f7ccd1c04 100644
--- a/docs/start/getting-started.md
+++ b/docs/start/getting-started.md
@@ -7,8 +7,15 @@ read_when:
# Getting Started
+
+
Goal: go from **zero** → **first working chat** (with sane defaults) as quickly as possible.
+
+
+Diagram source (Mermaid)
+
```mermaid
flowchart TD
A[Plugin Discovery] --> B[1. Config Paths\nplugins.load.paths]
@@ -135,6 +140,8 @@ flowchart TD
K --> Q[Plugin Hooks]
```
+
+
+
Fastest chat: open the Control UI (no channel setup needed). Run `moltbot dashboard`
and chat in the browser, or open `http://127.0.0.1:18789/` on the gateway host.
Docs: [Dashboard](/web/dashboard) and [Control UI](/web/control-ui).
diff --git a/docs/start/pairing.md b/docs/start/pairing.md
index 9921e55f0..d77207f42 100644
--- a/docs/start/pairing.md
+++ b/docs/start/pairing.md
@@ -14,6 +14,11 @@ It is used in two places:
1) **DM pairing** (who is allowed to talk to the bot)
2) **Node pairing** (which devices/nodes are allowed to join the gateway network)
+
+
+Diagram source (Mermaid)
+
```mermaid
flowchart TD
A[Install Moltbot\nnpm install -g moltbot] --> B[Run Onboarding Wizard\nmoltbot onboard --install-daemon]
@@ -22,6 +29,8 @@ flowchart TD
I --> J[Send First Message\nmoltbot agent --message 'Hello']
```
+
+
+
Security context: [Security](/gateway/security)
## 1) DM pairing (inbound chat access)
diff --git a/docs/tools/browser.md b/docs/tools/browser.md
index 6ff0612e6..f1f5ea51e 100644
--- a/docs/tools/browser.md
+++ b/docs/tools/browser.md
@@ -321,6 +321,11 @@ High-level flow:
This design keeps the agent on a stable, deterministic interface while letting
you swap local/remote browsers and profiles.
+
+
+Diagram source (Mermaid)
+
```mermaid
sequenceDiagram
participant S as Sender / Device
@@ -37,6 +42,8 @@ sequenceDiagram
S->>GW: Future connects use device token
```
+
+
+
## CLI quick reference
All commands accept `--browser-profile Diagram source (Mermaid)
+
```mermaid
flowchart TD
AGENT[Agent Tool Call\nbrowser action] --> TARGET{Target?}
@@ -339,6 +344,8 @@ flowchart TD
SB --> RESULT
```
+
+
+
## Disabling tools
You can globally allow/deny tools via `tools.allow` / `tools.deny` in `moltbot.json`
Diagram source (Mermaid)
+
```mermaid
graph LR
subgraph Runtime [group:runtime]
@@ -60,6 +65,8 @@ graph LR
end
```
+