@turmind/halo 0.1.9

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

@@ -0,0 +1,149 @@
+# Web
+
+Talk to a halo agent over plain HTTP from any client you control — a browser, a curl script, a custom frontend, your own mobile app. The Web channel is the "build your own UI" channel: it gives you a token, you give the token to whatever client you wrote.
+
+> If you want a ready-made browser frontend without writing code, halo ships `packages/web-demo` — a tiny Express app that wraps the Web channel with its own password gate. See "Standalone web-demo frontend" at the bottom.
+
+## What you'll end up with
+
+- A 24-byte random token (base64url-encoded) bound to one workspace
+- A few public HTTP endpoints under `/api/web/*` that accept that token
+
+The token is **the** credential — anyone holding it can talk to the agent at the bound workspace's access level. Treat it like a password.
+
+## Step 1 — Create an account
+
+Open halo admin → **Channels** → **Web** → **Add Account**:
+
+| Field | Value |
+|---|---|
+| Workspace path | absolute path, e.g. `/home/ubuntu/my-project` |
+| Label | optional |
+| Access level | `readonly` (default), `workspace`, or `full` |
+| Language | `en` or `zh` |
+
+Click **Create**. The success screen shows the auto-generated token **once** — copy it now, you can't retrieve it again. (You can always delete the account and create a new one if you lose the token.)
+
+## Step 2 — Use the token
+
+All public endpoints require an `x-token: <token>` header (or `?token=<token>` query for endpoints that can't easily set headers, like SSE in browsers).
+
+### Send a message (SSE stream back)
+
+```bash
+curl -N -H "x-token: $TOKEN" -H "Content-Type: application/json" \
+  -d '{"message":"hello"}' \
+  http://localhost:9527/api/web/chat
+```
+
+Response is a stream of `data: {json}\n\n` SSE frames:
+
+```
+data: {"type":"session","sessionId":"web_abc123_m1xyz"}
+data: {"type":"thinking","text":"..."}
+data: {"type":"tool_call","toolName":"file_read","toolInput":{...}}
+data: {"type":"tool_result","toolName":"file_read","result":"..."}
+data: {"type":"stream","text":"Hello! "}
+data: {"type":"stream","text":"How can I help?"}
+data: {"type":"complete"}
+```
+
+Parse the `type` field on each event to render text vs tool calls vs completion.
+
+### Other endpoints
+
+| Method | Path | Purpose |
+|---|---|---|
+| `POST /api/web/chat` | Send a message; SSE response |
+| `POST /api/web/stop` | Cancel the running task |
+| `GET /api/web/history` | Fetch session message history |
+| `GET /api/web/subscribe` | Reconnect to a running session's SSE stream |
+
+All four accept the same auth header.
+
+### Per-request overrides
+
+By default each token is locked to the workspace and active session set by the admin. External integrations (notably the [ACP adapter](acp.md)) need finer control:
+
+- `workspace` — server-side absolute path, **gated on `accessLevel === 'full'`** (readonly / workspace tokens can't escape their bound workspace; the override is rejected)
+- `sessionId` — explicit halo session id; lets clients pre-mint stable ids and address them across reconnects
+- `agentId` — only used when the request creates a new session
+
+These can be passed as POST body fields, headers (`x-workspace`, `x-session-id`, `x-agent-id`), or query params (`?workspace=…&sessionId=…&agentId=…`). POST body wins on conflict.
+
+For browser apps you almost never want these — leave them off and use the per-token defaults.
+
+## Step 3 — Send images / files
+
+`/api/web/chat` accepts an optional `images` array, base64-encoded:
+
+```json
+{
+  "message": "what's in this picture?",
+  "images": [
+    { "data": "<base64>", "mimeType": "image/png" }
+  ]
+}
+```
+
+Images go to the LLM as multimodal content. Audio and other binary uploads aren't supported on this endpoint directly — for those, save the file to `<workspace>/.halo/assets/web/inbound/<accountId>/<date>/` first (out-of-band) and reference its path in your message text.
+
+The standalone web-demo handles voice + arbitrary files for you; if you want that, use it as a reference implementation.
+
+## Slash commands
+
+Slash commands are intercepted before they reach the agent — same set as every other channel:
+
+| Command | Effect |
+|---|---|
+| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` |
+| `/agent <verb>` | Manage agents (`list` / `switch` / `desc` open to all; `delete` full; `create` / `update` via skill, full) |
+| `/skill <verb>` | Manage skills (`list` / `desc` open; `disable` / `enable` workspace; `delete` full; `create` / `update` via skill, full) |
+| `/workspace <verb>` | Workspace: `info` (all) / `switch <path>` (full) / `setup` / `tidy` (workspace) / `share` (full) |
+| `/help` | List commands — object commands show only the verbs you can run |
+
+Send a slash command exactly like a normal message — the server detects the leading `/`.
+
+## Common problems
+
+| Symptom | Cause / fix |
+|---|---|
+| `401` on every call | Missing `x-token` header, or token is for a deleted account |
+| `403` when passing `workspace=…` | Token is `readonly` / `workspace` access — only `full` can override |
+| SSE stream hangs forever | Reverse proxy buffering. Disable buffering for `text/event-stream` (nginx: `proxy_buffering off`, Cloudflare: enable streaming) |
+| Token leaked accidentally | Delete the account in admin, create a new one. The old token is invalidated immediately |
+| Want to share one token across multiple users | Don't — every request would land on the same active session. Create one account per user / app |
+
+## Standalone web-demo frontend
+
+If you want a browser UI with login, image upload, voice recording, and multi-language support without writing it yourself:
+
+```bash
+cd packages/web-demo
+node server.js
+```
+
+Environment variables:
+
+| Variable | Required | Description |
+|---|---|---|
+| `HALO_API` | yes | Halo server URL, e.g. `http://localhost:9527` |
+| `HALO_TOKEN` | yes | The web-channel token from Step 1 |
+| `HALO_WEB_DEMO_PASSWORD` | no | Password gate; empty means open access |
+| `PORT` | no | Listen port; default `9528` |
+
+The demo holds your token server-side and exposes its own password-based session — the browser never sees the halo token. Open `http://localhost:9528` to use it.
+
+## Security notes
+
+- **Tokens are unhashed** in `~/.halo/secrets/channels/channels.db`. Restrict that file to the user that runs halo
+- **No rate limit at the channel level** — if you expose the API on the public internet, put a reverse proxy with rate limits in front
+- **Admin endpoints** (`POST /api/web/accounts`, `PATCH`, `DELETE`) require admin cookie auth, **not** the token. They're for the admin panel, not for the token holder
+- A `full`-access token can call `/workspace <abs-path>` to switch the bound workspace database-side. If you don't want that, give out `workspace` or `readonly` tokens instead
+
+## Reference
+
+- Code: `packages/server/src/channels/web/`
+- Routes: `packages/server/src/routes/web.ts`
+- Admin UI: `packages/admin/src/features/web/web-settings.tsx`
+- Design notes: [../../design/web.md](../../design/web.md)

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

@@ -0,0 +1,110 @@
+# WeChat (微信)
+
+Talk to a halo agent from WeChat on your phone. Halo registers an **iLink-style bot** with `ilinkai.weixin.qq.com` and you bind it by **scanning a QR code with WeChat** — no developer registration, no public webhook needed.
+
+> The iLink bot is a personal-account bot, not a Public Account / Mini Program. The bot you scan-bind to is the account you'll DM in WeChat — there's no separate "follow this bot" step.
+
+## What you'll end up with
+
+- A bot account row keyed by your WeChat user id (the one that scanned the QR)
+- An `ilinkai` long-poll loop pulling messages on behalf of that bot
+- Bot owner = whoever scanned the QR. The same WeChat ID is used as the default cron-job recipient
+
+## Step 1 — Create a workspace folder
+
+You need an existing absolute path on the server before scanning. Either:
+
+- Open the workspace in halo's web UI (the `.halo/` folder gets auto-created), then copy the absolute path
+- Or `mkdir -p /home/ubuntu/my-project` from a terminal
+
+Halo auto-creates `.halo/` inside the folder if it doesn't exist; the path itself must already exist.
+
+## Step 2 — Open the admin scan flow
+
+Open halo admin → **Channels** → **WeChat** → **Add Account**.
+
+The form is **just the workspace + label + access level + language** — no bot token field, because the token comes from the scan:
+
+| Field | Value |
+|---|---|
+| Workspace path | absolute path from Step 1, e.g. `/home/ubuntu/my-project` |
+| Label | optional, shown in admin's account list |
+| Access level | `readonly` (default), `workspace`, or `full` |
+| Language | `en` or `zh` |
+
+Click **Generate QR**. Halo hits `ilinkai.weixin.qq.com` to mint a fresh QR code and starts a poll loop waiting for the scan.
+
+## Step 3 — Scan with WeChat
+
+1. Open WeChat on your phone
+2. Tap the `+` in the top right → **Scan / 扫一扫**
+3. Aim at the QR shown in the admin UI
+4. Tap **Confirm Login / 确认登录** on the phone
+
+Within a few seconds the admin UI shows "登录成功" / "Logged in" and switches to the success page. Behind the scenes:
+
+- iLink returns the bot's token, the IDC-specific `baseUrl`, and your WeChat-side `ilink_user_id`
+- Halo writes those into the new account row
+- The long-poll loop starts immediately — the bot is now live
+
+The QR is valid for ~3 minutes; if it expires the admin UI auto-refreshes. If you cancel and come back later, just open the form again — a new QR is minted.
+
+## Step 4 — Test it
+
+The bot's name in your WeChat contacts is whatever the iLink platform set it to (typically a generic placeholder like `小助手`; you can rename it locally). Open the bot's chat in WeChat and send `hello` → expect a streamed reply.
+
+If nothing happens, check halo server logs for `[weixin]` lines.
+
+## How halo handles inbound
+
+- **Text** — sent to the agent
+- **Images** — passed to the LLM as multimodal content
+- **Voice** — decrypted, saved under `<workspace>/.halo/assets/weixin/inbound/<accountId>/<date>/`, path included in the agent's input
+- **Video / files** — same as voice
+- **Group chats** — not supported in v1 (group messages are dropped)
+- **Self-loop** — bot-authored messages are filtered out
+
+## Slash commands
+
+Same set as the other channels — type as plain text in your WeChat DM with the bot:
+
+| Command | Effect |
+|---|---|
+| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` |
+| `/agent <verb>` | Manage agents (`list` / `switch` / `desc` open to all; `delete` full; `create` / `update` via skill, full) |
+| `/skill <verb>` | Manage skills (`list` / `desc` open; `disable` / `enable` workspace; `delete` full; `create` / `update` via skill, full) |
+| `/workspace <verb>` | Workspace: `info` (all) / `switch <path>` (full) / `setup` / `tidy` (workspace) / `share` (full) |
+| `/help` | List commands — object commands show only the verbs you can run |
+| `/qr [level]` | Generate an invite QR (admin only) |
+
+## Cron jobs targeting WeChat
+
+WeChat is single-recipient — cron output goes to the QR-bind owner (the WeChat user who scanned in Step 3). The dispatcher resolves recipients in this order:
+
+1. Explicit `chatId` on the cron target row (set when the cron is created from inside WeChat)
+2. The QR-bind owner (`account.userId`) — the "report to me on a schedule" default
+3. Most-recent inbound chat ID, as a fallback for shared bots
+
+Fan-out across multiple WeChat users is not supported — one bot, one owner.
+
+## Common problems
+
+| Symptom | Cause / fix |
+|---|---|
+| QR shows but scan does nothing | iLink platform thinks the QR is for a different account. Cancel and regenerate |
+| "二维码已过期" / QR expired | Admin UI should auto-refresh. If not, click Generate again |
+| Bot stops responding after a few hours | Long-poll likely lost its `syncBuf`. Restart the server; reconnect is automatic |
+| Two halo processes both poll the same bot | Each process gets a copy of every message, replied twice. Make sure only one server runs — see `~/.halo/global/server.pid` |
+| Group chat doesn't trigger the bot | Expected — groups aren't supported in v1 |
+| Sent voice message returns no reply | Check that the account has `workspace` or `full` access; readonly cannot save inbound media |
+
+## Multi-workspace / multi-bot
+
+Each scan = one account = one workspace binding. To use a second workspace, open the admin form again and scan a second time (with the same WeChat user or a different one). Each scan mints a fresh `ilink_bot_id` even from the same WeChat account, so the two are independent.
+
+## Reference
+
+- Code: `packages/server/src/channels/wechat/`
+- Login flow: `packages/server/src/channels/wechat/login.ts`
+- Admin UI: `packages/admin/src/features/weixin/weixin-settings.tsx`
+- Design notes: [../../design/wechat.md](../../design/wechat.md)

package/bundled-docs/guide/chat.md

@@ -0,0 +1,112 @@
+# Chat — User Guide
+
+The Chat panel at the bottom is the main surface for talking to an agent.
+
+## Picking an agent
+
+The dropdown to the left of the input lists every agent (global + workspace).
+
+- The agent with the highest `priority` is auto-selected for new sessions. The seed `Default` agent uses `priority: 99`, so it wins until you raise another agent above it.
+- Once you manually pick an agent, that choice is remembered across `clear` / new sessions until you pick something else.
+- **A conversation is locked to one agent**: once you start chatting, the dropdown locks. To change agent, start a new session (`/session new`).
+
+## Sending messages
+
+- Enter to send
+- Shift+Enter for a newline
+- The agent streams its reply; tool calls render inline as cards
+
+## Context injection
+
+Next to the chat is a `📎 Context` toggle (on by default). When on, Halo auto-injects:
+- The currently open file path: `[Currently viewing: src/foo.ts]`
+- The editor's current selection: `[Selected text in foo.ts:10-25]\n\`\`\`...\n\`\`\``
+
+Turn it off if you don't want that context injected.
+
+## `@` file mention
+
+Typing `@` in the input opens a file search:
+- Real-time fuzzy matching (150 ms debounce)
+- Selecting inserts a path chip
+- You can `@` multiple files back-to-back
+
+The search scans the whole project on the server — independent of Explorer expansion state.
+
+## Attachments
+
+- **Drag**: drop files onto the input
+- **Paste**: paste an image from the clipboard
+- **Button**: click the 📎 on the left
+
+Images are sent to the agent as base64, with multimodal support (Claude 4.6 can see images).
+
+## Slash commands
+
+Typing `/` opens autocomplete.
+
+Most commands are noun-verb **object commands**: `/<obj> <verb> [args]`. Bare `/<obj>` (or `/<obj> help`) lists the verbs you're allowed to run.
+
+| Command | Purpose |
+|---|---|
+| `/session <verb>` | Manage sessions — `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context`. All built-in, available to everyone. `new` starts a fresh conversation (old session stays in the sidebar; running sub-agents keep going); `compact` keeps the most recent N messages intact (N defaults to 5, `general.compact.keep_messages`); `context` shows token usage, agent info, and available tools |
+| `/clear` | Admin-UI alias for `/session new` |
+| `/agent <verb>` | Manage agents — `list` / `switch <name\|index>` / `desc` (built-in, open to all) · `delete` (built-in, full access) · `create` / `update` (handled by the `agent` skill, full access) |
+| `/skill <verb>` | Manage skills — `list` / `desc` (built-in, open to all) · `disable` / `enable` (built-in, workspace access) · `delete` (built-in, full access) · `create` / `update` (handled by the `skill` skill, full access) |
+| `/workspace <verb>` | Manage the workspace — `info` (built-in, open to all) · `switch <path>` (built-in, full access) · `setup` / `tidy` (workspace skill, workspace access; init / reorganize `.halo/` INDEX.md / INSTRUCTIONS.md / memory/) · `share` (workspace skill, full access; export a shareable bundle) |
+| `/cron <verb>` | Scheduled agent runs — `create` / `list` / `update` / `enable` / `disable` / `delete` (cron skill, full access) |
+| `/acp <verb>` | Talk to other agents over ACP — `kiro <q>` / `claude <q>` ask a local agent directly; `add` / `list` / `remove` manage generated `ask-<label>` bindings (acp skill, full access) |
+| `/evo [hint]` | Queue a self-evolution run on this session (full access only) |
+| `/help` | List every command — object commands only show the verbs you can run |
+
+Skills can also register slash commands (put `command: /xxx` in the SKILL.md frontmatter).
+
+### WeChat channel commands
+
+If you're chatting from WeChat, the same shared commands are available (routed through the common command dispatcher), plus one WeChat-specific extra:
+
+| Command | Purpose |
+|---|---|
+| `/session new` | Create a new session; old sessions stay accessible via `/session list` + `/session switch` (nothing is archived) |
+| `/session list` | List recent sessions (newest first); the active one is marked `→` |
+| `/session switch <index>` | Switch the active session to the indexed one (readonly bot 仅能切到自己的 [我] 会话) |
+| `/workspace info` / `/workspace switch <path>` | Show or switch workspace (absolute path; 切换仅 full 权限 bot 可用) |
+| `/qr [level]` | Generate an invite QR for a new bot account (full 权限 bot 专用) |
+| `/help` | Show help |
+
+If the session is currently compacting or busy when your message arrives, you'll see a hint — ("⏳ integrating context…" / "🔄 queued…") — and the message is queued (while compacting it's dropped; while busy it's kept).
+
+## Interrupt vs Stop
+
+Two ways to interrupt the agent:
+
+**Graceful interrupt**: send another message during streaming. The message is queued on the server; at the next tool-call checkpoint, the agent wraps up the current turn and then runs the queued message. Multiple messages can queue in order.
+
+**Hard stop**: click the red ⏹ button. Immediate abort, queue cleared, no checkpoint waiting.
+
+## Token ring
+
+The ring in the bottom-right of the input shows context window usage:
+- Green: < 50%
+- Yellow: 50–70%
+- Orange: 70–90%
+- Red: > 90%
+
+Reaching `compressAt` (default 70%) auto-triggers compact. While the agent is running you can't click the TokenRing (guarded by `isStreaming`).
+
+## Session history
+
+Next to the header is the session-list dropdown:
+- Lists every session in the current workspace
+- Click to switch (the current one auto-saves + detaches)
+- Sub-agent sessions show as indented entries
+
+For full inspection, use the Activity Bar's "Sessions" tab — Debug mode lets you inspect tool calls, system prompts, usage, etc.
+
+## Common situations
+
+**"Queued" hint**: the previous turn hasn't finished; your message is queued and will run next turn.
+
+**"Rate limited, retrying in Xs..."**: Bedrock throttled; automatic exponential backoff (up to 5 retries).
+
+**A sudden `[Message from xxx]`**: a sub-agent finished and auto-reported back to the parent agent's conversation.

package/bundled-docs/guide/cli.md

@@ -0,0 +1,197 @@
+# CLI / TUI
+
+Standalone terminal client for Halo. Runs the agent loop directly in the CLI process — no server required. Shares the same agent core, tools, session management, and command system as the admin panel and other channels.
+
+## Installation
+
+```bash
+pnpm --filter @turmind/halo-cli build
+```
+
+The binary is at `packages/cli/bin/halo.js`. For global access, link it:
+
+```bash
+pnpm --filter @turmind/halo-cli link --global
+```
+
+### Publishing to npm (maintainers)
+
+The published package is `@turmind/halo` — a self-contained esbuild bundle
+(CLI + server + admin-out + templates), staged under `packages/cli/dist-pub/`
+by `scripts/build-bundle.mjs`. The workspace `@turmind/halo-cli` can't be
+published directly (it has `workspace:*` deps); the bundle flattens them.
+
+```bash
+# 1. bump packages/cli/package.json "version" (e.g. 0.1.2)
+# 2. build the upstream artifacts the bundle consumes
+pnpm --filter @turmind/halo-core build
+pnpm --filter @turmind/halo-server build
+cd packages/admin && npx next build --no-lint && node scripts/copy-monaco.mjs && cd ../..
+# 3. stage the release bundle — HALO_RELEASE=1 stamps the bare version
+#    (0.1.2), NOT the default <version>-<sha>: a `-<sha>` suffix is a semver
+#    prerelease that `npm install` skips and never tags as `latest`.
+HALO_RELEASE=1 node packages/cli/scripts/build-bundle.mjs
+# 4. preview + publish
+cd packages/cli/dist-pub
+npm pack --dry-run        # inspect tarball contents
+npm publish               # @turmind/halo@<version>, tag latest, public
+```
+
+npm versions are immutable — a published version can never be overwritten,
+so bump first and verify with `npm pack --dry-run` before `npm publish`.
+End users then install with `npm install -g @turmind/halo`.
+
+## CLI Mode (non-interactive)
+
+Run a one-shot prompt and exit:
+
+```bash
+halo "review this PR"
+halo -w /path/to/workspace "analyze code"
+echo "review the changes" | halo
+cat prompt.txt | halo -w /path/to/review-ws
+```
+
+### Options
+
+| Flag | Short | Default | Description |
+|---|---|---|---|
+| `--workspace` | `-w` | cwd | Workspace path |
+| `--agent` | `-a` | `default` | Agent ID |
+| `--session` | `-s` | auto | Resume session by ID |
+| `--format` | `-f` | `text` | Output format: `text` or `json` |
+| `--verbose` | `-v` | off | Show thinking, tool calls, usage on stderr |
+| `--access` | | `full` | Access level: `full`, `workspace`, `readonly` |
+| `--agents` | | | List available agents and exit |
+| `--sessions` | | | List recent sessions and exit |
+| `--lang` | | `en` | Language: `en` or `zh` |
+
+### Output
+
+- **text format**: Agent response is rendered as styled markdown (headings, bold, code blocks, tables) on stdout. Tool calls, thinking, usage go to stderr (visible with `-v`).
+
+  Usage line mirrors the admin chat-panel badge format (timestamp / in / out / ctx / read / write / cache% / ttft / e2e / think / model). `ctx` is the rolled-up context size — `inputTokens + cacheRead + cacheWrite + outputTokens` — so it doesn't look misleading next to a large cache hit:
+
+  ```
+  [ 17:23:02  in 0.0K  out 0.1K  ctx 5.8K  read 5.3K  write 0.3K  cache 94%  e2e 3.3s  think medium  claude-sonnet-4-6 ]
+  ```
+- **json format**: Single JSON object on stdout after completion:
+
+```json
+{
+  "text": "...",
+  "sessionId": "cli_abc123",
+  "toolCalls": [{ "name": "file_list", "durationMs": 1 }],
+  "usage": { "inputTokens": 6, "outputTokens": 42, "cacheReadInputTokens": 10000, "modelId": "..." },
+  "error": null
+}
+```
+
+### Pipeline integration
+
+```bash
+# Code review in CI
+halo -w /path/to/review-ws "review the diff" --format json | jq '.text'
+
+# Pipe content in
+git diff HEAD~1 | halo -w /path/to/review-ws "review this diff"
+
+# Exit code: 0 = success, 1 = error, 130 = SIGINT
+halo "check for issues" && echo "OK" || echo "FAILED"
+```
+
+## TUI Mode (interactive)
+
+```bash
+halo -i
+halo -i -w /path/to/workspace
+halo -i -s sid_abc123   # resume session
+```
+
+Multi-turn conversation. Supports all standard Halo slash commands:
+
+| Command | Description |
+|---|---|
+| `/help` | Show available commands |
+| `/session new` | Start a new session |
+| `/session list` | List recent sessions |
+| `/session switch <n>` | Switch to session by number |
+| `/session stop` | Stop current agent task (ends the turn, no re-run) |
+| `/session interrupt` | Interrupt the running turn now (aborts a command mid-run); any messages queued while busy then run as one follow-up turn |
+| `/session compact` | Compact session context |
+| `/session context` | Show context window + agent info |
+| `/agent <verb>` | Manage agents: `list` / `switch <name\|index>` / `desc` / `delete` / `create` / `update` |
+| `/skill <verb>` | Manage skills: `list` / `desc` / `disable` / `enable` / `delete` / `create` / `update` |
+| `/workspace info` | Show current workspace |
+| `/workspace switch <path>` | Switch workspace (full access only) |
+| `/workspace setup` / `/workspace tidy` / `/workspace share` | Set up / tidy the `.halo/` knowledge files, or export a shareable bundle (workspace skill) |
+| `/cron <verb>` | Manage scheduled agent runs: `create` / `list` / `update` / `enable` / `disable` / `delete` |
+| `/acp <verb>` | Ask other agents over ACP (`kiro <q>` / `claude <q>`) and manage `ask-*` bindings (`add` / `list` / `remove`) |
+| `/evo [hint]` | Queue a self-evolution run on this session (full access only) |
+| `/quit` | Exit |
+
+Bare `/<obj>` (or `/<obj> help`) lists the verbs you may run. Verbs gated above your access level are hidden.
+
+### Keybindings
+
+| Key | Action |
+|---|---|
+| `Esc` (while running) | Interrupt the current turn immediately — aborts a command mid-execution, then any messages typed while it was running are folded into one follow-up turn. Same as `/session interrupt`. |
+| `Ctrl+C` | Graceful exit; press twice to force |
+| `Ctrl+O` | Toggle the sub-agent navigator — lists every sub-agent spawned this session, each showing its agent name, task title (same as the session list), and status (`●` running green / `○` idle grey / `✕` stopped red, plus a `▢ archived` marker when the session is archived); `↑↓` to move, `Enter` to view that sub-agent's log, `Esc`/`q` to close. (Was `Shift+Tab`, but Windows terminals consume that as backtab.) The log viewer auto-refreshes while the viewed session is still running (a `● live` hint shows in the header) and follows the bottom as new output lands — unless you've scrolled up to read, in which case it stays put (`G` jumps back to the bottom and resumes following). |
+| `↑` / `↓` | Walk input history (when no popup is open) |
+
+On resume (`-s <id>`, or the default latest session), the TUI replays the session's prior conversation on screen so you see where you left off. `shell_exec` output is shown inline by default (other tools' output needs `-v`).
+
+## File, Image, and Scope References
+
+Attach files or images to your message with `@file` and `@image`, or pull a directory's instructions into the turn with `@scope`:
+
+```
+> summarize @file src/index.ts
+> compare @file a.ts and @file b.ts
+> describe @image screenshot.png
+> review @file "path with spaces/readme.md"
+> @scope packages/server refactor the session manager
+```
+
+- `@file path` — reads the file and inlines its content in the message as `<file>` block
+- `@image path` — reads the image as base64 and sends it via the model's vision input
+- `@file photo.png` — image extensions (`.png`, `.jpg`, `.gif`, `.webp`, `.bmp`) are auto-detected as images
+- `@scope dir` — injects the directory-scoped `.halo/INSTRUCTIONS.md` along the path from the workspace root down to `dir` (root level excluded — it's already in the system prompt) into **this turn only**. Use it to bring a sub-directory's conventions into scope for one request. It does not change where tools run.
+- Paths are relative to the workspace; absolute paths also work
+- Quoted paths supported for filenames with spaces: `@file "my file.txt"`
+- **Tab completion** in TUI mode: type `@file ` (or `@scope `, which lists directories only) then press Tab to browse
+
+### Limits
+
+- **Text files**: truncated at 100KB with a `[truncated]` marker
+- **Images**: skipped if larger than 5MB
+- If the current model does not support vision, a warning is shown and images are ignored
+
+## Architecture
+
+```
+packages/cli/
+  src/
+    index.ts        — Entry: arg parsing, mode dispatch, SIGINT handling
+    harness.ts      — Shared agent harness wrapping SessionManager
+    cli.ts          — Non-interactive: stdin/args → agent → stdout → exit
+    tui.ts          — Interactive: readline loop + event display + commands
+    format-usage.ts — Usage-line formatter (mirrors admin UsageLine badge order)
+    resolve-refs.ts — @file / @image reference resolution with size limits
+    render-md.ts    — Terminal markdown rendering (marked + marked-terminal)
+```
+
+The CLI directly imports server agent-core modules (`SessionManager`, `dispatchCommand`, tools, config, DB) via `@turmind/halo-server/*` subpath exports. No HTTP/WS layer is involved.
+
+Session prefix: `cli_`. Sessions are persisted to `<workspace>/.halo/sessions/` and visible in the admin panel.
+
+### Initialization
+
+The CLI replicates the server's init sequence:
+1. `initLogger()` — redirect console to stderr + file logger
+2. `ensureHaloHome()` — ensure `~/.halo/` structure
+3. `initBwrapCheck()` — probe sandbox availability
+4. `setSandboxHiddenPaths()` — configure sandbox paths
+5. `new SessionManager(workspace)` — create agent session manager

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

@@ -0,0 +1,93 @@
+# Getting Started
+
+What to do the first time you open Halo.
+
+## Log in
+
+Open `http://localhost:9527` (or your deployment URL) in a browser and enter the password.
+
+- The default password is printed to the **server console** (auto-generated if you haven't set `HALO_PASSWORD`)
+- You can also pin a password via `server.password` in `~/.halo/secrets/config.yaml`
+
+## Open a workspace
+
+After login, you land in the workspace. A URL with `?folder=/abs/path` opens that directory directly; without `?folder`, Halo falls back to your home directory as the workspace — everything still works.
+
+The Explorer top bar has two ways to switch workspace:
+- **Type an absolute path** + Enter — invalid paths raise an error
+- **Click the 📁🔍 button** — opens a VS Code-style directory picker: single click to select, double click to enter, ArrowUp to go up, 🏠 for home, paste paths into the top input
+
+Halo auto-creates a `.halo/` subdirectory in the target folder (for sessions, agents, skills, memory). If `.halo/` already exists, opening the folder just works.
+
+## First conversation (bootstrap)
+
+The first time a new user chats with the Default agent, the agent asks a few questions:
+- What should I call you?
+- What would you like to call me?
+- Preferred communication style (formal/casual, English/other language, etc.)
+
+Your answers are written to `~/.halo/global/USER.md`; from then on every root agent reads that user profile.
+
+> Don't want the bootstrap flow? Create `~/.halo/global/USER.md` manually (any content) and the agent will skip the guided flow.
+
+### Workspace onboarding
+
+The global `INSTRUCTIONS.md` template explains Halo's `.halo/` conventions (`INDEX.md`, `INSTRUCTIONS.md`, `memory/`). When the current workspace has no `INDEX.md`, the system prompt also nudges the agent to offer drafting one from the README / package.json. If you want a guided setup, type `/workspace setup`; to clean up an existing workspace later, type `/workspace tidy` — both backed by the `workspace` skill (setup: interview + draft; tidy: review + prune + reshape).
+
+## Send a message
+
+In the bottom Chat panel:
+1. Type in the input
+2. Enter to send (Shift+Enter for newline)
+3. The agent streams its reply, showing text + tool call cards
+
+You can keep typing while it replies — messages queue and run at the next safe checkpoint.
+
+**Stop button** (red): interrupt immediately, no checkpoint waiting.
+
+## Handy shortcuts
+
+| Action | Shortcut / Method |
+|---|---|
+| File mention | Type `@` in the input, pick a file |
+| Slash command | Type `/`, auto-complete pops up (`/session`, `/agent`, …) |
+| Quick find file | `Cmd/Ctrl+P` |
+| Save file | `Cmd/Ctrl+S` |
+| New conversation | `/session new` |
+| Compact context | `/session compact` |
+| Set up / reorganize workspace | `/workspace setup` / `/workspace tidy` |
+
+## What `~/.halo/` looks like
+
+After `halo setup`:
+
+```
+~/.halo/
+├── global/                   ← server-managed, see overwrite policy below
+│   ├── INSTRUCTIONS.md       ← refreshed on upgrade
+│   ├── prompts/{bootstrap,all,root}/   ← refreshed on upgrade
+│   ├── models/<provider>.yaml          ← refreshed on upgrade
+│   ├── docs/                 ← refreshed on upgrade (bundled platform docs)
+│   ├── agents/               ← built-in ids refreshed; user-added ones untouched
+│   └── skills/               ← built-in ids refreshed; user-added ones untouched
+└── secrets/                  ← never overwritten after first creation
+    ├── config.yaml           ← leaf-merged: new server knobs added, existing values kept
+    ├── settings.yaml         ← created empty if missing; otherwise untouched
+    └── channels/channels.db  ← per-channel account state
+```
+
+**When does "refreshed on upgrade" actually run?** `halo setup` always re-runs the seed; the server's startup check also re-runs it automatically when `~/.halo/global/.template-version` is behind the bundled `TEMPLATE_VERSION`. So the routine flow `halo upgrade && halo server restart` is enough — no need to remember `halo setup`.
+
+**Server-refreshed**: `INSTRUCTIONS.md`, `prompts/`, `models/`, `docs/`, the built-in agent ids (`default`, `executor`, `deep-executor`, `__evo_agent__`, `__score__`, `__apply_agent__`), and the built-in skill ids (`agent`, `skill`, `workspace`, `cron`, `acp`, `send-file`, `self`, `aws-knowledge`, `nova-web-search`, `halo`). To customize one, copy it into the workspace scope (`<project>/.halo/...`) — workspace replaces global at runtime.
+
+**Never overwritten**: anything else under `agents/` or `skills/` (your own creations), and everything under `secrets/`.
+
+**`secrets/config.yaml`** is leaf-merged on each refresh — new keys introduced by a server upgrade are added, your existing `value`s (password, port, jwt_secret) are kept.
+
+## Next
+
+- [chat.md](chat.md) — everything the chat panel does
+- [agents.md](agents.md) — managing agents
+- [skills.md](skills.md) — what skills are and how to use them
+- [sessions.md](sessions.md) — viewing session history, debugging
+- [workspace.md](workspace.md) — the overall interface