@turmind/halo 1.5.4 → 1.5.5

package/bundled-docs/guide/testing-agents-and-skills.md

@@ -6,7 +6,7 @@ How to verify an agent you just created behaves right, and how to exercise a ski
 
 ### 1. Open the agent
 
-Activity Bar → `👥 Agents` → click the agent you want to test.
+Activity Bar → `🤖 Agents` → click the agent you want to test.
 
 ### 2. Click Test
 
@@ -32,21 +32,20 @@ The Explorer's Chat panel is now ready with your agent pre-selected. Send a mess
 
 - **Does it greet the way AGENT.md says?** Send "Hi". Check the reply matches the personality you wrote.
 - **Does it call the right tools?** If the agent is supposed to read files, ask it to. Watch the inline tool-call card — it shows the tool name, arguments, and (expandable) output.
-- **Is the system prompt what you expect?** Open the Sessions panel (Activity Bar → `🕘 Sessions`), select this session, toggle **Debug mode**, click the **Prompt** button on the first message. Full rendered system prompt (AGENT.md + USER.md + INSTRUCTIONS.md + skill metadata + tool list).
+- **Is the system prompt what you expect?** Open the Sessions panel (Activity Bar → `📨 Sessions`), select this session, toggle **Debug mode**, click the **Prompt** button in the viewer header. Full rendered system prompt (AGENT.md + USER.md + INSTRUCTIONS.md + skill metadata + tool list).
 - **Is the model correct?** Debug mode's usage badges show `model` on every assistant turn.
 
 ### 5. Iterate
 
-Edits take effect on the **next** session, not retroactively:
+Edits are never retroactive — the turn that is running finishes on the old config — but a session is rebuilt from disk after every run, so the **next turn** of an existing session already picks them up:
 
 | What you changed | When it takes effect |
 |---|---|
-| `AGENT.md` body | Next `/session new` session |
-| `agent.yaml` tools / skills / model | Next session spawn |
-| `settings.yaml` values | Next session spawn (or next `activate_skill` call for SKILL bodies) |
-| Env vars (`<<ENV>>` placeholders) | Restart server, then next session spawn |
+| `AGENT.md` body, `agent.yaml` tools / skills / model | Next turn (and any new session) |
+| `settings.yaml` values | Next turn (or next `activate_skill` call for SKILL bodies) |
+| Env vars (`<<ENV>>` placeholders) | Restart server, then next turn |
 
-So the loop is: edit → `/session new` → re-test. No server restart for MD/YAML/settings changes.
+So the loop is: edit → send another message (or `/session new` for a clean slate) → re-test. No server restart for MD/YAML/settings changes. Full table in [delegation-and-access.md](delegation-and-access.md#2-when-a-config-edit-takes-effect).
 
 ---
 
@@ -56,7 +55,7 @@ There is **no separate "test this skill" button**. Skills exist to be called by
 
 ### 1. Attach the skill to an agent
 
-In the agent's Form view, the **Skills** section lists every skill in the workspace. Check the one you want to test. Save.
+In the agent's Form view, the **Skills** section lists every skill in the workspace. Check the one you want to test (the form auto-saves).
 
 Equivalent YAML edit:
 
@@ -114,22 +113,22 @@ The env var is unset. Halo renders the literal placeholder so you (and the agent
 
 ### Saved agent changes don't seem to apply
 
-You might be looking at a session that started *before* the edit. Every session caches its own assembled system prompt at spawn time. `/session new` to start fresh, or switch to a different session and back.
+You might be looking at a turn that was already running when you saved — it finishes on the old config, and the edit applies from the next turn. If the next turn still behaves the old way, `/session new` to start fresh.
 
 ### Deleting a test session
 
-Sessions → select → context menu → Delete. Or programmatically: `DELETE /api/sessions/logs/:id`. Deletion cascades to child sessions (sub-agents), their JSON files, and the SQLite rows. See [dev/api.md#session-logs](../dev/api.md#session-logs-unified).
+Sessions → hover the session → trash icon. Or programmatically: `DELETE /api/sessions/logs/:id`. Deletion cascades to child sessions (sub-agents), their JSON files, and the SQLite rows. See [dev/api.md#session-logs](../dev/api.md#session-logs-unified).
 
 ### "Test button does something weird" — the session is orphaned
 
-Since 1.5.3-alpha, Test no longer clears any stored session: it only opens a new draft tab (the old `localStorage.halo_session_<projectId>` key is gone). The new session is created by the first message you send from that tab. If you see an old conversation instead of an empty one, the draft tab isn't the one on screen. Click **+** at the bottom of the session tabs to bring it back (an unused draft is reused).
+Since 1.5.3-alpha, Test no longer clears any stored session: it only opens a new draft tab (the old `localStorage.halo_session_<projectId>` key is gone). The new session is created by the first message you send from that tab. If you see an old conversation instead of an empty one, the draft tab isn't the one on screen. Click **+** below the session tabs to bring it back (an unused draft is reused).
 
 ---
 
 ## References
 
 - Test button implementation: `testAgent` in [packages/admin/src/features/agents/agent-management-main.tsx](../../../packages/admin/src/features/agents/agent-management-main.tsx)
-- `activate_skill` runtime: [packages/server/src/agents/agent-loader.ts:111-159](../../../packages/server/src/agents/agent-loader.ts#L111-L159) (function `createSkillTool`)
-- Skill metadata → system prompt: [packages/server/src/agents/agent-loader.ts:97-102](../../../packages/server/src/agents/agent-loader.ts#L97-L102) (function `buildSkillPrompt`)
-- Chat session creation on first message: [packages/server/src/ws/handler.ts:263-344](../../../packages/server/src/ws/handler.ts#L263-L344) (function `handleChat`)
+- `activate_skill` runtime: [packages/server/src/agents/agent-loader.ts](../../../packages/server/src/agents/agent-loader.ts) (function `createSkillTool`)
+- Skill metadata → system prompt: [packages/server/src/agents/agent-loader.ts](../../../packages/server/src/agents/agent-loader.ts) (function `buildSkillPrompt`)
+- Chat session creation on first message: [packages/server/src/ws/handler.ts](../../../packages/server/src/ws/handler.ts) (function `handleChat`)
 - End-to-end test scenarios for the session system: [test/session.md](../test/session.md)

package/bundled-docs/guide/workspace.md

@@ -21,17 +21,23 @@ Overall interface layout plus the three sidebar features.
 - **Sidebar** is resizable
 - **Bottom Panel** is resizable; the header has a Chat / Terminal switch
 
-The Skills tab is an exception — it takes the full right side, no Bottom Panel.
+The docked Bottom Panel belongs to the Explorer tab; every other tab fills the whole right side (a floating panel stays visible on any tab).
 
 ## Activity Bar tabs
 
 | Icon | Tab | Purpose |
 |---|---|---|
 | 📄 Files | Explorer | File tree + Monaco editor |
+| 🌿 Branch | Source Control | Changes, commit, push, history (hidden for non-git workspaces) |
 | 📨 Messages | Sessions | Session history + debug viewer |
-| 🪄 Wand | Skills | Skill editing (mini workspace) |
-| 👥 Users | Agents | Agent configuration (Form/YAML/MD) |
-| ⚙️ Gear | Settings | Settings editor (Form/YAML) |
+| ⚡ Zap | Skills | Skill editing (mini workspace) |
+| 🤖 Bot | Agents | Agent configuration (Form / Edit) |
+| 💬 Chat bubble | Channels | Web / Telegram / Slack / Feishu / WeCom / WeChat accounts |
+| ✨ Sparkles | Evolution | Self-evolution runs and review |
+| 🕐 Clock | Cron | Scheduled agent runs |
+| 🎚️ Sliders | Settings | Settings form (bottom of the bar) |
+
+Below Settings sits the **quick toggles** gear. The thin bar under it has one segment per item: network (green = connected, amber = probing, red = disconnected; the gear turns red too), finish notification, and in the desktop app also pin-on-top and keep-screen-awake (amber when on). Hover for a summary. Click to open a panel where you switch them; it stays open until you click outside, press Esc, or click the gear again.
 
 ## Switching workspace
 
@@ -44,29 +50,30 @@ The Explorer top bar has a path input + 📁🔍 picker button:
   - Single click to select / double click to enter
   - Open button to confirm
 
-The URL carries `?folder=/abs/path`, persisting the workspace across refreshes. When `folder` is absent, Halo falls back to the home directory.
+The URL carries `?folder=/abs/path`, persisting the workspace across refreshes. When `folder` is absent, Halo reopens the last workspace you used, or the home directory if there isn't one.
 
 ## Explorer (file tree)
 
 VS Code style:
-- Click: select
-- Double click: open in a new Tab
+- Click a file: select, then open it after a short delay (300 ms)
+- Double click: open the file right away; on a folder, expand / collapse it
+- Click a folder: expand / collapse
 - Ctrl/Cmd + click: toggle multi-select
 - Shift + click: range select
 - Drag: move files/folders (multi-select drag supported)
 
-Right-click menu: New File / New Folder / Rename / Delete / Download.
+Right-click menu: New File / New Folder / Open in Integrated Terminal / Reveal in File Manager (desktop app only) / Open to the Side / Download / Rename / Delete / Open as Workspace (folders).
 
 **Quick Open**: `Cmd/Ctrl+P` opens fuzzy file search — server-side, full-project, independent of expansion state.
 
 ### Skipped directories
-`node_modules`, `__pycache__`, `.halo` (knowledge dir, not shown in the tree; use `file_read` directly).
+`.git`, `.DS_Store`, `node_modules`, `__pycache__`.
 
 ## Editor
 
 Monaco, multi-tab:
 - Drag tabs to reorder
-- Unsaved tabs show a red dot
+- Unsaved tabs show an amber dot
 - Closing an unsaved tab prompts for confirmation
 - **Auto-refresh**: detects agent-written file changes by mtime and updates contents
 - **Tab persistence**: stored in localStorage, survives refreshes
@@ -91,13 +98,13 @@ Once installed, matching files open in the extension's viewer. If more than one
 
 Bottom-panel Terminal tab:
 - xterm.js frontend + node-pty backend
-- Multi-instance (each tab owns its own PTY)
+- Multi-instance (each terminal owns its own PTY), listed as a collapsible vertical tab strip on the right
 - cwd = current project root
-- Reconnect grace: 60 s
+- Reconnect grace: 5 min (`timeout.terminal_grace`)
 
 ## Settings
 
-`⚙️ Settings` tab. Form / YAML split view:
+`⚙️ Settings` tab. Form view:
 - Auto-generated controls (text / number / password / toggle) per declared field
 - Each row shows source (`workspace` / `inherited from global` / `unset`) + Reset
 
@@ -105,7 +112,10 @@ Scope: Global / Workspace toggle. Same key: workspace overrides global, leaf by
 
 Sections are grouped by declarer:
 - **System** — server-built-in knobs (session limits, compaction, sandbox, logging)
+- **Security** — change password, log out
+- **Extensions** — installed canvas preview extensions
 - **Model Providers** — secrets declared by each `models/<id>.yaml` (AWS, Kimi, DeepSeek, …)
+- **Agents** — params/secrets declared by each global agent's `agent-config.yaml`
 - **Skills** — params/secrets declared by each `skills/<id>/config.yaml`
 - **Orphans** — values in settings.yaml whose namespace isn't currently declared (uninstalled skill leftovers); manual cleanup only
 
@@ -127,11 +137,13 @@ See [requirements/settings.md](../requirements/settings.md), [secrets-and-creden
 |---|---|
 | `Cmd/Ctrl + P` | Quick Open |
 | `Cmd/Ctrl + S` | Save file |
-| `Cmd/Ctrl + W` | Close tab |
+| `Alt + W` | Close editor tab (browser; the desktop app uses `Cmd/Ctrl + W`) |
+| `Cmd/Ctrl + \`` | Switch the bottom panel between Chat and Terminal |
+| `Esc` | Leave editor maximize |
 
 ## Bottom panel switching
 
-Two tabs in the header: Chat / Terminal. Current tab lives in `editorStore.bottomTab` and survives refresh.
+Two tabs in the header: Chat / Terminal, plus maximize and float / dock buttons. The panel opens on Chat after a refresh.
 
 ## Login / logout
 

package/bundled-docs/requirements/agent.md

@@ -1,10 +1,10 @@
 # Agent — Requirements
 
-Agent configuration management: creating, editing YAML / Form / AGENT.md.
+Agent configuration management: creating, editing via Form / mini workspace (agent.yaml, AGENT.md).
 
 ## Layout
 
-Left sidebar has two collapsible groups (Global / Workspace); right side is the editor:
+Left sidebar has two collapsible groups (Global / Workspace — the latter only while a workspace is open); right side is the editor. Each group header has a `+` to create an agent in that scope, and the sidebar header has a refresh button:
 
 ```
 ┌─────────────────┬───────────────────────────────┐
@@ -20,22 +20,22 @@ Left sidebar has two collapsible groups (Global / Workspace); right side is the
 
 ## Core behaviour
 
-### YAML / Form dual view
-- **YAML view**: Monaco-edit the raw `agent.yaml`
-- **Form view**: data-driven form derived from YAML fields (name / description / model / tools / skills / thinking)
-- Switching views preserves edits
+### Form / Edit dual view
+- **Form view** (default): data-driven form derived from the YAML fields (name / description / priority / model incl. thinking and capabilities / system_prompt / team / tools / skills). Edits auto-save to `agent.yaml` (debounced 500 ms). If `agent.yaml` fails to load or parse, the form is replaced by an error with a Retry button and nothing is auto-saved (an unparsable file is fixed in Edit view); below the form, a read-only preview of `AGENT.md` is shown when it has content
+- **Edit view**: the **Edit** button opens a mini workspace (file tree + editor) rooted at the agent's folder, for editing `agent.yaml` / `AGENT.md` directly; **Back** returns to the form, which reloads from disk
+- The chosen view is remembered per agent in `localStorage`
 
 ### CRUD
 | Operation | API |
 |---|---|
 | List | `GET /api/agent-configs?projectId=xxx` |
 | Create | `POST /api/agent-configs` (body: `{name, description, scope, projectId?}`) |
-| Read YAML | `GET /api/agent-configs/:id/yaml` |
-| Write YAML | `PUT /api/agent-configs/:id/yaml` |
-| Delete | `DELETE /api/agent-configs/:id` |
+| Read YAML | `GET /api/agent-configs/:id/yaml` (`scope=workspace` requires `projectId`, else 400) |
+| Write YAML | `PUT /api/agent-configs/:id/yaml` (same `projectId` rule) |
+| Delete | `DELETE /api/agent-configs/:id` (same `projectId` rule — never falls back to deleting the same-named global agent) |
 | Toggle disabled | `PATCH /api/agent-configs/:id/toggle` → `{ ok, disabled }` |
 
-Creating requires name + description; the backend uses `defaultAgentYaml(name, description)` to produce a full YAML.
+Creating requires a name (description is optional); the id is derived from the name. The backend uses `defaultAgentYaml(name, description)` to produce a full YAML and also scaffolds an `AGENT.md`.
 
 ### Scope (Global / Workspace)
 - **Global**: `~/.halo/global/agents/<id>/agent.yaml` — shared across projects
@@ -45,18 +45,18 @@ Same id present in both scopes: workspace wins; the overridden global is greyed
 
 **Cross-scope conflict**: creating a same-name agent in the other scope prompts about the overwrite behaviour.
 
-**Delete protection**: at least one global agent must remain (server-enforced).
+**Delete protection**: at least one global agent must remain (server-enforced). The sidebar offers delete (hover trash) on workspace agents only; global rows show a crown instead.
 
 ### Disable / Enable
-- Toggle switch on each agent row in the admin sidebar. Disabled state is stored per workspace in the `disabled_items` table of `halo.db` (not in agent.yaml). Both global and workspace agents can be independently toggled per workspace.
+- Toggle switch on each agent row in the admin sidebar (shown on hover while enabled; not offered for internal agents or when no workspace is open). Disabled state is stored per workspace in the `disabled_items` table of `halo.db` (not in agent.yaml). Both global and workspace agents can be independently toggled per workspace.
 - Disabled agents are greyed out (opacity-40) with sub-text "disabled"; the toggle stays visible.
 - Hidden from: the delegation roster, chat agent selector, `/workspace share` export.
 - Still visible in the admin management sidebar for re-enabling.
 
 ### Tool selection
 - **Session tools**: `start_session` / `session_list` / `query_session` / `interrupt_session` / `stop_session` / `archive_session` / `get_session_output` / `query_agent` — **not** selected by name; the whole bundle is granted automatically by a non-empty `team` (see below). Listing them under `agent.yaml tools` has no effect.
-- **Workspace tools**: `file_read` / `file_write` / `file_edit` / `file_list` / `shell_exec` / `grep` / `glob` / `web_fetch`, returned by `GET /api/agent-configs/tools`
-- **`activate_skill`**: auto-injected whenever the YAML lists `skills`; loads the full SKILL.md on demand
+- **Workspace tools**: `file_read` / `view_image` / `file_write` / `file_edit` / `file_list` / `shell_exec` / `grep` / `glob` / `web_fetch`, plus the single `relay_send` chip (grants the whole cross-workspace relay set, full-access sessions only), returned by `GET /api/agent-configs/tools`. `view_image` is dropped at runtime when the model can't take images (the form dims it)
+- **`activate_skill`**: auto-injected when the YAML lists at least one usable skill (not disabled, allowed at the session's access level); loads the full SKILL.md on demand
 
 ### Team (delegation switch + whitelist)
 - Optional `team: [id, …]` field in `agent.yaml`. A **non-empty** list is the on/off switch for delegation: it grants the whole session-tool bundle (`start_session` / `query_agent` / …) plus the prompt roster, AND scopes which agents this one may reach.
@@ -67,7 +67,7 @@ Same id present in both scopes: workspace wins; the overridden global is greyed
 - **Picker only offers effective, enabled agents.** A chip shows iff the *effective* agent for that id is runnable — same resolve-then-check the runtime uses: a workspace agent shadows the same-id global (the overridden global is skipped), then anything disabled is dropped. So a global stays out of the picker when its workspace override is disabled, even though that global's own record isn't flagged disabled. Matches the chat / cron selectors and the runtime roster — you can never pick a teammate that can't actually run.
 
 ### Skill selection
-`GET /api/skills?projectId=xxx` lists available skills; `agent.yaml`'s `skills` references them by id.
+`GET /api/skills?projectId=xxx` lists available skills; `agent.yaml`'s `skills` references them by id. The form offers enabled skills only; ids that are referenced but not installed show as red ⚠ chips (click to remove).
 
 ### MD file editing
 
@@ -75,13 +75,14 @@ Same id present in both scopes: workspace wins; the overridden global is greyed
 |---|---|---|
 | AGENT.md | yes | Agent personality / behaviour (overrides YAML `system_prompt`) |
 | INSTRUCTIONS.md | yes | User preferences (global or workspace scope) |
+| INDEX.md | no | Project index, read-only through this API |
 
-The MD editor has a **Global / Workspace** scope toggle (visible when a workspace is open).
+The admin edits `AGENT.md` through the Edit mini workspace; `INSTRUCTIONS.md` is not edited from this tab.
 
-API: `GET/PUT /api/agent-configs/:id/md/:fileType`
+API: `GET/PUT /api/agent-configs/:id/md/:fileType`, `GET /api/agent-configs/:id/md-all`
 
 ### Test button
-- Sets `selectedAgentId` in the chat store
+- Opens a fresh chat draft tab (an untouched draft is reused) with this agent selected
 - Dispatches a `halo:navigate` event to switch to explorer/chat
 - The user chats with the selected agent in the main chat panel
 - **Not rendered for internal agents** (`internal: true`) — they're delegated to by other agents, never driven directly

package/bundled-docs/requirements/chat.md

@@ -5,10 +5,9 @@ The primary surface for talking to an agent.
 ## Core behaviour
 
 ### Agent selection
-- Bottom-left dropdown in the chat panel selects which agent to use
-- Lists every available agent (from `GET /api/agent-configs`; overridden and disabled agents are hidden)
-- Default agent has a "default" badge
-- **Locked during an active session** — the agent is bound to the session; to change, start a new session (/session new)
+- Dropdown in the composer's left control cluster (after the Debug button) selects which agent to use; hidden when only one agent is usable
+- Lists every available agent (from `GET /api/agent-configs`; overridden, disabled and internal agents are hidden), highest priority first. A new session starts on the top one
+- **Locked during an active session** (and while a response is streaming) — the agent is bound to the session; to change, start a new session (/session new)
 - The Agents panel's "Test" button can also preselect an agent
 
 ### Access level
@@ -22,8 +21,8 @@ The primary surface for talking to an agent.
 ### Message rendering
 - Markdown + code-block highlighting
 - Tool-call card: expandable, shows tool name / input / output
-- Sub-agent messages carry the agent-name label (e.g. "Coder", "Researcher")
-- Streaming text has a cursor animation
+- Sub-agent streams stay out of the chat: their reports land as a green callout, and Debug mode adds agent start/done markers labelled with the agent name (e.g. "Coder", "Researcher")
+- A reply that has produced nothing yet shows a spinner with "Thinking..."
 - The user bubble shows its send time (`HH:mm`, browser-local) at the left of its header row, after the expand chevron (see [User-message actions](#user-message-actions-expand--copy--delete)); hovering it gives the full date. Same bubble component as the Sessions tab, so both surfaces get it
 - In Debug mode the system-prompt `context` row stays in the list but doesn't open an exchange of its own, so there is no blank strip above the first bubble
 
@@ -39,7 +38,7 @@ Actions on user-role turns: the blue sticky user bubble, plus the sub-agent-repo
   - An expanded body is capped at 40vh and scrolls inside the bubble, because the bubbles are sticky.
   - The compact-summary callout is collapsed by default and toggles from its own header, as before.
 - **Copy** — copies the prompt text to the clipboard
-- **Delete** (confirm dialog) — removes the whole exchange (the user turn + all responses up to the next user turn) with **two-layer semantics**: the LLM context (`rawMessages`) drops the turn physically — the model never sees it again, freeing context; the UI keeps the messages, rendered greyed-out with a "deleted" tag, as an audit trail. No undo; a deleted exchange loses its Delete button. Rejected with an error toast while the agent is running or compacting. Root sessions only (sub-session logs don't offer Delete). If the turn was already compacted out of raw context, only the UI marking happens (silent degrade). Once a session has **archived history** the action is refused for the whole session with a plain explanatory notice (not an `Error:` bubble) — per-turn positions can no longer be mapped once older turns left the active file. Design details in [design/session.md](../design/session.md#exchange-deletion-soft-ui--hard-raw), protocol in [design/ws.md](../design/ws.md).
+- **Delete** (confirm dialog) — removes the whole exchange (the user turn + all responses up to the next user turn) with **two-layer semantics**: the LLM context (`rawMessages`) drops the turn physically — the model never sees it again, freeing context; the UI keeps the messages, rendered greyed-out with a "deleted" tag, as an audit trail. No undo; a deleted exchange loses its Delete button. Rejected with an `Error:` message in the chat while the agent is running or compacting. Root sessions only (sub-session logs don't offer Delete). If the turn was already compacted out of raw context, only the UI marking happens (silent degrade). If a compact archived history while the panel was open, the action is refused with a plain explanatory notice (not an `Error:` bubble) — the panel's turn positions no longer match the active file; reopening the session re-anchors it and Delete works again. Design details in [design/session.md](../design/session.md#exchange-deletion-soft-ui--hard-raw), protocol in [design/ws.md](../design/ws.md).
 
 ### Archived history (scroll up to load)
 Long sessions get their older exchanges moved out of the active log on compact, so opening a session stays fast no matter how long it has run. Loading older messages is **two-tiered** — a local, no-network tier first, then the network-backed archive:
@@ -49,19 +48,19 @@ Long sessions get their older exchanges moved out of the active log on compact,
 - Only once the local window is fully expanded does the next scroll-to-top (or the "Load earlier messages" row that takes over the same slot) reach for the **network** tier: it loads one archived segment per gesture, oldest-newer order preserved, and becomes "No earlier messages" once everything is loaded. The two tiers can't be skipped or reordered — the archive row only appears once there's nothing left to expand locally
 - Either tier preserves the reading position when older messages prepend — the view doesn't jump
 - Loaded archive segments sit in a **collapsed** block ("Archived · N segment(s) · M messages") — the user scrolled up for older context, not to have hundreds of exchanges re-flow the view; expanding renders them like normal messages, growing **upward** so the viewport stays pinned to the newest end, with the expand/collapse toggle below the revealed content
-- Archived exchanges are **read-only**: Copy still works, Delete is absent (the server refuses it for archived sessions)
+- Archived exchanges are **read-only**: Copy still works, Delete is absent (they are no longer in the active log, so a turn position can't address them)
 - Segments already loaded aren't re-fetched; a failed load can simply be retried with the same row
 
 ### Session tabs (right side)
-The workspace's root sessions as **Chrome-style vertical tabs** on the right edge of the chat panel (`VerticalTabList` rows inside a `ResizableSidebar`, default 200px). The list **is** the tab list: every session is "open", clicking a row shows it, and there is no close — deleting the session is the only way a tab goes away. Since 1.5.3-alpha this replaces the top tab strip, the History and New-session buttons beside the composer, and the "N previous sessions" link in the empty state.
+The workspace's root sessions as **Chrome-style vertical tabs** on the right edge of the chat panel (`VerticalTabRow` rows inside a `ResizableSidebar`, default 200px). The list **is** the tab list: every session is "open", clicking a row shows it, and there is no close — deleting the session is the only way a tab goes away. Since 1.5.3-alpha this replaces the top tab strip, the History and New-session buttons beside the composer, and the "N previous sessions" link in the empty state.
 
 - **Resize / collapse**: drag the left edge to resize (120–480px). Collapse from the header; the collapsed list is a `w-10` rail of square tabs, each showing the title's first letter plus the status dot in a corner, with a "+" at the bottom. Both settings are global preferences in `localStorage` (`halo_session_sidebar_open`, `halo_session_sidebar_width`); the list is open by default.
-- **Rows**: one line per row, 🎯 + title. Message count, time-ago and model are in the tooltip. `N msgs` counts the session's user turns **over its whole lifetime**, so compacting or archiving history never makes it go backwards.
+- **Rows**: one line per row, status dot + title. Message count, time-ago and model are in the tooltip. `N msgs` counts the session's user turns **over its whole lifetime**, so compacting or archiving history never makes it go backwards.
   - Each row leads with one fixed-size status dot (fixed so a state change never reflows a narrow list — the spinner it replaced did): **amber, pulsing** while a loaded tab's turn is running; **blue** when a loaded background tab is idle with unread output (output landed while it wasn't on screen; cleared when shown); **green** otherwise — including sessions no tab has loaded and tabs a reconnect released. The list endpoint's `status` is not used.
   - Infinite scroll pages older sessions. A "+" footer starts a new session.
 - **New session**: "+", `/session new` and `/clear` open a **draft tab**. A "New session" row sits on top while it is on screen, and an untouched draft is reused rather than duplicated. The session is created by the draft's first message or command. The previous session keeps streaming in its own tab.
 - **Background tabs**: one WS connection carries every loaded tab, so a session that isn't on screen keeps receiving its turn. After a reconnect only the tab on screen is reattached; the others reload when clicked. Live capture and face (`<<<SHOW>>>`) markers only act for the tab on screen.
-- **Delete (✕)**: deletes the session after a confirm dialog in the UI language ("Delete this session? Its history cannot be recovered." / its Chinese counterpart). Deletion is the REST delete first, then the WS one, so sub-session files go too. The ✕ is always visible on the active tab and appears on hover for the others; hover also reveals a **rename** pencil.
+- **Delete (trash icon)**: deletes the session after a confirm dialog in the UI language ("Delete this session? Its history cannot be recovered." / its Chinese counterpart). Deletion is the REST delete first, then the WS one, so sub-session files go too. The trash icon, like the **rename** pencil, appears only on hover — the active tab included.
 - **Inline rename**: pencil → input in place, Enter/blur commits (`PATCH /sessions/logs/:id`), Esc cancels; empty or unchanged title is a no-op. Other session-list consumers refresh via the `session:changed` WS push
 - **Persistence**: only the session on screen is remembered, per workspace, as `{active}` under `halo_chat_tabs_<projectId>`. A refresh restores and loads only that tab. The pre-tabs keys `halo_session_<projectId>` / `halo_session_id` are read once to seed it and then removed.
 - **Switch loading**: clicking a row that hasn't loaded yet shows a "Loading session…" state in the message area, cleared only when the server's `state:snapshot` for that exact sessionId arrives (empty sessions included). Past 30s it degrades to "Slow network — still loading…" plus a Retry button (re-subscribes) — slow ≠ failed, nothing aborts on its own. Switching to an already-loaded tab is instant, and its scroll position is restored
@@ -72,9 +71,9 @@ The full command list is fetched from `GET /api/commands` per session and includ
 
 | Command | Type | Purpose |
 |---|---|---|
-| `/help` | client | List available commands |
+| `/help` | server | List available commands |
 | `/clear` | client | Alias for `/session new` (admin-UI shortcut, no server registration) |
-| `/session new` | server | Start a new session |
+| `/session new` | server | Start a new session (the admin handles it client-side as a new draft tab, like `/clear`) |
 | `/session context` | server | Show context window usage, agent info |
 | `/session compact` | server | LLM-summary compact of the conversation |
 
@@ -93,7 +92,7 @@ When `contextEnabled` is on (default), user messages are auto-prepended with:
 - `[Currently viewing: path/to/file.ts]`
 - `[Selected text in file.ts:10-25]\n\`\`\`...\n\`\`\``
 
-### File attachments
+### File attachments (images)
 - Drag to chat input
 - Clipboard paste
 - File-picker button
@@ -101,7 +100,7 @@ When `contextEnabled` is on (default), user messages are auto-prepended with:
 Images ride along as base64; multimodal supported. Pasted images are also persisted to `<workspace>/.halo/assets/web/inbound/web/<date>/` so a `[图片已保存: /abs/path]` marker survives page reload and renders as a click-to-preview chip (shared with the WeChat channel's inbound media flow).
 
 ### Inline media chips
-Any message containing `[图片/视频/语音/文件 已保存: /path]` markers (WeChat + web) or a leading `MEDIA: /path` line (agent-emitted, e.g. from `wechat-send`) renders a compact chip with filename + icon. Clicking opens a full-size preview modal (image/video/audio inline, file → download link). The modal has a Download button (top-right, next to close) for image/video/audio; the media URL carries a per-open cache-buster (`&t=<timestamp>`) so overwritten files (same path, new bytes) always show current content. Paths inside the active workspace or under `/tmp/` are previewable; everything else degrades to a non-clickable chip.
+Any message containing `[图片/视频/语音/文件 已保存: /path]` markers (WeChat + web) or a leading `MEDIA: /path` line (agent-emitted, e.g. from `wechat-send`) renders a compact chip with filename + icon. Clicking opens a full-size preview modal (image/video/audio inline, file → download link). The modal has a Download button (top-right, next to close) for image/video/audio; the media URL carries a per-open cache-buster (`&t=<timestamp>`) so overwritten files (same path, new bytes) always show current content. Paths inside the active workspace or under the OS temp dir (`/tmp/`) are previewable; everything else degrades to a non-clickable chip.
 
 ### Live capture (desktop only)
 Lets the agent *see something live* on demand. Desktop client (Electron) only — the entry points never render in a plain browser. Borrows the meeting-app "share" model: the user binds one source, then the agent requests a frame when it actually needs to look.
@@ -115,7 +114,7 @@ Once bound, a frame is **not** attached to every message. Instead a one-line ins
 Constraints:
 - Shown only when the selected agent's model accepts image input (capture is pointless on a text-only model); switching to a text-only model auto-unbinds.
 - Screen share needs macOS **Screen Recording** permission; the camera prompts for **Camera** permission on first use, with an "Open Settings" path if previously denied.
-- Binding is **in-memory only** — switching sessions or restarting requires re-selecting.
+- Binding is **in-memory only** and shared by all chat tabs — a page reload or restart requires re-selecting.
 
 ### The agent's face (`self.html`)
 A second channel beyond text: a visual space the agent drives in real time to express itself. Works everywhere (pure HTML/canvas, no Electron dependency) — desktop **and** plain browser.
@@ -123,7 +122,7 @@ A second channel beyond text: a visual space the agent drives in real time to ex
 - **What it is.** A self-contained animated particle canvas at `<workspace>/.halo/canvas/self.html` — a breathing core that reacts to the cursor (knows when it's watched), can form words/CJK/ASCII-from-emoji, play choreographed sequences, and gesture (pulse/flash/shake). Zero external references (no CDN/remote fonts) — ships and runs offline.
 - **Seeding.** Force-copied from `packages/server/templates/canvas/self.html` into every workspace on open (platform-owned, like built-in skills). The `self` built-in skill (wired into the default agent) teaches the agent it has this face and how to drive it.
 - **Opening it.** The ✨ button in the chat-input toolbar opens the face in the editor preview (switches to Explorer, render-mode on → lands on the live face) and posts `self.intro()` once it has mounted, so there's always a greeting when a human turns to look. The greeting is driven solely by this open action — the page does **not** self-fire it on load — so it plays exactly once, on both first and subsequent opens. The user can also just open the file directly (no auto-greeting in that path).
-- **Driving it.** The agent emits `<<<SHOW: …js… >>>` markers in a reply; Halo forwards the payload **verbatim** (it never parses it) to the open preview iframe via `postMessage`, where it's `eval`'d against the face's `self` API (`say`/`play`/`react`/`pulse`/`flash`/`shake`/`intro`) inside the sandboxed iframe. Markers are stripped from the rendered chat (like `<<<CAPTURE>>>`) — the user sees the face move, not the code. Multiple markers in one reply **queue and play in order**.
+- **Driving it.** The agent emits `<<<SHOW: …js… >>>` markers in a reply; Halo forwards the payload **verbatim** (it never parses it) to the open preview iframe via `postMessage`, where it's `eval`'d against the face's `self` API (`say`/`play`/`react`/`pulse`/`flash`/`shake`/`intro`/`voice`) inside the sandboxed iframe. Markers are stripped from the rendered chat (like `<<<CAPTURE>>>`) — the user sees the face move, not the code. Multiple markers in one reply **queue and play in order**.
 - **Engine vs. expression.** `self.html` is a stable *engine* (defines how the face can move); the agent expresses itself by sending runtime JS, **never** by editing the file — so the force-copy-on-open never clobbers anything meaningful. The engine only changes when the platform adds a new capability (template edit + `TEMPLATE_VERSION` bump).
 - **No open preview = no-op.** `<<<SHOW>>>` only reaches a mounted preview; if the face isn't open the marker is silently dropped (the skill tells the agent to invite the user to open it rather than rely on a marker landing in the void).
 - **Identity.** Deliberately nameless ("HELLO / A MIND / IS HERE / BEYOND WORDS") — the conversational identity is user-configurable and the model may not be Claude, so the face never hard-codes a name.

package/bundled-docs/requirements/command.md

@@ -10,8 +10,8 @@ Top-level built-in slash commands: `/help` `/evo` `/session` `/agent` `/skill` `
 
 | Name | Slash | Type | Purpose |
 |---|---|---|---|
-| `help` | `/help` | client | List commands — object commands show only the verbs the user can run; a command is hidden entirely if no verb is runnable |
-| `evo` | `/evo [text]` | server | Flat command (no verbs), **full-only**. Trigger self-evolution on the current root session: snapshot the conversation + queue an evo run. Optional text becomes a hint for what to focus on. Available only when `general.evolution.level=L1`. See [plans/self-evolution.md](../plans/self-evolution.md). |
+| `help` | `/help` | server | List commands — object commands show only the verbs the user can run; a command is hidden entirely if no verb is runnable |
+| `evo` | `/evo [text]` | server | Flat command (no verbs), **full-only**. Trigger self-evolution on the current root session: snapshot the conversation + queue an evo run. Optional text becomes a hint for what to focus on. Works at every `general.evolution.level` (L0 = manual only; L1 also drafts automatically on pre-compact). Hidden from `/help` for non-full users. See [design/evolution.md](../design/evolution.md). |
 
 The rest are noun-verb **object commands**: `/<obj> <verb> [args]`. Some verbs are built-in deterministic code (`SUBCOMMAND_ROUTES`); the others fall through to the same-name skill (LLM, dispatched via `$1`). Bare `/<obj>` or `/<obj> help` lists the verbs available to the user (filtered by access level).
 
@@ -38,7 +38,7 @@ Resolution starts from the caller's active session, walks up to its root (`id.sp
 
 ## Command aliases
 
-`dispatchCommand` expands shorthand aliases before routing, so every channel (WS, WeChat, Telegram, Web, CLI/TUI) gets the same shortcuts uniformly. Aliases are read from a single seed file:
+`dispatchCommand` expands shorthand aliases before routing, so every channel (WS, Web, the IM channels, CLI/TUI) gets the same shortcuts uniformly. Aliases are read from a single seed file:
 
 - **`~/.halo/global/aliases.yaml`** — seeded once on first run (`init.ts`, via `writeIfMissing`), **never overwritten**, so the user can freely edit it. Deleting the file disables all aliases. Changes take effect immediately: the loader caches the parsed YAML keyed by file **mtime**, re-reading only when the file changes (no restart, no per-command disk parse on the hot path).
 
@@ -58,7 +58,7 @@ The canonical command is `/workspace`; `/w` is its bare alias. `/ws` and `/wi` a
 
 ## Cross-channel commands
 
-All channels (WS, WeChat, Telegram, Web, CLI/TUI) share `dispatchCommand` for common commands. Channel-specific commands (e.g. WeChat `/name`) are handled in the channel handler before reaching the shared dispatch.
+All channels (WS, Web, Telegram, Slack, Feishu, WeCom, WeChat, CLI/TUI) share `dispatchCommand` for common commands. Channel-specific commands (e.g. WeChat `/qr`) are handled in the channel handler.
 
 ## Skill-as-command
 
@@ -88,30 +88,30 @@ When triggered, the skill body is read from disk and sent to the agent session a
 
 User args are filled via `$ARGUMENTS` / `$1`–`$9` placeholders (args are no longer appended verbatim to the body end); a verb reaches the body as `$1` for dispatch.
 
-Every `GET /api/commands?projectId=xxx` rescans skill directories.
+Every `GET /api/commands` call that carries `sessionId` / `agentId` rescans skill directories.
 
 ### Conflict detection
 
 A skill's `command` must not collide with a built-in slash command or with another skill's. Collisions are resolved at scan time in `scanSkillDescriptors`, the single source feeding both dispatch and the discovery API:
 
-- **Built-ins always win** — a skill command colliding with a built-in is not registered as a command. This is by design for object commands: their same-name skill (e.g. `agent`, `skill`, `workspace`) is shadowed as a command, but its body still serves the skill verbs (create / update etc.) via the verb fallback.
+- **Built-ins always win** (hidden ones too) — a skill command colliding with a built-in is not registered as a command. This is by design for object commands: their same-name skill (e.g. `agent`, `skill`, `workspace`) is shadowed as a command, but its body still serves the skill verbs (create / update etc.) via the verb fallback.
 - **Among skills, first-come wins** (workspace scope is merged over global before this check); the later one is dropped with a warning.
-- Colliding entries are **dropped** from the command list and a warning is logged (`[CommandRegistry] skill "<id>" command "/x" shadowed by …`). Dropping at the shared source guarantees a command can never appear in the palette that dispatch is unable to route ("visible but unreachable").
+- Colliding entries are **dropped** from the command list; a skill-vs-skill clash also logs a warning (`[CommandRegistry] skill "<id>" command "/x" shadowed by …`), a built-in owning the name doesn't. Dropping at the shared source guarantees a command can never appear in the palette that dispatch is unable to route ("visible but unreachable").
 
 Note: a skill's `command` collision only removes the *slash command*; the skill itself remains usable via the agent's normal skill activation.
 
 ## Command discovery API
 
 ```
-GET /api/commands?projectId=xxx
+GET /api/commands?projectId=xxx[&sessionId=][&agentId=]
 → { commands: CommandDescriptor[] }
 ```
 
-Returns every non-hidden command (built-in + skill). The frontend calls this on project switch to populate the command palette.
+Returns every non-hidden built-in command, plus the skill commands the session's / agent's skill whitelist and access level allow when `sessionId` or `agentId` is given (with neither, built-ins only). The frontend calls this on project switch to populate the command palette.
 
 ## Adding a new command
 
-A server-handled command lives in **three** places that must stay in sync —
+A server-handled command lives in **four** places that must stay in sync —
 miss any one and the server either throws at startup or silently no-ops:
 
 1. Add a `exec<Name>` function in `channels/shared/commands.ts`

package/bundled-docs/requirements/editor.md

@@ -15,18 +15,19 @@ Monaco-based multi-tab code editor + binary file previewer — surfaced in the U
 ## Core behaviour
 
 ### Multi-tab editing
-- Click a file in Explorer (single click = select, double click = open tab)
+- Click a file in Explorer (single click = select, then opens after a 300 ms delay; double click opens immediately)
 - Each tab independently tracks content, original content, language, mtime
-- Unsaved tabs show a small red dot
+- Unsaved tabs show a small amber dot (the ✕ appears on hover)
 - Closing an unsaved tab prompts for confirmation
+- The tab bar's **Split right** button opens a second pane (two at most); each pane has its own tabs, Edit/Preview and Diff state
 
 ### Save
 - `Cmd+S` / `Ctrl+S` calls `PUT /api/files`
 - Server returns the new `modifiedAt`; the tab updates its mtime
 
 ### Auto-refresh (mtime-based)
-When agents write files through tools, the canvas detects it:
-1. Periodically poll `GET /api/files/stat`
+When agents write files through tools, the canvas detects it — push-based, no polling:
+1. The server's WS `file:changed` (`change`) event re-reads the matching open tab; the active tab is also re-checked with `GET /api/files/stat` on tab switch, window focus and WS reconnect
 2. If `diskMtime > tab.mtime`, pull fresh content
 3. Skip if the user has unsaved edits (don't overwrite)
 
@@ -34,7 +35,7 @@ When agents write files through tools, the canvas detects it:
 Open tabs and the active tab live in localStorage; survive refresh.
 
 ### Diff view
-- Tracked files → `GET /api/git/diff` (returns `{ original, modified }`) for git diff
+- A tab with unsaved edits shows a **Diff** button in its pane's tab bar: last saved content vs. the current buffer, computed in the client (no git involved; `GET /api/git/diff` is the Source Control panel's)
 - Monaco left/right compare view
 
 ### Binary previews
@@ -66,13 +67,13 @@ File types without a built-in plugin can be handled by an **installed extension*
 
 ### Renderable text formats (Markdown / HTML)
 Markdown and HTML open as text in Monaco *and* have a rendered view — Canvas defaults to the **rendered** view since the primary audience is an AI generating reports / pages for humans to read.
-- Header shows an **Edit / Preview** toggle (same `textRenderMode` state for both formats)
+- Each pane's tab bar shows an **Edit / Preview** toggle for the active Markdown / HTML tab; the state is per pane, shared by both formats
 - **Markdown** → `MarkdownPreview` (react-markdown + GFM; relative image `src` rewritten to the download endpoint so local images work)
-- **HTML** → sandboxed iframe (`sandbox="allow-same-origin"`; scripts, top-navigation, forms, pop-ups all blocked — safe against hostile HTML)
+- **HTML** → sandboxed iframe (`sandbox="allow-scripts allow-same-origin"`: the page's own JS runs, so a self-contained page renders live; top-navigation, forms and pop-ups stay blocked. Trusted like opening the file in Monaco — it comes from the user's own workspace)
 - Toggle to Edit → Monaco source, Cmd+S saves as usual
 
 ### Preview caching (MRU)
-Recently opened preview tabs stay mounted (up to 5, MRU) so switching between them doesn't re-fetch or re-parse. Plugins flagged `heavy: true` bypass the cache — only the active instance mounts, others unmount. Closing a preview tab removes it from the cache immediately (aborting any in-flight fetch).
+Recently opened preview tabs stay mounted (up to 5, MRU) so switching between them doesn't re-fetch or re-parse. Plugins flagged `heavy: true` bypass the cache — only the active instance mounts, others unmount. An extension tab with unsaved edits stays pinned beyond the 5. Closing a preview tab removes it from the cache immediately (aborting any in-flight fetch).
 
 ### File metadata in header
 The Canvas header shows `(size · Created … · Modified …)` for the active tab. Both text tabs and preview tabs populate this — preview tabs fetch `GET /api/files/stat` on open (and on tab restore from localStorage) since they never read content.
@@ -91,5 +92,5 @@ Canvas (including Monaco instances, file tree, and open tab contents) stays moun
 |---|---|
 | Cmd/Ctrl + P | Quick Open (fuzzy file search) |
 | Cmd/Ctrl + S | Save current tab |
-| Alt + W | Close current tab (Cmd+W cannot be overridden in browsers) |
+| Alt + W | Close current tab (Cmd+W cannot be overridden in browsers; the desktop app uses Cmd/Ctrl + W, and closes the window when no tab is open) |
 | Esc | Exit maximized Canvas (when not inside an input / Monaco / Quick Open) |

package/bundled-docs/requirements/explorer.md

@@ -6,22 +6,25 @@ VS Code-style file tree sidebar with multi-select, drag-drop, right-click menu.
 
 ### Initialization
 - URL `?folder=/abs/path` → use that directly as workspace
-- No `?folder` → call `GET /api/fs/home`, take the home directory as fallback, write it back into the URL; UI behaves identically
+- No `?folder` → reopen the last workspace (`halo_last_folder` in localStorage); if none is stored or it no longer resolves, fall back to `GET /api/fs/home`. Either way the path is written back into the URL; UI behaves identically
+- The path is resolved through `POST /api/fs/workspace/resolve`, which rejects non-directories and filesystem roots and seeds the workspace's `.halo/` scaffold
 - There's always a valid workspace; every frontend feature (file tree / sessions / agents / settings) depends on it
 
 ### Path input
 - Explorer top bar has a path input + 📁🔍 picker button
-- Pressing Enter calls `GET /api/fs/exists?path=...` first — a miss shows an alert, no switch
-- **Recent-workspaces dropdown**: focusing the input shows the most-recently-used list; typing filters it by substring. Each row shows the folder name + full path; clicking one switches to it; a hover "×" removes a single entry. Entries are recorded only after a switch validates the path (so invalid paths never land), in canonical resolved form, MRU-ordered and deduped, capped at 8. Persisted in localStorage (`halo_recent_workspaces`)
+- Pressing Enter calls `GET /api/fs/exists?path=...` first — a miss (or a non-directory) shows an alert, no switch
+- **Recent-workspaces dropdown**: focusing the input shows the most-recently-used list; typing filters it by substring. The current workspace is left out. Each row shows the folder name + full path; clicking one switches to it; a hover "×" removes a single entry. Entries are recorded only after a switch validates the path (so invalid paths never land), in canonical resolved form, MRU-ordered and deduped, capped at 8. Persisted in localStorage (`halo_recent_workspaces`)
 
 ### Desktop windows (multi-window)
 Desktop app only — the browser has one tab per window natively.
 - **New window**: `Cmd+N` (macOS, via the File menu) / `Ctrl+N` (Windows/Linux, bound at the webContents level since those platforms have no app menu). Each window is a fresh view onto the **one shared local server** — no second server process spawns.
 - **Per-window workspace**: windows share the server origin, hence one localStorage, so a window tracks its own workspace via its URL `?folder=` (not localStorage, which would clobber across windows). Different windows can sit on different workspaces; the same workspace can be open in two windows.
 - **Quit semantics** (platform split): on macOS, closing every window keeps the app in the Dock (only `Cmd+Q` truly exits) and clicking the Dock icon reopens a window; on Windows/Linux there's no Dock to resummon from, so closing the last window quits.
+- **Quick toggles entry** (bottom of the activity bar, below Settings; browser and desktop): a gear with a thin segmented status bar under it — one segment per available item, in fixed order network → notify → pin → keep-awake (browser: network + notify, or network alone without the Web Notification API; desktop: all four). Network segment: emerald = fresh, pulsing amber = stale, red = down (the gear itself also turns red when down); notify / pin segments: primary when on; keep-awake: amber when on (it stops the screen locking, so it gets its own colour); off = dimmed muted grey. The native hover title lists every item's state. Clicking opens a panel (titled "Status & window") to the right of the entry: a read-only network row, then one switch row per toggle; switches apply immediately and the panel stays open; outside click, Esc or a second entry click closes it. Segments, rows and the hover summary all come from one item list (`useQuickToggleItems` in `features/workspace/quick-toggles.tsx`).
 - **Pin (always-on-top)** acts per-window — each window pins independently.
+- **Keep screen awake** (desktop only) acts per-window and isn't persisted — a restart or a new window starts off, a reload keeps it. While any opted-in window is neither minimized nor hidden (merely covered by other windows still counts), the app holds one display-sleep blocker, so the screen won't dim or lock when you step away.
 - **Activity awareness**: while the agent streams a reply the sidebar's workspace name carries an amber pulsing dot (emerald when idle) and the window title gains a `●` prefix (`● Halo — <name>` busy vs `Halo — <name>` idle) — both are plain web behaviour that Electron mirrors to the native title bar.
-- **Finish notification** (works in both the desktop app and a plain browser): an opt-in bell toggle sits in the activity bar next to the pin, **off by default**, persisted per-machine in localStorage (`halo_notify_on_finish`). It's shown whenever a notification can be raised — the desktop shell (`window.haloNotify` bridge) or a browser with the Web Notification API; turning it on in a browser requests Notification permission from within the toggle click (the required user gesture). When on, a turn finishing in **any loaded chat tab** — on screen or in the background — triggers two decoupled cues (sessions no tab has loaded, or released by a reconnect, never ring; tab switches and snapshot replays aren't completions): a **self-synthesized WebAudio chime** that always plays (regardless of focus — an audible "it's done" even while you're watching the tab, and not subject to the OS per-site notification-sound setting), plus — **only when the window is unfocused** — a banner (desktop: native notification + Dock bounce / taskbar flash; browser: a Web Notification whose click refocuses the tab) whose body names the session by its title ("“<title>” finished responding."; generic text if the title isn't known). Focused → chime only, no banner.
+- **Finish notification** (works in both the desktop app and a plain browser): an opt-in toggle in the quick-toggles panel, **off by default**, persisted per-machine in localStorage (`halo_notify_on_finish`). It's shown whenever a notification can be raised — the desktop shell (`window.haloNotify` bridge) or a browser with the Web Notification API; turning it on in a browser requests Notification permission from within the toggle click (the required user gesture). When on, a turn finishing in **any loaded chat tab** — on screen or in the background — triggers two decoupled cues (sessions no tab has loaded, or released by a reconnect, never ring; tab switches and snapshot replays aren't completions; queued messages drained back to back ring once, after the last one): a **self-synthesized WebAudio chime** that always plays (regardless of focus — an audible "it's done" even while you're watching the tab, and not subject to the OS per-site notification-sound setting), plus — **only when the window is unfocused** — a banner (desktop: native notification + Dock bounce / taskbar flash; browser: a Web Notification whose click refocuses the tab) whose body names the session by its title ("“<title>” finished responding."; generic text if the title isn't known). Focused → chime only, no banner.
 
 ### Directory picker (FolderPicker modal)
 Visual directory browser opened by the 📁🔍 button:
@@ -47,8 +50,8 @@ Visual directory browser opened by the 📁🔍 button:
 
 ### Selection model
 VS Code-style highlight selection (no checkboxes):
-- **Click**: select and highlight
-- **Double click**: open in editor tab
+- **Click**: select and highlight; a file also opens in the editor after a short (300 ms) delay, a folder toggles open/closed
+- **Double click**: open the file in an editor tab right away (cancels the delayed open)
 - **Ctrl/Cmd + click**: toggle multi-select
 - **Shift + click**: range select
 
@@ -60,7 +63,7 @@ VS Code-style highlight selection (no checkboxes):
 
 ### Right-click menu
 
-Items shown depend on the click target:
+Items shown depend on the click target. With several items selected the menu offers only Delete; on the workspace root row only New File / New Folder / Open in Integrated Terminal / Reveal in File Manager apply:
 
 | Action | Shown when | API / behavior |
 |---|---|---|