@turmind/halo 1.5.3-alpha → 1.5.5

package/bundled-docs/guide/channels/telegram.md

@@ -24,27 +24,25 @@ Sending `/setcommands` to BotFather lets Telegram clients show a menu next to th
 /setcommands → pick your bot → paste:
 
 start - 开始 / start
-new - 新会话 / new session
-list - 会话列表 / list sessions
-switch - 切换会话 / switch session
-stop - 中断任务 / stop running task
-compact - 压缩上下文 / compact context
-ws - 查看/切换 workspace
+session - 会话管理 / manage sessions
+agent - 智能体 / manage agents
+skill - 技能 / manage skills
+workspace - 查看/切换 workspace
 help - 帮助 / help
 ```
 
 ## Step 3 — Add the account in halo admin
 
-Open halo admin → **Channels** → **Telegram** → **Add Account**:
+Open halo admin → **Channels** → **Telegram** → **Add Bot**:
 
 | Field | Value |
 |---|---|
-| Bot token | the `…:ABC…` from Step 1 |
-| Workspace path | absolute path, e.g. `/home/ubuntu/my-project` |
-| Label | optional |
+| Bot Token (from @BotFather) | the `…:ABC…` from Step 1 |
+| Bind to workspace | absolute path, e.g. `/home/ubuntu/my-project` |
+| Name (optional) | a label for the account |
 | Access level | `readonly` (default), `workspace`, or `full` |
 | Language | `en` or `zh` |
-| Allowed users | optional whitelist; comma-separated user IDs and/or `@usernames`. Empty = anyone can talk to the bot |
+| Allowed users (optional) | whitelist; comma-separated user IDs and/or `@usernames`. Empty = anyone can talk to the bot |
 
 On submit halo calls Telegram's `getMe` to validate the token and auto-fill `botUsername`. If that call fails the account isn't created.
 
@@ -52,7 +50,7 @@ On submit halo calls Telegram's `getMe` to validate the token and auto-fill `bot
 
 - **Empty** — anyone who finds the bot can chat with it. Fine for personal bots, dangerous if the bot is `full`-access
 - **Numeric IDs** (e.g. `123456789`) — recommended. A user's id is stable and you can find it by sending `/start` to `@userinfobot` in Telegram
-- **`@username`** — works for inbound filtering but **cron fan-out skips them** (Telegram's Bot API needs a numeric chat id, and `@username` lookup isn't always reliable)
+- **`@username`** — works for inbound filtering (matched case-insensitively against the sender's current username, so it breaks if they rename)
 
 For team bots prefer numeric IDs.
 
@@ -60,13 +58,15 @@ For team bots prefer numeric IDs.
 
 In Telegram, search the bot's username (`@halo_dev_bot`) → press **Start** → say `hello` → expect a streamed reply.
 
-If nothing happens, check halo server logs for `[telegram]` lines.
+If nothing happens, check halo server logs for `[Telegram]` lines.
 
 ## How halo handles inbound
 
 - **Private chats** — every message routes to the bot
-- **Group chats** — not supported in v1 (group messages are dropped)
-- **Photos / documents** — the file URL is included in the agent's input text; images aren't yet sent to vision automatically (by design — Telegram's photo URLs are short-lived and the upstream LLM can't always reach them)
+- **Group chats** — supported. Each member talks to their **own** session (the same one they use in DM with the bot), and the bot replies in the group. `allowedUsers` is checked against the sender, so non-whitelisted members are refused there too. By default Telegram's *privacy mode* only delivers `/command@yourbot` and replies to the bot's messages; to have the bot see every group message, send `/setprivacy` → **Disable** to BotFather (then re-add the bot to the group) or make it a group admin
+- **Photos** — downloaded, sent to the model as vision input and saved under `<workspace>/.halo/assets/telegram/inbound/<accountId>/<date>/`; the saved path is appended to the message text
+- **Documents / voice / round video** — downloaded (20 MB cap) to the same folder; the agent gets the saved path in the message text, not the content
+- **After a server restart** — if the agent was mid-task when halo restarted, its reply still reaches the most recent private chat the user talked in; a group conversation reconnects on the user's next message there
 - **Slash commands** — handled by halo, not by Telegram. The BotFather menu in Step 2 is just a UI hint
 
 ## Slash commands
@@ -74,31 +74,25 @@ If nothing happens, check halo server logs for `[telegram]` lines.
 | Command | Effect |
 |---|---|
 | `/start` | Welcome message |
-| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` |
+| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` / `info` |
 | `/agent <verb>` | Manage agents (`list` / `switch` / `desc` open to all; `delete` full; `create` / `update` via skill, full) |
 | `/skill <verb>` | Manage skills (`list` / `desc` open; `disable` / `enable` workspace; `delete` full; `create` / `update` via skill, full) |
 | `/workspace <verb>` | Workspace: `info` (all) / `switch <path>` (full) / `setup` / `tidy` (workspace) / `share` (full) |
+| `/cron` `/acp` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
 | `/help` | List commands — object commands show only the verbs you can run |
 
 ## Cron jobs targeting Telegram
 
-When a cron job is created from inside a Telegram chat, the dispatcher targets that chat. From the admin UI you can also enter chat IDs directly (comma-separated for fan-out). The dispatcher resolves recipients in this order:
-
-1. Explicit chat IDs on the cron target row (if provided in the form)
-2. Fan-out to every numeric ID in the account's `allowedUsers` whitelist
-3. The most-recent inbound chat ID, as a single-recipient fallback
-
-Want to fan out a daily report to your whole team? Add their numeric IDs to `allowedUsers` and create a cron without an explicit chat ID — halo delivers to each one and records per-recipient ✓/✗ in the cron run history.
+When a cron job is created from inside a Telegram chat, the dispatcher targets that chat. From the admin UI you can also enter chat IDs directly (comma-separated for fan-out). A Telegram target **must** carry an explicit numeric chat ID (for a private chat it equals the user ID; a group's is negative) — there is no fallback to the whitelist or to the last inbound chat, and the dispatch fails without one. Per-recipient ✓/✗ is recorded in the cron run history. A report longer than 4000 characters is sent as several messages, in order.
 
 ## Common problems
 
 | Symptom | Cause / fix |
 |---|---|
-| "Unauthorized" / `getMe` fails on Add Account | Bot token has a typo, or the bot was deleted in BotFather |
+| "Unauthorized" / `getMe` fails on Add Bot | Bot token has a typo, or the bot was deleted in BotFather |
 | Bot exists but doesn't reply | Check `allowedUsers` — if non-empty, your user must be in it |
-| Bot used to work, now silent | Maybe two halo processes are running and stealing each other's `getUpdates` long-poll. Check `~/.halo/global/server.pid` |
-| Group messages don't trigger the bot | Expected — groups aren't supported in v1 |
-| Cron fan-out skips a whitelisted user | The user is listed as `@username`. Add their numeric ID instead |
+| Bot used to work, now silent | Maybe two halo processes are running and stealing each other's `getUpdates` long-poll. Check `~/.halo/global/server.lock` |
+| Group messages don't trigger the bot | Privacy mode is on (the default): only `/command@yourbot` and replies to the bot get through. Disable it with BotFather `/setprivacy` and re-add the bot, or make it a group admin |
 
 ## Multi-bot setup
 

package/bundled-docs/guide/channels/web.md

@@ -13,13 +13,13 @@ The token is **the** credential — anyone holding it can talk to the agent at t
 
 ## Step 1 — Create an account
 
-Open halo admin → **Channels** → **Web** → **Add Account**:
+Open halo admin → **Channels** → **Web** → **Create Access**:
 
 | Field | Value |
 |---|---|
-| Workspace path | absolute path, e.g. `/home/ubuntu/my-project` |
-| Label | optional |
-| Access level | `readonly` (default), `workspace`, or `full` |
+| Bind to workspace | absolute path, e.g. `/home/ubuntu/my-project` |
+| Name (optional) | a label for the account |
+| Access level | `readonly` (default), `workspace`, `full`, or `observer` (global read-only, for dashboards / metrics) |
 | Language | `en` or `zh` |
 
 Click **Create**. The success screen shows the auto-generated token **once** — copy it now, you can't retrieve it again. (You can always delete the account and create a new one if you lose the token.)
@@ -55,18 +55,20 @@ Parse the `type` field on each event to render text vs tool calls vs completion.
 | Method | Path | Purpose |
 |---|---|---|
 | `POST /api/web/chat` | Send a message; SSE response |
+| `POST /api/web/sessions` | Mint a new root session in the token's namespace; returns `{sessionId}` |
 | `POST /api/web/stop` | Cancel the running task |
 | `GET /api/web/history` | Fetch session message history |
 | `GET /api/web/subscribe` | Reconnect to a running session's SSE stream |
+| `GET /api/web/file?path=…` | Fetch a file from the bound workspace (path relative to it; `.halo` runtime state is refused) |
 
-All four accept the same auth header.
+All six accept the same auth header.
 
 ### Per-request overrides
 
 By default each token is locked to the workspace and active session set by the admin. External integrations (notably the [ACP adapter](acp.md)) need finer control:
 
 - `workspace` — server-side absolute path, **gated on `accessLevel === 'full'`** (readonly / workspace tokens can't escape their bound workspace; the override is rejected)
-- `sessionId` — explicit halo session id; lets clients pre-mint stable ids and address them across reconnects
+- `sessionId` — explicit halo session id; lets clients address a session across reconnects. **Gated on ownership**: `full` tokens may name any id; `readonly` / `workspace` tokens only ids under their own account (`web_<accountId>_*`, e.g. minted by `POST /api/web/sessions`) — anything else is `403`
 - `agentId` — only used when the request creates a new session
 
 These can be passed as POST body fields, headers (`x-workspace`, `x-session-id`, `x-agent-id`), or query params (`?workspace=…&sessionId=…&agentId=…`). POST body wins on conflict.
@@ -86,7 +88,7 @@ For browser apps you almost never want these — leave them off and use the per-
 }
 ```
 
-Images go to the LLM as multimodal content. Audio and other binary uploads aren't supported on this endpoint directly — for those, save the file to `<workspace>/.halo/assets/web/inbound/<accountId>/<date>/` first (out-of-band) and reference its path in your message text.
+Images go to the LLM as multimodal content. Any other `mimeType` (audio, PDF, …) in the same array is not sent to the model: the server saves it to `<workspace>/.halo/assets/web/inbound/<accountId>/<date>/` and appends a `[语音已保存: <path>]` line to your message so the agent can open it with its file tools.
 
 The standalone web-demo handles voice + arbitrary files for you; if you want that, use it as a reference implementation.
 
@@ -96,10 +98,11 @@ Slash commands are intercepted before they reach the agent — same set as every
 
 | Command | Effect |
 |---|---|
-| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` |
+| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` / `info` |
 | `/agent <verb>` | Manage agents (`list` / `switch` / `desc` open to all; `delete` full; `create` / `update` via skill, full) |
 | `/skill <verb>` | Manage skills (`list` / `desc` open; `disable` / `enable` workspace; `delete` full; `create` / `update` via skill, full) |
 | `/workspace <verb>` | Workspace: `info` (all) / `switch <path>` (full) / `setup` / `tidy` (workspace) / `share` (full) |
+| `/cron` `/acp` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
 | `/help` | List commands — object commands show only the verbs you can run |
 
 Send a slash command exactly like a normal message — the server detects the leading `/`.
@@ -109,7 +112,8 @@ Send a slash command exactly like a normal message — the server detects the le
 | Symptom | Cause / fix |
 |---|---|
 | `401` on every call | Missing `x-token` header, or token is for a deleted account |
-| `403` when passing `workspace=…` | Token is `readonly` / `workspace` access — only `full` can override |
+| `429` | 5 bad tokens from one IP within 15 minutes locks that IP out for 15 minutes (in-memory, cleared on restart) |
+| `403` when passing `workspace=…` or a foreign `sessionId` | Token is `readonly` / `workspace` access — only `full` can override the workspace or address sessions it didn't mint |
 | SSE stream hangs forever | Reverse proxy buffering. Disable buffering for `text/event-stream` (nginx: `proxy_buffering off`, Cloudflare: enable streaming) |
 | Token leaked accidentally | Delete the account in admin, create a new one. The old token is invalidated immediately |
 | Want to share one token across multiple users | Don't — every request would land on the same active session. Create one account per user / app |
@@ -139,9 +143,9 @@ Alternatively, the gear icon (header / login screen) opens **direct-connect mode
 ## Security notes
 
 - **Tokens are unhashed** in `~/.halo/secrets/channels/channels.db`. Restrict that file to the user that runs halo
-- **No rate limit at the channel level** — if you expose the API on the public internet, put a reverse proxy with rate limits in front
+- **Bad-token lockout only** — 5 invalid tokens from one IP in 15 minutes locks that IP out (`429`) for 15 minutes; there is no per-token request rate limit, so if you expose the API on the public internet put a reverse proxy with rate limits in front
 - **Admin endpoints** (`POST /api/web/accounts`, `PATCH`, `DELETE`) require admin cookie auth, **not** the token. They're for the admin panel, not for the token holder
-- A `full`-access token can call `/workspace <abs-path>` to switch the bound workspace database-side. If you don't want that, give out `workspace` or `readonly` tokens instead
+- A `full`-access token can call `/workspace switch <abs-path>` to switch the bound workspace database-side. If you don't want that, give out `workspace` or `readonly` tokens instead
 
 ## Reference
 

package/bundled-docs/guide/channels/wechat.md

@@ -21,18 +21,18 @@ Halo auto-creates `.halo/` inside the folder if it doesn't exist; the path itsel
 
 ## Step 2 — Open the admin scan flow
 
-Open halo admin → **Channels** → **WeChat** → **Add Account**.
+Open halo admin → **Channels** → **WeChat** → **Add Bot**.
 
 The form is **just the workspace + label + access level + language** — no bot token field, because the token comes from the scan:
 
 | Field | Value |
 |---|---|
-| Workspace path | absolute path from Step 1, e.g. `/home/ubuntu/my-project` |
-| Label | optional, shown in admin's account list |
+| Bind to workspace | absolute path from Step 1, e.g. `/home/ubuntu/my-project` |
+| Name (optional) | shown in admin's account list |
 | Access level | `readonly` (default), `workspace`, or `full` |
 | Language | `en` or `zh` |
 
-Click **Generate QR**. Halo hits `ilinkai.weixin.qq.com` to mint a fresh QR code and starts a poll loop waiting for the scan.
+Click **Next: Scan**. Halo hits `ilinkai.weixin.qq.com` to mint a fresh QR code and starts a poll loop waiting for the scan.
 
 > **What the access level covers.** A WeChat account is bound to exactly one WeChat user — the one who scans — so there's no whitelist to configure; the scanner *is* the whitelist. The level you choose here is what that phone gets: `full` means whoever holds the unlocked phone has shell access as the server user. The same applies to invite QRs minted with `/qr full` from inside the chat — each scan creates a separate account at the level you named, so hand those out as you would an SSH key.
 
@@ -43,19 +43,19 @@ Click **Generate QR**. Halo hits `ilinkai.weixin.qq.com` to mint a fresh QR code
 3. Aim at the QR shown in the admin UI
 4. Tap **Confirm Login / 确认登录** on the phone
 
-Within a few seconds the admin UI shows "登录成功" / "Logged in" and switches to the success page. Behind the scenes:
+Within a few seconds the admin UI shows "Connected (<id>)" and closes the dialog. Behind the scenes:
 
 - iLink returns the bot's token, the IDC-specific `baseUrl`, and your WeChat-side `ilink_user_id`
 - Halo writes those into the new account row
 - The long-poll loop starts immediately — the bot is now live
 
-The QR is valid for ~3 minutes; if it expires the admin UI auto-refreshes. If you cancel and come back later, just open the form again — a new QR is minted.
+The server waits up to ~8 minutes for the scan and gives up after the QR has expired three times; the dialog then shows the error and a **Start over** button. If you cancel and come back later, just open the form again — a new QR is minted.
 
 ## Step 4 — Test it
 
 The bot's name in your WeChat contacts is whatever the iLink platform set it to (typically a generic placeholder like `小助手`; you can rename it locally). Open the bot's chat in WeChat and send `hello` → expect a streamed reply.
 
-If nothing happens, check halo server logs for `[wechat]` lines.
+If nothing happens, check halo server logs for `[WeChat]` lines.
 
 ## How halo handles inbound
 
@@ -63,7 +63,8 @@ If nothing happens, check halo server logs for `[wechat]` lines.
 - **Images** — passed to the LLM as multimodal content
 - **Voice** — decrypted, saved under `<workspace>/.halo/assets/weixin/inbound/<accountId>/<date>/` (the `weixin` directory name is kept for backward compatibility with existing workspaces), path included in the agent's input
 - **Video / files** — same as voice
-- **Group chats** — not supported in v1 (group messages are dropped)
+- **Group chats** — not supported: the WeChat (iLink) bot is a one-to-one contact and the platform doesn't deliver group messages to it, so there is nothing for halo to handle
+- **After a server restart** — if the agent was mid-task when halo restarted, its reply still reaches each user who has chatted with the bot (as long as the stored `context_token` is still accepted; otherwise it fails with `ret=-2` until they write again)
 - **Self-loop** — bot-authored messages are filtered out
 
 ## Slash commands
@@ -72,12 +73,13 @@ Same set as the other channels — type as plain text in your WeChat DM with the
 
 | Command | Effect |
 |---|---|
-| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` |
+| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` / `info` |
 | `/agent <verb>` | Manage agents (`list` / `switch` / `desc` open to all; `delete` full; `create` / `update` via skill, full) |
 | `/skill <verb>` | Manage skills (`list` / `desc` open; `disable` / `enable` workspace; `delete` full; `create` / `update` via skill, full) |
 | `/workspace <verb>` | Workspace: `info` (all) / `switch <path>` (full) / `setup` / `tidy` (workspace) / `share` (full) |
+| `/cron` `/acp` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
 | `/help` | List commands — object commands show only the verbs you can run |
-| `/qr [level]` | Generate an invite QR (admin only) |
+| `/qr [level]` | Generate an invite QR (`full`-access bot only; `level` = `readonly` (default) / `workspace` / `full`) |
 
 ## Cron jobs targeting WeChat
 
@@ -94,11 +96,10 @@ Fan-out across multiple WeChat users is not supported — one bot, one owner.
 | Symptom | Cause / fix |
 |---|---|
 | QR shows but scan does nothing | iLink platform thinks the QR is for a different account. Cancel and regenerate |
-| "二维码已过期" / QR expired | Admin UI should auto-refresh. If not, click Generate again |
+| "登录超时：二维码多次过期" / QR expired | Click **Start over** in the dialog and scan the new QR |
 | Bot stops responding after a few hours | Long-poll likely lost its `syncBuf`. Restart the server; reconnect is automatic |
-| Two halo processes both poll the same bot | Each process gets a copy of every message, replied twice. Make sure only one server runs — see `~/.halo/global/server.pid` |
-| Group chat doesn't trigger the bot | Expected — groups aren't supported in v1 |
-| Sent voice message returns no reply | Check that the account has `workspace` or `full` access; readonly cannot save inbound media |
+| Two halo processes both poll the same bot | Each process gets a copy of every message, replied twice. Make sure only one server runs — see `~/.halo/global/server.lock` |
+| Group chat doesn't trigger the bot | Expected — WeChat (iLink) doesn't support group chats for bots; talk to it one-to-one |
 | Cron push or a delayed reply fails with `ret=-2 prepare failed` while fresh chat replies work | Three causes: the report exceeds 16 KB (halo chunks at 3500 chars, so this is rare now); the account has no stored `context_token` for the recipient yet — the gateway wants outbound to echo the user's latest inbound token, which halo persists on every inbound message since 1.1.8; or that token has **expired** — the gateway stops accepting it some time after the user's last message (the window isn't fixed; failures were seen 12 min and 79 min after the last inbound), and only a new inbound message from that user refreshes it. In all cases: send the bot any message once and the next push carries a fresh token. The error names which case it is (`context_token missing` / `context_token age 79m`), and a dropped chat reply now shows up as a `⚠️ WeChat delivery failed` notification in the session log (admin Sessions tab) instead of vanishing silently |
 
 ## Multi-workspace / multi-bot

package/bundled-docs/guide/channels/wecom.md

@@ -40,7 +40,7 @@ Open halo admin → **Channels** → **WeCom** → **Add Bot**:
 | Bot ID | from Step 3 |
 | Secret | from Step 3 |
 | Bind to workspace | absolute path, e.g. `/home/ubuntu/my-project` |
-| Name | optional label |
+| Name (optional) | a label for the account |
 | Access level | `readonly` (default), `workspace`, or `full` |
 | Language | `en` or `zh` — for hints and command replies |
 
@@ -91,16 +91,21 @@ When the agent emits a `MEDIA:<path>` line (a file under the workspace), halo up
 
 Replies render **Markdown natively** — headings, bold, lists, quotes, links, code blocks and tables all display as formatted text.
 
+### After a server restart
+
+If the agent was mid-task when halo restarted, its reply still reaches the **most recent** chat the bot talked in (one per bot). Because the original message can no longer be answered directly, that reply arrives as a regular pushed message rather than as a reply to your message; once you write again, replies go back to normal.
+
 ## Slash commands
 
 Same set as the other channels — type as plain text in a **single chat** (commands are ignored in groups, where the shared session belongs to everyone):
 
 | Command | Effect |
 |---|---|
-| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` |
+| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` / `info` |
 | `/agent <verb>` | Manage agents (`list` / `switch` / `desc` open to all; `delete` full; `create` / `update` via skill, full) |
 | `/skill <verb>` | Manage skills (`list` / `desc` open; `disable` / `enable` workspace; `delete` full; `create` / `update` via skill, full) |
 | `/workspace <verb>` | Workspace: `info` (all) / `switch <path>` (full) / `setup` / `tidy` (workspace) / `share` (full) |
+| `/cron` `/acp` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
 | `/help` | List commands — object commands show only the verbs you can run |
 
 ## Cron jobs targeting WeCom

package/bundled-docs/guide/chat.md

@@ -28,16 +28,16 @@ A change applies from the next message you send, and the level is saved per sess
 
 ## Context injection
 
-Next to the chat is a `📎 Context` toggle (on by default). When on, Halo auto-injects:
+The input toolbar shows a context chip (the open file's name, or the selection) — click it to toggle; on by default. When on, Halo auto-injects:
 - The currently open file path: `[Currently viewing: src/foo.ts]`
 - The editor's current selection: `[Selected text in foo.ts:10-25]\n\`\`\`...\n\`\`\``
 
-Turn it off if you don't want that context injected.
+Click the chip (it turns struck-through) if you don't want that context injected.
 
 ## `@` file mention
 
 Typing `@` in the input opens a file search:
-- Real-time fuzzy matching (150 ms debounce)
+- Real-time fuzzy matching (120 ms debounce)
 - Selecting inserts a path chip
 - You can `@` multiple files back-to-back
 
@@ -49,7 +49,7 @@ The search scans the whole project on the server — independent of Explorer exp
 - **Paste**: paste an image from the clipboard
 - **Button**: click the 📎 on the left
 
-Images are sent to the agent as base64, with multimodal support (Claude 4.6 can see images).
+Chat attachments are images only — other dropped or pasted files are ignored. Images are sent to the agent as base64, with multimodal support (Claude 4.6 can see images).
 
 ## Slash commands
 
@@ -59,13 +59,14 @@ Most commands are noun-verb **object commands**: `/<obj> <verb> [args]`. Bare `/
 
 | Command | Purpose |
 |---|---|
-| `/session <verb>` | Manage sessions — `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context`. All built-in, available to everyone. `new` starts a fresh conversation (old session stays in the sidebar; running sub-agents keep going); `compact` keeps the most recent N messages intact (N defaults to 5, `general.compact.keep_messages`); `context` shows token usage, agent info, and available tools |
+| `/session <verb>` | Manage sessions — `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` / `info` (session tree). All built-in, available to everyone. `new` starts a fresh conversation (old session stays in the sidebar; running sub-agents keep going); `compact` keeps the most recent N messages intact (N defaults to 5, `general.compact.keep_messages`); `context` shows token usage, agent info, and available tools |
 | `/clear` | Admin-UI alias for `/session new` |
 | `/agent <verb>` | Manage agents — `list` / `switch <name\|index>` / `desc` (built-in, open to all) · `delete` (built-in, full access) · `create` / `update` (handled by the `agent` skill, full access) |
 | `/skill <verb>` | Manage skills — `list` / `desc` (built-in, open to all) · `disable` / `enable` (built-in, workspace access) · `delete` (built-in, full access) · `create` / `update` (handled by the `skill` skill, full access) |
 | `/workspace <verb>` | Manage the workspace — `info` (built-in, open to all) · `switch <path>` (built-in, full access) · `setup` / `tidy` (workspace skill, workspace access; init / reorganize `.halo/` INDEX.md / INSTRUCTIONS.md / memory/) · `share` (workspace skill, full access; export a shareable bundle) |
 | `/cron <verb>` | Scheduled agent runs — `create` / `list` / `update` / `enable` / `disable` / `delete` (cron skill, full access) |
 | `/acp <verb>` | Talk to other agents over ACP — `kiro <q>` / `claude <q>` ask a local agent directly; `add` / `list` / `remove` manage generated `ask-<label>` bindings (acp skill, full access) |
+| `/extension <verb>` | Canvas preview extensions — `install <id\|zip\|url>` / `list` / `remove <id>` (extension skill, full access) |
 | `/evo [hint]` | Queue a self-evolution run on this session (full access only) |
 | `/help` | List every command — object commands only show the verbs you can run |
 
@@ -103,8 +104,8 @@ Three ways to cut in while the agent is running:
 The ring in the bottom-right of the input shows context window usage:
 - Green: < 50%
 - Yellow: 50–70%
-- Orange: 70–90%
-- Red: > 90%
+- Orange: 70–85%
+- Red: > 85%
 
 Reaching `compressAt` (default 90%, setting `general.compact.compress_at`) auto-triggers compact. If the LLM summary fails or times out, Halo falls back to a local compact (notice: `Auto-compacted N older messages (local fallback — LLM summary failed: <reason>)`) rather than retrying. An auto-compact has no overall time limit — it only times out after 10 minutes with no data from the model. While the agent is running you can't click the TokenRing (guarded by `isStreaming`).
 
@@ -112,9 +113,9 @@ Reaching `compressAt` (default 90%, setting `general.compact.compress_at`) auto-
 
 Your sessions are listed as vertical tabs on the right edge of the chat panel:
 - Lists the workspace's main sessions, newest first; scroll down to load older ones
-- Click a tab to show that session. The one you left keeps running and streaming in its own tab: a spinner shows while it works, and a dot means new output arrived
+- Click a tab to show that session. The one you left keeps running and streaming in its own tab. Each tab's dot shows its state: pulsing amber while it works, blue when new output arrived in the background, green otherwise (including sessions not opened since the page loaded)
 - **+** (or `/session new`) opens a fresh tab; the session is created when you send its first message
-- Hover a tab to rename it (pencil); ✕ deletes it after a confirmation — deletion can't be undone
+- Hover a tab to rename it (pencil) or delete it (trash icon, after a confirmation) — deletion can't be undone
 - Drag the list's left edge to make it wider or narrower, or collapse it to a thin strip of initials
 - After a refresh, the session you were on reopens
 
@@ -126,6 +127,6 @@ Long messages you sent are collapsed to a one-line header: a chevron, the send t
 
 **"Queued" hint**: the previous turn hasn't finished; your message is queued and will run next turn.
 
-**"Rate limited, retrying in Xs..."**: Bedrock throttled; automatic exponential backoff (up to 5 retries).
+**"Rate limited, retrying in Xs..."**: the model provider throttled; automatic backoff, up to `general.agent.max_retries` attempts (default 5).
 
 **A sudden `[Message from xxx]`**: a sub-agent finished and auto-reported back to the parent agent's conversation.

package/bundled-docs/guide/cli.md

@@ -29,7 +29,7 @@ bundle flattens them.
 # 2. build the upstream artifacts the bundle consumes
 pnpm --filter @turmind/halo-core build
 pnpm --filter @turmind/halo-server build
-cd packages/admin && npx next build --no-lint && node scripts/copy-monaco.mjs && cd ../..
+pnpm --filter @turmind/halo-admin build
 # 3. stage the release bundle — HALO_RELEASE=1 stamps the bare version
 #    (0.1.2), NOT the default <version>-<sha>: a `-<sha>` suffix is a semver
 #    prerelease that `npm install` skips and never tags as `latest`.
@@ -136,6 +136,7 @@ Multi-turn conversation. Supports all standard Halo slash commands:
 | `/session interrupt` | Interrupt the running turn now (aborts a command mid-run); any messages queued while busy then run as one follow-up turn |
 | `/session compact` | Compact session context |
 | `/session context` | Show context window + agent info |
+| `/session info` | Show the session tree (descendants) |
 | `/agent <verb>` | Manage agents: `list` / `switch <name\|index>` / `desc` / `delete` / `create` / `update` |
 | `/skill <verb>` | Manage skills: `list` / `desc` / `disable` / `enable` / `delete` / `create` / `update` |
 | `/workspace info` | Show current workspace |
@@ -143,6 +144,7 @@ Multi-turn conversation. Supports all standard Halo slash commands:
 | `/workspace setup` / `/workspace tidy` / `/workspace share` | Set up / tidy the `.halo/` knowledge files, or export a shareable bundle (workspace skill) |
 | `/cron <verb>` | Manage scheduled agent runs: `create` / `list` / `update` / `enable` / `disable` / `delete` |
 | `/acp <verb>` | Ask other agents over ACP (`kiro <q>` / `claude <q>`) and manage `ask-*` bindings (`add` / `list` / `remove`) |
+| `/extension <verb>` | Canvas preview extensions: `install` / `list` / `remove` (full access only) |
 | `/evo [hint]` | Queue a self-evolution run on this session (full access only) |
 | `/quit` | Exit |
 
@@ -216,7 +218,7 @@ same binary. `start -d` runs it in the background **with a bounded respawn
 supervisor**: the detached process supervises the server and brings it back on
 a crash (non-zero exit, or a kill by anything other than SIGTERM/SIGINT), at
 most 5 times per 5 minutes with a 2s pause, logging each decision as
-`[respawn] …` into `~/.halo/global/logs/server.log`. `halo server stop` is
+`[respawn] …` into `~/.halo/logs/server.log`. `halo server stop` is
 recognized as intentional and never respawns; `halo server stop|restart|status`
 still target the server's own pid. Full policy in
 [dev/deploy.md](../dev/deploy.md#crash-semantics--why-restarton-failure-is-load-bearing).
@@ -226,8 +228,9 @@ still target the server's own pid. Full policy in
 ```
 packages/cli/
   src/
-    index.ts        — Entry: subcommand dispatch (tui/cli/agents/sessions/server/setup/acp), SIGINT/SIGTERM handling
+    index.ts        — Entry: subcommand dispatch (tui/cli/agents/sessions/server/setup/upgrade/acp), SIGINT/SIGTERM handling
     harness.ts      — Shared agent harness wrapping SessionManager
+    server-supervisor.ts — Respawn policy for `halo server start -d`
     cli.ts          — Non-interactive: stdin/args → agent → stdout → exit
     tui.tsx         — Interactive entry: mounts the ink app
     tui/
@@ -247,9 +250,8 @@ Session prefix: `cli_`. Sessions are persisted to `<workspace>/.halo/sessions/`
 
 ### Initialization
 
-The CLI replicates the server's init sequence:
+`tui` / `cli` / `agents` / `sessions` refuse to run ("~/.halo/global/ not initialized. Run halo setup first.") until `halo setup` has seeded `~/.halo/global/`. Then the CLI replicates the server's init sequence (`initRuntime()` in `harness.ts`):
 1. `initLogger()` — redirect console to stderr + file logger
-2. `ensureHaloHome()` — ensure `~/.halo/` structure
-3. `initBwrapCheck()` — probe sandbox availability
-4. `setSandboxHiddenPaths()` — configure sandbox paths
-5. `new SessionManager(workspace)` — create agent session manager
+2. `initBwrapCheck()` — probe sandbox availability
+3. `setSandboxHiddenPaths()` — configure sandbox paths
+4. `new SessionManager(workspace)` — create agent session manager (the workspace's `.halo/` is seeded via `ensureWorkspaceHalo`)

package/bundled-docs/guide/getting-started.md

@@ -12,7 +12,7 @@ Open `http://localhost:9527` (or your deployment URL) in a browser and enter the
 
 ## Open a workspace
 
-After login, you land in the workspace. A URL with `?folder=/abs/path` opens that directory directly; without `?folder`, Halo falls back to your home directory as the workspace — everything still works.
+After login, you land in the workspace. A URL with `?folder=/abs/path` opens that directory directly; without `?folder`, Halo reopens the last workspace you used, or your home directory if there isn't one — everything still works.
 
 The Explorer top bar has two ways to switch workspace:
 - **Type an absolute path** + Enter — invalid paths raise an error
@@ -22,7 +22,7 @@ Halo auto-creates a `.halo/` subdirectory in the target folder (for sessions, ag
 
 ## First conversation (bootstrap)
 
-The first time a new user chats with the Default agent, the agent asks a few questions:
+The first time a new user chats with the Default agent, it works in a few getting-to-know-you questions (if you open with a real task, it does the task first and asks over the next turns):
 - What should I call you?
 - What would you like to call me?
 - Preferred communication style (formal/casual, English/other language, etc.)
@@ -79,7 +79,7 @@ After `halo setup`:
 
 **When does "refreshed on upgrade" actually run?** `halo setup` always re-runs the seed; the server's startup check also re-runs it automatically when `~/.halo/global/.template-version` is behind the bundled `TEMPLATE_VERSION`. So the routine flow `halo upgrade && halo server restart` is enough — no need to remember `halo setup`.
 
-**Server-refreshed**: `INSTRUCTIONS.md`, `prompts/`, `models/`, `docs/`, the built-in agent ids (`default`, `executor`, `deep-executor`, `__evo_agent__`, `__score__`, `__apply_agent__`), and the built-in skill ids (`agent`, `skill`, `workspace`, `cron`, `acp`, `send-file`, `self`, `aws-knowledge`, `nova-web-search`, `halo`). To customize one, copy it into the workspace scope (`<project>/.halo/...`) — workspace replaces global at runtime.
+**Server-refreshed**: `INSTRUCTIONS.md`, `prompts/`, `models/`, `docs/`, the built-in agent ids (`default`, `executor`, `deep-executor`, `goal`, `__evo_agent__`, `__score__`, `__apply_agent__`), and the built-in skill ids (`agent`, `skill`, `workspace`, `cron`, `acp`, `send-file`, `self`, `aws-knowledge`, `web-search`, `halo`, `extension`). To customize one, copy it into the workspace scope (`<project>/.halo/...`) — workspace replaces global at runtime.
 
 **Never overwritten**: anything else under `agents/` or `skills/` (your own creations), and everything under `secrets/`.
 

package/bundled-docs/guide/secrets-and-credentials.md

@@ -35,7 +35,7 @@ Goal: a skill called `caption-image` that calls `api.example.com` with an API ke
 Beside `SKILL.md`:
 
 ```yaml
-# extensions/skills/caption-image/config.yaml
+# skills/caption-image/config.yaml
 params:
   - key: api_key
     description: API key for api.example.com
@@ -107,7 +107,7 @@ env vars (process.env.X) > workspace settings.yaml > global settings.yaml > sche
 
 If `process.env.EXAMPLE_KEY` is unset and the value at `caption-image.params.api_key` is `<<EXAMPLE_KEY>>`:
 - The agent sees the literal `<<EXAMPLE_KEY>>` in the rendered skill body
-- The server logs `[md-vars] Env var "EXAMPLE_KEY" not set — keeping <<EXAMPLE_KEY>> literal`
+- The server logs `[MdVars] Env var "EXAMPLE_KEY" not set — keeping <<EXAMPLE_KEY>> literal`
 - API calls the agent makes will fail with a clear error (usually HTTP 401) and the error message will reveal the literal, so the user can tell what to fix
 
 This is intentional: empty strings hide the misconfiguration; literals make it visible.
@@ -155,7 +155,7 @@ Free-form, but consistency helps. Common patterns in Halo:
 | Env var | Purpose |
 |---|---|
 | `HALO_PASSWORD` | Server login password |
-| `HALO_MODEL_ID` / `HALO_MODEL_PROVIDER` / `HALO_MAX_CONTEXT_TOKENS` | Server defaults |
+| `HALO_MAX_CONTEXT_TOKENS` | Server default context window (272000) |
 | `AWS_REGION` / `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | AWS / Bedrock |
 
 For your own skills, `UPPER_SNAKE` prefixed by the product is idiomatic (`NANO_BANANA_KEY`, `EXAMPLE_API_TOKEN`). The placeholder is case-sensitive — `<<example_key>>` won't match `EXAMPLE_KEY`.

package/bundled-docs/guide/sessions.md

@@ -24,7 +24,7 @@ The main agent (the one you talk to directly) sits at the top; any sub-agents it
 
 - Collapse/expand: click the arrow
 - Count badge `+3`: 3 descendants
-- Red ⏹ icon: session was stopped (stopped_at is set)
+- ⏹ icon: session was stopped (stopped_at is set)
 
 ## Message viewer
 
@@ -48,7 +48,7 @@ Top-right Bug icon toggles it. When on you also see:
 
 ## System prompt viewer
 
-In Debug mode the top-right gets an extra `Prompt` button; click to expand the full system prompt (AGENT.md + INSTRUCTIONS.md + INDEX.md + TOOL_GUIDELINES + skill metadata).
+Next to the Debug toggle, a `Prompt` button appears once the session has a recorded system prompt; click to expand the full system prompt (AGENT.md + INSTRUCTIONS.md + INDEX.md + TOOL_GUIDELINES + skill metadata).
 
 Use it to see exactly what context the agent was given for a given turn.
 
@@ -71,7 +71,7 @@ Refreshing the browser or a network blip:
 
 ## Deleting a session
 
-Click a session's trash icon (Sessions page) or ✕ on its chat tab, then confirm:
+Hover a session and click its trash icon (Sessions page or a chat tab), then confirm:
 - Cascade delete in SQLite (parent + all descendants)
 - `.halo/sessions/{agentId}/{sid}.json` removed
 - Sidebar entry removed

package/bundled-docs/guide/skills.md

@@ -30,7 +30,7 @@ Putting those in AGENT.md would bloat the system prompt. Skills use **progressiv
 
 Workspace overrides global (same id).
 
-**Built-in skills** (`agent`, `skill`, `workspace`, `cron`, `acp`, `send-file`, `self`, `aws-knowledge`, `nova-web-search`) are server-shipped and **force-overwritten on every server startup**. Local edits to these directories under `~/.halo/global/skills/` will be lost. To customize one, copy it into `<project>/.halo/skills/<id>/` (workspace replaces global) and edit there. Other skills under `~/.halo/global/skills/` — including any the user created via the admin UI — are untouched by the seeder.
+**Built-in skills** (`agent`, `skill`, `workspace`, `cron`, `acp`, `send-file`, `self`, `aws-knowledge`, `web-search`, `halo`, `extension`) are server-shipped and **force-overwritten on every server startup**. Local edits to these directories under `~/.halo/global/skills/` will be lost. To customize one, copy it into `<project>/.halo/skills/<id>/` (workspace replaces global) and edit there. Other skills under `~/.halo/global/skills/` — including any the user created via the admin UI — are untouched by the seeder.
 
 ## SKILL.md format
 
@@ -63,7 +63,7 @@ Follow the checklist in checklist.md...
 
 ## Open the Skills panel
 
-Left-side Activity Bar → `🪄 Skills` icon.
+Left-side Activity Bar → `⚡ Skills` icon.
 
 Click any skill and the right pane becomes a mini workspace:
 - File tree (every file in the skill directory) on the left
@@ -73,9 +73,9 @@ You can edit SKILL.md, add scripts, templates, example docs.
 
 ## Create / delete
 
-`+` button on the sidebar — fill in name / description / scope.
+Click the `+` on the **Global** or **Workspace** group header in the sidebar (the group you click decides the scope) and type a name.
 
-Delete: right-click → Delete.
+Delete: hover a skill and click its trash icon (after a confirmation). The toggle next to it disables / enables the skill.
 
 ## Letting an agent use a skill
 
@@ -158,7 +158,9 @@ Halo seeds these skills on every startup (the ids in `BUILTIN_SKILL_IDS`, `packa
 | send-file | Deliver an image/video/file as a channel attachment by emitting `MEDIA:<absolute_path>` — works on Web / WeChat / Telegram / Slack / Feishu (no command; model-activated, workspace access) |
 | self | The agent's own visual space (`.halo/canvas/self.html`) for self-expression (no command; model-activated, full access) |
 | aws-knowledge | Query the official AWS Knowledge MCP server for up-to-date AWS docs (no command, `user-invocable: false`; model auto-activates) |
-| nova-web-search | Real-time web search via Amazon Nova 2 Lite's nova_grounding (no command, `user-invocable: false`; model auto-activates) |
+| web-search | Real-time web search in two gears: fast (Amazon Nova grounding, default) and deep (`--deep`, GPT-5.6 `web_search` via Bedrock Mantle, slower and token-expensive) (no command, `user-invocable: false`; model auto-activates) |
+| halo | Platform self-knowledge — config directories, MD scopes, which bundled doc answers what (no command, `user-invocable: false`; model auto-activates) |
+| extension | Install / list / remove canvas preview extensions — backs `/extension` (full access) |
 
 All live under `~/.halo/global/skills/` and are force-overwritten on startup. To customize one, copy it into `<project>/.halo/skills/<id>/` and edit there (workspace overrides global). `tavily-web-search` remains an optional (non-seeded) skill.
 
@@ -278,7 +280,7 @@ nano-banana:
 
 1. **Merge order**: workspace `<project>/.halo/settings.yaml` deep-merges over global `~/.halo/secrets/settings.yaml` (field-level merge, not block replacement)
 2. **Env vars**: `<<ENV_NAME>>` inside a value is replaced with `process.env.ENV_NAME` at render time. **If the env var is missing, the `<<ENV_NAME>>` literal is kept** so agents can see what's unset and the user can fix it
-3. **Unknown placeholders** stay as-is (e.g. `{{foo}}`, `{{nano-banana.params.missing-key}}`); the server logs a `[md-vars] Unknown placeholder "…"` warning
+3. **Unknown placeholders** stay as-is (e.g. `{{foo}}`, `{{nano-banana.params.missing-key}}`); the server logs a `[MdVars]` line saying it left the placeholder as-is
 4. **Key charset**: `[\w-]`, hyphens allowed (e.g. `nano-banana`)
 
 ### Why put credentials in env vars