@turmind/halo 0.1.9

package/bundled-docs/guide/secrets-and-credentials.md

@@ -0,0 +1,161 @@
+# Secrets and Credentials
+
+How to give a skill or agent an API key / token / password without committing it to a repo or hard-coding it in a skill body.
+
+## The model: schema vs. value
+
+Halo's settings system mirrors VSCode's `contributes.configuration` pattern:
+
+| Side | What lives there | Where |
+|---|---|---|
+| **Schema** (declaration) | "This provider/skill needs a key called X, here's its description, and here's whether it's a secret" | Inside the package: `models/<provider-id>.yaml` `secrets:` section · `skills/<skill-id>/config.yaml` `params:` / `secrets:` sections |
+| **Value** | The user's actual key | `~/.halo/secrets/settings.yaml` (global) or `<workspace>/.halo/settings.yaml` (workspace overlay) |
+
+Removing or disabling a package only takes its **schema** out of the registry; values stay in `settings.yaml` and re-attach automatically if the same id comes back. The Settings page surfaces leftover values in an "Unclaimed" list so the user can prune them on their own schedule.
+
+## Two kinds of declared fields
+
+| Kind | Reachable from agent? | Storage path | Render |
+|---|---|---|---|
+| **`secrets`** | Never. Server-side only — model providers, OAuth app credentials, signing keys. | `<id>.secrets.<key>` | UI masks the value; the placeholder renderer rejects `{{<id>.secrets.…}}` so nothing leaks into prompts. |
+| **`params`** | Yes, via `{{<id>.params.<key>}}`. Use this for keys a skill needs to inject into its own `shell_exec` (e.g. Tavily search). | `<id>.params.<key>` | Substituted at `shell_exec` time inside the skill's command. |
+
+The boundary is enforced by:
+- [packages/server/src/prompts/md-vars.ts](../../../packages/server/src/prompts/md-vars.ts) — `renderMdBody` only replaces `{{<id>.params.<key>}}`; anything else stays literal.
+- [packages/server/src/tools/workspace-tools.ts](../../../packages/server/src/tools/workspace-tools.ts) — `substituteSecrets` does the same on every `shell_exec` call.
+
+A malicious agent that tries `curl -H "Bearer {{aws-bedrock-claude-invoke.secrets.secret_access_key}}"` gets the literal placeholder, not the value.
+
+## Worked example: a skill that needs an API key
+
+Goal: a skill called `caption-image` that calls `api.example.com` with an API key.
+
+### Step 1 — declare in the skill's `config.yaml`
+
+Beside `SKILL.md`:
+
+```yaml
+# extensions/skills/caption-image/config.yaml
+params:
+  - key: api_key
+    description: API key for api.example.com
+    description_zh: api.example.com 的 API Key
+    default: <<EXAMPLE_KEY>>      # placeholder shown in UI when value is unset
+    secret: true                  # UI masks the input + API response
+  - key: base_url
+    description: Endpoint base URL
+    default: https://api.example.com
+```
+
+The schema is what the package ships. The Settings page reads it and renders inputs.
+
+### Step 2 — set the value
+
+Two options:
+
+- **From the Settings page** — open the `caption-image` section, type the key, save. The value is written to `~/.halo/secrets/settings.yaml` at `caption-image.params.api_key`.
+- **Via env var** — leave the value as `<<EXAMPLE_KEY>>` (the default) and `export EXAMPLE_KEY=...` on the host. Both work; env vars are friendlier for ops automation, settings are friendlier for one-off keys.
+
+In either case the rendered value travels through the normal `<<ENV_NAME>>` → `process.env.ENV_NAME` resolution.
+
+### Step 3 — reference from `SKILL.md`
+
+Inside the skill's body you can write the **short form** — Halo auto-qualifies it with the skill id when `activate_skill` fires:
+
+```markdown
+---
+name: Caption Image
+description: Generate a caption for an image using the Example API
+---
+
+# Caption Image
+
+Call the endpoint `{{params.base_url}}/caption`:
+
+- Method: POST
+- Header: `Authorization: Bearer {{params.api_key}}`
+```
+
+Behind the scenes the activation rewrites `{{params.base_url}}` → `{{caption-image.params.base_url}}` before the body is shown to the agent. By the time `shell_exec` runs the curl, `workspace-tools` substitutes the real value.
+
+You can also write the long form `{{caption-image.params.api_key}}` directly if you prefer it explicit (e.g. when one skill references another's params).
+
+## Workspace overlay
+
+`<workspace>/.halo/settings.yaml` deep-merges on top of the global file, key by key. So a project-specific Tavily key would live at:
+
+```yaml
+# /home/me/myproject/.halo/settings.yaml
+tavily-search:
+  params:
+    api_key: tvly-project-specific-…
+```
+
+…and overrides whatever sits at `tavily-search.params.api_key` in `~/.halo/secrets/settings.yaml`. The Settings UI shows source badges (`workspace` / `inherited from global` / `unset`) and an explicit Reset button to drop a workspace override.
+
+## Precedence
+
+```
+env vars (process.env.X) > workspace settings.yaml > global settings.yaml > schema default
+```
+
+`<<ENV_NAME>>` substitution happens **at render time** — right before the skill/agent body is handed to the LLM, and at `shell_exec` time inside values that came from a `{{<id>.params.<key>}}` lookup.
+
+**Trust boundary**: `<<ENV>>` is only honored inside settings-resolved values. Cmd text the agent writes directly 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.
+
+## Missing env var
+
+If `process.env.EXAMPLE_KEY` is unset and the value at `caption-image.params.api_key` is `<<EXAMPLE_KEY>>`:
+- The agent sees the literal `<<EXAMPLE_KEY>>` in the rendered skill body
+- The server logs `[md-vars] Env var "EXAMPLE_KEY" not set — keeping <<EXAMPLE_KEY>> literal`
+- API calls the agent makes will fail with a clear error (usually HTTP 401) and the error message will reveal the literal, so the user can tell what to fix
+
+This is intentional: empty strings hide the misconfiguration; literals make it visible.
+
+## Placeholder rules
+
+In an MD body, `{{xxx}}` is resolved as:
+
+1. **No dots** → built-in (`args`, `workspace_root`, `working_dir`, `now`, `user_name`, `ai_name`, `agent_name`)
+2. **Matches `<id>.params.<key>`** → settings tree lookup, then `<<ENV>>` expansion
+3. **Anything else** → kept literal + warning logged
+
+| In MD body | Result |
+|---|---|
+| `{{caption-image.params.api_key}}` | Replaced with the value (after `<<ENV>>` resolution) |
+| `{{params.api_key}}` inside a SKILL.md | Auto-rewritten to `{{<this-skill-id>.params.api_key}}` at `activate_skill` time |
+| `{{aws-bedrock-claude-invoke.secrets.access_key_id}}` | Kept as literal — the renderer hard-rejects `secrets.*` paths |
+| `{{general.compact.keep_messages}}` | Same — kept literal |
+| `{{args}}`, `{{workspace_root}}`, etc. | Built-ins, replaced |
+
+This whitelist is the single defence preventing prompt-injection-style theft of server-side secrets via skill content.
+
+## What NOT to do
+
+| Anti-pattern | Why it's bad | Right fix |
+|---|---|---|
+| Paste the key directly into `SKILL.md` | The SKILL is usually git-tracked or shared; the key leaks | Use `{{params.api_key}}` |
+| Paste the key into `settings.yaml` and commit it | The file holds real secrets | Set the value to `<<KEY>>` + `export KEY=...` |
+| Store the key in `AGENT.md` | Same reason | Use a `params:` declaration on the agent or a skill it depends on |
+| Put a model-provider key under a skill's `params:` | Any agent could borrow it via `shell_exec` | Declare it as `secrets:` in the model provider yaml |
+| Reference `{{<id>.secrets.x}}` from a skill body | Hard-rejected — kept as literal | If a skill genuinely needs server-side credentials, that's a sign it should be a server tool, not a `shell_exec` skill |
+
+## Rotating a credential
+
+1. Generate the new value
+2. Either edit it in the Settings page (writes `settings.yaml` immediately), or update the env var and restart the server
+3. Existing running sessions keep the old value baked into already-rendered SKILL bodies of previous `activate_skill` calls. They pick up the new value on the next activation.
+
+No code change. No yaml schema change.
+
+## Env var naming conventions
+
+Free-form, but consistency helps. Common patterns in Halo:
+
+| Env var | Purpose |
+|---|---|
+| `HALO_PASSWORD` | Server login password |
+| `HALO_MODEL_ID` / `HALO_MODEL_PROVIDER` / `HALO_MAX_CONTEXT_TOKENS` | Server defaults |
+| `AWS_REGION` / `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | AWS / Bedrock |
+
+For your own skills, `UPPER_SNAKE` prefixed by the product is idiomatic (`NANO_BANANA_KEY`, `EXAMPLE_API_TOKEN`). The placeholder is case-sensitive — `<<example_key>>` won't match `EXAMPLE_KEY`.

package/bundled-docs/guide/sessions.md

@@ -0,0 +1,104 @@
+# Sessions — User Guide
+
+A session is "one continuous conversation with an agent". It includes your conversation with the main agent plus any sub-agents the main agent spawns.
+
+## Sessions panel
+
+Left-side Activity Bar → `📨 Sessions` (message icon).
+
+```
+┌─────────────────┬──────────────────────────┐
+│ Sessions        │  Message viewer          │
+│─────────────────│                          │
+│ ▼ My task      │                          │
+│   📨 user msg   │                          │
+│ ▶ └ 🤖 coder    │                          │
+│ ▶ └ 🤖 sleeper  │                          │
+│ 📨 Old chat     │                          │
+└─────────────────┴──────────────────────────┘
+```
+
+## Hierarchy tree
+
+The main agent (the one you talk to directly) sits at the top; any sub-agents it delegates to are shown indented.
+
+- Collapse/expand: click the arrow
+- Count badge `+3`: 3 descendants
+- Red ⏹ icon: session was stopped (stopped_at is set)
+
+## Message viewer
+
+Click a session on the left to open the viewer:
+- User messages and assistant replies (Markdown)
+- Tool-call cards (expandable for input/output)
+- Timestamps and agent-name badges
+
+## Debug mode
+
+Top-right Bug icon toggles it. When on you also see:
+
+| Colour | Type | Content |
+|---|---|---|
+| Purple | Context | Full system prompt |
+| Blue | Tool Call | Full tool input JSON |
+| Green/Red | Tool Result | Full tool output |
+| — | Usage | Token counts / latency / cache hit% / model ID |
+
+**Essential for debugging and reviewing agent behaviour.**
+
+## System prompt viewer
+
+In Debug mode the top-right gets an extra `Prompt` button; click to expand the full system prompt (AGENT.md + INSTRUCTIONS.md + INDEX.md + TOOL_GUIDELINES + skill metadata).
+
+Use it to see exactly what context the agent was given for a given turn.
+
+## Non-destructive /session new
+
+Typing `/session new` in the chat:
+1. Saves the current session to disk
+2. Creates a background handler to keep the old session's in-flight events flowing
+3. UI resets to an empty session
+4. **The old session's sub-agents keep running** (not killed)
+
+When you switch back, the background-finished events are already in the file and render normally.
+
+## Refresh / reconnect
+
+Refreshing the browser or a network blip:
+- SessionManager keeps the session alive for the grace period (5 minutes)
+- On reconnect, messageLog + in-flight streaming state are restored from disk
+- If the agent is still running, live streaming resumes; if it finished, the full history loads
+
+## Deleting a session
+
+Right-click a session → Delete:
+- Cascade delete in SQLite (parent + all descendants)
+- `.halo/sessions/{agentId}/{sid}.json` removed
+- Sidebar entry removed
+
+**Not recoverable** — be careful.
+
+## Session tools (agent-side)
+
+Agents can manage other sessions via tools. The whole bundle is granted automatically when an agent declares a non-empty `team` in `agent.yaml` (no separate tool checklist); empty or absent `team` = no delegation:
+
+| Tool | Purpose |
+|---|---|
+| `start_session` | Start a sub-agent, asynchronous, auto-reports on completion |
+| `session_list` | List the current session's children |
+| `query_session` | Send a message to a session (idle = run now, busy = queue) |
+| `interrupt_session` | Interrupt + re-run |
+| `stop_session` | Stop (no re-run, recoverable) |
+| `archive_session` | Cascade archive (not recoverable) |
+| `get_session_output` | Read a session's latest turn output |
+| `query_agent` | Inspect another agent (team-gated to the roster) |
+
+See [dev/tools.md](../dev/tools.md).
+
+## Scenarios
+
+**Figuring out why an agent messed up**: open the session → Debug mode → scroll through tool-call cards to see inputs and outputs.
+
+**Reusing a historical task**: find a relevant session → click `Prompt` → copy the system prompt into a new agent's AGENT.md.
+
+**Following multi-level delegation**: within the depth-16 cap, the indented tree is easy to follow; click any sub-session to see exactly what it did.

package/bundled-docs/guide/skills.md

@@ -0,0 +1,302 @@
+# Skills — User Guide
+
+A skill is a "knowledge pack" an agent can reference — a detailed instruction set plus optional templates or scripts.
+
+## Why skills
+
+To extract capabilities an agent uses occasionally but needs full instructions for. For example:
+- "Code Review": review code against a checklist
+- "Deploy check": the pre-deploy checklist
+- "Translate to academic English": a specific translation flow
+
+Putting those in AGENT.md would bloat the system prompt. Skills use **progressive disclosure**:
+1. On startup the agent only sees each skill's name + description
+2. When the user triggers the skill or the agent decides it needs it, it calls `activate_skill` to load the full body
+
+## Directory layout
+
+```
+~/.halo/global/skills/               # Global skills
+  code-review/
+    SKILL.md
+    checklist.md
+    examples/review-sample.md
+
+<project>/.halo/skills/              # Workspace skills
+  deploy-check/
+    SKILL.md
+    scripts/verify.sh
+```
+
+Workspace overrides global (same id).
+
+**Built-in skills** (`agent`, `skill`, `workspace`, `cron`, `acp`, `send-file`, `self`, `aws-knowledge`, `nova-web-search`) are server-shipped and **force-overwritten on every server startup**. Local edits to these directories under `~/.halo/global/skills/` will be lost. To customize one, copy it into `<project>/.halo/skills/<id>/` (workspace replaces global) and edit there. Other skills under `~/.halo/global/skills/` — including any the user created via the admin UI — are untouched by the seeder.
+
+## SKILL.md format
+
+```markdown
+---
+name: code-review
+description: Review code for correctness, performance, and style
+command: /review       # optional: also register a slash command
+---
+
+# Code Review
+
+Review the code for:
+
+1. Correctness bugs
+2. Performance issues
+3. Style / consistency with codebase
+
+Follow the checklist in checklist.md...
+```
+
+**Frontmatter fields**:
+| Field | Required | Purpose |
+|---|---|---|
+| name | yes | kebab-case, = directory name (lowercase / digits / hyphens, ≤64) |
+| description | yes | One-line description (what agents see at discovery time) |
+| command | no | Also register as a slash command (`/xxx` user-triggerable) — opt-in, unlike the upstream Agent Skills standard where the directory name automatically becomes a command |
+
+**Body**: the full instructions, returned when the agent calls `activate_skill(skill_id)`.
+
+## Open the Skills panel
+
+Left-side Activity Bar → `🪄 Skills` icon.
+
+Click any skill and the right pane becomes a mini workspace:
+- File tree (every file in the skill directory) on the left
+- Monaco editor + Markdown preview on the right
+
+You can edit SKILL.md, add scripts, templates, example docs.
+
+## Create / delete
+
+`+` button on the sidebar — fill in name / description / scope.
+
+Delete: right-click → Delete.
+
+## Letting an agent use a skill
+
+Edit agent.yaml:
+
+```yaml
+skills:
+  - code-review
+  - deploy-check
+```
+
+After Save, from the next conversation:
+- The system prompt gets `<available_skills> <skill><name>...</name><id>...</id>... </skill> </available_skills>`
+- The agent automatically receives the `activate_skill` tool
+
+When the agent decides a skill fits, it calls `activate_skill(skill_id='code-review')`, receives the full SKILL.md, and follows the instructions.
+
+## Skill-as-Command
+
+When SKILL.md frontmatter has a `command` field, the user can slash-trigger it:
+
+```
+User: /review src/foo.ts
+```
+
+Halo renders the SKILL.md body (user args reach it via `$ARGUMENTS` / `$1`–`$9` placeholders — they are not appended to the end) and sends it as a message for the agent:
+
+```
+[Skill activated: /review]
+
+{SKILL.md body, with $ARGUMENTS → "src/foo.ts"}
+```
+
+The agent follows the skill's instructions.
+
+## Resource files
+
+Files in the same directory as SKILL.md are listed at the end of `activate_skill`'s return:
+
+```
+Resource files in skill directory:
+- checklist.md
+- examples/review-sample.md
+```
+
+The agent uses `file_read` to load them on demand.
+
+## Settings integration
+
+For configurable parameters (API keys, regions, model presets), declare them in a `config.yaml` next to `SKILL.md` and reference them from the body with `{{params.x}}` (short form — auto-qualified to `{{<skill-id>.params.x}}` at activation). See [Placeholders (template variables)](#placeholders-template-variables) below.
+
+`config.yaml` example (sits beside `SKILL.md`):
+
+```yaml
+params:
+  - key: api_key
+    description: API key for the Example service
+    default: <<EXAMPLE_KEY>>
+    secret: true
+secrets: []   # rare for skills — server-side only, never substituted into shell_exec
+```
+
+The Settings page reads this declaration and renders inputs grouped under the skill's name. The user's value lands in `~/.halo/secrets/settings.yaml` at `<skill-id>.params.api_key`.
+
+> Credentials **do not** belong directly in `settings.yaml` — use `<<ENV_NAME>>` placeholders with the real value in env vars, or type them once into the Settings page (which still encrypts in the UI but stores plaintext on disk). Don't write credentials in SKILL.md either. SKILL.md + the schema in `config.yaml` are meant to be shareable; values are the user's.
+
+See the full credential model at [secrets-and-credentials.md](secrets-and-credentials.md).
+
+## Built-in skills
+
+Halo seeds these skills on every startup (the ids in `BUILTIN_SKILL_IDS`, `packages/server/src/init.ts`):
+
+| ID | Purpose |
+|---|---|
+| agent | Create / update agents — backs the `create` / `update` verbs of `/agent` |
+| skill | Create / update skills — backs the `create` / `update` verbs of `/skill` |
+| workspace | Workspace maintenance — backs `/workspace setup` / `tidy` (init / reorganize `.halo/` INDEX.md / INSTRUCTIONS.md / memory/) and `/workspace share` (export a shareable bundle) |
+| cron | Create / list / update / enable / disable / delete scheduled agent runs — backs `/cron` |
+| acp | Talk to other agents over ACP (`/acp kiro\|claude <q>`) and manage `ask-<label>` bindings for halo-to-halo delegation (`/acp add\|list\|remove`) |
+| send-file | Deliver an image/video/file as a channel attachment by emitting `MEDIA:<absolute_path>` — works on Web / WeChat / Telegram / Slack / Feishu (no command; model-activated, workspace access) |
+| self | The agent's own visual space (`.halo/canvas/self.html`) for self-expression (no command; model-activated, full access) |
+| aws-knowledge | Query the official AWS Knowledge MCP server for up-to-date AWS docs (no command, `user-invocable: false`; model auto-activates) |
+| nova-web-search | Real-time web search via Amazon Nova 2 Lite's nova_grounding (no command, `user-invocable: false`; model auto-activates) |
+
+All live under `~/.halo/global/skills/` and are force-overwritten on startup. To customize one, copy it into `<project>/.halo/skills/<id>/` and edit there (workspace overrides global). `tavily-web-search` remains an optional (non-seeded) skill.
+
+## SKILL.md field reference
+
+Frontmatter fields (Halo dialect of the Agent Skills standard):
+
+```markdown
+---
+name: code-review                    # required, kebab-case, = directory name
+description: Review code changes     # required, one-line description (agents use this to decide when to activate)
+command: /review                     # optional, register as a slash command (opt-in)
+requiresAccess: workspace            # optional (Halo), object-level access gate: full | workspace | readonly
+verbs:                               # optional (Halo extension), subcommand declarations
+  - { name: list, builtin: true, desc: List things }
+  - { name: create, requiresAccess: full, desc: Create a thing }
+disable-model-invocation: true       # optional (standard), command stays but the model can't auto-activate
+user-invocable: false                # optional (standard), never becomes a slash command; model can still activate
+---
+
+# Skill Body...
+```
+
+**Field notes**:
+
+| Field | Required | Purpose |
+|---|---|---|
+| name | yes | kebab-case, = directory name; appears in the agent system prompt's `<available_skills>` block |
+| description | yes | Helps agents decide when to activate |
+| command | no | Register a slash command — see Skill-as-Command above |
+| requiresAccess | no | Halo-specific access gate (`full` / `workspace` / `readonly`) for the whole skill |
+| verbs | no | **Halo extension** — list of `{ name, builtin?, requiresAccess?, desc? }`. `builtin: true` marks a verb handled by platform code (declarative; actual routing lives in `SUBCOMMAND_ROUTES`); skill verbs take their access gate from this declaration. The verb reaches the body via `$1` |
+| disable-model-invocation | no | Standard — `true` keeps the slash command but the skill isn't injected for the model (no auto-activation) |
+| user-invocable | no | Standard — `false` means no slash command ever; the model can still activate it |
+
+> **Disable / Enable**: managed per workspace in the `disabled_items` table of `halo.db` (not in SKILL.md). Toggle via admin sidebar or `/skill disable|enable`; disabled skills are excluded from system prompt injection, activate_skill tool, agent form picker, and `/workspace share` export. Still visible in admin sidebar (dimmed + toggle switch).
+
+**Minimal SKILL.md**: frontmatter with `name` + `description` + body; everything else is optional.
+
+**What `activate_skill` returns**:
+
+```
+# Skill: {name}
+
+{body}
+
+Resource files in skill directory:
+- checklist.md
+- examples/review.md
+...
+```
+
+**When a skill auto-injects**: whenever `agent.yaml`'s `skills` lists that skill's id. Skills not in the list are invisible to the agent (but the user can still trigger via `/command` if registered).
+
+## Placeholders (template variables)
+
+SKILL.md body supports `{{var}}` placeholders, rendered on activation. AGENT.md uses the same syntax.
+
+User command-line args additionally use the **standard** syntax `$ARGUMENTS` / `$1`–`$9` (quote-aware; `\$` escapes; `$5.00` / `$12` / `$PATH` are left alone). The two systems coexist without cross-translation: `$…` carries user args, `{{…}}` carries Halo-injected values. For object commands, the verb arrives as `$1`.
+
+### Built-ins (no dot)
+
+| Variable | Description |
+|---|---|
+| `{{args}}` | User args from a slash command. Empty string when invoked via `activate_skill` |
+| `{{workspace_root}}` | Current workspace absolute path |
+| `{{working_dir}}` | Agent's working_dir (defaults to workspace_root) |
+| `{{now}}` | ISO8601 timestamp |
+| `{{user_name}}` / `{{ai_name}}` | From USER.md frontmatter |
+| `{{agent_name}}` | Current agent's display name |
+
+### Settings paths (dotted)
+
+`{{<id>.params.<key>}}` looks up a declared param and substitutes its value. Only `params` paths are substituted — `secrets` paths and anything else (`general.*`, top-level keys) stay as literal text. The `<id>` is the namespace declared in `models/<provider>.yaml` or `skills/<skill-id>/config.yaml`.
+
+**Short form inside SKILL.md** — drop the namespace; activation auto-qualifies it for you:
+
+```markdown
+---
+name: Nano Banana Caption
+---
+
+Call API `{{params.base_url}}` with key `{{params.api_key}}`.
+Max `{{params.max_files}}` files per run.
+Files: {{args}}
+```
+
+If the skill id is `nano-banana`, those become `{{nano-banana.params.base_url}}` / `{{nano-banana.params.api_key}}` / `{{nano-banana.params.max_files}}` before reaching the agent.
+
+**`<skill-dir>/config.yaml`** declares what's needed:
+
+```yaml
+params:
+  - key: api_key
+    description: Nano Banana API key
+    default: <<NANO_BANANA_KEY>>
+    secret: true
+  - key: base_url
+    description: API endpoint
+    default: https://api.nano-banana.example
+  - key: max_files
+    description: Max files per review pass
+    default: "10"
+```
+
+**`~/.halo/secrets/settings.yaml`** holds the values (created by the Settings UI):
+
+```yaml
+nano-banana:
+  params:
+    api_key: <<NANO_BANANA_KEY>>
+    base_url: https://api.nano-banana.example
+    max_files: 10
+```
+
+### Resolution rules
+
+1. **Merge order**: workspace `<project>/.halo/settings.yaml` deep-merges over global `~/.halo/secrets/settings.yaml` (field-level merge, not block replacement)
+2. **Env vars**: `<<ENV_NAME>>` inside a value is replaced with `process.env.ENV_NAME` at render time. **If the env var is missing, the `<<ENV_NAME>>` literal is kept** so agents can see what's unset and the user can fix it
+3. **Unknown placeholders** stay as-is (e.g. `{{foo}}`, `{{nano-banana.params.missing-key}}`); the server logs a `[md-vars] Unknown placeholder "…"` warning
+4. **Key charset**: `[\w-]`, hyphens allowed (e.g. `nano-banana`)
+
+### Why put credentials in env vars
+
+So settings.yaml can go to git or be shared:
+- `<<NANO_BANANA_KEY>>` only describes "there should be a key here", it doesn't expose the value
+- Deploy with `export NANO_BANANA_KEY=xxx`; the agent only sees the real value at render time
+- Unset env var → the agent sees the literal `<<NANO_BANANA_KEY>>`, making it obvious what's missing
+
+### Two activation paths
+
+- Skill-as-command (`/review xxx`): `{{args}}` = the user's args
+- `activate_skill(skill_id)` tool: `{{args}}` = empty string
+
+Settings and env placeholders render identically either way.
+
+### AGENT.md placeholders
+
+AGENT.md runs through the same renderer; on session start, placeholders in the agent personality are substituted before injection. Useful for wiring API config into an agent ("You use `{{weather-skill.params.endpoint}}`"). AGENT.md must use the **fully-qualified** form (no short-form rewrite happens here — that's a skill-only convenience).
+
+Implementation: [md-vars.ts](../../../packages/server/src/prompts/md-vars.ts) `renderMdBody` — the shared entry point for both skill and agent rendering.