@turmind/halo 0.1.9

package/bundled-docs/requirements/editor.md

@@ -0,0 +1,82 @@
+# Canvas — Requirements
+
+Monaco-based multi-tab code editor + binary file previewer — surfaced in the UI as **Canvas**.
+
+> Naming note: "Canvas" is the user-visible name (header label, this doc). Source code still uses `editor`
+> (`packages/admin/src/features/editor/`, `useEditorStore`, `EditorPanel`) — those names are internal.
+
+> Store scoping: `useEditorStore` is the **default singleton** powering the main Explorer Canvas.
+> Nested `EditorPanel` instances that need isolated tabs/fileTree/selection (e.g. Skills editor)
+> wrap their subtree in `<EditorStoreProvider>`; inside the provider, `useScopedEditorStore()`
+> returns a fresh store instance instead of the singleton. Without a provider the hook falls
+> back to the default, so regular call sites don't change. `EditorPanel` also accepts
+> `showMaximize={false}` for nested contexts where viewport-fullscreen makes no sense.
+
+## Core behaviour
+
+### Multi-tab editing
+- Click a file in Explorer (single click = select, double click = open tab)
+- Each tab independently tracks content, original content, language, mtime
+- Unsaved tabs show a small red dot
+- Closing an unsaved tab prompts for confirmation
+
+### 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`
+2. If `diskMtime > tab.mtime`, pull fresh content
+3. Skip if the user has unsaved edits (don't overwrite)
+
+### Tab persistence
+Open tabs and the active tab live in localStorage; survive refresh.
+
+### Diff view
+- Tracked files → `GET /api/files/diff` for git diff
+- Monaco left/right compare view
+
+### Binary previews
+Non-text files go through `FilePreview`, which looks up a **plugin** in the preview registry by file extension. Built-in plugins:
+- **PDF** — browser-native iframe
+- **DOCX / DOC** — `mammoth` → HTML (parsed in a Web Worker so the UI stays responsive)
+- **XLSX / XLS / CSV** — `xlsx` (SheetJS) → table (parsed in a Web Worker; CSV decoded as UTF-8 with BOM strip)
+- **PPTX / PPT** — `pptx-preview` list mode. Fidelity is approximate — complex animations / SmartArt / embedded fonts may not render perfectly; users can download for the exact source. Flagged `heavy: true` so only the *active* pptx mounts (canvas-based rendering needs the main thread)
+- **Images / video / audio** — native `<img>` / `<video>` / `<audio>`, supports HTTP Range for seek-without-full-download
+
+All previews share a **standard header** (`PreviewShell`) with filename, Download, Open-as-Text, and an `extraToolbar` slot for plugin-specific buttons (e.g. DOCX Print, XLSX sheet tabs).
+
+Fetched via `GET /api/files/download?inline=1` (supports Range, streams on the server).
+
+Adding new file types is a plugin concern — see `dev/previews.md` for the extension guide.
+
+### 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)
+- **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)
+- 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).
+
+### 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.
+
+### Selection tracking
+Canvas tracks current selection and cursor. When `contextEnabled` is on, the selection is auto-injected into chat messages as context.
+
+### Maximize
+The header has a maximize button on the far right. Toggling it expands Canvas to fill the entire viewport — activity bar, sidebar, and bottom panel are hidden. The state persists in localStorage so reloads keep the mode. Press `Esc` to exit — except when focus is inside an input, Monaco, or Quick Open, so those can handle `Esc` first.
+
+Canvas (including Monaco instances, file tree, and open tab contents) stays mounted across activity-tab switches and maximize toggles — switching away and back does **not** reload content.
+
+## Shortcuts
+
+| Shortcut | Action |
+|---|---|
+| 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) |
+| Esc | Exit maximized Canvas (when not inside an input / Monaco / Quick Open) |

package/bundled-docs/requirements/explorer.md

@@ -0,0 +1,89 @@
+# Explorer — Requirements
+
+VS Code-style file tree sidebar with multi-select, drag-drop, right-click menu.
+
+## Workspace switching
+
+### 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
+- 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
+
+### Directory picker (FolderPicker modal)
+Visual directory browser opened by the 📁🔍 button:
+- Top: breadcrumb input (paste paths here) + ⬆ up + 🏠 home
+- Middle: `GET /api/fs/browse?path=...` pulls the current directory's children
+  - Drops entries starting with `.`
+  - Single click = select (updates the current path only)
+  - Double click = enter
+- Bottom: Cancel / Open. Open triggers the same switch flow as Enter (including existence check).
+
+## Core behaviour
+
+### File tree (lazy)
+- Root level: `GET /api/files/tree?projectId=xxx` returns only the first level
+- Subdirectories: only fetched on expand via `?path=<subdir>`
+- Every directory node carries `hasChildren: boolean` so the arrow renders correctly
+- Directories first, alphabetical
+- Hides only well-known noise: `.git`, `.DS_Store`, `node_modules`, `__pycache__`. Other dotfiles (`.gitignore`, `.env`, `.vscode/` etc.) are shown — modern IDE convention
+- No max depth limit
+- Expansion state lives in localStorage; restored on refresh and lazily reloaded
+- WebSocket `file:changed` events incrementally update loaded branches; unloaded branches are left alone (re-fetched on expand)
+
+### Selection model
+VS Code-style highlight selection (no checkboxes):
+- **Click**: select and highlight
+- **Double click**: open in editor tab
+- **Ctrl/Cmd + click**: toggle multi-select
+- **Shift + click**: range select
+
+### Drag-move
+- Selected files/folders drag onto a target dir
+- Multi-file drag supported
+- Each file goes through `POST /api/files/rename` with `{oldPath, newPath}`
+
+### Right-click menu
+
+Items shown depend on the click target:
+
+| Action | Shown when | API / behavior |
+|---|---|---|
+| New File / New Folder | Always | `POST /api/files/new` · `mkdir`; auto-expands the parent folder so the inline input is visible |
+| Open in Integrated Terminal | Always | Spawns a terminal at the target dir (or file's parent) |
+| Open to the Side | File only | Splits the editor and opens the file in the right pane |
+| Download | File only | `GET /api/files/download?path=...` |
+| Rename | Single file/folder | `POST /api/files/rename` |
+| Delete | Single or multi-select | `DELETE /api/files?path=...` (with confirm) |
+| Open as Workspace | Folder only | Switches the active workspace to that folder, reusing the path-input switch flow (validate → persist → reload). Shown at the bottom of the menu |
+
+The menu auto-clamps to the viewport, so right-clicking near the window edge does not clip the bottom items.
+
+### Modification indicator
+Files with unsaved editor edits show a coloured dot in the tree (synced from `editorStore.modifiedPaths`).
+
+### Git decorations
+When the workspace is a git repo, the tree also colors file/folder names + badges by git status, and dims `.gitignore`'d paths — driven by `/api/git/status` + `/api/git/ignored`. See [source-control.md](source-control.md#explorer-git-decorations). (A real change wins over ignored; a non-repo workspace carries no decorations.)
+
+### File type icons
+Extension-to-icon mapping across common filetypes.
+
+### Quick Open
+- `Cmd+P` / `Ctrl+P` opens fuzzy file search
+- Query via `GET /api/files/search?projectId=X&q=...&limit=50` (150 ms debounce)
+- Empty query doesn't display (avoids scanning the whole project)
+- Enter opens in a new tab
+
+### `@` file mention (chat input)
+- Typing `@` in the chat input opens the file selector
+- Query via `GET /api/files/search?projectId=X&q=<after-@>&limit=15` (120 ms debounce)
+- Selecting inserts a path chip
+
+### `@scope` directory reference (chat input)
+- Typing `@scope ` opens a directory-only selector (query via `GET /api/files/search?...&dirsOnly=1`)
+- Unlike `@` mention (which lifts the path into a separate chip list), `@scope <dir>` stays as **literal text** in the message — the server expands it into that directory's scoped `.halo/INSTRUCTIONS.md` for the turn (see [prompt-system.md](../design/prompt-system.md#directory-scoped-instructions-scope))
+
+Quick Open and `@` mention both use the search API (not the lazy tree) so unexpanded files can still be found.

package/bundled-docs/requirements/overview.md

@@ -0,0 +1,62 @@
+# Product Overview
+
+> "Tiangong Kaiwu" — throw in an idea, the agents build it.
+> Halo = the international spelling of "Kaiwu"; "halo" in Finnish hints at a spring source.
+
+## One-liner
+
+**Halo is a multi-agent collaborative workspace. The user drives the entire delivery of complex projects through natural language.**
+
+## Problems it solves
+
+### 1. Multi-agent collaboration is opaque to users
+
+Cursor / Claude Code / Devin are developer tools at heart — users have to configure agents, manage context, wire up workflows. Halo hides the orchestration: users just chat; the main agent decides how to split up work.
+
+> Halo is a **self-orchestrating harness** wrapped in a human-readable workspace.
+
+### 2. Agent work products get lost
+
+Existing memory systems are patchwork — MEMORY.md is manual notes, vector search is semantic crumbs. An agent makes a slide deck and remembers "I made a slide deck", but the design thinking, iterations, reasoning chain are gone.
+
+Halo's answer: **everything lives in the workspace. Knowledge is tied to the project, not the agent.**
+
+## Role model
+
+```
+             User
+              |  natural language
+              v
+     +------------------+
+     |  Main Agent       |
+     |  (Orchestrator)   |
+     |  Understands intent,
+     |  decomposes tasks,
+     |  creates/schedules sub-agents,
+     |  escalates key decisions
+     +---+------+------+-+
+         |      |      |
+         v      v      v
+      Sub-A  Sub-B  Sub-C
+      (each with its own tools + skills)
+```
+
+**The main agent is a proposer, not a dictator.** It lays out the plan, the user asks "why", adjusts, confirms, and only then does it execute. The user can pause, revert, or redirect at any step.
+
+## Core principles
+
+1. **Thinking is visible** — the user sees task breakdowns, progress, file changes, tool calls. Not a black box.
+2. **User in the loop** — the user always has veto power. Any step can be paused, modified, or rejected.
+3. **Structured workspace** — all knowledge, decisions, rejected alternatives, and intermediate state are saved as project files. Agents don't need "memory" — they have archives.
+4. **Progressive autonomy** — v1: every step needs the human. v2: user-defined autonomy scope. v3: the agent decides what to ask and what to just do.
+
+## Competitive comparison
+
+| Dimension | Cursor / Claude Code | Devin | MetaGPT | Manus | **Halo** |
+|---|---|---|---|---|---|
+| Target user | Developers | Developers | Developers | General | **Anyone** |
+| Agent count | 1 | 1 | Multiple (preset) | 1 | **1 main + N sub** |
+| Orchestration | Manual | Black-box | Pipeline | Black-box | **Self-orchestrating + user override** |
+| Process visibility | Low | Low | None | Low | **High (the key differentiator)** |
+| Mid-run intervention | Yes | No | No | Limited | **Yes** |
+| Project memory | Limited | Limited | None | None | **Structured workspace** |

package/bundled-docs/requirements/session.md

@@ -0,0 +1,73 @@
+# Session — Requirements
+
+Session history viewer: hierarchy tree, message playback, debug mode, system prompt inspection.
+
+## Core behaviour
+
+### Session tree view
+- Top-level sessions (no parentSessionId) act as roots; child sessions render indented
+- Each row shows: title, agent-name badge, message count, 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
+- 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. Capped at 300 top-level rows — past that, "load more" stops (older sessions, e.g. from a busy Slack channel, aren't worth scrolling to)
+
+### Message viewer
+- All messages rendered by role
+- Assistant messages render Markdown
+- System messages summarise tool calls
+
+### 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
+
+### 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).
+
+### 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 and cascade-deletes all descendants in SQLite
+- Assistant messages embed a `toolCalls` array so tool-call cards persist across refresh
+
+### Non-destructive /session new
+`/session new` (session:clear) **does not** destroy the old session:
+1. Save current session to disk
+2. Create a background handler to keep the old session's in-flight events flowing
+3. Reset client state, enter empty conversation
+4. The old session's sub-agents keep running independently
+5. Switching back loads from the file
+
+## Session categorisation
+
+| Scenario | Display |
+|---|---|
+| Main session | Sidebar top level |
+| Child session (has parentSessionId) | Nested under parent |
+| Stopped session | 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
+
+Unified session logs API (recommended):
+
+| Operation | Endpoint |
+|---|---|
+| List | `GET /api/sessions/logs?projectId=...` |
+| Read | `GET /api/sessions/logs/:id?projectId=...` |
+| Delete | `DELETE /api/sessions/logs/:id?projectId=...` |
+
+The List endpoint serves two consumers: this tree view (default — roots + all
+descendants, paginated, rebuilt into a tree client-side) and the chat-header
+recent-sessions dropdown (`rootOnly=1` — a flat list of roots). Both paginate
+via `cursor` / `nextCursor`. See [dev/api.md](../dev/api.md#get-apisessionslogsprojectidabsrootonly01includearchived01cursormslimitn) for the full contract.
+
+Implementation detail: [design/session.md](../design/session.md).

package/bundled-docs/requirements/settings.md

@@ -0,0 +1,224 @@
+# Settings — Requirements
+
+Global + workspace configuration. The shape mirrors VSCode's `contributes.configuration` model: **schema** (declared by each package — provider yaml, skill yaml, server built-ins) is separate from **values** (stored in the user's `settings.yaml`).
+
+## Storage layout
+
+```yaml
+# ~/.halo/secrets/settings.yaml — values only
+general:                                  # built-in declarer (server itself)
+  session:
+    max_queue_size: 256
+    max_nesting_depth: 16
+  compact:
+    keep_messages: 5
+    max_summary_input: 15000
+    ...
+  sandbox:
+    hidden_dirs: "~/.halo/secrets,~/.aws,~/.ssh,~/.gnupg,~/.docker"
+    hidden_files: "~/.npmrc,~/.bash_history,~/.gitconfig"
+    writable_dirs: ""                     # e.g. ~/.kiro,~/.local/share/kiro-cli — rw bind-mounts in bwrap; ignored for readonly sessions
+  logging:
+    level: warn
+
+aws-bedrock-claude-invoke:                # provider id from models/<id>.yaml
+  secrets:
+    access_key_id: ""
+    secret_access_key: ""
+
+kimi:
+  secrets:
+    api_key: <<KIMI_API_KEY>>
+
+deepseek:
+  secrets:
+    api_key: <<DEEPSEEK_API_KEY>>
+
+tavily-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
+- `<kind>` is `param` or `secret`
+- `<key>` is the leaf, dotted for grouping (e.g. `general.compact.keep_messages`)
+
+`general` is the only namespace that doesn't follow the `<id>.{params|secrets}.<key>` pattern — its declared keys are flat (`general.<key>`) since the server is the implicit declarer.
+
+## Two kinds of fields
+
+| Kind | Reachable from agent? | UI render |
+|---|---|---|
+| **`params`** | Yes — via `{{<id>.params.<key>}}` placeholders. Substituted at `shell_exec` time. | Plain text / number input. |
+| **`secrets`** | Never. Server-side only (model providers, signing keys). The placeholder renderer rejects `{{<id>.secrets.…}}`; the API returns masked values to the browser. | Masked password input; `<<ENV>>` references shown plainly (they're not the real value). |
+
+## Schema declaration
+
+Schema lives **inside the package**, alongside its other files:
+
+### Provider secrets — `models/<provider-id>.yaml`
+
+```yaml
+id: aws-bedrock-claude-invoke
+displayName: AWS Bedrock Claude (Invoke API)
+defaultEndpoint: https://bedrock-runtime.us-west-2.amazonaws.com
+
+secrets:
+  - key: access_key_id
+    description: AWS Access Key ID
+    description_zh: AWS Access Key ID
+    secret: true
+  - key: secret_access_key
+    description: AWS Secret Access Key
+    description_zh: AWS Secret Access Key
+    secret: true
+
+models: [...]
+```
+
+### Skill params/secrets — `skills/<skill-id>/config.yaml`
+
+```yaml
+params:
+  - key: api_key
+    description: Tavily API Key
+    description_zh: Tavily 搜索 API Key
+    default: <<TAVILY_API_KEY>>
+    secret: true
+secrets: []
+```
+
+### 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.*`, `session.*`, `compact.*`, `sandbox.*`, `logging.*`, `evolution.*`, `limits.*`.
+
+`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).
+
+`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()`.
+
+### Field attributes
+
+| Attribute | Required | Purpose |
+|---|---|---|
+| `key` | yes | Leaf key under the namespace |
+| `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>>` |
+| `secret` | no | `true` → masked in API responses + password input in UI |
+
+## Scope: global vs. workspace
+
+| Scope | File | Priority |
+|---|---|---|
+| Global | `~/.halo/secrets/settings.yaml` | Base |
+| Workspace | `<project>/.halo/settings.yaml` | Overrides global, key by key |
+
+Read order: `<schema default> <- <global> <- <workspace>`.
+
+The Settings page shows source badges per field:
+- `workspace` (green-blue, override applied here)
+- `inherited from global` (grey, value pulled from global because workspace has none)
+- `unset` (no value at any layer; the `default` is shown as placeholder)
+
+A Reset button on each field removes the value at the current scope, letting it fall back to the lower scope (or unset).
+
+## Environment variable injection
+
+Values can carry `<<ENV_NAME>>` placeholders. They're expanded:
+- At `shell_exec` time inside values resolved through `{{<id>.params.<key>}}` — see [workspace-tools.ts](../../../packages/server/src/tools/workspace-tools.ts) `substituteSecrets`.
+- At read time when server-side code calls `getServerSecret(namespaceId, key)` — see [config.ts](../../../packages/server/src/config.ts).
+
+**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.
+
+## Agent visibility
+
+Placeholder syntax in MD bodies (SKILL.md / AGENT.md):
+
+| In MD body | Result |
+|---|---|
+| `{{<skill-id>.params.<key>}}` (long form) | Replaced with the value (after `<<ENV>>` resolution) at `shell_exec` time |
+| `{{params.<key>}}` (short form) inside a SKILL.md | Auto-rewritten to `{{<this-skill-id>.params.<key>}}` at `activate_skill` |
+| `{{<id>.secrets.<key>}}` | Hard-rejected — kept as literal, server logs a whitelist warning |
+| `{{general.compact.keep_messages}}` | Same — kept literal |
+| `{{args}}`, `{{workspace_root}}`, etc. | Built-ins, replaced at render time |
+
+Enforced in two places:
+- [md-vars.ts](../../../packages/server/src/prompts/md-vars.ts) `renderMdBody` — only matches `^[\w-]+\.params\.[\w-][\w.-]*$`.
+- [workspace-tools.ts](../../../packages/server/src/tools/workspace-tools.ts) `substituteSecrets` — same regex on `{{}}` placeholders.
+
+A malicious skill that tries `curl -H "Bearer {{aws-bedrock-claude-invoke.secrets.secret_access_key}}"` gets the literal placeholder, not the value.
+
+## 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.
+
+`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.
+
+## API
+
+| 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>` |
+| Delete key | DELETE | `/api/settings` | Remove a leaf (used for Reset / Remove orphan) |
+
+### `/api/settings/schema` response
+
+```json
+{
+  "scope": "global" | "workspace",
+  "sections": [
+    {
+      "namespaceId": "aws-bedrock-claude-invoke",
+      "source": "provider",
+      "displayName": "AWS Bedrock Claude (Invoke API)",
+      "description": "...",
+      "fields": [
+        {
+          "key": "access_key_id",
+          "kind": "secret",
+          "description": "AWS Access Key ID",
+          "description_zh": "...",
+          "default": null,
+          "secret": true,
+          "value": "AK****ST",
+          "hasValue": true,
+          "source": "global",
+          "inheritedFromGlobal": false
+        }
+      ]
+    }
+  ],
+  "orphans": [
+    { "namespaceId": "tavily", "kind": "param", "key": "api_key" }
+  ]
+}
+```
+
+### PATCH body
+
+```json
+{
+  "scope": "global" | "workspace",
+  "projectId": "...",            // required if scope=workspace
+  "key": "aws-bedrock-claude-invoke.secrets.access_key_id",
+  "value": "AKIA…"
+}
+```
+
+### 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.
+
+## i18n
+
+The admin UI is bilingual (en/zh). Field descriptions are localized via `description_zh` with fallback to `description`. Fixed UI labels live in `packages/admin/src/shared/i18n/`.
+
+## 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()`.

package/bundled-docs/requirements/skill.md

@@ -0,0 +1,125 @@
+# Skill — Requirements
+
+A skill is a knowledge pack an agent can reference — prompts, templates, scripts, reference docs.
+
+## Core behaviour
+
+### Mini workspace
+Clicking a skill in the sidebar turns the main area into a mini workspace:
+- File tree: every file in the skill directory
+- Monaco editor: edit any file (SKILL.md, templates, scripts)
+- Reuses the main workspace's editor / explorer components
+
+The skill editor runs in an **isolated** `EditorStoreProvider` — its tabs, file tree, and
+selection are independent of the main Explorer Canvas, so switching back to Explorer
+restores that Canvas untouched. The provider is keyed on `${id}:${scope}`, so switching
+between skills also resets the mini workspace (no cross-skill tab bleed). The maximize
+button is hidden in this mode (`showMaximize={false}`).
+
+### CRUD
+
+| Operation | API |
+|---|---|
+| List | `GET /api/skills?projectId=xxx` — returns BOTH global and workspace skills as separate entries (no merge); global entries shadowed by a same-id workspace skill are flagged `overridden: true` |
+| Create | `POST /api/skills` (body: name, description, scope, projectId) |
+| Delete | `DELETE /api/skills/:id?scope=...&projectId=...` |
+| Toggle disabled | `PATCH /api/skills/:id/toggle?scope=...&projectId=...` → `{ ok, disabled }` |
+
+### Scope (Global / Workspace)
+
+| Scope | Path | Notes |
+|---|---|---|
+| Global | `~/.halo/global/skills/<id>/` | Shared across projects |
+| Workspace | `<project>/.halo/skills/<id>/` | Wins over a same-id global skill at runtime |
+
+### 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)
+- 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.
+- 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)
+
+The Skills sidebar and any open mini-workspace editor stay in sync with the file system via `file:changed` WS events — but the server's watcher is scoped to the current workspace, so the guarantees differ by scope:
+
+| Change | Workspace skills | Global skills |
+|---|---|---|
+| Create / delete a skill dir | Live (watcher emits add/unlink → `skill-bus` bump → sidebar refetches) | Refreshed opportunistically on **window focus** |
+| Edit a file inside a skill while the mini-workspace editor has it open | Live (EditorPanel translates workspace-rel path into its own tab.path and refetches) | Live for the currently-open tab (same code path) — but the file tree change won't show new/removed sibling files until focus refresh |
+| Edit from external CLI / SSH | Same as above | Same as above |
+
+So when an agent (or the `skill` skill) creates a **global** skill, the Skills sidebar won't reflect it until the user refocuses the browser window. The `skill` skill documents this so agents can warn the user.
+
+### SKILL.md protocol
+
+```markdown
+---
+name: code-review
+description: Automated code review with checklist
+command: /review
+---
+
+# Code Review
+
+Review the code for:
+1. Correctness
+2. Performance
+...
+```
+
+- **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)
+- **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).
+
+### Access-level gate (`requiresAccess`)
+
+A skill can declare a minimum session access level in frontmatter:
+
+```yaml
+---
+name: workspace
+description: ...
+command: /workspace
+requiresAccess: workspace
+---
+```
+
+When set, the skill is hidden from agents whose session access level is more restricted (e.g. a `readonly` Telegram channel can't see or invoke a `requiresAccess: full` skill). The check runs both at metadata-load time (so it never enters the system prompt's `<available_skills>` block) and at slash-command execution time (server-side gate, so a user typing the slash manually still hits it). `requiresAccess` is independent of `command`: an agent-activated-only skill (no `command`) is still hidden from too-restricted sessions.
+
+Default is unset → the skill is visible to all access levels. `full` is the standard "admin-only" marker for skills that mutate global state (cron, self, etc.).
+
+### Settings integration
+
+When a skill needs configuration (API keys, endpoints, preset values):
+1. Declare them in a `config.yaml` next to `SKILL.md` — schema lives with the package
+2. Reference them from the SKILL.md body with the short form `{{params.<key>}}` (auto-qualified to `{{<skill-id>.params.<key>}}` at activation)
+3. Values live in `~/.halo/secrets/settings.yaml` at `<skill-id>.params.<key>` — written by the user via the Settings page or by hand
+4. Use `<<ENV_NAME>>` placeholders for sensitive values; the real value comes from env vars at render time
+
+Full rules: [guide/skills.md](../guide/skills.md#placeholders-template-variables) and [requirements/settings.md](settings.md).
+
+### Agent references
+Agents reference skills by id in `agent.yaml`'s `skills` field:
+
+```yaml
+skills:
+  - code-review
+  - test-writer
+```
+
+Runtime uses **progressive disclosure**:
+1. **Discovery**: only skill metadata (name + description) is injected into the system prompt
+2. **Activation**: the agent calls `activate_skill(skill_id)` to load the full SKILL.md
+3. **Execution**: the agent follows the loaded instructions; `file_read` can pull resources from the skill directory
+
+Avoids bloating the system prompt with unused skill content.