@turmind/halo 1.5.4 → 1.5.6

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
@@ -59,20 +60,21 @@ File types without a built-in plugin can be handled by an **installed extension*
 - **Resolution order** for a file extension: `default`-priority extensions (newest install wins) → built-in plugins → `option`-priority extensions. `.glb` with the `glb` extension installed opens in the viewer directly; an `option` extension only shows up in the header's **Open with** menu
 - **Opening and tab restore**: whether a file opens as text or in a viewer is decided when it is clicked, restored after a page reload, or opened to the side. Since an installed extension may claim a type (`.glb`) or even a text suffix (`.json`), a file that would open as text first waits for the page's initial extension list (up to 3 s), so a `.glb` tab survives a reload as a viewer rather than coming back as text. Files that already have a built-in viewer open without waiting. If the list isn't back within 3 s (or failed to load), files open as if no extension were installed — a `.glb` opens as text; a list that arrives later still updates the viewer of tabs that are already previews
 - **Open with** (header menu, shown only when there are >2 candidates counting *Open as text*): switches the current tab's viewer; the choice is per tab and not persisted
-- **Fallback**: a file with no built-in plugin and no installed extension shows a static page — "no built-in preview for this type; extensions for more file types are on halo-hub ↗" — plus Open as text / Download. No online lookup
+- **Fallback**: a file with no built-in plugin and no installed extension shows a static page — "no built-in preview for this type; extensions for more file types are on <hub> ↗", where `<hub>` is the extension skill's `hub_repo` (default halo-hub; a local path / ssh remote shows as text) — plus Open as text / Download. No online lookup
 - **Editable extensions** (manifest `capabilities: ["save"]`): the iframe reports dirty → tab shows the dirty dot → header **Save** button (Ctrl/Cmd+S is *not* wired for extension tabs — Monaco isn't mounted) → `PUT /api/files/raw`. If the file changed on disk since it was loaded the save gets a 409 and the user is asked "changed on disk … Overwrite?". An external change while the tab is clean reloads it; while dirty, local edits are kept silently and the conflict surfaces at the next save
+- **Install sources**: Settings → Extensions zip upload; `/extension install <id|zip|url>` (listed by the built-in `default` agent, full access), where an id comes from the hub in Settings → Skills → extension → `hub_repo` (default halo-hub; GitHub / Gitea / Forgejo / GitLab release zips, or tags of any other git repo); or a manual directory drop
 - **Live install / upgrade / uninstall** (from Settings → Extensions upload / remove, the `/extension` skill, or a manual directory change): pushed over WS, no reload. An upgraded extension remounts open tabs (or shows a "updated — reload" banner if the tab is dirty); uninstalling drops clean tabs to the fallback page and keeps dirty tabs alive with a banner
 - **Settings → Extensions**: lists installed extensions (name, version, file types, license/homepage) and manifest errors; upload `.zip` (≤ 100 MB) and remove. Any logged-in admin can do both — the admin cookie has no access level
 
 ### 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; switching between two heavy tabs of the same type (e.g. two `.ipynb`) remounts the viewer, so it shows the newly active file. 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 +93,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 |
 |---|---|---|

package/bundled-docs/requirements/session.md

@@ -6,12 +6,12 @@ Session history viewer: hierarchy tree, message playback, debug mode, system pro
 
 ### Session tree view
 - Top-level sessions (no parentSessionId) act as roots; child sessions render indented
-- Each row shows: title, agent-name badge, message count (user turns over the session's lifetime — never shrinks when history is compacted/archived), relative time, and status icons (StopCircle for stopped, amber Archive for archived)
-- Clicking loads the full message list into SessionChatPanel
-- Collapse / expand via arrow buttons
-- Clicking the count badge (e.g. "+3") shows total descendant count
+- Each row shows: title, message count (user turns over the session's lifetime — never shrinks when history is compacted/archived), relative time, and status icons (amber Archive for archived; StopCircle for stopped, sub-agent rows only). Sub-agent rows also carry an agent-name badge; a root row shows an "active" badge when it is the chat panel's current session
+- Clicking a row previews its full message list in SessionChatPanel; double-clicking a root row opens it in an Explorer chat tab
+- Collapse / expand via the arrow buttons; a row with descendants shows a non-clickable "+N" total descendant count
+- Hover trash on a root row (confirm dialog) hard-deletes the session and its whole subtree via REST
 - Inline title rename (admin-only): a hover pencil on any row — root **or** sub-agent — opens an inline input (Enter commits, Escape cancels, blur commits); persists via `PATCH /api/sessions/logs/:id`
-- Infinite scroll loads more roots in pages; a silent reload (after streaming ends, or a delete / create / archive elsewhere) re-fetches the **same depth** already scrolled to rather than snapping back to the first page. No cap on depth: a reload deeper than the endpoint's 500-row page limit pages through with the cursor in 500s and renders once at the end (the 300-top-level cap was removed in 1.5.3-alpha)
+- Infinite scroll loads more roots in pages; a silent reload (after streaming ends, or a delete / create / archive elsewhere) re-fetches only the first page and merges it over the rows already loaded, so the list keeps its depth and scroll position. Rows beyond the first page aren't re-checked until the next full reload (mount / project switch). No cap on depth (the 300-top-level cap was removed in 1.5.3-alpha)
 - Viewed sessions are cached (LRU, 20 sessions; the one on screen is never evicted): switching back to a cached session shows the kept copy at once — transcript, archive position and reading position — and a stale copy (its log file changed, or the WS reconnected) is refetched in the background. Refetches are single-flight per session: at most one request in flight plus one queued re-pull. A session that is open in an Explorer chat tab shows that tab's live stream instead
 - The Sessions tab mounts on first open and then stays mounted (CSS-hidden while another activity tab is up), so the cache and reading positions survive switching tabs
 
@@ -22,29 +22,27 @@ Session history viewer: hierarchy tree, message playback, debug mode, system pro
 - For a session whose history was compacted, scrolling to the top shows a "load earlier messages" row; scrolling further or clicking it pulls one archived segment at a time. Pulled history renders expanded above the active log, with a divider marking where it ends, and is read-only (no delete)
 
 ### Debug mode
-Top Debug toggle (Bug icon). When on:
-- **Normal mode**: user message + assistant reply (with inline tool-call cards); sub-agent notifications hidden
-- **Debug mode**: every message, including:
-  - **Context / System Prompt** (purple) — full injected prompt, expandable
-  - **Tool Call** (blue) — full tool input JSON, expandable
-  - **Tool Result** (green/red) — full tool output JSON, expandable
-  - **Usage** — token counts, latency (ttft / e2e), model ID, cache hit ratio
-  - Sub-agent messages carry an agent-name badge
+Top Debug toggle (Bug icon), persisted in `localStorage` as `halo_session_debug`. When on:
+- **Normal mode**: user message + assistant reply (with inline tool-call cards, click to expand IN / OUT); sub-agent notifications hidden
+- **Debug mode**: adds, on top of the normal view:
+  - **Thinking** blocks (purple, expandable, with char count) inside assistant messages
+  - **Usage** line after each turn — timestamp, token counts (in / out / ctx, cache read / write / hit ratio), latency (ttft / e2e), thinking effort, model ID
+  - Sub-agent start / done markers labelled with the agent name
 
 ### System prompt viewer
-The Prompt button (FileText icon) shows the system prompt used by this session. Extracted from the first `context`-type message; displays the full injected prompt (AGENT.md + INSTRUCTIONS.md + INDEX.md + TOOL_GUIDELINES + skills).
+The Prompt button (FileText icon, shown only when the session has a prompt; open state persisted as `halo_session_prompt`) shows the system prompt used by this session in a floating card. Extracted from the first `context`-type message (never rendered inline in the list); displays the full injected prompt (AGENT.md + INSTRUCTIONS.md + INDEX.md + TOOL_GUIDELINES + skills).
 
 ### Session lifecycle
 - Created on the first `chat` WS message (with a new sessionId)
 - Auto-saved after every `complete` event
 - Sessions restore from disk on refresh / WS reconnect (loaded at subscribe time; running sessions reattach from the detached pool)
-- Deleting a session removes the JSON file (plus any archived history segments) and cascade-deletes all descendants in SQLite
+- Deleting a session removes the JSON file (plus any archived history segments) and cascade-deletes all descendants (their files and SQLite rows)
 - Assistant messages persist their `contentBlocks` (text / thinking / tool calls, in the order they happened) so tool-call cards survive a refresh in the right places. Sessions written before content blocks existed carry a flat `toolCalls` array instead and still render, as a fallback
 
 ### Non-destructive /session new
 `/session new` (also `/clear` and "+ New Session") **does not** destroy the old session:
 1. A new draft tab opens in the chat panel with an empty conversation; the session is created on its first message or command
-2. The old session keeps its tab and keeps streaming into it in the background (its row shows a running mark, and an unread dot once new output lands)
+2. The old session keeps its tab and keeps streaming into it in the background (its row's status dot pulses amber while it runs and turns blue once new output lands unseen)
 3. The old session's sub-agents keep running independently
 4. Switching back shows the old tab as it is; after a reconnect it reloads from the server
 
@@ -56,7 +54,7 @@ The Prompt button (FileText icon) shows the system prompt used by this session.
 |---|---|
 | Main session | Sidebar top level |
 | Child session (has parentSessionId) | Nested under parent |
-| Stopped session | Icon decorated with StopCircle |
+| Stopped session (sub-agent row) | Icon decorated with StopCircle |
 | Archived session | Shown dimmed (50% opacity) with an amber Archive icon — the list fetches `includeArchived=1`, so archived rows stay visible for inspection rather than being hidden |
 
 ## API
@@ -69,6 +67,7 @@ Unified session logs API (recommended):
 | Read | `GET /api/sessions/logs/:id?projectId=...` |
 | Read archived history | `GET /api/sessions/logs/:id/archive/:n?projectId=...` |
 | Delete | `DELETE /api/sessions/logs/:id?projectId=...` |
+| Rename | `PATCH /api/sessions/logs/:id?projectId=...` (body `{title}`) |
 
 The List endpoint serves two consumers: this tree view (default — roots + all
 descendants, paginated, rebuilt into a tree client-side) and the chat panel's

package/bundled-docs/requirements/settings.md

@@ -17,8 +17,8 @@ general:                                  # built-in declarer (server itself)
     max_summary_input: 15000
     ...
   sandbox:
-    hidden_dirs: "~/.halo/secrets,~/.aws,~/.ssh,~/.gnupg,~/.docker,~/.config/gh"
-    hidden_files: "~/.npmrc,~/.bash_history,~/.gitconfig,~/.git-credentials,~/.netrc,~/.halo/global/runs.db"
+    hidden_dirs: "~/.kube"                # extras — appended to the built-in list, never replace it
+    hidden_files: "~/.pgpass"             # extras — appended to the built-in list, never replace it
     writable_dirs: ""                     # e.g. ~/.kiro,~/.local/share/kiro-cli — rw bind-mounts in bwrap; ignored for readonly sessions
   logging:
     level: warn
@@ -36,13 +36,13 @@ deepseek:
   secrets:
     api_key: <<DEEPSEEK_API_KEY>>
 
-tavily-search:                            # skill id from skills/<id>/config.yaml
+tavily-web-search:                        # skill id from skills/<id>/config.yaml
   params:
     api_key: <<TAVILY_API_KEY>>
 ```
 
 The path always reads as `<namespace-id>.<kind>s.<key>`:
-- `<namespace-id>` is `general`, a provider id, or a skill id
+- `<namespace-id>` is `general`, a provider id, a skill id, or an agent id
 - `<kind>` is `param` or `secret`
 - `<key>` is the leaf, dotted for grouping (e.g. `general.compact.keep_messages`)
 
@@ -91,15 +91,19 @@ params:
 secrets: []
 ```
 
+Built-in skills declare theirs the same way — today `extension`, with a plain `hub_repo` param (the hub `/extension install <id>` pulls from; empty = turmind/halo-hub), and `web-search`, with plain `fast_region` / `deep_region` params (AWS regions for its two Bedrock gears; empty = us-east-1 fast, us-west-2 deep / us-east-1 for sol). `halo setup` asks only for built-in skills' `secret: true` params; plain params are configured in Settings → Skills only.
+
+Global agents declare theirs the same way in `agents/<agent-id>/agent-config.yaml` (same `params:` / `secrets:` lists; shown under Settings → Agents).
+
 ### General — built-in
 
-Declared in [packages/server/src/settings-schema.ts](../../../packages/server/src/settings-schema.ts) `generalSection()`. The server itself is the implicit declarer. Keys: `language`, `agent.*`, `server.*`, `session.*`, `compact.*`, `sandbox.*`, `logging.*`, `evolution.*`, `limits.*`. All `general.*` keys are `globalOnly`: `config.ts` resolves them through `settingsValue()` against `~/.halo/secrets/settings.yaml` only, so a workspace `settings.yaml` cannot override them. Per-workspace layering applies to namespaced `params` / `secrets` (`getServerSecret(ns, key, workspaceRoot)`, `substituteSecrets`).
+Declared in [packages/server/src/settings-schema.ts](../../../packages/server/src/settings-schema.ts) `generalSection()`. The server itself is the implicit declarer. Keys: `language`, `theme`, `agent.max_retries`, `server.*`, `session.*`, `compact.*`, `sandbox.*`, `logging.*`, `observability.*` (read once at boot — restart to apply), `evolution.*`, `limits.*`. All `general.*` keys are `globalOnly`: `config.ts` resolves them through `settingsValue()` against `~/.halo/secrets/settings.yaml` only, so a workspace `settings.yaml` cannot override them. Per-workspace layering applies to namespaced `params` / `secrets` (`getServerSecret(ns, key, workspaceRoot)`, `substituteSecrets`).
 
 `server.trust_proxy` (boolean, default `false`, `globalOnly`): whether the brute-force rate limiter (`middleware/brute-force.ts` `getClientIp`) trusts the `x-forwarded-for` header for client IP resolution. Direct-connect deployments leave it `false` and get the socket address. Behind a reverse proxy (nginx / Cloudflare / etc.), set it to `true` so the real client IP is honored instead of the proxy's — but only when that proxy is one you control and rewrites the header itself, otherwise a client can forge XFF to dodge lockouts.
 
-`sandbox.hidden_dirs` / `sandbox.hidden_files` / `sandbox.writable_dirs` are `globalOnly` — they define the security boundary agents run inside, so a workspace `settings.yaml` cannot override them (a workspace overriding them could lift its own sandbox constraints).
+`sandbox.hidden_dirs` / `sandbox.hidden_files` / `sandbox.writable_dirs` are `globalOnly` — they define the security boundary agents run inside, so a workspace `settings.yaml` cannot override them (a workspace overriding them could lift its own sandbox constraints). `hidden_dirs` / `hidden_files` hold **extra** entries: the effective list is the built-in default (`DEFAULT_HIDDEN_DIRS` / `DEFAULT_HIDDEN_FILES` in `tools/sandbox.ts`, the single source — `~/.halo/secrets`, `~/.aws`, `~/.ssh`, `~/.gnupg`, `~/.docker`, `~/.config/gh`, `~/.halo/global/internal-sessions`, `~/.halo/global/logs`; `~/.npmrc`, `~/.bash_history`, `~/.gitconfig`, `~/.git-credentials`, `~/.netrc`, the global `evo` / `cron` / `runs` databases + `-wal` / `-shm`) plus the user's entries, deduped (`config.ts` `resolveSandboxPaths()`, used by both the server and the CLI). A default entry cannot be removed from the list in settings. The lists apply only to workspace / readonly sessions (bwrap / Seatbelt, or `assertPathAllowed` without an OS sandbox); Full sessions, the admin file explorer (`validatePath`, workspace-bound only) and the terminal never consult them. The schema `default` is empty so the placeholder doesn't suggest copying the built-ins; the field description names them. `writable_dirs` is a plain list (no built-ins).
 
-`evolution.*` controls the self-evolution subsystem (see [plans/self-evolution.md](../plans/self-evolution.md)). All `evolution.*` keys are `globalOnly` — they live in `~/.halo/secrets/settings.yaml` only, not workspace settings. Notable knobs: `evolution.level` (`L0` = off, `L1` = human + LLM assist), `evolution.max_concurrent_run` / `max_concurrent_apply` (wrapper concurrency caps), `evolution.run_timeout_minutes` / `apply_timeout_minutes` (heartbeat timeouts), `evolution.max_attempts` (per-row retry cap), `evolution.triggers.pre_compact` (snapshot session before compaction).
+`evolution.*` controls the self-evolution subsystem (see [design/evolution.md](../design/evolution.md)). All `evolution.*` keys are `globalOnly` — they live in `~/.halo/secrets/settings.yaml` only, not workspace settings. Notable knobs: `evolution.level` (`L0` = manual only: `/evo` drafts, a reviewer approves; `L1` = L0 plus automatic drafting on pre-compact), `evolution.max_concurrent_run` / `max_concurrent_apply` (wrapper concurrency caps), `evolution.run_timeout_minutes` / `apply_timeout_minutes` (heartbeat timeouts), `evolution.max_attempts` (per-row retry cap), `evolution.triggers.pre_compact` (snapshot session before compaction).
 
 Goal mode's entry points are offline (the `/goal` command, admin banner and creation of new goal sessions are hidden). To reopen them, set `general.goal_mode_enabled` — a global-only boolean, default `false`, read from `~/.halo/secrets/settings.yaml` only (a workspace `settings.yaml` has no effect) and not shown in the Settings UI — then restart the Halo server and refresh the browser (existing goal bindings and history are not touched either way):
 
@@ -110,18 +114,26 @@ general:
 
 The value is read once at process start, so unlike other settings it is **not** picked up by the mtime-watching reload.
 
-`agent.default_provider` is rendered as an `enum` whose options are the provider ids found under `~/.halo/global/models/*.yaml`. It controls **which provider a freshly scaffolded agent.yaml uses** — the model id, endpoint, prompt-caching TTL and thinking defaults are then derived from that provider's YAML (`defaultModelId`, `defaultEndpoint`, per-model `capabilities.promptCaching.default`, `capabilities.thinking.defaultEnabled / default / defaultBudgetTokens`). Existing agents are not retroactively touched. Implementation: [packages/server/src/routes/agent-configs.ts](../../../packages/server/src/routes/agent-configs.ts) `buildScaffoldModelBlock()`.
+There is no "default provider" setting: a newly created agent's `model:` is a copy of the **default agent's** `model:` mapping — for workspace scope `<project>/.halo/agents/default/agent.yaml` when it exists, else the global `~/.halo/global/agents/default/agent.yaml`; for global scope the global one. When that file is missing or has no `model` mapping, the scaffold falls back to the provider registry (`aws-bedrock-claude-invoke` if installed, else the first provider on disk), deriving model id / endpoint / prompt caching / thinking from that provider's YAML. Only `model` is copied; `context` stays the scaffold default. Existing agents are not retroactively touched. A leftover `general.agent.default_provider` in `settings.yaml` is ignored. Implementation: [packages/server/src/routes/agent-configs.ts](../../../packages/server/src/routes/agent-configs.ts) `scaffoldModelBlock()`.
+
+**Advanced fold**: on the General page, `language` and `theme` are shown in the open; every other General field is in an "Advanced" area, collapsed by default (schema flag `advanced: true`, set in `generalSection()`).
+
+**Restart-required fields**: `agent.max_retries`, `session.max_queue_size`, `session.max_nesting_depth`, `compact.keep_messages`, `compact.max_summary_input`, `compact.max_message_slice`, `logging.level` and the four `observability.*` keys are read once at server start (object literals in `config.ts`; observability is mapped onto `OTEL_*` env by `initObservability()` at boot). They carry `restartRequired: true`; after a save or Reset of one of them the Settings page shows a notice above the section listing the saved keys and saying the Halo server must be restarted (dismissable; it stays until dismissed). Every other General key is read live.
 
 ### Field attributes
 
 | Attribute | Required | Purpose |
 |---|---|---|
 | `key` | yes | Leaf key under the namespace |
+| `type` | no | `string` (default) / `int` / `float` / `boolean` / `enum` — picks the input widget |
+| `options` / `optionLabels` | no | For `type: enum`: the allowed values, and optional display labels parallel to them |
 | `description` | no | English description rendered as help text |
 | `description_zh` | no | Chinese description (UI picks based on lang) |
-| `default` | no | Placeholder shown when the value is unset; supports `<<ENV>>` |
+| `default` | no | Placeholder shown when the value is unset; supports `<<ENV>>`. For provider / skill / agent fields it is display-only: an unset param's `{{<id>.params.<key>}}` stays literal at substitution, so the consumer applies its own fallback (the `extension` skill's `ext.sh` treats `{{…}}` as "use the default hub"; `web-search`'s `search.py` as "use the default region") |
 | `secret` | no | `true` → masked in API responses + password input in UI |
-| `globalOnly` | no | `true` → read from global settings only; workspace overrides are ignored at runtime. UI disables the workspace input and shows a "global only" hint |
+| `restartRequired` | no | `true` → read once at server start; the Settings page shows a restart notice after saving it. Built-in `general` section only |
+| `advanced` | no | `true` → rendered in the collapsed "Advanced" area. Built-in `general` section only (every field except `language` / `theme`) |
+| `globalOnly` | no | `true` → read from global settings only; workspace overrides are ignored at runtime. UI disables the workspace input and shows a "global only" hint; `PUT` / `PATCH` / `DELETE` of such a key at workspace scope is rejected with 400. Set by the built-in `general` section only — provider / skill / agent yaml declarations don't read it |
 
 ## Scope: global vs. workspace
 
@@ -133,7 +145,8 @@ The value is read once at process start, so unlike other settings it is **not**
 Read order: `<schema default> <- <global> <- <workspace>` (workspace layer applies to namespaced `params` / `secrets` only — see General above).
 
 The Settings page shows source badges per field:
-- `workspace` (green-blue, override applied here)
+- `workspace` (blue, override applied here)
+- `global` (green, value set at the global layer)
 - `inherited from global` (grey, value pulled from global because workspace has none)
 - `unset` (no value at any layer; the `default` is shown as placeholder)
 
@@ -147,7 +160,7 @@ Values can carry `<<ENV_NAME>>` placeholders. They're expanded:
 
 **Trust boundary**: `<<ENV>>` is only expanded inside settings-resolved values. Raw cmd text the agent writes is not scanned — `shell_exec "echo <<HOME>>"` keeps the literal. This prevents an agent from naming an env var and forcing the server to dump it.
 
-Env var unset → the `<<ENV_NAME>>` literal stays verbatim, plus `[md-vars] Env var "X" not set — keeping <<X>> literal` in the server log. The Settings UI returns the literal too — the browser never sees the real env value.
+Env var unset → the `<<ENV_NAME>>` literal stays verbatim, plus `[MdVars] Env var "X" not set — keeping <<X>> literal` in the server log. The Settings UI returns the literal too — the browser never sees the real env value.
 
 ## Agent visibility
 
@@ -169,7 +182,7 @@ A malicious skill that tries `curl -H "Bearer {{aws-bedrock-claude-invoke.secret
 
 ## Orphans
 
-Values present in `settings.yaml` whose namespace doesn't appear in any current schema declaration are surfaced as **orphans** in a dedicated tab. They aren't deleted automatically — uninstalling a skill keeps its values around so re-installing pops them back in. Users prune them on their own schedule via the orphan tab's per-key Remove buttons.
+`params` / `secrets` values present in `settings.yaml` that no current schema declaration covers (the whole namespace is gone, or just that key) are surfaced as **orphans** in a dedicated tab. They aren't deleted automatically — uninstalling a skill keeps its values around so re-installing pops them back in. Users prune them on their own schedule via the orphan tab's per-key Remove buttons.
 
 `general.*` is intentionally excluded from orphan detection — its declared keys are enumerated by the built-in schema, so anything else there is treated as either a typo or a forward-compat field, not an orphan.
 
@@ -177,7 +190,7 @@ Values present in `settings.yaml` whose namespace doesn't appear in any current
 
 A **Security** entry in the left nav (below the System group) opens a page with two cards. Like `__orphans` it's a synthetic nav target, not a schema section — the credential lives in `~/.halo/secrets/config.yaml` (`server.password`, scrypt hash), not `settings.yaml`, and the header shows that path accordingly.
 
-**Change password** — three inputs: current password, new password, confirm. Live client-side feedback while typing: strength rule (≥8 chars, at least one letter and one digit), new ≠ current, confirm matches; the submit button stays disabled until all pass. Submit posts to `POST /api/auth/change-password` (see [dev/api.md](../dev/api.md)) — the server re-runs the same checks authoritatively; a server rejection is shown verbatim under the form. Success shows an inline confirmation and clears all three fields. Existing sessions stay signed in (`jwt_secret` is not rotated). Forgotten password (can't provide the current one) is out of scope here — that's `halo setup`'s reset path.
+**Change password** — three inputs: current password, new password, confirm. Live client-side feedback while typing: strength rule (≥8 chars, at least one letter and one digit), new ≠ current, confirm matches; the submit button stays disabled until all pass. Submit posts to `POST /api/auth/change-password` (see [dev/api.md](../dev/api.md)) — the server re-runs the same checks authoritatively; a server rejection is shown verbatim under the form. Success shows an inline confirmation and clears all three fields. When the password is supplied by the `HALO_PASSWORD` env var the endpoint refuses with 400, since the stored hash is not what login checks. Existing sessions stay signed in (`jwt_secret` is not rotated). Forgotten password (can't provide the current one) is out of scope here — that's `halo setup`'s reset path.
 
 **Log out** — the login state is an httpOnly JWT cookie, so JS can't clear it directly: the button calls `POST /api/auth/logout` (server expires the cookie via Set-Cookie) and reloads; the boot auth check then lands on the login page. This browser only — no server-side token blacklist.
 
@@ -185,7 +198,6 @@ A **Security** entry in the left nav (below the System group) opens a page with
 
 | Operation | Method | Endpoint | Purpose |
 |---|---|---|---|
-| Read merged settings (legacy) | GET | `/api/settings?projectId=xxx` | Raw read, used by older tooling |
 | Read schema + resolved values | GET | `/api/settings/schema?projectId=xxx` | Drives the new Settings page |
 | Replace scope | PUT | `/api/settings` | Bulk replace one yaml file |
 | Patch single key | PATCH | `/api/settings` | Set a leaf at `<dotted-key>` |
@@ -208,7 +220,7 @@ A **Security** entry in the left nav (below the System group) opens a page with
           "kind": "secret",
           "description": "AWS Access Key ID",
           "description_zh": "...",
-          "default": null,
+          "default": "...",                        // omitted when the schema declares none
           "secret": true,
           "value": "AK****ST",
           "hasValue": true,
@@ -237,7 +249,7 @@ A **Security** entry in the left nav (below the System group) opens a page with
 
 ### DELETE body
 
-Same shape minus `value`. Removes the leaf at `key`. For Reset behaviour: workspace scope DELETE → field falls back to global / default; global scope DELETE → field becomes unset.
+Same shape minus `value`. Removes the leaf at `key`. For Reset behaviour: workspace scope DELETE → field falls back to global / default; global scope DELETE → field becomes unset. Like PUT / PATCH it fires the settings-change notification; deleting a key that is already absent is a no-op (no write, no notification). Like PATCH, a `globalOnly` key at workspace scope is rejected with 400 and the file is left untouched.
 
 ## i18n
 
@@ -245,4 +257,4 @@ The admin UI is bilingual (en/zh). Field descriptions are localized via `descrip
 
 ## Config caching
 
-`config.ts` reads `settings.yaml` lazily with mtime-watching: every read stats the file and reparses if the mtime has changed. UI saves bump the mtime, so the server picks up new secrets on the next call without a restart. See [packages/server/src/config.ts](../../../packages/server/src/config.ts) `getSettings()`.
+`config.ts` reads `settings.yaml` lazily with mtime-watching: every read stats the file and reparses if the mtime has changed. UI saves bump the mtime, so the server picks up new secrets, params and most General keys on the next read without a restart. The exceptions are the `restartRequired` General keys (see General above) and `general.goal_mode_enabled`, which are read once at boot — those need a server restart. See [packages/server/src/config.ts](../../../packages/server/src/config.ts) `getSettings()`.

package/bundled-docs/requirements/skill.md

@@ -35,11 +35,11 @@ button is hidden in this mode (`showMaximize={false}`).
 ### Management UI
 
 The Skills sidebar mirrors the Agents sidebar layout:
-- Two collapsible sections — **Global** (globe icon) and **Workspace** (folder icon). Expanded state persists in `halo_skills_expandedScopes` (localStorage)
+- Two collapsible sections — **Global** (globe icon) and **Workspace** (folder icon, shown only while a workspace is open). Expanded state persists in `halo_skills_expandedScopes` (localStorage)
 - Each section header has its own **+ button** — scope is implicit from which button is clicked, no pop-up picker
 - Creating a name that collides with the other scope prompts a one-time confirmation explaining the runtime override
 - Items overridden by a workspace skill are rendered dimmed with "overridden" subtitle
-- Disabled skills are rendered dimmed with "disabled" subtitle and a toggle switch (always visible). Disabled state is stored per workspace in the `disabled_items` table of `halo.db` (not in SKILL.md frontmatter). Both global and workspace skills can be independently toggled per workspace. Disabled skills are excluded from system prompt injection, activate_skill tool, agent form skill picker, and `/workspace share` export.
+- Each row has a toggle switch (shown on hover while enabled, always visible once disabled) and a hover trash button. Disabled skills are rendered dimmed with "disabled" subtitle. Disabled state is stored per workspace in the `disabled_items` table of `halo.db` (not in SKILL.md frontmatter). Both global and workspace skills can be independently toggled per workspace. Disabled skills are excluded from system prompt injection, activate_skill tool, agent form skill picker, and `/workspace share` export.
 - Selection uses a composite `id:scope` key (localStorage `halo_skills_selectedKey`) so the same id in different scopes can coexist
 
 ### Auto-sync behaviour (workspace vs. global)
@@ -73,13 +73,13 @@ Review the code for:
 
 - **Frontmatter** (required): `name` (kebab-case, = directory name) + `description` — injected into the agent system prompt for discovery
 - **Body**: the full instructions, lazily loaded by the agent via `activate_skill`
-- **Optional fields**: `allowed-tools` (space-separated), `metadata` (custom kv), `command` (slash command registration — opt-in, only declared commands exist), `requiresAccess` (one of `full` / `workspace` / `readonly`), `verbs` (Halo extension — subcommand list, each `{ name, builtin?, requiresAccess?, desc? }`; skill verbs' access gates are declared here), `disable-model-invocation` (standard — command exists but skill is not injected for model auto-activation), `user-invocable` (standard — `false` = never a slash command, model can still activate)
+- **Optional fields**: `command` (slash command registration — opt-in, only declared commands exist), `requiresAccess` (one of `full` / `workspace` / `readonly`), `verbs` (Halo extension — subcommand list, each `{ name, builtin?, requiresAccess?, desc? }`; skill verbs' access gates are declared here), `disable-model-invocation` (standard — command exists but skill is not injected for model auto-activation), `user-invocable` (standard — `false` = never a slash command, model can still activate). Other standard fields (`allowed-tools`, `metadata`) are tolerated but not read
 - **Arguments**: user command-line args fill `$ARGUMENTS` / `$1`–`$9` placeholders in the body (quotes respected, `\$` escapes, `$5.00`/`$PATH` untouched); `{{...}}` placeholders (params/channel/workspace_root etc.) carry platform-injected values — the two coexist without cross-translation. A verb reaches the body as `$1` for dispatch; args are no longer appended verbatim to the body end
 
 ### Skill-as-command
 When a `command` field is present (e.g. `command: /review`), the skill auto-registers as a slash command. Users trigger it with `/review`. See [commands](command.md).
 
-If the `command` collides with a built-in slash command (or another skill's `command`), it is dropped from the command list with a warning — built-ins win, then first-come among skills. Only the slash command is lost; the skill stays usable via `activate_skill`. See [conflict detection](command.md#conflict-detection).
+If the `command` collides with a built-in slash command (or another skill's `command`), it is dropped from the command list (a warning is logged when another skill owns the name) — built-ins win, then first-come among skills. Only the slash command is lost; the skill stays usable via `activate_skill`. See [conflict detection](command.md#conflict-detection).
 
 ### Access-level gate (`requiresAccess`)
 

package/bundled-docs/requirements/source-control.md

@@ -19,7 +19,7 @@ The Source Control **activity-bar entry itself is hidden in non-git workspaces**
 Once the entry is shown, the panel resolves to one of these on open, driven by `GET /api/git/status`:
 
 1. **Not a repo** (`{isRepo: false}`) — the folder has no git work-tree at its root (either no repo at all, or it only sits *inside* an ancestor's repo). Shows an **Initialize Repository** empty state. Never a 500/console error — a non-repo folder is a normal state.
-2. **Repo, no remote** — `GET /api/git/remotes` is empty. Shows an **Add Remote** prompt to guide first publish. Adding a remote is a purely local op with **no commit precondition** — a freshly-`init`'d empty repo can set its remote URL right away (not gated behind "must have a commit first", which would be a mis-applied VSCode *Publish* gate).
+2. **Repo, no remote** — `GET /api/git/remotes` is empty. The Changes view shows an **Add Remote** prompt (push/pull buttons hidden) to guide first publish. Adding a remote is a purely local op with **no commit precondition** — a freshly-`init`'d empty repo can set its remote URL right away (not gated behind "must have a commit first", which would be a mis-applied VSCode *Publish* gate).
 3. **Repo with remote** — the full panel: CHANGES list, commit box, history graph.
 
 ### Ancestor-repo guard
@@ -30,7 +30,7 @@ A workspace placed *under* another repo (e.g. a dotfiles `$HOME`, or a monorepo
 - CHANGES section lists every modified/added/deleted/untracked/renamed file, split into **Staged** and **Changes** groups (mirrors the porcelain X/Y status chars).
 - Each row shows a VSCode-style status badge: **M** modified (blue), **A** added / **U** untracked (green), **D** deleted (red), **R** renamed / **C** copied (blue), **U→Conflict** unmerged (red).
 - Stage / unstage individual files or all at once (`POST /api/git/stage` · `unstage`).
-- Click a file → opens a **Monaco side-by-side diff** (`GET /api/git/diff`); original side is HEAD (or the rename's old path), modified side is the working/staged copy. Binary files show git's "Binary files differ" rather than crashing.
+- Click a file → opens a **Monaco side-by-side diff** (`GET /api/git/diff`); original side is HEAD (or the rename's old path), modified side is the working/staged copy. There is no binary special case: both sides are read as UTF-8 text (`git show` / the working-tree file), so a binary file opens as garbled text rather than a "Binary files differ" notice.
 - **Single-file discard is intentionally omitted** — it's an "operation", not a "view". Use the command line (`git checkout`).
 
 ## Commit & sync
@@ -39,6 +39,7 @@ A workspace placed *under* another repo (e.g. a dotfiles `$HOME`, or a monorepo
 - **Push** (`POST /api/git/push`): first push of an untracked branch sets upstream automatically (`-u origin <branch>`).
 - **Push failure is surfaced as a friendly red banner**, never a raw leak. A missing-credentials push (`fatal: could not read Username for 'https://...'`) is detected and rephrased into a "configure credentials" guide rather than dumping git's stderr.
 - Pull (`POST /api/git/pull`).
+- The branch row shows the current branch plus **ahead / behind** counts against its upstream (↑N / ↓N, from `GET /api/git/status`; hidden when both are 0), next to the Pull / Push buttons (shown only once a remote exists).
 
 ## Auto-refresh (no polling)
 
@@ -80,4 +81,4 @@ The file tree colors and badges files by git status (VSCode-style), driven by th
 
 ## Out of scope (this round)
 
-Branch create / switch / merge, ahead/behind indicator, AI-generated commit messages, clone, merge-conflict resolution UI, stash, worktree, timeline, PR management, the **DAG rail graph** (branch fork/merge visualization), and single-file discard. The DAG graph + ahead/behind are deferred to the branch-operations round, where they have live branch actions to feed them — standalone they're decoration, not a viewing need.
+Branch create / switch / merge, AI-generated commit messages, clone, merge-conflict resolution UI, stash, worktree, timeline, PR management, the **DAG rail graph** (branch fork/merge visualization), and single-file discard. The DAG graph is deferred to the branch-operations round, where it has live branch actions to feed it — standalone it's decoration, not a viewing need.