@turmind/halo 1.5.3-alpha → 1.5.5

package/bundled-docs/dev/api.md

@@ -105,13 +105,14 @@ Unified session log API — list + read session files across all agents.
 
 | Method | Path | Purpose |
 |---|---|---|
-| GET | `/api/sessions/logs?projectId=` | List session metadata, keyset-paginated. Default returns each top-level row + all descendants (sidebar tree); `rootOnly=1` returns roots only (chat-panel session tabs). Each row carries `status` (`running` also while a sub-session runs). A `projectId` with no `.halo/` (plain or missing directory) returns `{sessions: [], nextCursor: null}` without scaffolding it — a list never turns a directory into a workspace |
+| GET | `/api/sessions/logs?projectId=` | List session metadata, keyset-paginated. Default returns each top-level row + all descendants (sidebar tree); `rootOnly=1` returns roots only (chat-panel session tabs). A `projectId` with no `.halo/` (plain or missing directory) returns `{sessions: [], nextCursor: null}` without scaffolding it — a list never turns a directory into a workspace |
 | GET | `/api/sessions/logs/:id?projectId=` | Full session log (scans across agent dirs) — the **active** file only; archived history is a separate call |
 | GET | `/api/sessions/logs/:id/archive/:n?projectId=` | One archived UI-log segment — see [detail](#get-apisessionslogsidarchivenprojectidabs) |
-| DELETE | `/api/sessions/logs/:id?projectId=` | Delete the session log (and all of its archive segments) |
-| PATCH | `/api/sessions/logs/:id?projectId=` | Rename a session (admin-only) — updates the log file's title and the mirrored `agent_sessions.title`. Accepts any session id (root or sub-agent); the sidebar exposes the rename affordance on every row |
+| DELETE | `/api/sessions/logs/:id?projectId=` | Permanently delete the session and all its descendants — log files (with archive segments) and `agent_sessions` rows. Returns `{ok, deleted}` |
+| PATCH | `/api/sessions/logs/:id?projectId=` | Rename a session (admin-only; body `{title}`) — updates the log file's title and the mirrored `agent_sessions.title`. Accepts any session id (root or sub-agent); the sidebar exposes the rename affordance on every row |
+| GET | `/api/sessions/goal?projectId=` | Legacy goal binding of the workspace (`{goal: {goalSessionId, workerSessionId, status, round, maxRounds} \| null}`); refresh seed for the goal banner, which only shows when `general.goal_mode_enabled` is on |
 
-The list endpoint returns flat metadata (id / agentId / agentName / title / timestamps / exchangeCount / parentSessionId / stoppedAt / contextTokens / totalOutputTokens / goalSessionId — the last is a retained legacy field, non-null only on a goal-bound worker row; existing bindings are unchanged), served from the mirrored `agent_sessions` columns rather than by parsing each session file (rows predating the columns are backfilled from the file on first read). The frontend builds the tree from `parentSessionId`.
+The list endpoint returns flat metadata (id / agentId / agentName / title / timestamps / exchangeCount / parentSessionId / stoppedAt / archivedAt / contextTokens / totalOutputTokens / status / goalSessionId — the last is a retained legacy field, non-null only on a goal-bound worker row; existing bindings are unchanged), served from the mirrored `agent_sessions` columns rather than by parsing each session file (rows predating the columns are backfilled from the file on first read). The frontend builds the tree from `parentSessionId`.
 
 The get endpoint returns the full session file. If only `rawMessages` is present (no event-log `messages`), `convertRawMessages()` transforms it into display format on the fly.
 
@@ -261,8 +262,8 @@ Every write except `/api/git/init` is gated on the project being a git work-tree
 | GET | `/api/git/credentials` | List stored HTTPS credentials — `{credentials: [{host, username}]}`. **Never returns the token.** Source of truth is `~/.git-credentials` (one line per host) |
 | POST | `/api/git/credentials` | Body `{host, username, token}`. Upserts the `https://user:token@host` line in `~/.git-credentials` (0600). 400 if any field missing |
 | DELETE | `/api/git/credentials/:host` | Remove the credential line(s) for one host (idempotent). `:host` is sent `encodeURIComponent`'d; Hono decodes it |
-| GET | `/api/git/ssh/keys` | Private keys found in `~/.ssh` + an `encrypted` flag each. Never returns key contents. Returns `{keys: [...]}` |
-| GET | `/api/git/ssh/agent` | ssh-agent reachability + loaded key count |
+| GET | `/api/git/ssh/keys` | Private keys found in `~/.ssh` + an `encrypted` flag each. Never returns key contents. Returns `{keys: [{name, path, encrypted}]}` |
+| GET | `/api/git/ssh/agent` | ssh-agent reachability + loaded keys. Returns `{agentRunning, loadedKeys: string[]}` (`ssh-add -l` lines) |
 | POST | `/api/git/ssh/unlock` | Body `{keyPath, passphrase}`. Loads a passphrase-protected key into the shared ssh-agent. `keyPath` must resolve to a file **directly inside `~/.ssh`** (rejects traversal / arbitrary paths, 400). Passphrase is fed to `ssh-add` via a throwaway `SSH_ASKPASS` helper (never argv / disk / log); the helper is answer-once so a wrong passphrase returns immediately. Returns `{ok}` on success, `{ok:false, error}` (normalized — never ssh-add's raw stderr) on failure |
 | GET | `/api/git/remote/protocol?projectId=` | Current `origin` url + detected protocol. Returns `{url, protocol}` |
 | POST | `/api/git/remote/protocol` | Body `{projectId, to: 'https'\|'ssh'}`. Rewrites `origin` between HTTPS and scp-style SSH. Returns `{ok, url}` |
@@ -301,10 +302,10 @@ gets JSON, and additionally gates on `accessLevel`.
 
 | Method | Path | Purpose |
 |---|---|---|
-| POST | `/api/web/chat` | Send message, receive SSE stream. Body: `{message, images?, workspace?, sessionId?, agentId?}` (overrides also accepted as `?workspace=`/`?sessionId=` query or `x-workspace`/`x-session-id` headers; `workspace` only honored when token has `accessLevel: full`). `sessionId` must be owned by the token unless `accessLevel: full` → otherwise 403. |
+| POST | `/api/web/chat` | Send message, receive SSE stream. Body: `{message, images?, workspace?, sessionId?, agentId?}` (overrides also accepted as `?workspace=`/`?sessionId=` query or `x-workspace`/`x-session-id` headers; `workspace` only honored when token has `accessLevel: full`). `sessionId` must be a safe id segment (else 400) and owned by the token unless `accessLevel: full` → otherwise 403. A client that disconnects ends its stream right away; the turn keeps running (reconnect via `/subscribe`, stop via `/stop`). |
 | POST | `/api/web/sessions` | Mint a root session in the token's own `web_<accountId>_` namespace → `{sessionId}`. Body / query / header: `workspace?` (full tokens only), `agentId?`. Used by the ACP adapter's `session/new`. |
 | POST | `/api/web/stop` | Stop running task → `{stopped: boolean}` |
-| GET | `/api/web/history` | Active session history → `{sessionId, messages[], running}` |
+| GET | `/api/web/history` | Active session history → `{sessionId, messages[], running}`. With an explicit `sessionId` that doesn't exist in the workspace → 404 `{error: "session not found"}` |
 | GET | `/api/web/subscribe` | Reconnect SSE to running session |
 | GET | `/api/web/file?path=` | Inline-serve a workspace-relative file (image / video / pdf etc.). Path-traversal-checked against the token's bound workspace: the lexical check is re-verified against the realpath'd root, so a symlink inside the workspace pointing outside it returns 403; a dangling symlink (target doesn't exist) returns 404. Workspace runtime state (`.halo/sessions`, `.halo/logs`, `.halo/evo`, `halo.db*`) is hidden for every access level → 403 `{error: "path is not accessible"}`, checked on the realpath so symlinks into those dirs are caught too. |
 
@@ -321,7 +322,7 @@ runtime so the frontend can render rooms (workspaces) + characters (sessions).
 | Method | Path | Purpose |
 |---|---|---|
 | GET | `/api/show/state` | `full` or `observer` token → every known workspace; otherwise the account's own. Returns `{ serverTime, uptime, accessLevel, skills[], workspaces[] }` |
-| GET | `/api/show/session?ws=&id=` | Inspector-panel detail for a single session. Trimmed message log (last 40, content/tool I/O capped) plus `contextTokens` / `outputTokens` / `maxContextTokens` / `isRunning`. Non-`full`/`observer` tokens may only read their own workspace, and within it only sessions their own account minted (`web_<accountId>_*`); anything else is 403. |
+| GET | `/api/show/session?ws=&id=` | Inspector-panel detail for a single session. Trimmed message log (last 40, content/tool I/O capped) plus `totalMessages` / `contextTokens` / `outputTokens` / `maxContextTokens` / `isRunning`. Non-`full`/`observer` tokens may only read their own workspace, and within it only sessions their own account minted (`web_<accountId>_*`); anything else is 403. |
 
 `observer` is more than an aggregate-counts role: past `/show/state`, it can also call `/show/session` to read **any workspace's** session transcript (last 40 messages, content truncated to 600 chars, tool input to 200 chars). Mint it knowing it grants cross-workspace transcript read access, not just dashboard counters.
 
@@ -339,20 +340,20 @@ File: `packages/server/src/routes/agent-configs.ts`
 | GET | `/api/agent-configs/tools` | Available workspace tools |
 | GET | `/api/agent-configs/models` | Available model providers and models |
 | POST | `/api/agent-configs` | Create a new agent |
-| GET | `/api/agent-configs/:id/yaml?scope=&projectId=` | Read agent.yaml |
-| PUT | `/api/agent-configs/:id/yaml?scope=&projectId=` | Write agent.yaml |
-| DELETE | `/api/agent-configs/:id?scope=&projectId=` | Delete agent (global has "last one" protection) |
+| GET | `/api/agent-configs/:id/yaml?scope=&projectId=` | Read agent.yaml. `scope=workspace` without `projectId` → 400; `scope` other than `global` / `workspace` (omitted = `global`) → 400 `Invalid scope` |
+| PUT | `/api/agent-configs/:id/yaml?scope=&projectId=` | Write agent.yaml. Same 400s as GET |
+| DELETE | `/api/agent-configs/:id?scope=&projectId=` | Delete agent (global has "last one" protection). Same 400s as GET — never falls back to the same-named global agent or skips the last-one guard |
 | PATCH | `/api/agent-configs/:id/toggle?scope=&projectId=` | Toggle disabled in workspace DB. `projectId` required. Returns `{ ok, disabled }`. |
 | GET | `/api/agent-configs/:id/md/:fileType` | Read an MD file (AGENT.md / INSTRUCTIONS.md / INDEX.md) |
-| PUT | `/api/agent-configs/:id/md/:fileType` | Write an MD file (AGENT.md / INSTRUCTIONS.md) |
-| GET | `/api/agent-configs/:id/md-all` | Read every MD at once |
+| PUT | `/api/agent-configs/:id/md/:fileType` | Write an MD file (AGENT.md / INSTRUCTIONS.md). `scope=workspace` without `projectId` → 400 (never writes the global AGENT.md / INSTRUCTIONS.md) |
+| GET | `/api/agent-configs/:id/md-all` | Read every MD at once. `scope=workspace` without `projectId` → 400 |
 | GET | `/api/agent-configs/:id/sessions?projectId=` | List the agent's session files |
 | GET | `/api/agent-configs/:id/sessions/:sessionId` | Read a session |
 | POST | `/api/agent-configs/:id/sessions` | Save / update a session |
 | DELETE | `/api/agent-configs/:id/sessions/:sessionId` | Delete a session |
 | DELETE | `/api/agent-configs/:id/sessions?all=1` | Delete every session for the agent |
 
-Every `:id` / `:sessionId` route param that becomes a path segment (here and in `DELETE /api/skills/:id`) is validated with `isSafeIdSegment()` (`routes/workspace-path.ts`) before it reaches `path.join` — `.` / `..` rejected outright, everything else must match `/^[\w.:>\u4e00-\u9fff-]+$/` (the union of the real id charsets: slug + CJK agent names, `__internal__`, and session ids embedding `_ - : . >`). Hono decodes `%2F` / `%2e` into params, so a raw `..%2F..%2Fetc` would otherwise arrive as a traversal. A rejected param is **400** (`Invalid agent id` / `Invalid skill id` / `Invalid session id`), distinct from the **404** a well-formed-but-missing session file gets.
+Every `:id` / `:sessionId` route param that becomes a path segment (here and in `DELETE /api/skills/:id`) is validated with `isSafeIdSegment()` (`routes/workspace-path.ts`) before it reaches `path.join` — `.` / `..` rejected outright, everything else must match `/^[\w.:>\u4e00-\u9fff-]+$/` (the union of the real id charsets: slug + CJK agent names, `__internal__`, and session ids embedding `_ - : . >`). Hono decodes `%2F` / `%2e` into params, so a raw `..%2F..%2Fetc` would otherwise arrive as a traversal. A rejected param is **400** (`Invalid agent id` / `Invalid skill id` / `Invalid session id`, or `Invalid id` on the session read / delete routes), distinct from the **404** a well-formed-but-missing session file gets.
 
 ## Skills
 
@@ -409,18 +410,18 @@ In `PUBLIC_PATHS` (no admin cookie). Auth is a web-channel `x-token` (header or
 
 ## Self-Evolution
 
-File: `packages/server/src/routes/evolution.ts`. Surfaces the global `evolution_runs` / `evolution_applies` queues to the admin UI's Evolution tab; see [plans/self-evolution.md](../plans/self-evolution.md) for the full design.
+File: `packages/server/src/routes/evolution.ts`. Surfaces the global `evolution_runs` / `evolution_applies` queues to the admin UI's Evolution tab; see [design/evolution.md](../design/evolution.md) for the full design. Unknown run id → 404 `{error: "not found"}`.
 
 | Method | Path | Purpose |
 |---|---|---|
-| GET | `/api/evolution/runs` | List all evolution runs across workspaces. Carries the latest `apply_id`/`apply_status` per run. (Score isn't surfaced in the list — it's read from `score.json` on the detail fetch only.) |
+| GET | `/api/evolution/runs?archived=0\|1&limit=20&before=<createdAt>` | List evolution runs across workspaces, newest first, cursor-paginated (`limit` 1–300, `before` = previous page's `nextCursor`; `archived=1` lists archived runs instead). Returns `{runs, hasMore, nextCursor}`; each row carries the latest `applyId`/`applyStatus`. (Score isn't surfaced in the list — it's read from `score.json` on the detail fetch only.) |
 | GET | `/api/evolution/runs/:id` | Detail: db row + `patch.md` + `score.json` + `.skip.md` (when `status='skipped'`) + wrapper/sub-cli logs + a snapshot summary (first user message + first assistant reply + message count). Row carries `failureReason` (and `applyFailureReason` from the latest apply) — apply-side values include `phase A': apply cli exited <code>`, `phase A': apply agent aborted: <first line of ABORT.md>`, and `phase A': apply agent didn't produce apply.log`. |
-| POST | `/api/evolution/runs/:id/approve` `{reviewerHint?}` | Move run from `awaiting_review` → `approved`, insert a pending `evolution_applies` row that the ticker will pick up. |
-| POST | `/api/evolution/runs/:id/reject` | Move run from `awaiting_review` → `rejected`. |
-| POST | `/api/evolution/runs/:id/retry` `{hint}` | Reset a finished run back to `pending` with the supplied (required) hint so the wrapper picks it up again. Rejected with 409 when the run is already `running` / `pending`. |
-| POST | `/api/evolution/runs/:id/hint` `{hint}` | Append text to `user_hint` — memo only, doesn't change status. |
-| DELETE | `/api/evolution/runs/:id` | Delete a finished run: its on-disk artifacts (run dir + archive zip) **and** the DB row. Rejected with 409 for in-flight states (`pending` / `running` / `approved`) so a live wrapper / queued apply isn't pulled out from under. Broadcasts `evolution:run_changed` with `kind:'deleted'`. |
-| GET | `/api/evolution/applies` | List apply rows (used for status badges). |
+| POST | `/api/evolution/runs/:id/approve` `{reviewerHint?}` | Move run from `awaiting_review` → `approved`, insert a pending `evolution_applies` row that the ticker will pick up. Returns `{ok, applyId}`; 409 when the run isn't `awaiting_review`. |
+| POST | `/api/evolution/runs/:id/reject` | Move run from `awaiting_review` → `rejected`; 409 otherwise. |
+| POST | `/api/evolution/runs/:id/retry` `{hint}` | Reset a finished run back to `pending` (attempts cleared) with the supplied hint (required, else 400) so the wrapper picks it up again. Rejected with 409 when the run is already `running` / `pending`. |
+| POST | `/api/evolution/runs/:id/hint` `{hint}` | Append text to `user_hint` (hint required, else 400) — memo only, doesn't change status. Returns `{ok, userHint}`. |
+| DELETE | `/api/evolution/runs/:id` | Delete a finished run: its on-disk artifacts (run dir + archive zip + wrapper log) **and** the DB row, plus every apply that references it (artifacts + row, `evolution:apply_changed` `kind:'deleted'`). Rejected with 409 for in-flight states (`pending` / `running` / `approved`) so a live wrapper / queued apply isn't pulled out from under. Broadcasts `evolution:run_changed` with `kind:'deleted'`. |
+| GET | `/api/evolution/applies` | List in-flight apply rows (`pending` / `running` / `syncing`, newest 200; used for status badges). Returns `{applies}`. |
 
 ## AgentCore adapter (runtime-mode only)
 
@@ -434,7 +435,7 @@ Bodies and response shapes for the endpoints agents most commonly help users cal
 
 ### POST `/api/auth/login`
 
-Source: [packages/server/src/middleware/auth.ts:123-134](../../../packages/server/src/middleware/auth.ts#L123-L134)
+Source: [packages/server/src/middleware/auth.ts](../../../packages/server/src/middleware/auth.ts)
 
 ```json
 // Request
@@ -492,6 +493,9 @@ Source: [packages/server/src/routes/files.ts](../../../packages/server/src/route
 ```json
 // 200
 {
+  "projectId": "<absPath>",
+  "root": "<project dir name>",
+  "path": "<relPath>",
   "tree": [
     { "name": "packages", "path": "packages", "type": "directory", "hasChildren": true },
     { "name": "README.md", "path": "README.md", "type": "file" }
@@ -499,7 +503,7 @@ Source: [packages/server/src/routes/files.ts](../../../packages/server/src/route
 }
 ```
 
-Skipped entries: dotfiles (except `.halo`), `node_modules`, `__pycache__`.
+Skipped entries: `.git`, `.DS_Store`, `node_modules`, `__pycache__` (other dotfiles — `.halo`, `.gitignore`, `.env` — are listed).
 
 ### GET `/api/files?path=<rel>&projectId=<abs>`
 
@@ -507,7 +511,10 @@ Reads file content. Max 10 MB.
 
 ```json
 // 200
-{ "content": "..." }
+{ "path": "...", "content": "...", "size": 123, "modifiedAt": 1714000000000, "createdAt": 1714000000000 }
+
+// 413 over 10 MB
+{ "error": "File too large (max 10MB)" }
 
 // 404 if path doesn't exist
 { "error": "File not found" }
@@ -515,7 +522,7 @@ Reads file content. Max 10 MB.
 
 ### POST `/api/agent-configs`
 
-Source: [packages/server/src/routes/agent-configs.ts:199-255](../../../packages/server/src/routes/agent-configs.ts#L199-L255)
+Source: [packages/server/src/routes/agent-configs.ts](../../../packages/server/src/routes/agent-configs.ts)
 
 ```json
 // Request
@@ -540,12 +547,18 @@ Source: [packages/server/src/routes/agent-configs.ts:199-255](../../../packages/
   "conflictScope": null            // or "global" / "workspace" to warn of override
 }
 
+// 400 empty id after slugging ("Invalid agent name") or workspace scope without projectId
+{ "error": "Invalid agent name" }
+
+// 403 id `goal` while general.goal_mode_enabled is off
+{ "error": "Goal mode is disabled." }
+
 // 409 already exists
 { "error": "Agent already exists" }
 ```
 
 Files created:
-- `<agentDir>/agent.yaml` — scaffold with `SCAFFOLD_MODEL`, empty tools/skills
+- `<agentDir>/agent.yaml` — scaffold whose `model` block comes from the provider named by `general.agent.default_provider` (else `aws-bedrock-claude-invoke`, else the first installed provider), empty tools/skills
 - `<agentDir>/AGENT.md` — `# <name>\n\n<description>\n`
 
 ### PUT `/api/agent-configs/:id/yaml?scope=&projectId=`
@@ -560,6 +573,12 @@ Files created:
 // 400 invalid YAML
 { "error": "Invalid YAML: <parser message>" }
 
+// 400 scope=workspace without projectId
+{ "error": "projectId required for workspace agents" }
+
+// 400 scope other than global / workspace
+{ "error": "Invalid scope" }
+
 // 404
 { "error": "Agent not found" }
 ```
@@ -574,8 +593,7 @@ Source: [packages/server/src/routes/skills.ts](../../../packages/server/src/rout
   "name": "Code Review",
   "description": "Review code for correctness and style",
   "scope": "workspace",
-  "projectId": "/abs/ws",
-  "command": "/review"            // optional — registers as slash command
+  "projectId": "/abs/ws"
 }
 
 // 201
@@ -588,11 +606,16 @@ Source: [packages/server/src/routes/skills.ts](../../../packages/server/src/rout
     "scope": "workspace"
   }
 }
+
+// 409 already exists
+{ "error": "Skill already exists" }
 ```
 
+Also adds the skill's entry to the scope's `settings.yaml`.
+
 ### GET `/api/sessions/logs?projectId=<abs>&rootOnly=0|1&includeArchived=0|1&cursor=<ms>&limit=<n>`
 
-Source: [packages/server/src/routes/sessions.ts:189-258](../../../packages/server/src/routes/sessions.ts#L189-L258)
+Source: [packages/server/src/routes/sessions.ts](../../../packages/server/src/routes/sessions.ts)
 
 Keyset-paginated over `updatedAt` (descending). `limit` defaults to 50 (max 500); the
 response's `nextCursor` (epoch ms of the last row's `updatedAt`, or `null` on
@@ -618,15 +641,14 @@ Two shapes, selected by `rootOnly`:
       "agentId": "default",
       "agentName": "Default",
       "title": "First user message...",
-      "source": "explorer",
-      "createdAt": "2026-04-30T08:00:00Z",
-      "updatedAt": "2026-04-30T08:05:00Z",
+      "createdAt": 1777536000000,
+      "updatedAt": 1777536300000,
       "exchangeCount": 12,
-      "parentSessionId": null,
       "contextTokens": 5975,
       "totalOutputTokens": 6058,
       "stoppedAt": null,
       "archivedAt": null,
+      "goalSessionId": null,
       "status": "idle"
     }
   ],
@@ -636,7 +658,7 @@ Two shapes, selected by `rootOnly`:
 
 Archived sessions are excluded by default; pass `?includeArchived=1` to include them.
 
-`status` is `'running' | 'idle' | 'stopped'`. A root counts as `running` while any of its sub-sessions runs. The admin's chat tab list uses it to show a running mark on a tab that hasn't loaded yet; a loaded tab follows its own stream.
+`status` is `'running' | 'idle' | 'stopped'`. A root counts as `running` while any of its sub-sessions runs. Returned since 1.5.3-alpha; the current admin no longer reads it. `parentSessionId` is present only on sub-sessions (omitted for roots). Timestamps are epoch ms.
 
 Rows are served from the mirrored `agent_sessions` metadata columns (`title` / `exchange_count` / `context_tokens` / `total_output_tokens`) — no session file is opened. A row whose `exchangeCount` is `null` predates those columns: the route reads that one file once, mirrors the values back, and never pays the cost again. `exchangeCount` counts **main user turns over the session's lifetime** (kept + archived), so unlike the file's `messageCount` it doesn't shrink when a compact archives history.
 
@@ -691,7 +713,7 @@ The `n > archiveCount` check is the point, not a formality: `archiveCount` in th
 
 ### GET `/api/settings/schema?projectId=<abs>`
 
-Resolves declared schema (from `models/<id>.yaml` `secrets:` and `skills/<id>/config.yaml`) against current settings, returning per-field source/state and a list of orphan keys. Drives the Settings page.
+Resolves declared schema (from `models/<id>.yaml` `secrets:`, `skills/<id>/config.yaml`, and global `agents/<id>/agent-config.yaml`) against current settings, returning per-field source/state and a list of orphan keys. Drives the Settings page.
 
 ```json
 // 200
@@ -699,8 +721,8 @@ Resolves declared schema (from `models/<id>.yaml` `secrets:` and `skills/<id>/co
   "scope": "global",                              // or "workspace" when projectId set
   "sections": [
     {
-      "namespaceId": "aws-bedrock-claude-invoke", // 'general' | provider id | skill id
-      "source": "provider",                        // 'general' | 'provider' | 'skill'
+      "namespaceId": "aws-bedrock-claude-invoke", // 'general' | provider id | skill id | agent id
+      "source": "provider",                        // 'general' | 'provider' | 'skill' | 'agent'
       "displayName": "AWS Bedrock Claude (Invoke API)",
       "displayName_zh": "AWS Bedrock Claude（Invoke API）",
       "description": "...",
@@ -711,7 +733,7 @@ Resolves declared schema (from `models/<id>.yaml` `secrets:` and `skills/<id>/co
           "kind": "secret",                        // 'param' | 'secret'
           "description": "...",
           "description_zh": "...",
-          "default": null,                         // schema-default placeholder
+          "default": "...",                        // schema-default placeholder; omitted when the schema declares none
           "secret": true,                          // UI masks input + value
           "value": "AK****ST",                     // already masked when secret:true; null = unset
           "hasValue": true,                        // any layer has a non-empty value
@@ -744,18 +766,18 @@ Resolves declared schema (from `models/<id>.yaml` `secrets:` and `skills/<id>/co
 { "ok": true }
 ```
 
-PUT replaces the full scope; DELETE takes `{scope, projectId, key}` and removes the key. The Settings page uses DELETE for both Reset (current scope removed → falls back to lower scope / unset) and orphan Remove.
+PUT replaces the full scope; PUT / PATCH / DELETE with `scope: "workspace"` reject a `globalOnly` key with 400 (`<key> is global-only and cannot be set per workspace`) and an unresolvable `projectId` with 404 `Project not found`. DELETE takes `{scope, projectId, key}` and removes the key. PUT / PATCH / DELETE fire the server's `onSettingsChange` listeners (e.g. the sandbox hidden-paths reload); a DELETE of an already-absent key is a no-op — `{ ok: true }`, no file write, no notify. The Settings page uses DELETE for both Reset (current scope removed → falls back to lower scope / unset) and orphan Remove.
 
 ### POST `/api/wechat/login/start`
 
-Source: [packages/server/src/routes/wechat.ts:39-43](../../../packages/server/src/routes/wechat.ts#L39-L43)
+Source: [packages/server/src/routes/wechat.ts](../../../packages/server/src/routes/wechat.ts)
 
 ```json
 // Request
 { "sessionKey": "optional-resume-key", "force": false }
 
 // 200
-{ "qrcodeUrl": "https://...", "sessionKey": "abc123" }
+{ "qrcodeUrl": "https://...", "message": "...", "sessionKey": "abc123" }
 ```
 
 ### POST `/api/wechat/login/wait`
@@ -766,7 +788,7 @@ Source: [packages/server/src/routes/wechat.ts:39-43](../../../packages/server/sr
   "sessionKey": "abc123",
   "workspacePath": "/abs/path",     // required, must be absolute
   "label": "My Bot",                // optional
-  "accessLevel": "readonly",        // "full" | "readonly", default readonly
+  "accessLevel": "readonly",        // "full" | "workspace" | "readonly", default readonly
   "language": "en",                 // "en" | "zh", default "en" — controls system message language
   "timeoutMs": 120000               // optional, how long to wait for scan
 }
@@ -774,10 +796,11 @@ Source: [packages/server/src/routes/wechat.ts:39-43](../../../packages/server/sr
 // 200 waiting for scan (retry polling)
 { "connected": false, "message": "..." }
 
-// 200 connected — account inserted + long-poll started
-{ "connected": true, "accountId": "abc-im-bot" }
+// 200 connected — account inserted (or updated if it already exists) + long-poll started
+{ "connected": true, "accountId": "abc-im-bot", "message": "..." }
 
-// 400 bad input
+// 400 bad input (sessionKey / workspacePath missing, relative path, bad accessLevel;
+// after a successful scan also "workspace path not found")
 { "error": "workspacePath required" }
 ```
 
@@ -797,17 +820,18 @@ Full WS protocol in [design/ws.md](../design/ws.md). The four high-traffic clien
   "message": "hello",
   "agentId": "default",                                    // optional override
   "clientMsgId": "abc123",                                 // optional — ack/resend dedup id
+  "accessLevel": "workspace",                              // optional — "full" | "workspace" | "readonly", idle session only
   "images": [ { "data": "<base64>", "mimeType": "image/png" } ]  // optional
 }
 ```
 
-Server behaviour ([handler.ts `handleChat`](../../../packages/server/src/ws/handler.ts#L263-L344)):
+Server behaviour (`handleChat` in `ws/handler.ts`; `sessionId`, `projectId` and `message` are all required, else an `error` frame):
 - Creates / reuses a session with the specified agent
-- Persists pasted images to `<ws>/.halo/web/inbound/<date>/`
+- Persists pasted images to `<ws>/.halo/assets/web/inbound/web/<date>/`
 - If the model does not support image input (`capabilities.image: false`), images are filtered out and a text notice is appended instead of sending to the API
-- Queues if busy/compacting; otherwise runs the agent turn
+- Queues if busy/compacting (a `chat:queued` frame is sent only for the compacting case); otherwise runs the agent turn. `accessLevel` applies only on the idle path and is forced to `full` when the host has no OS sandbox
 - When `clientMsgId` is present, replies `{ "type": "chat:ack", "clientMsgId" }` once the message is appended to the session log; resends with an already-acked id are re-acked without re-appending (dedup — see [design/ws.md](../design/ws.md#chat-delivery-ack--resend--dedup))
-- Streams events back via `message`, `tool_call`, `usage`, etc.
+- Streams events back via `chat:stream`, `agent:tool_call`, `chat:usage`, etc. (table below)
 
 ### `subscribe` (C→S)
 
@@ -871,13 +895,15 @@ It does not remove session files. The full delete (rows + JSON + archive segment
 
 | Type | Fields | Purpose |
 |---|---|---|
-| `message` | `content`, `role`, `taskId?` | Text chunk from the agent |
-| `tool_call` | `toolName`, `toolInput`, `taskId?` | Tool invocation card |
-| `tool_result` | `toolName`, `toolOutput`, `durationMs`, `taskId?` | Tool result |
-| `usage` | `usage`, `modelId`, `turnId`, `taskId?` | Token accounting per turn |
-| `complete` | `stopReason`, `taskId?` | Turn finished |
+| `chat:stream` | `text`, `agentName`, `turnId`, `taskId?` | Text chunk from the agent |
+| `chat:thinking` | `text`, `agentName`, `turnId`, `taskId?` | Thinking chunk |
+| `agent:tool_call` | `tool`, `toolUseId`, `input`, `agentName`, `turnId`, `taskId?` | Tool invocation card |
+| `agent:tool_result` | `result`, `toolUseId`, `agentName`, `durationMs`, `taskId?` | Tool result |
+| `chat:usage` | `contextTokens`, `outputTokens`, `usage`, `modelId`, `turnId` | Token accounting per model call (root only) |
+| `chat:complete` | `batchBoundary?` | Turn finished |
 | `error` | `error`, `sessionId?` | Error message |
-| `chat:queued` | `reason`, `message`, `sessionId` | Message queued (compact/busy) |
+| `chat:queued` | `reason: 'compact'`, `message`, `sessionId` | Message queued behind a compact |
+| `chat:ack` | `clientMsgId` | Chat appended to the session log (or re-acked on resend) |
 | `listener:released` | `sessionId` | Event listener reclaimed — re-send `subscribe` (see above) |
 
 Events with `taskId` set belong to sub-agent turns (nested sessions); events without are the root agent's. Session-scoped frames carry `sessionId` (the root session they belong to); the admin routes each one to the tab holding that session, and a frame without one goes to the tab on screen. Full list in [design/ws.md](../design/ws.md).

package/bundled-docs/dev/deploy.md

@@ -47,7 +47,7 @@ Nginx is **not required**. Use it only for domain routing, SSL termination, or w
 ## Prerequisites
 
 - Node.js ≥ 22
-- pnpm ≥ 9
+- pnpm 11 (pinned by the root `packageManager`; `corepack enable` picks it up)
 - AWS credentials configured (`~/.aws/credentials` or env vars) with Bedrock access
 
 ## 1. Install dependencies and build
@@ -63,7 +63,7 @@ pnpm --filter @turmind/halo-admin build   # next build + copy-monaco; never a ba
 
 ## 2. Runtime data locations
 
-No directory needs to be created by hand. SQLite databases are created automatically on first use: per-workspace state at `<workspace>/.halo/halo.db`, plus global queues at `~/.halo/global/evo.db`, `~/.halo/global/cron.db` and `~/.halo/global/runs.db`.
+No directory needs to be created by hand. SQLite databases are created automatically on first use: per-workspace state at `<workspace>/.halo/halo.db`, plus global queues at `~/.halo/global/evo.db`, `~/.halo/global/cron.db` and `~/.halo/global/runs.db`, and channel accounts at `~/.halo/secrets/channels/channels.db`.
 
 ## 3. Run `halo setup`
 
@@ -90,7 +90,7 @@ When `HALO_PASSWORD` is set, the password chosen via `halo setup` is ignored at
 
 ## 5. Start the server
 
-> **单实例锁**：server 启动时会写 `~/.halo/global/server.lock`（Linux 用 flock，macOS/Windows 回退到 pid 探测），退出时自动清理。如果 lock 里记录的进程还活着，新 server 会拒绝启动并打印 `kill <pid>` 提示。原因是 WeChat 长轮询循环跟 HTTP server 解耦，多个进程并存会导致同一条微信消息被 fan out 到多个 session。陈旧 lock（进程已不在）会被自动识别并清除。要手动重启先 kill 旧的：`kill $(cat ~/.halo/global/server.lock)`。
+> **单实例锁**：server 启动时会写 `~/.halo/global/server.lock`（有 `flock` 命令时用 flock，没有就回退到 pid 探测），退出时自动清理。如果 lock 里记录的进程还活着，新 server 会拒绝启动并打印 `kill <pid>` 提示。原因是 WeChat 长轮询循环跟 HTTP server 解耦，多个进程并存会导致同一条微信消息被 fan out 到多个 session。陈旧 lock（进程已不在）会被自动识别并清除。要手动重启先 kill 旧的：`kill $(cat ~/.halo/global/server.lock)`。
 
 ### Option A: quick start
 
@@ -155,8 +155,8 @@ server as its child (`packages/cli/src/server-supervisor.ts`). Policy:
   up (exit 1) with a log line telling you to fix the cause and re-run `halo
   server start -d`.
 - **2s pause between attempts**, so an instant-crash loop can't spin the CPU.
-- Every decision lands in the daemon log as `[respawn] …`, on the same fds the
-  server writes to (`~/.halo/global/logs/server.log`).
+- Every decision lands in the daemon log as `[respawn] …` — the stdout/stderr
+  capture `~/.halo/logs/server.log`, which `halo server logs` tails.
 
 `halo server stop` (and `--force`) is not mistaken for a crash: it stamps the
 server pid into a marker file `~/.halo/global/server.stop` *before* signalling,
@@ -219,6 +219,7 @@ This installs the `halo` binary on `$PATH`. Subcommands available:
 | `halo tui` | Interactive TUI client |
 | `halo cli "<prompt>"` | One-shot prompt → reply, exit |
 | `halo agents` / `halo sessions` | List agents / sessions |
+| `halo acp` | Stdio bridge that lets an ACP client (e.g. Claude Code) drive a halo server — see [acp-adapter.md](acp-adapter.md) |
 
 ### Upgrade flow
 
@@ -239,7 +240,7 @@ Use only for a new public release; the retained details here are not extra prepa
 
 **npm token gotcha**: `npm publish` on this package needs a granular access token created with **"Bypass 2FA"** checked — scope / permission alone yields `403 Two-factor authentication or granular access token with bypass 2fa enabled is required`. `npm whoami` and `npm token list` succeed with a non-bypass token, so neither is a valid pre-flight; check `GET https://registry.npmjs.org/-/npm/v1/tokens` (with the token as bearer) and look for `"bypass_2fa": true` on the token in use before starting a release.
 
-The published package contains a single bundled JS entry (~620 KB), all built-in templates (agents / skills / prompts / models), bundled platform docs, and the admin Web UI static export. Total install footprint ≈ 120 MB after npm dedupes shared deps.
+The published package contains a single bundled JS entry (~1.4 MB), all built-in templates (agents / skills / prompts / models), bundled platform docs, and the admin Web UI static export. Total install footprint ≈ 120 MB after npm dedupes shared deps.
 
 ### Non-interactive (Docker / CI) details
 
@@ -247,6 +248,7 @@ The published package contains a single bundled JS entry (~620 KB), all built-in
 
 - Seeds / refreshes `~/.halo/global/` from the bundled templates (per the per-category overwrite policy in `init.ts`)
 - Generates `server.jwt_secret` if missing
+- Binds the built-in agents to the provider named by `HALO_DEFAULT_PROVIDER`, when set (an unknown id only warns)
 - **Does not** set a password — supply one via `HALO_PASSWORD` env
 
 Minimal Dockerfile:

package/bundled-docs/dev/env.md

@@ -51,9 +51,9 @@ nohup node dist/index.js >> /dev/null 2>&1 &   # HALO_PASSWORD read from env/con
 ## Prerequisites
 
 - Node.js ≥ 22 (better-sqlite3 native binding is bound to v22)
-- pnpm ≥ 9
+- pnpm 11 (pinned by the root `packageManager`; `corepack enable` picks it up)
 - AWS credentials configured (`~/.aws/credentials` or env vars) with Bedrock access
-- bubblewrap (`sudo apt install bubblewrap`) — OS-level sandbox for non-full access levels. Without it, only app-level path validation is active and `shell_exec` is blocked for non-full sessions
+- bubblewrap (`sudo apt install bubblewrap`) — OS-level sandbox for non-full access levels on Linux (macOS uses the built-in Seatbelt). Without one, only app-level path validation is active and `shell_exec` is blocked for non-full sessions
 
 ### nvm PATH
 
@@ -67,7 +67,7 @@ Your deployment scripts should also prepend this line.
 
 ## Runtime directories
 
-- SQLite: `<workspace>/.halo/halo.db` (per-workspace, auto-created on first use) + global queues `~/.halo/global/evo.db`, `~/.halo/global/cron.db` and `~/.halo/global/runs.db`
+- SQLite: `<workspace>/.halo/halo.db` (per-workspace, auto-created on first use) + global queues `~/.halo/global/evo.db`, `~/.halo/global/cron.db` and `~/.halo/global/runs.db` + channel accounts `~/.halo/secrets/channels/channels.db`
 - Session files: `.halo/sessions/{agentId}/{sessionId}.json`
 - Global config: `~/.halo/global/`
 - Per-project config: `<workspace>/.halo/`
@@ -78,14 +78,14 @@ Three config file types, precedence **env vars > config.yaml / settings.yaml > c
 
 | File | Scope | Contents |
 |---|---|---|
-| `~/.halo/secrets/config.yaml` | System | Port, password, CORS, timeouts, limits, logging — "infrastructure" settings |
-| `~/.halo/secrets/settings.yaml` | User | Model, region, session behaviour — "preferences" |
-| `<project>/.halo/settings.yaml` | Project | Overrides of global settings |
+| `~/.halo/secrets/config.yaml` | System | Port, password, JWT secret, CORS, timeouts, log rotation — "infrastructure" settings |
+| `~/.halo/secrets/settings.yaml` | User | Provider secrets, skill params, `general.*` server knobs (session, compaction, limits, sandbox, logging) — "preferences" |
+| `<project>/.halo/settings.yaml` | Project | Overrides of provider / skill `params` and `secrets`; every `general.*` key is global-only (a workspace value is rejected by the API and ignored at runtime) |
 
 `init.ts` seeds these on first run with a per-category policy. Refresh trigger: `halo setup` always re-runs the seed, and the server's startup check re-runs it automatically when `~/.halo/global/.template-version` is behind the bundled `TEMPLATE_VERSION` (see `init.ts:TEMPLATE_VERSION` + `index.ts` startup block).
 
-- **Always overwritten** (platform-owned, refreshed when the template version moves): `~/.halo/global/{prompts,models,docs}/`, `INSTRUCTIONS.md`, the built-in agent ids (`default`, `executor`, `deep-executor`, `__evo_agent__`, `__score__`, `__apply_agent__`), built-in skill ids (`agent`, `skill`, `workspace`, `cron`, `acp`, `send-file`, `self`, `aws-knowledge`, `nova-web-search`, `halo`).
-- **Built-in agents** keep the user's `model:` block on overwrite — the admin UI lets users change which model an agent uses, and that choice survives upgrades.
+- **Always overwritten** (platform-owned, refreshed when the template version moves): `~/.halo/global/{prompts,models,docs}/`, `INSTRUCTIONS.md`, the built-in agent ids (`default`, `executor`, `deep-executor`, `goal`, `__evo_agent__`, `__score__`, `__apply_agent__`), built-in skill ids (`agent`, `skill`, `workspace`, `cron`, `acp`, `send-file`, `aws-knowledge`, `web-search`, `self`, `halo`, `extension`).
+- **Built-in agents** keep the user's `model:` and `context:` blocks on overwrite — the admin UI lets users change which model an agent uses and its context limits, and that choice survives upgrades.
 - **Optional skills** (`tavily-web-search`) install only when picked via `halo setup`; the opt-in list is `~/.halo/global/.installed-optional-skills`. Picked skills are force-overwritten alongside the always-overwritten set.
 - **`secrets/config.yaml`** is leaf-merged: existing leaf `value`s preserved, new leaves added when a server upgrade introduces them.
 - **`secrets/settings.yaml`** is created empty if missing and never touched again. Defaults live in `settings-schema.ts`.
@@ -99,7 +99,7 @@ Source: `packages/server/src/config.ts`
 | `HALO_PORT` | `9527` | `config.yaml server.port` | Hono listen port |
 | `HALO_PASSWORD` | (none) | `config.yaml server.password` (scrypt hash) | Plaintext login password. When set, takes precedence over the stored hash and bypasses scrypt entirely — intended for Docker / systemd / CI. It also satisfies the **startup gate**: the server refuses to boot with no password configured, and env plaintext counts as a first-class credential there, so an env-only deployment (`halo setup -y && HALO_PASSWORD=... halo server start`, no stored hash) boots fine. The hash is set by `halo setup` for interactive installs. |
 | `HALO_CORS_ORIGINS` | empty (reflect any origin) | `config.yaml server.cors_origins` | CORS allowlist (comma-separated). Empty = reflect any incoming Origin so credentials work cross-origin. Set explicit list to enforce strict CORS. |
-| `HALO_FRONTEND_DIR` | `packages/admin/out` | — | Static frontend dir (resolved as absolute path from project root) |
+| `HALO_FRONTEND_DIR` | auto (bundled `admin-out`, else `packages/admin/out`) | — | Static frontend dir; resolved against the current working directory |
 | `HALO_MAX_CONTEXT_TOKENS` | `272000` | — | Model max context |
 | `HALO_SHELL_TIMEOUT` | `120000` | `config.yaml timeout.shell_exec` | Shell command timeout (ms) |
 | `HALO_WEB_FETCH_TIMEOUT` | `10000` | `config.yaml timeout.web_fetch` | web_fetch timeout |
@@ -114,6 +114,10 @@ Source: `packages/server/src/config.ts`
 | `HALO_BADGE` | (none) | — | Environment badge (e.g. `DEV`) returned by `GET /api/auth/check` on **both** the 200 and 401 branches, so the admin can brand the login screen too. The admin repaints the favicon with a badge band and prefixes the tab title, making parallel dev/prod tabs tellable apart. dev and prod serve the same static build, so this has to be a runtime signal. Unset / whitespace-only → `null` → stock branding. Because the 401 branch carries it, the value is **public to unauthenticated clients** — keep it a label (`DEV`, `staging`), never anything sensitive. |
 | `HALO_RUNTIME_MODE` | (none) | — | `agentcore` runs the server as an Amazon Bedrock AgentCore Runtime container (see [design/agentcore.md](../design/agentcore.md)) |
 | `HALO_WORKSPACE` | `process.cwd()` | — | Workspace root in agentcore mode |
+| `HALO_DEFAULT_PROVIDER` | (none) | — | Read by `halo setup --non-interactive`: binds the built-in agents to this provider id (and its default model). An unknown id only prints a warning |
+| `HALO_CLI` | `halo` (`halo.cmd` on Windows) | — | `halo` cli executable that cron runs and the evolution wrapper spawn — a dev override |
+| `HALO_VERSION` | `dev` | — | Version string reported by `GET /api/health` and the cli; stamped by the bundle / desktop launcher, so normally not set by hand |
+| `HALO_PROMPT` | (none) | — | `plain` makes `halo setup` use numbered-menu prompts instead of the raw-mode TUI |
 
 settings.yaml only (no env override):
 - `general.session.max_queue_size` (default 256)
@@ -140,7 +144,7 @@ settings.yaml only (no env override):
 When a provider manifest declares a `default: <<NAME>>` for a secret, `halo setup` offers a "Use env $NAME" action. Picking it **writes the literal `<<NAME>>` placeholder into settings.yaml**, which the standard env-var interpolation ([storage.md](../design/storage.md#env-var-interpolation-env_name)) expands against `process.env` at read time. There is no separate runtime env fallback — the placeholder in the file is the only mechanism (an unset env var leaves the literal `<<NAME>>` visible in the request, failing loudly).
 
 `<skill-id>.params.*` (referenceable from skills via `{{<skill-id>.params.<key>}}`, or short form `{{params.<key>}}` inside SKILL.md; declared in `skills/<id>/config.yaml`):
-- `tavily-search.params.api_key` — example only; declared by whichever skill needs it
+- `tavily-web-search.params.api_key` — example only; declared by whichever skill needs it
 
 Hardcoded (config.ts, no override):
 - `auth.tokenMaxAge` — 14 days
@@ -152,7 +156,8 @@ settings.yaml-driven `general.limits.*` (no env override):
 - `general.limits.web_fetch_bytes` (default 50 KiB)
 - `general.limits.grep_default_matches` (default 50)
 - `general.limits.tool_result_render_chars` (default 8000)
-- `general.limits.ws_event_buffer` (default 5000)
+- `general.limits.tool_result_ui_chars` (default 64 KiB)
+- `general.limits.auto_report_chars` (default 8192)
 - `general.limits.terminal_scrollback_bytes` (default 50000)
 
 Two ways to authenticate:

package/bundled-docs/dev/logging.md

@@ -6,28 +6,26 @@ File: `packages/server/src/logger.ts`
 
 ## Architecture
 
-On startup the logger intercepts `console.log` / `console.error` / `console.warn` / `console.debug`. Every call writes twice:
+On startup the logger intercepts `console.log` / `console.error` / `console.warn` / `console.debug`. A call that passes the level gate (`general.logging.level` / `HALO_LOG_LEVEL`, default `warn`) writes to:
 1. The original console (stdout/stderr) — live monitoring
 2. A disk log file — persistent history
+3. The OTel logger, when observability is on (see [design/observability.md](../design/observability.md))
 
-## Log locations
+Any `?token=…` value in a message is replaced with `?token=<redacted>` before it reaches a sink.
 
-| Scenario | Directory | File |
-|---|---|---|
-| Default (no workspace) | `~/.halo/logs/` | `server.log` |
-| Workspace open | `<project>/.halo/logs/` | `server.log` |
+## Log locations
 
-When the WS handler receives a `subscribe` or `chat` with `projectId`, it calls `setLogDir()` to switch to the project's log directory.
+One file for the whole server: `~/.halo/global/logs/server.log`. A single server process serves many workspaces, so there is no per-workspace log. Cron runs and evolution runs keep their own logs under `~/.halo/global/logs/{cron,evo}/`. `halo server start -d` additionally captures the process's stdout/stderr in `~/.halo/logs/server.log` (plus the supervisor's `[respawn]` lines) — that is the file `halo server logs` tails.
 
 ## Log format
 
 ```
-2026-04-19T10:30:00.000Z INFO  [Server] Hono server listening on http://localhost:9527
-2026-04-19T10:30:01.234Z ERROR [WS] Chat error: ThrottlingException
-2026-04-19T10:30:02.567Z WARN  [Orchestrator] Context overflow, auto-compacting...
+time=2026-04-19T10:30:00.000Z level=info [Server] Hono server listening on http://localhost:9527
+time=2026-04-19T10:30:01.234Z level=error [WS] Chat error: ThrottlingException
+time=2026-04-19T10:30:02.567Z level=warn [SessionManager] Context overflow, auto-compacting...
 ```
 
-Every line: `ISO timestamp` + `level (DEBUG/INFO/WARN/ERROR)` + `message`.
+Every line is logfmt-flavored: `time=<ISO timestamp> level=<debug|info|warn|error> <message>`; the message keeps its `[Module]` prefix.
 
 ## Rotation
 
@@ -41,8 +39,9 @@ When the log file exceeds the cap:
 
 | Config key | Default | Env var | Purpose |
 |---|---|---|---|
-| `logging.maxFileSize` | 10 MB | `HALO_LOG_MAX_SIZE` | Rotation threshold |
-| `logging.maxFiles` | 5 | `HALO_LOG_MAX_FILES` | Retained rotated files |
+| `logging.max_file_size` (`config.yaml`) | 10 MB | `HALO_LOG_MAX_SIZE` | Rotation threshold |
+| `logging.max_files` (`config.yaml`) | 5 | `HALO_LOG_MAX_FILES` | Retained rotated files |
+| `general.logging.level` (`settings.yaml`) | `warn` | `HALO_LOG_LEVEL` | Minimum level written: debug \| info \| warn \| error |
 
 Defined in `packages/server/src/config.ts`.
 
@@ -54,18 +53,8 @@ initLogger()
 ```
 
 Called once from `packages/server/src/index.ts` at startup. Steps:
-1. Create the log directory
-2. Replace console methods with the interceptor
-3. Each interceptor calls the original method and appends to the log file
-
-## Workspace switching
-
-```typescript
-import { setLogDir } from './logger.js'
-setLogDir('/path/to/project')
-```
-
-Called from `packages/server/src/ws/handler.ts` when the client subscribes to a workspace.
+1. Replace console methods with the interceptor
+2. Each interceptor calls the original method and appends to the log file (the directory is created on first write)
 
 ## Error handling
 
@@ -78,8 +67,5 @@ Log writes use synchronous `fs.appendFileSync` and fail silently — logging mus
 tail -f /tmp/server.log
 
 # file logs (always written, regardless of nohup redirection)
-tail -f ~/.halo/logs/server.log
-
-# project-specific logs
-tail -f /path/to/your-project/.halo/logs/server.log
+tail -f ~/.halo/global/logs/server.log
 ```