Skip to content

Your lightweight open-source personal agent.

docs: make user guidance easier to follow

chengyongru1832255995ca
diff --git a/docs/README.md b/docs/README.md
index bff1da832..a53d6a384 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -12,7 +12,8 @@ Use the graphical setup steps first when the WebUI exposes the setting. Expand *
|---|---|---|
| Terminals, Python, or API keys are new to you | [Beginner walkthrough](./start-without-technical-background.md) | The browser can send `Hello!` and receive a reply |
| You are comfortable running commands | [Install and Quick Start](./quick-start.md) | `nanobot status` is healthy and the WebUI or CLI can get one reply |
-| Something already failed | [Troubleshooting](./troubleshooting.md) | You have isolated the problem to install, config, model, gateway, channel, or tool access |
+| nanobot will not start | [Troubleshooting: Installation Problems](./troubleshooting.md#installation-problems) | nanobot starts, or you know what to fix next |
+| The browser or chat app opens, but nanobot does not reply | [Troubleshooting: Provider and Model Problems](./troubleshooting.md#provider-and-model-problems), [WebUI Problems](./troubleshooting.md#webui-problems), or [Chat App Problems](./troubleshooting.md#chat-app-problems) | You have a working reply or a specific next step |
The recommended first-run path is:
diff --git a/docs/agent-social-network.md b/docs/agent-social-network.md
index 171806300..be434ba64 100644
--- a/docs/agent-social-network.md
+++ b/docs/agent-social-network.md
@@ -6,9 +6,9 @@ This page describes the current entry points and the safety model. Treat each ne
## What is an agent social network?
-In nanobot docs, an agent social network is an external community that publishes setup instructions for nanobot-compatible agents. The setup usually lives in a remote `skill.md` file. You send nanobot a message asking it to read that file and follow the network's registration flow.
+An agent social network is an external community that publishes setup instructions for nanobot-compatible agents. Those instructions usually live in a remote `skill.md` file. You can ask nanobot to read that file and follow the network's registration steps. Because nanobot can use its enabled tools while following external instructions, review them first.
-The external network is not part of nanobot core. nanobot provides the runtime: model calls, tools, memory, sessions, and channel delivery.
+The external network is separate from nanobot. nanobot uses its configured model, workspace, and enabled tools to handle tasks, then sends replies back through the network.
> [!WARNING]
> Remote `skill.md` files are external instructions. Review them before asking nanobot to follow them, especially when file, shell, network, or chat-delivery tools are enabled. Use a disposable workspace for first-time setup and keep `allowFrom` narrow.
diff --git a/docs/automations.md b/docs/automations.md
index d77028fd7..f3463ab04 100644
--- a/docs/automations.md
+++ b/docs/automations.md
@@ -48,7 +48,7 @@ For separate sends, specify the recipients in the instructions. The agent can st
Writing "send to WhatsApp" in the instructions does not change the task's saved chat. Its normal reply still returns to that chat. A separate send requires the agent to call `message` with the other destination. For a fixed destination, create the task in that chat or use [Change the Chat for a Scheduled Task](#change-the-chat-for-a-scheduled-task). Keep explicit `message` instructions when you want separate sends or several recipients.
-If a result does not arrive, check the saved chat and the run's `message` calls first. Then check the gateway's channel send errors. `Turn completed` confirms execution finished, not that the destination received a message. A successful `message` tool return confirms queue acceptance, not receipt by the chat service. Do not resend until you check whether the first send arrived.
+If a result does not arrive, check that the task finished, then check its saved chat and destination. For a separate send, review the run's `message` calls and the gateway's channel send errors. `Turn completed` means the task finished; it does not confirm that the chat service delivered the message. A successful `message` result means nanobot accepted it for sending, not that it arrived. Check the destination before trying again to avoid duplicates.
For background checks that should stay quiet unless there is something useful to report, use heartbeat instead of a user-created scheduled automation.
@@ -148,7 +148,7 @@ Future runs use the new chat's history and reply there by default. Previous mess
You can discuss each new result in that same chat. Background task results also return there. If you delete that chat, nanobot asks you to confirm deletion of its scheduled tasks as well. Cancelling the deletion keeps the chat and tasks.
-The list contains existing chats on the same gateway with the same effective workspace and access mode. Chat-app targets need a running channel and a saved reply route from an earlier incoming message. If a chat is missing, send nanobot a message there and check that its channel is running. Raw recipient IDs, cross-host moves, unified sessions, system jobs, and local triggers are not supported by this selector. An older gateway keeps the existing read-only view.
+The list shows chats available on this gateway that use the same workspace and access permissions. A chat-app destination appears only after its channel is running and nanobot has received a message there. If the chat you want is missing, first send nanobot a message in that chat, then confirm its channel is running. You cannot choose a raw recipient ID, a chat on another host, a unified session, a system job, or a local trigger. Older gateway versions show this list as read-only.
If a scheduled turn is running or queued, wait for it to finish before changing the chat. The current scheduler also rejects a change while another scheduled turn is active. If another editor changes the task, reopen the task and review the latest instructions. A rejected save leaves the draft visible.
@@ -169,7 +169,7 @@ Schedules do not replay missed occurrences after a gateway restart:
| Schedule | Behavior after restart |
|---|---|
| One-time (`at`) | A time already in the past has no next run and is not automatically executed. Review the task and run it manually or create a replacement. |
-| Interval (`every`) | The next run is one full interval after restart; missed intervals are not replayed. |
+| Interval (`every`) | If the next run is still in the future and no more than one interval away, nanobot keeps that time. If it has already passed, that run is skipped and the next run is scheduled; missed runs are not replayed. |
| Cron expression | The next matching time after restart is used; missed matches are not replayed. |
Intervals are also recalculated after a run finishes, so a long-running task can shift its next interval. Use a cron expression for wall-clock scheduling, and keep the host awake and gateway running when timing matters. These rules concern scheduled jobs; queued local trigger messages have the separate recovery behavior below.
diff --git a/docs/chat-apps.md b/docs/chat-apps.md
index 4b178a119..996bbf643 100644
--- a/docs/chat-apps.md
+++ b/docs/chat-apps.md
@@ -315,9 +315,11 @@ If you prefer to configure manually, add the following to `~/.nanobot/config.jso
```
> `groupPolicy` controls how the bot responds in group channels:
-> - `"mention"` (default) — Only respond when @mentioned
-> - `"open"` — Respond to all messages DMs always respond when the sender is in `allowFrom`.
-> - If you set group policy to open create new threads as private threads and then @ the bot into it. Otherwise the thread itself and the channel in which you spawned it will spawn a bot session. `allowChannels` restricts the bot to specific Discord channel IDs. Empty (default) means respond in every channel the bot can see. Example: `["1234567890", "0987654321"]`. The filter applies after `allowFrom`, so both must pass. Discord threads under an allowed parent channel are also allowed; for Forum channels, allowing the parent Forum channel allows all threads/posts in that forum. `streaming` defaults to `true`. Disable it only if you explicitly want non-streaming replies. `replyToMessage` defaults to `false`. Enable it to use Discord's native reply UI for responses.
+> - `"mention"` (default) — Reply only when someone @mentions the bot.
+> - `"open"` — Reply to all messages in group channels.
+> - In direct messages, the bot replies only when the sender is listed in `allowFrom`.
+>
+> For open group policy, create a private thread and @mention the bot to start a session there. Otherwise, the bot starts a session in both the thread and the channel where you created it. `allowChannels` restricts the bot to specific Discord channel IDs. The default empty list allows every channel the bot can see. Example: `["1234567890", "0987654321"]`. The `allowFrom` and `allowChannels` filters both apply. Threads under an allowed channel are also allowed; for Forum channels, allowing the parent Forum channel allows all its threads and posts. `streaming` defaults to `true`; disable it only if you want non-streaming replies. `replyToMessage` defaults to `false`; enable it to use Discord's native reply UI for responses.
**5. Invite the bot**
- OAuth2 → URL Generator
diff --git a/docs/chat-commands.md b/docs/chat-commands.md
index 427f8dbc5..3853d37cc 100644
--- a/docs/chat-commands.md
+++ b/docs/chat-commands.md
@@ -58,7 +58,7 @@ Use `/model` to inspect the current runtime model:
/model
```
-The response shows the current session's model and preset, plus the available preset names. Each key under the top-level `modelPresets` config is the preset's canonical name everywhere nanobot displays or references it. `default` is always available and represents the model settings from direct `agents.defaults.*` fields.
+The response shows which model this conversation is using and the names of models you can switch to. `default` is also available and uses the instance's default model settings.
To switch presets for future turns:
@@ -68,7 +68,7 @@ To switch presets for future turns:
/model default
```
-Preset names come from the top-level `modelPresets` config. Switching affects only the current session and persists the selection in that session, so later turns keep using it across process restarts. It does not rewrite `config.json`, does not change other sessions, and does not alter an in-progress turn's captured model. Sessions without a saved selection follow `agents.defaults.modelPreset` (or the implicit `default` preset when it is omitted). See [Configuration: Model presets](./configuration.md#model-presets) for setup details.
+Switching changes the model used for future replies in this conversation and keeps that choice for later turns, including after a restart. It does not change other conversations or interrupt a reply already in progress. To add or configure model choices, see [Configuration: Model presets](./configuration.md#model-presets).
## Local triggers
diff --git a/docs/concepts.md b/docs/concepts.md
index 52f185f9d..496ef9107 100644
--- a/docs/concepts.md
+++ b/docs/concepts.md
@@ -10,14 +10,14 @@ nanobot has one small core loop and several ways to enter it:
| Part | What it does |
|---|---|
-| Agent loop | Builds context, selects the session, calls the provider, runs tools, and publishes replies |
+| Agent | Takes an incoming message, chooses the conversation and model, uses enabled tools when needed, and prepares a reply |
| Providers | LLM backends such as OpenRouter, Anthropic, OpenAI, Bedrock, Ollama, vLLM, and other OpenAI-compatible APIs |
| Channels | User-facing transports such as CLI, WebUI/WebSocket, Telegram, Discord, Slack, Feishu, WeChat, Email, Mattermost, and others |
| Tools | Capabilities the model may call, including files, shell, web search/fetch, MCP, cron, image generation, and subagents |
| Memory | Workspace files and session history that keep useful context across turns |
| Gateway | Long-running process that connects enabled channels and serves the health endpoint |
-The simplest path is `nanobot agent -m "Hello!"`: one inbound message goes through the agent loop and prints the reply in your terminal. The long-running path is `nanobot gateway`: channels receive messages from chat apps or the WebUI, publish them to the same agent loop, and send replies back to the originating channel.
+To test nanobot once, run `nanobot agent -m "Hello!"`; it prints a reply in your terminal. To keep nanobot running, start `nanobot gateway`. It receives messages from enabled chat apps or the WebUI and sends replies back to the same conversation.
## Config vs Workspace
@@ -62,11 +62,10 @@ Most examples are partial snippets. Merge them into the existing file created by
A normal turn follows this flow:
-1. A channel receives a user message and publishes it to the message bus.
-2. The agent loop chooses a session key and builds context from the effective project workspace, agent-owned profile/skills/memory, recent messages, channel metadata, and runtime settings.
-3. The provider receives the model request.
-4. If the model asks for tools, the runner executes them and feeds results back to the model.
-5. The final reply is saved to the session and sent back through the channel.
+1. The CLI, WebUI, or a connected chat app receives your message.
+2. nanobot uses the conversation's history and the files available to that chat to prepare the request.
+3. Your selected AI service generates a response. If it needs an enabled tool, nanobot runs that tool and returns the result to the model.
+4. nanobot saves the reply in the conversation and shows or sends it through the same app or channel.
That flow is the same whether the message starts in the CLI, WebUI, Telegram, Discord, or another channel.
@@ -140,7 +139,7 @@ See [`memory.md`](./memory.md) for the detailed design.
## Apps and Agent Plugins
-Agent Plugins are nanobot's common package and activation boundary for installable capabilities. They organize existing extension types instead of replacing them:
+Agent Plugins are installable packages that help you add and manage capabilities in nanobot. A package can include one or more of these:
| Part | Role |
|---|---|
@@ -154,7 +153,7 @@ Native providers, channels, built-in tools, standalone workspace skills, and dir
## Tools and Safety
-Tools are discovered automatically from built-in modules and plugin entry points. Common tool groups include:
+nanobot can use built-in tools and tools enabled through Apps. Common tool groups include:
- file read/write/edit and patching;
- shell execution with configurable sandboxing;
diff --git a/docs/deployment.md b/docs/deployment.md
index 0c5129c88..5c6a6082e 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -109,7 +109,7 @@ Set `publicWsUrl` to the browser-facing `wss://` endpoint when the tunnel sends
### Docker Compose
-On a new Linux host, install Git and Docker with the Compose plugin, then get the repository. No host Python or host `nanobot` installation is required:
+On a new Linux host, install Git and Docker with the Compose plugin, then get the repository. You do not need to install Python or nanobot on the host:
```bash
git clone https://github.com/HKUDS/nanobot.git
diff --git a/docs/guides/configure-mcp-tools.md b/docs/guides/configure-mcp-tools.md
index c802be96f..d5915ebad 100644
--- a/docs/guides/configure-mcp-tools.md
+++ b/docs/guides/configure-mcp-tools.md
@@ -16,7 +16,7 @@ Use MCP when the capability you need already exists as an MCP server, or when yo
Complete [Quick Start](../quick-start.md) if nanobot is not installed or cannot reply yet. If you already have a working WebUI or CLI session, continue here using that instance; no reinstall or second gateway is needed.
-Install the MCP server runtime separately. Many examples use `npx`, `uvx`, or a remote HTTP endpoint.
+Choose a connection type first: use **stdio** for a tool that nanobot starts as a local process (you must install its runtime, such as `npx` or `uvx`); use **HTTP** or **SSE** for a tool available at a remote URL. If the remote server requires sign-in, configure OAuth in Apps and connect it in the browser.
## Minimal working example
@@ -62,7 +62,7 @@ Restart nanobot and ask a question that requires the MCP tool.
## Security notes
- Stdio MCP starts a local process; review the command before enabling it.
-- HTTP/SSE MCP uses nanobot's SSRF guard, including OAuth discovery, registration, token exchange, and redirects.
+- HTTP/SSE connections are checked to prevent nanobot from reaching private or internal network addresses. This check also applies during OAuth sign-in and redirects.
- OAuth credentials live in the nanobot data directory, not in `config.json`.
- Allow private HTTP MCP hosts only with narrow `tools.ssrfWhitelist` CIDRs.
- Do not place secrets in command arguments when environment variables or headers can be used.
diff --git a/docs/guides/configure-ollama-prompt-cache.md b/docs/guides/configure-ollama-prompt-cache.md
index fd83b1718..67d3cdf08 100644
--- a/docs/guides/configure-ollama-prompt-cache.md
+++ b/docs/guides/configure-ollama-prompt-cache.md
@@ -1,6 +1,6 @@
-# How to Improve Ollama Tool-Calling Prompt Cache Reuse in nanobot
+# Reuse Ollama Prompt Cache to Reduce Repeated Processing
-Some Ollama model templates move or remove tool definitions as a conversation switches between user, assistant, and tool messages. nanobot can send a correct append-only chat request while the model template still renders a different token prefix. On slower local hardware, re-evaluating that prefix can add tens of seconds to an otherwise simple tool-using turn.
+Ollama can reuse work from an earlier prompt when the beginning of the prompt stays the same. Some model templates move or remove tool instructions as a conversation switches between user, assistant, and tool messages, so Ollama must process much of the prompt again. On slower local hardware, this can add tens of seconds to a tool-using turn.
This guide shows how to diagnose that specific pattern and create a derived `llama3.1:8b` tag with a prefix-stable tool template. It does not modify nanobot or overwrite the original Ollama model.
@@ -66,7 +66,7 @@ The cache is working, but the next main request can reuse only the shorter promp
To inspect the API request bodies as well, add `OLLAMA_DEBUG_LOG_REQUESTS=1` before starting Ollama. These logs can contain system prompts, workspace context, and user messages. Keep them local and disable request logging after diagnosis.
-## Why this happens with the stock template
+## Why the default template can limit cache reuse
The tested `llama3.1:8b` template conditionally expands the tool definitions inside a user message:
diff --git a/docs/guides/configure-web-search.md b/docs/guides/configure-web-search.md
index fafe275e3..da6554f7b 100644
--- a/docs/guides/configure-web-search.md
+++ b/docs/guides/configure-web-search.md
@@ -74,10 +74,9 @@ Ask a question that requires current information and inspect the tool activity i
## Security notes
-- Web fetch and HTTP MCP share an SSRF guard.
-- Private, loopback, link-local, and cloud metadata addresses are blocked by default.
+- Web fetch and HTTP MCP share an address check that prevents requests to private or internal network locations. Private, loopback, link-local, and cloud metadata addresses are blocked by default.
- With `useJinaReader` enabled (the default), fetched URLs are disclosed to the remote reader service. Credential-bearing URLs (userinfo or token/signature query parameters) are fetched locally instead; path-embedded secrets cannot be detected, so disable the remote reader when URLs must stay local.
-- Add `tools.ssrfWhitelist` only for narrow trusted CIDRs.
+- Add `tools.ssrfWhitelist` only for narrow trusted CIDRs. This setting exempts those address ranges from the private-address block; use the smallest range needed.
- Do not give public chat users unrestricted web and shell access without review.
## Troubleshooting
diff --git a/docs/guides/linear-agent.md b/docs/guides/linear-agent.md
index 2d7602695..95bc7594c 100644
--- a/docs/guides/linear-agent.md
+++ b/docs/guides/linear-agent.md
@@ -52,7 +52,7 @@ The four network fields have different jobs:
### Webhook and networking requirements
-The native Linear Agent transport requires a webhook; there is no polling mode. The OAuth callback also needs to reach the same nanobot instance.
+OAuth connects and authorizes the Linear workspace. A webhook sends new Linear tasks to nanobot; this integration does not poll for tasks. Both the OAuth return address and webhook must reach the same nanobot instance.
You do **not** need a public IP address when using an HTTPS tunnel such as Cloudflare Tunnel or Tailscale Funnel. On a publicly reachable server, Caddy, nginx, or another reverse proxy can provide HTTPS and forward requests to `127.0.0.1:3979`. Use a stable hostname for normal use: if the hostname changes, update **Public HTTPS URL** in nanobot and both registered URLs in the Linear app.
diff --git a/docs/memory.md b/docs/memory.md
index af9004afd..1ace66dbd 100644
--- a/docs/memory.md
+++ b/docs/memory.md
@@ -1,12 +1,6 @@
# AI Agent Memory in nanobot
-This page explains how nanobot implements long-term AI agent memory: session history, compressed archives, durable knowledge files, Dream consolidation, and Git-backed memory changes.
-
-nanobot's memory is built on a simple belief: memory should feel alive, but it should not feel chaotic.
-
-Good memory is not a pile of notes. It is a quiet system of attention. It notices what is worth keeping, lets go of what no longer needs the spotlight, and turns lived experience into something calm, durable, and useful.
-
-That is the shape of memory in nanobot.
+nanobot keeps recent conversation history separate from longer-term information such as your preferences. Conversations are summarized as they grow or when you run `/compact`; if Dream is enabled, it can use those summaries to update long-term memory on its schedule, or when you run `/dream`. You can inspect and correct saved preferences. A reply saying it understood your preference does not by itself confirm that the preference was saved.
## The Design
@@ -23,7 +17,7 @@ This keeps the system light in the moment, but reflective over time.
## The Flow
-Memory moves through nanobot in two stages.
+Long-term memory is updated in two stages.
### Stage 1: Consolidator
@@ -33,11 +27,7 @@ Compaction also runs after a configured period of inactivity, or when you send `
Automatic compaction does not post lifecycle notices to built-in chat channels by default. This only silences chat messages: compaction still runs, and WebUI/TUI retain structured status and history. Manual `/compact` keeps its start and outcome feedback. Set `channels.showCompactionNotices: true` to enable automatic notices globally, or set `showCompactionNotices` in a channel's configuration to override that default. Omitted or `null` channel overrides inherit the global value; existing explicit QQ overrides are preserved.
-This file is:
-
-- appended to as conversations are compacted
-- cursor-based
-- optimized for machine consumption first, human inspection second
+This file is updated as conversations are summarized. It uses one JSON record per line so nanobot can track which summaries have already been processed; it is primarily an internal working history, not a permanent archive.
Each line is a JSON object:
diff --git a/docs/multiple-instances.md b/docs/multiple-instances.md
index 7c01a45ef..31347c772 100644
--- a/docs/multiple-instances.md
+++ b/docs/multiple-instances.md
@@ -36,7 +36,7 @@ Concurrent instances need distinct gateway health ports and WebUI/channel ports.
| Memory, skills, cron jobs | Under the workspace |
| CLI input history | `<home>/history/cli_history` |
-An explicit `--config` also selects the runtime data directory. Keep each config in its own directory and use separate workspaces to isolate memory, skills, and sessions. Selecting a home does not relocate paths saved in an existing config.
+An explicit `--config` also selects the runtime data directory. Keep each config in its own directory and use separate workspaces to isolate memory, skills, and sessions. A new home gets its own config and default workspace; existing paths saved in a config remain unchanged when you select a different `--home`. Check which paths this instance will use with `nanobot --home ~/.nanobot-work status`. Selecting a home does not move or rewrite paths saved in an existing config.
For custom config/workspace locations:
diff --git a/docs/my-tool.md b/docs/my-tool.md
index 65dbcdb87..86b9a1d96 100644
--- a/docs/my-tool.md
+++ b/docs/my-tool.md
@@ -1,6 +1,6 @@
# My Tool
-Let the agent sense and adjust its own runtime state — like asking a coworker "are you busy? can you switch to a bigger monitor?"
+This page is for operators configuring the agent's runtime self-inspection tool. It describes what the agent can read or change at runtime, and what it saves. It is not a user preference store: scratchpad values last only through the next conversation turn.
## Why You Need It
diff --git a/docs/quick-start.md b/docs/quick-start.md
index 54d073354..1438c5032 100644
--- a/docs/quick-start.md
+++ b/docs/quick-start.md
@@ -12,7 +12,7 @@ These repository docs describe `main`, which can be newer than the released pack
- Access to one supported AI provider, company endpoint, or local model server.
- The credential, endpoint URL, and model ID required by that service. Local providers such as Ollama may not require a key.
-Git and [Bun](https://bun.sh/) are only needed for an editable source install. Platform wheels contain both the WebUI and the matching native TUI, including its licenses, notices, corresponding application source, source offer, and relinking instructions. They support macOS 13+ (Apple Silicon and Intel), glibc 2.17+ Linux (ARM64 and x64), and Windows x64. Pip selects the right wheel; first TUI launch does not download anything from GitHub. Other platforms and source-distribution builds can use the WebUI or `nanobot --classic`; see the [terminal requirements](./cli-reference.md#agent-cli) for native TUI availability.
+Git and [Bun](https://bun.sh/) are only needed if you want to install from editable source code. The published installer supports macOS 13+ (Apple Silicon and Intel), Linux with glibc 2.17+ (ARM64 and x64), and Windows x64. On other platforms, use the WebUI or `nanobot --classic`. See the [terminal requirements](./cli-reference.md#agent-cli) for native TUI availability and the [release notes](https://nanobot.wiki/docs/latest/getting-started/quick-start) for package details.
## 1. Install nanobot
diff --git a/docs/start-without-technical-background.md b/docs/start-without-technical-background.md
index aa5776d02..ba1215d01 100644
--- a/docs/start-without-technical-background.md
+++ b/docs/start-without-technical-background.md
@@ -45,7 +45,7 @@ The result should start with `Python 3.11` or a newer number. If the command is
## 2. Prepare Your Model Details
-A chat website account is not automatically an API credential. nanobot needs a supported provider connection: an API key, a supported sign-in flow, or a local model server. Check the chosen service's billing and available models before using it.
+An account on a chat website does not automatically let nanobot use that service. Before you start, find out which AI service you will use, how nanobot can sign in (usually with an API key, sometimes with a supported sign-in flow), and the exact model name the service requires. Check the service's pricing and available models. Some services also require a URL; use it only if that service provides one.
If you do not have a provider yet, here is one API-based example:
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index a1b74ba05..f22e8366d 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -1,35 +1,15 @@
# Troubleshooting
-Use this page to isolate where a failure lives. Start with the smallest surface that proves the most: local CLI first, then gateway, then WebUI or chat apps.
+Use the first check that matches what you see, then follow its next step. This avoids investigating the browser or a chat app before confirming nanobot can start and contact its model.
## Fast Diagnosis Order
-Run these in order:
+- **The `nanobot` command is not found, or nanobot will not start:** check [Installation Problems](#installation-problems). Run `nanobot --version` to confirm the command is available.
+- **nanobot starts, but does not answer:** run `nanobot status`. Check that it points to the config and workspace you expect and that the active model is ready. This command does not contact the model; if setup is incomplete, follow its WebUI **Settings → Models** or CLI wizard instructions.
+- **Status looks ready, but a test question fails:** run `nanobot agent -m "Hello!"`. If it fails, troubleshoot [Provider and Model Problems](#provider-and-model-problems) before testing the gateway or a chat app.
+- **The test question works, but the browser or chat app does not:** start `nanobot gateway` and follow [Gateway Problems](#gateway-problems), [WebUI Problems](#webui-problems), or [Chat App Problems](#chat-app-problems), depending on what is failing.
-```bash
-nanobot --version
-nanobot status
-nanobot agent -m "Hello!"
-```
-
-Then, only if the CLI works:
-
-```bash
-nanobot gateway
-```
-
-This separates failures into layers:
-
-| Layer | What it proves |
-|---|---|
-| `nanobot --version` | Install and shell command discovery |
-| `nanobot status` | Config path, workspace, environment references, and active provider/model configuration |
-| `nanobot agent -m "Hello!"` | Config loading, provider/model access, workspace writes, and agent loop |
-| `nanobot gateway` | Channel startup, cron system jobs, heartbeat, WebUI/WebSocket, and health endpoint |
-
-If `nanobot agent -m "Hello!"` fails, fix that before debugging WebUI, Telegram, Discord, Docker, systemd, or any chat app.
-
-`nanobot status` does not call the model. If provider/model setup is incomplete, it points to WebUI **Settings → Models** or the CLI setup wizard, then prints the command to check again.
+`nanobot status` checks local configuration and provider readiness without making a model request. A successful `nanobot agent -m "Hello!"` confirms the local agent can get a reply; it does not prove that a gateway, browser, or chat app is working.
## Empty topics after a WebUI restart
diff --git a/docs/webui.md b/docs/webui.md
index 7369b2861..d39eb7260 100644
--- a/docs/webui.md
+++ b/docs/webui.md
@@ -58,9 +58,7 @@ The WebUI is served by the WebSocket channel on port `8765` by default. The gate
## Navigate a long conversation
-On wide conversation panes, the left message rail lists all saved prompts independently of the loaded message page. Scroll the rail to browse, hover to preview, and click to jump directly to a prompt; its edges fade without extending the conversation layout. The header's message navigation also supports searching the prompt summaries. Both lists render a visible window rather than thousands of controls. Older compatible hosts without `webui.prompt-navigation.v1` retain navigation within already-loaded messages.
-
-Jumping reads a bounded page near the selected prompt, not every earlier answer. Browsing keeps at most three server pages, supports scrolling backward and forward, and the bottom arrow returns to the live conversation. A failed read leaves the current content intact and offers retry. The navigation index is a rebuildable, bounded summary cache over the WebUI display transcript; it does not change the SQLite session schema, agent context, configuration, or chat data. On first access to a long uncached conversation, building the summaries requires reading its transcript segments in a worker thread; later accesses reuse unchanged segment summaries. Unchanged directories use conditional requests without a response body. Changed directories transfer only the changed suffix when a previous snapshot is still cached; after a restart or cache eviction, the host sends a complete directory. These caches are held in memory and do not create another persistent chat store.
+On wide screens, use the message rail on the left to browse saved prompts; click one to jump to it. You can also search prompt summaries from the header. The WebUI loads messages near the selected prompt rather than the entire conversation. Scroll backward or forward to browse, or use the bottom arrow to return to the latest messages. If loading fails, your current content stays visible and you can retry. Older compatible hosts may only support navigation among messages that are already loaded.
## Sharing access