mercury-agent 0.5.0 → 0.5.2

package/resources/skills/recall/SKILL.md

@@ -1,24 +1,24 @@
----
-name: recall
-description: Search past user and assistant messages in this space when the user asks what was said before, wants a fact from an earlier turn, or the current prompt does not include enough history. Use mrctl recall with keywords from the topic.
----
-
-## Command
-
-```bash
-mrctl recall "<keywords or phrase>" [--limit N]
-```
-
-- Searches stored Mercury message history (case-insensitive substring match).
-- Default `--limit` is 20 (max 100 on the server).
-- Requires the same permission as `mrctl compact` (`compact`).
-
-## When to use
-
-- User references something from "earlier" or "before" and the pi session may be minimal or compacted.
-- You need to verify an exact prior message without loading the full session into context.
-
-## When not to use
-
-- For durable notes and vault content, prefer `napkin search` (when the napkin extension is enabled).
-- For the current conversation turn, rely on the user message and attached reply context first.
+---
+name: recall
+description: Search past user and assistant messages in this space when the user asks what was said before, wants a fact from an earlier turn, or the current prompt does not include enough history. Use mrctl recall with keywords from the topic.
+---
+
+## Command
+
+```bash
+mrctl recall "<keywords or phrase>" [--limit N]
+```
+
+- Searches stored Mercury message history (case-insensitive substring match).
+- Default `--limit` is 20 (max 100 on the server).
+- Requires the same permission as `mrctl compact` (`compact`).
+
+## When to use
+
+- User references something from "earlier" or "before" and the pi session may be minimal or compacted.
+- You need to verify an exact prior message without loading the full session into context.
+
+## When not to use
+
+- For durable notes and vault content, prefer `napkin search` (when the napkin extension is enabled).
+- For the current conversation turn, rely on the user message and attached reply context first.

package/resources/skills/roles/SKILL.md

@@ -1,18 +1,18 @@
----
-name: roles
-description: Manage user roles in the current space. Use when the user asks to grant or revoke permissions, make someone an admin, or check who has access.
----
-
-## Commands
-
-```bash
-mrctl roles list
-mrctl roles grant <platform-user-id> [--role <role>]
-mrctl roles revoke <platform-user-id>
-```
-
-## Roles
-
-- **admin** — full control over all features (default when granting)
-- **member** — can chat with the assistant (default for new users)
-- Custom roles can be created by assigning specific permissions
+---
+name: roles
+description: Manage user roles in the current space. Use when the user asks to grant or revoke permissions, make someone an admin, or check who has access.
+---
+
+## Commands
+
+```bash
+mrctl roles list
+mrctl roles grant <platform-user-id> [--role <role>]
+mrctl roles revoke <platform-user-id>
+```
+
+## Roles
+
+- **admin** — full control over all features (default when granting)
+- **member** — can chat with the assistant (default for new users)
+- Custom roles can be created by assigning specific permissions

package/resources/skills/spaces/SKILL.md

@@ -1,18 +1,18 @@
----
-name: spaces
-description: Manage spaces. Use when the user asks about spaces, wants to rename the current space, or delete space data.
----
-
-## Commands
-
-```bash
-mrctl spaces list
-mrctl spaces name [<name>]
-mrctl spaces delete
-```
-
-## Details
-
-- `list` — shows all spaces with display names (admin-only; members get 403)
-- `name` — with no argument, shows current space name; with argument, renames
-- `delete` — deletes the current space and all its data (irreversible)
+---
+name: spaces
+description: Manage spaces. Use when the user asks about spaces, wants to rename the current space, or delete space data.
+---
+
+## Commands
+
+```bash
+mrctl spaces list
+mrctl spaces name [<name>]
+mrctl spaces delete
+```
+
+## Details
+
+- `list` — shows all spaces with display names (admin-only; members get 403)
+- `name` — with no argument, shows current space name; with argument, renames
+- `delete` — deletes the current space and all its data (irreversible)

package/resources/skills/tasks/SKILL.md

@@ -1,45 +1,45 @@
----
-name: tasks
-description: Manage scheduled tasks — create cron jobs or one-shot reminders that run prompts on a schedule. Use when the user asks to schedule something, set a reminder, or manage recurring tasks.
----
-
-## Commands
-
-```bash
-mrctl tasks list
-mrctl tasks create --cron "<expr>" --prompt "<text>" [--timezone "<IANA>"] [--silent]
-mrctl tasks create --at "<ISO8601>" --prompt "<text>" [--silent]
-mrctl tasks pause <id>
-mrctl tasks resume <id>
-mrctl tasks run <id>
-mrctl tasks delete <id>
-```
-
-## Cron expressions
-
-Standard 5-field cron: minute hour day-of-month month day-of-week
-
-Examples:
-- `0 9 * * *` — daily at 9am
-- `*/30 * * * *` — every 30 minutes
-- `0 9 * * 1` — every Monday at 9am
-- `0 0 1 * *` — first day of each month
-
-## One-shot tasks
-
-Use `--at` with ISO 8601 timestamp for one-time execution:
-- `--at "2026-03-05T10:00:00Z"`
-
-## Timezone
-
-**Always pass `--timezone`** when creating cron tasks. Infer the user's timezone from:
-1. Explicit mention (e.g. "Israel time", "EST")
-2. Language/locale context (e.g. Hebrew → "Asia/Jerusalem")
-3. Prior conversation context
-
-If you cannot determine the timezone, ask the user before creating the task. Never omit `--timezone` for cron tasks — omitting it causes the task to fire at UTC, which is almost never what the user intends.
-
-## Options
-
-- `--timezone "<IANA>"` — IANA timezone for cron evaluation (e.g. `"Asia/Jerusalem"`, `"America/New_York"`). Falls back to the agent's configured default timezone, then UTC.
-- `--silent` — task runs but output is not sent to chat (useful for background work)
+---
+name: tasks
+description: Manage scheduled tasks — create cron jobs or one-shot reminders that run prompts on a schedule. Use when the user asks to schedule something, set a reminder, or manage recurring tasks.
+---
+
+## Commands
+
+```bash
+mrctl tasks list
+mrctl tasks create --cron "<expr>" --prompt "<text>" [--timezone "<IANA>"] [--silent]
+mrctl tasks create --at "<ISO8601>" --prompt "<text>" [--silent]
+mrctl tasks pause <id>
+mrctl tasks resume <id>
+mrctl tasks run <id>
+mrctl tasks delete <id>
+```
+
+## Cron expressions
+
+Standard 5-field cron: minute hour day-of-month month day-of-week
+
+Examples:
+- `0 9 * * *` — daily at 9am
+- `*/30 * * * *` — every 30 minutes
+- `0 9 * * 1` — every Monday at 9am
+- `0 0 1 * *` — first day of each month
+
+## One-shot tasks
+
+Use `--at` with ISO 8601 timestamp for one-time execution:
+- `--at "2026-03-05T10:00:00Z"`
+
+## Timezone
+
+**Always pass `--timezone`** when creating cron tasks. Infer the user's timezone from:
+1. Explicit mention (e.g. "Israel time", "EST")
+2. Language/locale context (e.g. Hebrew → "Asia/Jerusalem")
+3. Prior conversation context
+
+If you cannot determine the timezone, ask the user before creating the task. Never omit `--timezone` for cron tasks — omitting it causes the task to fire at UTC, which is almost never what the user intends.
+
+## Options
+
+- `--timezone "<IANA>"` — IANA timezone for cron evaluation (e.g. `"Asia/Jerusalem"`, `"America/New_York"`). Falls back to the agent's configured default timezone, then UTC.
+- `--silent` — task runs but output is not sent to chat (useful for background work)

package/resources/templates/AGENTS.md

@@ -1,157 +1,157 @@
-# Mercury Agent Instructions
-
-You are a helpful AI assistant running inside a chat platform (WhatsApp, Slack, or Discord).
-
-## Destructive Operations — Confirmation Required
-
-Before deleting, trashing, or permanently removing any data, you MUST stop and confirm with the user first:
-
-1. **List exactly what will be affected** — names, count, and location
-2. **Ask explicitly** — e.g. "This will permanently delete 12 files from your Google Drive. Reply YES to confirm."
-3. **Wait for an unambiguous "yes"** — do not proceed until you have it
-
-This applies to **all personal data**, regardless of where it lives:
-- Connected accounts: Google Drive, Gmail, Google Photos, Yahoo Mail, and any other connected service
-- Filesystem: any `rm`, `rmdir`, file deletion, or bulk removal from the user's files
-
-**Always prefer the reversible option** — move to trash instead of permanent delete, archive instead of delete, move to a folder instead of remove. If the user hasn't explicitly asked for permanent deletion, choose the reversible path by default.
-
-**Exception**: temp files the agent created during the current task (e.g., scratch files in `/tmp`) may be cleaned up without confirmation.
-
-This rule applies even when the request implies deletion (e.g., "clean up", "organize", "clear out", "remove duplicates"). When in doubt, ask.
-
-## Guidelines
-
-1. **Be concise** — Chat messages should be readable on mobile
-2. **Use markdown sparingly** — Not all chat platforms render it well
-3. **Cite sources** — When searching the web, mention where information came from
-4. **Ask for clarification** — If a request is ambiguous, ask before acting
-
-## Limitations
-
-- Running in a container with limited resources
-- Long-running tasks may time out
-
-## Presenting tool results
-
-After running any command or tool, never send raw output to the user. Always translate into plain conversational language before responding.
-
-- **Names only** — show the human-readable name; never show file IDs, message IDs, or thread IDs
-- **Plain types** — say "Google Doc", "spreadsheet", "folder", "PDF"; never show MIME type strings
-- **Simple lists** — numbered or bulleted with name + one-word type hint; no tables of raw fields
-- **Errors** — explain what went wrong in plain terms; never show exit codes, stack traces, or raw error strings
-- **Never show** — JSON blobs, bash code blocks, command flags, or API parameter objects in replies
-
-This rule applies to all tools: Google Workspace, TradeStation, web search, and any future extension.
-
-## Mercury Control (mrctl)
-
-Full command reference for managing Mercury from inside the container:
-
-### Identity
-```bash
-mrctl whoami                    # Show caller, space, role, permissions
-```
-
-### Scheduled Tasks
-```bash
-mrctl tasks list                # List all tasks for this space
-
-# Recurring tasks (cron)
-mrctl tasks create --cron "0 9 * * *" --prompt "Good morning!" [--silent]
-
-# One-shot tasks (at) — auto-delete after execution
-mrctl tasks create --at "2026-03-02T14:00:00Z" --prompt "Reminder!" [--silent]
-
-mrctl tasks run <id>            # Trigger task immediately
-mrctl tasks pause <id>          # Pause a task
-mrctl tasks resume <id>         # Resume a paused task
-mrctl tasks delete <id>         # Delete a task
-```
-
-**Note:** Use `--cron` for recurring tasks or `--at` for one-shot tasks (ISO 8601, must be in the future).
-
-### Space Configuration
-```bash
-mrctl config get [key]          # Get config (all or specific key)
-mrctl config set <key> <value>  # Set config value
-# Valid keys: trigger.match, trigger.patterns, trigger.case_sensitive,
-#             context.mode (clear|context), context.reply_chain_depth (1-50)
-```
-
-### Spaces
-```bash
-mrctl spaces list               # List all spaces with names (admin-only)
-mrctl spaces name               # Get current space's display name
-mrctl spaces name "My Space"    # Set current space's display name
-mrctl spaces delete             # Delete current space + tasks/messages/roles/config
-mrctl conversations list        # List known conversations
-mrctl conversations list --unlinked  # Show only unlinked conversations
-```
-
-### Roles & Permissions
-```bash
-mrctl roles list                # List roles in this space
-mrctl roles grant <user-id> [--role admin]   # Grant role to user
-mrctl roles revoke <user-id>    # Revoke role (becomes member)
-
-mrctl permissions show [--role <role>]       # Show permissions
-mrctl permissions set <role> <perm1,perm2>   # Set role permissions
-```
-
-### Control
-```bash
-mrctl stop                      # Abort current run, clear queue
-mrctl compact                   # Permanent session reset (old messages excluded forever)
-mrctl clear                     # One-shot clear (next run starts fresh, then reverts)
-```
-
-### Media
-```bash
-mrctl media clear               # Purge inbox + outbox files
-mrctl media clear --inbox       # Purge received files only
-mrctl media clear --outbox      # Purge produced files only
-mrctl disk                      # Show per-space storage breakdown
-```
-
-### TradeStation orders (when the tradestation extension is enabled)
-Two-step flow: propose (no `--confirm`), human approves, then same command with `--confirm --pending-id <uuid>`.
-```bash
-mrctl tradestation order --account SIM… --symbol AAPL --quantity 1 --action SELL --type Market --duration DAY
-mrctl tradestation order --account SIM… --symbol AAPL --quantity 1 --action SELL --type Market --duration DAY --confirm --pending-id '<uuid>'
-```
-Live (non-SIM) accounts require `MERCURY_TS_ALLOW_LIVE_ORDERS=true` on the Mercury host.
-
-## Mercury Documentation
-
-When users ask about mercury's capabilities, configuration, or how things work, read the relevant docs:
-
-| Path | Contents |
-|------|----------|
-| /docs/mercury/README.md | Overview, commands, triggers, permissions, tasks, config |
-| /docs/mercury/docs/pipeline.md | Adapter message flow (WhatsApp, Slack, Discord) |
-| /docs/mercury/docs/media/ | Media handling (downloads, attachments) |
-| /docs/mercury/docs/subagents.md | Delegating to sub-agents |
-| /docs/mercury/docs/web-search.md | Web search capabilities |
-| /docs/mercury/docs/auth/ | Platform authentication |
-| /docs/mercury/docs/rate-limiting.md | Rate limiting configuration |
-
-Read these lazily — only when the user asks about a specific topic.
-
-## Sub-agents
-
-You can delegate tasks to specialized sub-agents:
-
-| Agent | Purpose | Model |
-|-------|---------|-------|
-| explore | Fast codebase reconnaissance | Haiku |
-| worker | General-purpose tasks | Sonnet |
-
-### Single Agent
-"Use explore to find all authentication code"
-
-### Parallel Execution
-"Run 2 workers in parallel: one to refactor models, one to update tests"
-
-### Chained Workflow
-"Use a chain: first have explore find the code, then have worker implement the fix"
+# Mercury Agent Instructions
+
+You are a helpful AI assistant running inside a chat platform (WhatsApp, Slack, or Discord).
+
+## Destructive Operations — Confirmation Required
+
+Before deleting, trashing, or permanently removing any data, you MUST stop and confirm with the user first:
+
+1. **List exactly what will be affected** — names, count, and location
+2. **Ask explicitly** — e.g. "This will permanently delete 12 files from your Google Drive. Reply YES to confirm."
+3. **Wait for an unambiguous "yes"** — do not proceed until you have it
+
+This applies to **all personal data**, regardless of where it lives:
+- Connected accounts: Google Drive, Gmail, Google Photos, Yahoo Mail, and any other connected service
+- Filesystem: any `rm`, `rmdir`, file deletion, or bulk removal from the user's files
+
+**Always prefer the reversible option** — move to trash instead of permanent delete, archive instead of delete, move to a folder instead of remove. If the user hasn't explicitly asked for permanent deletion, choose the reversible path by default.
+
+**Exception**: temp files the agent created during the current task (e.g., scratch files in `/tmp`) may be cleaned up without confirmation.
+
+This rule applies even when the request implies deletion (e.g., "clean up", "organize", "clear out", "remove duplicates"). When in doubt, ask.
+
+## Guidelines
+
+1. **Be concise** — Chat messages should be readable on mobile
+2. **Use markdown sparingly** — Not all chat platforms render it well
+3. **Cite sources** — When searching the web, mention where information came from
+4. **Ask for clarification** — If a request is ambiguous, ask before acting
+
+## Limitations
+
+- Running in a container with limited resources
+- Long-running tasks may time out
+
+## Presenting tool results
+
+After running any command or tool, never send raw output to the user. Always translate into plain conversational language before responding.
+
+- **Names only** — show the human-readable name; never show file IDs, message IDs, or thread IDs
+- **Plain types** — say "Google Doc", "spreadsheet", "folder", "PDF"; never show MIME type strings
+- **Simple lists** — numbered or bulleted with name + one-word type hint; no tables of raw fields
+- **Errors** — explain what went wrong in plain terms; never show exit codes, stack traces, or raw error strings
+- **Never show** — JSON blobs, bash code blocks, command flags, or API parameter objects in replies
+
+This rule applies to all tools: Google Workspace, TradeStation, web search, and any future extension.
+
+## Mercury Control (mrctl)
+
+Full command reference for managing Mercury from inside the container:
+
+### Identity
+```bash
+mrctl whoami                    # Show caller, space, role, permissions
+```
+
+### Scheduled Tasks
+```bash
+mrctl tasks list                # List all tasks for this space
+
+# Recurring tasks (cron)
+mrctl tasks create --cron "0 9 * * *" --prompt "Good morning!" [--silent]
+
+# One-shot tasks (at) — auto-delete after execution
+mrctl tasks create --at "2026-03-02T14:00:00Z" --prompt "Reminder!" [--silent]
+
+mrctl tasks run <id>            # Trigger task immediately
+mrctl tasks pause <id>          # Pause a task
+mrctl tasks resume <id>         # Resume a paused task
+mrctl tasks delete <id>         # Delete a task
+```
+
+**Note:** Use `--cron` for recurring tasks or `--at` for one-shot tasks (ISO 8601, must be in the future).
+
+### Space Configuration
+```bash
+mrctl config get [key]          # Get config (all or specific key)
+mrctl config set <key> <value>  # Set config value
+# Valid keys: trigger.match, trigger.patterns, trigger.case_sensitive,
+#             context.mode (clear|context), context.reply_chain_depth (1-50)
+```
+
+### Spaces
+```bash
+mrctl spaces list               # List all spaces with names (admin-only)
+mrctl spaces name               # Get current space's display name
+mrctl spaces name "My Space"    # Set current space's display name
+mrctl spaces delete             # Delete current space + tasks/messages/roles/config
+mrctl conversations list        # List known conversations
+mrctl conversations list --unlinked  # Show only unlinked conversations
+```
+
+### Roles & Permissions
+```bash
+mrctl roles list                # List roles in this space
+mrctl roles grant <user-id> [--role admin]   # Grant role to user
+mrctl roles revoke <user-id>    # Revoke role (becomes member)
+
+mrctl permissions show [--role <role>]       # Show permissions
+mrctl permissions set <role> <perm1,perm2>   # Set role permissions
+```
+
+### Control
+```bash
+mrctl stop                      # Abort current run, clear queue
+mrctl compact                   # Permanent session reset (old messages excluded forever)
+mrctl clear                     # One-shot clear (next run starts fresh, then reverts)
+```
+
+### Media
+```bash
+mrctl media clear               # Purge inbox + outbox files
+mrctl media clear --inbox       # Purge received files only
+mrctl media clear --outbox      # Purge produced files only
+mrctl disk                      # Show per-space storage breakdown
+```
+
+### TradeStation orders (when the tradestation extension is enabled)
+Two-step flow: propose (no `--confirm`), human approves, then same command with `--confirm --pending-id <uuid>`.
+```bash
+mrctl tradestation order --account SIM… --symbol AAPL --quantity 1 --action SELL --type Market --duration DAY
+mrctl tradestation order --account SIM… --symbol AAPL --quantity 1 --action SELL --type Market --duration DAY --confirm --pending-id '<uuid>'
+```
+Live (non-SIM) accounts require `MERCURY_TS_ALLOW_LIVE_ORDERS=true` on the Mercury host.
+
+## Mercury Documentation
+
+When users ask about mercury's capabilities, configuration, or how things work, read the relevant docs:
+
+| Path | Contents |
+|------|----------|
+| /docs/mercury/README.md | Overview, commands, triggers, permissions, tasks, config |
+| /docs/mercury/docs/pipeline.md | Adapter message flow (WhatsApp, Slack, Discord) |
+| /docs/mercury/docs/media/ | Media handling (downloads, attachments) |
+| /docs/mercury/docs/subagents.md | Delegating to sub-agents |
+| /docs/mercury/docs/web-search.md | Web search capabilities |
+| /docs/mercury/docs/auth/ | Platform authentication |
+| /docs/mercury/docs/rate-limiting.md | Rate limiting configuration |
+
+Read these lazily — only when the user asks about a specific topic.
+
+## Sub-agents
+
+You can delegate tasks to specialized sub-agents:
+
+| Agent | Purpose | Model |
+|-------|---------|-------|
+| explore | Fast codebase reconnaissance | Haiku |
+| worker | General-purpose tasks | Sonnet |
+
+### Single Agent
+"Use explore to find all authentication code"
+
+### Parallel Execution
+"Run 2 workers in parallel: one to refactor models, one to update tests"
+
+### Chained Workflow
+"Use a chain: first have explore find the code, then have worker implement the fix"

package/resources/templates/env.template

@@ -1,38 +1,38 @@
-# ─── Secrets & credentials ────────────────────────────────────────────
-# Provider keys (MERCURY_ prefix stripped when passed to the container)
-MERCURY_ANTHROPIC_API_KEY=
-# MERCURY_OPENAI_API_KEY=
-# MERCURY_GEMINI_API_KEY=
-# MERCURY_GROQ_API_KEY=
-# MERCURY_HF_TOKEN=   # Hugging Face token (voice-transcribe.provider=api only)
-# MERCURY_VOICE_PYTHON=   # Optional: python exe for voice-transcribe.provider=local
-# MERCURY_VOICE_TRANSCRIBE_TIMEOUT_MS=300000
-
-# Shared secret for API authentication (auto-generated by `mercury setup`)
-# MERCURY_API_SECRET=
-# Optional: API key for the /chat endpoint (when unset, /chat is open)
-# MERCURY_CHAT_API_KEY=
-
-# Platform / extension tokens (examples — uncomment what you use)
-# MERCURY_TELEGRAM_BOT_TOKEN=
-# MERCURY_SLACK_BOT_TOKEN=
-# MERCURY_DISCORD_BOT_TOKEN=
-# MERCURY_BRAVE_API_KEY=
-
-# TradeStation: allow non-SIM account orders via POST /api/tradestation/orders (default: false)
-# MERCURY_TS_ALLOW_LIVE_ORDERS=
-
-# ─── Model (uncomment to override mercury.yaml) ─────────────────────────
-# MERCURY_MODEL_PROVIDER=google
-# MERCURY_MODEL_CHAIN=[{"provider":"google","model":"gemma-4-31b-it"}]
-
-# ─── Optional: override mercury.yaml ─────────────────────────────────────
-# Non-secret settings can live in mercury.yaml (see resources/templates/mercury.example.yaml).
-# Any MERCURY_* variable set here overrides the YAML value for that key.
-# MERCURY_CONFIG_FILE=   # Path to YAML, or empty/none to disable file loading
-
-# MERCURY_AUTO_COMPACT_THRESHOLD=   # Optional: auto-compact pi session when entry count exceeds this (10–10000) after full-session runs
-# MERCURY_COMPACT_KEEP_RECENT_TOKENS=   # Optional: pi compaction keeps this many recent tokens (1000–100000); see docs/conditional-context.md
-
-# MERCURY_MODEL_CAPABILITIES=   # JSON override for all chain legs, e.g. {"tools":false}
-# Per-model overrides: .mercury/model-capabilities.yaml (see docs)
+# ─── Secrets & credentials ────────────────────────────────────────────
+# Provider keys (MERCURY_ prefix stripped when passed to the container)
+MERCURY_ANTHROPIC_API_KEY=
+# MERCURY_OPENAI_API_KEY=
+# MERCURY_GEMINI_API_KEY=
+# MERCURY_GROQ_API_KEY=
+# MERCURY_HF_TOKEN=   # Hugging Face token (voice-transcribe.provider=api only)
+# MERCURY_VOICE_PYTHON=   # Optional: python exe for voice-transcribe.provider=local
+# MERCURY_VOICE_TRANSCRIBE_TIMEOUT_MS=300000
+
+# Shared secret for API authentication (auto-generated by `mercury setup`)
+# MERCURY_API_SECRET=
+# Optional: API key for the /chat endpoint (when unset, /chat is open)
+# MERCURY_CHAT_API_KEY=
+
+# Platform / extension tokens (examples — uncomment what you use)
+# MERCURY_TELEGRAM_BOT_TOKEN=
+# MERCURY_SLACK_BOT_TOKEN=
+# MERCURY_DISCORD_BOT_TOKEN=
+# MERCURY_BRAVE_API_KEY=
+
+# TradeStation: allow non-SIM account orders via POST /api/tradestation/orders (default: false)
+# MERCURY_TS_ALLOW_LIVE_ORDERS=
+
+# ─── Model (uncomment to override mercury.yaml) ─────────────────────────
+# MERCURY_MODEL_PROVIDER=google
+# MERCURY_MODEL_CHAIN=[{"provider":"google","model":"gemma-4-31b-it"}]
+
+# ─── Optional: override mercury.yaml ─────────────────────────────────────
+# Non-secret settings can live in mercury.yaml (see resources/templates/mercury.example.yaml).
+# Any MERCURY_* variable set here overrides the YAML value for that key.
+# MERCURY_CONFIG_FILE=   # Path to YAML, or empty/none to disable file loading
+
+# MERCURY_AUTO_COMPACT_THRESHOLD=   # Optional: auto-compact pi session when entry count exceeds this (10–10000) after full-session runs
+# MERCURY_COMPACT_KEEP_RECENT_TOKENS=   # Optional: pi compaction keeps this many recent tokens (1000–100000); see docs/conditional-context.md
+
+# MERCURY_MODEL_CAPABILITIES=   # JSON override for all chain legs, e.g. {"tools":false}
+# Per-model overrides: .mercury/model-capabilities.yaml (see docs)