min-agent 0.2.1 → 0.4.0

package/docs/superpowers/specs/2026-08-20-unified-tui-default-design.md

@@ -0,0 +1,165 @@
+# 根命令默认 TUI + 合并 chat/code — 设计文档
+
+**日期:** 2026-08-20
+**状态:** 已批准
+**范围:** CLI 对齐 Codex（根命令进 TUI、`exec` 非交互）；取消 chat/code 双模式，统一为原 code 能力
+
+---
+
+## 背景
+
+当前 `min-agent` 无参数会打印 Usage 并退出；对话必须 `min-agent chat`，项目感知必须 `min-agent code`。Codex 的根命令就是交互 TUI，子命令才是特殊模式。
+
+两套模式的实现差异很小：工具几乎相同，code 额外有项目扫描、coding system prompt、`task` 工具，以及存在 `EXA_API_KEY` 时的 `codesearch`。用户确认不再保留 chat/code 概念，以 code 为准。
+
+## 设计决策（已与用户确认）
+
+| 决策 | 结论 |
+|------|------|
+| 空参数 | `min-agent` 直接进入交互 TUI（不再打印 Usage） |
+| 根命令带消息 | `min-agent "修 lint"` 进 TUI，并把该文本作为第一轮立刻提交 |
+| 非交互 | 新增 `min-agent exec <message>`（脚本/CI）；根命令一律不跑完即退 |
+| 模式 | 取消 chat/code 双模式，全程原 code 能力 |
+| `chat` / `code` 子命令 | 静默别名，行为与根命令 TUI 相同，文案不再提两种模式 |
+| HTTP | `/v1/chat` 走原 code 路径；`/v1/code` 保留为别名 |
+
+## 目标与非目标
+
+**目标:**
+
+- 根命令默认进入与现在 `min-agent code` 同等能力的 TUI
+- 根命令可选首条 prompt、顶层 flag（`-m` / `--provider` / `-i` / `--resume` / `-y`）
+- `exec` 单次运行后退出，使用同一套 agent 能力
+- 删除运行时 `mode: "chat" \| "code"` 分支
+- README、`printUsage`、`/help`、`docs/API.md`、serve 测试同步
+
+**非目标:**
+
+- 不引入 Codex 的 sandbox / profile / `exec resume` / ephemeral
+- 不把 `exec` 做成 JSON event stream（保持现有 `runAgent` 终端输出）
+- 不新增 TUI 内「切换模式」斜杠命令
+- 不把 `history` / `mcp` 等子命令改成 Codex 同名结构
+
+---
+
+## 1. CLI 分发
+
+从 argv 里跳过「带值 flag 及其参数」和布尔 flag，得到第一个位置参数。已知带值 flag：`--model`/`-m`、`--provider`、`--resume`、`--image`/`-i`、`--port`/`-p`、`--host`。布尔：`--yes`/`-y`。
+
+**保留子命令（第一个位置参数匹配则走原子命令，不把后续词当 prompt）：**
+
+`setup`、`models`、`serve`、`mcp`、`history`、`memory`、`skills`、`update`、`init`、`rules`、`exec`、`chat`、`code`
+
+分发规则：
+
+| argv | 行为 |
+|------|------|
+| （空） | TUI，无首条消息 |
+| `-h` / `--help` 作为第一个 token | 打印 Usage，退出 0 |
+| `-v` / `--version` 作为第一个 token | 打印版本，退出 0 |
+| 第一个位置参数 ∈ 保留子命令 | 现有分支；`chat`/`code` 见下 |
+| 其余 | 视为交互会话：`parseFlags(args)` 后 `positionals.join(" ")` 作为可选首条 prompt |
+
+抽出纯函数 `resolveCliInvocation(argv: string[]): CliInvocation`，便于单测、避免把「未知命令」误打成 prompt 或把 prompt 误打成未知命令。
+
+`chat` / `code`：解析其后 flag 与剩余位置参数，调用与根命令相同的 `runTui(...)`。`min-agent chat "你好"` ≡ `min-agent "你好"`。不打印弃用警告。
+
+未配置时（`!isConfigured()`）：TUI 与 `exec` 都与现在 `chat` 相同——打印 `Not configured. Run: min-agent setup` 并退出 1。
+
+`--resume` 仅作用于 TUI（根命令 / `chat` / `code`）。与非空首条 prompt 同时出现时：先加载会话，再把 prompt 作为新的一轮提交（允许「恢复后立刻跟一句」）。`exec` 不支持 `--resume`。
+
+## 2. TUI 首条 prompt
+
+`TuiOptions` 增加 `initialPrompt?: string`，去掉 `mode`。始终 `scanProject()` + `buildCodeSystemPrompt()`。
+
+启动后、进入输入循环前：
+
+- 仅 prompt：追加一条 user 文本消息，立刻 `runner.run()`
+- 仅 `-i` 图片：保持现有逻辑（空文本 + 图片，立刻 run）
+- prompt + 图片：同一条 user 消息里文本 + 图片，立刻 run
+- `--resume` 且有 prompt：在已加载消息后追加上述 user 消息再 run
+- 皆无：空会话，等用户输入
+
+## 3. `min-agent exec`
+
+非交互、跑完退出。能力与 TUI 相同（coding prompt + 完整工具）。危险操作仍走 `confirm`；脚本需显式 `-y` / `--yes`（不默认放开）。
+
+**Prompt 来源（与 Codex exec 同序）：**
+
+1. 位置参数拼成 prompt（可多词）
+2. prompt 为 `-`：从 stdin 读全部
+3. 无位置参数且 stdin 非 TTY：从 stdin 读全部
+4. 无位置参数且 stdin 是 TTY：打印用法到 stderr，退出 1
+5. 既有位置参数（且不是单独的 `-`）又有管道 stdin：prompt 正文后追加 `\n\n` + stdin
+
+支持与现有 `chat` 单次调用相同的 `--model`、`--provider`、`--image`、`-y`。不支持 `--resume`、`--port`、`--host`。
+
+实现：现有 `runAgent` 改为使用统一后的 `runOnce`（coding prompt）。`exec` 在 agent 以错误结束时进程退出码为 1（当前 `runAgent` 打印错误后仍可能以 0 退出，本项一并修掉）。未配置退出 1。stdin 读失败退出 1。
+
+不把会话写入 `history`（与当前 `runAgent` 一致）。
+
+## 4. 运行时去掉双模式
+
+| 现状 | 目标 |
+|------|------|
+| `createChatTools` / `createCodeTools` | 只保留一套 `createTools()`（原 `createCodeTools`：含条件 `codesearch`） |
+| `buildTools(mode)` | 无 mode；始终挂 `explore` + `task`；`todo` 仍每轮替换 |
+| `runOnce` vs `runOnceWithSystem` | `runOnce` 内部 `scanProject` + `buildCodeSystemPrompt`；`runOnceWithSystem` 仅测试/自定义 system 仍可用 |
+| `runOnceCore(..., mode)` | 去掉 mode 参数；日志不再写 `mode=chat/code` |
+| `AgentRunnerDeps.mode` / `codeSystemPrompt?` | 始终传入 system prompt；runner 只走 `runOnceWithSystem`（或合并后的单一入口） |
+
+`src/tools/task.ts` 改为调用 `createTools()`。
+
+## 5. HTTP API
+
+- `POST /v1/chat`：始终原 code 路径（扫描项目、coding prompt、完整工具）
+- `POST /v1/code`：路径保留，内部与 `/v1/chat` 同一 handler，不再有 `codeMode` 布尔
+- 非流式/SSE `done`：**去掉 `mode` 字段**；**始终带 `project`**
+- `POST /v1/paste`：去掉对 `code` 的分支，始终项目感知；请求里多传 `code` 忽略，不 400
+- `GET /v1/project` 不变
+
+文档与测试同步：`tests/serve.test.ts` 里「paste + `code: true` 期望 `mode: "code"`」改为期望有 `project`、无 `mode`。`/v1/chat` 成功响应同样有 `project`。
+
+## 6. 文档与用户可见文案
+
+`printUsage`、README Quick Start / Commands、`docs/API.md`：
+
+```
+min-agent                      # 交互会话
+min-agent "hello"              # 交互会话，并立刻发送
+min-agent exec "hello"         # 非交互，跑完退出
+min-agent --resume <id>        # 恢复会话
+```
+
+不再出现「Chat 模式」「Code 模式」「project-aware coding mode」作为两种产品模式。`/help` 无需加新斜杠命令（无新 `/` 命令）。`chat`/`code` 可在 Usage 里写成「同无子命令的交互会话（兼容）」一行，或不列出——推荐仍列一行以免旧脚本使用者找不到，但不解释模式差异。
+
+## 7. 错误处理
+
+- 未知子命令不再存在：非保留词一律当 prompt（包括看起来像拼错的 `setpu`，会进 TUI 并发送该词）。Usage 必须把保留子命令列清楚，避免误触。
+- 空 prompt 的 TUI 合法；空 prompt 的 `exec` 在 TTY 上不合法（见 §3）
+- `--resume` 指向不存在的 id：保持现有 TUI 行为（当新会话），不另造错误
+
+## 8. 测试
+
+- 新增 `tests/cli-invoke.test.ts`（或同等）：覆盖 `resolveCliInvocation`——空 argv、help/version、`setup`、`exec`、`chat` 别名、纯 prompt、flag+prompt、`--resume`、`-m` 在子命令前
+- 更新 `tests/serve.test.ts`：chat/paste 均有 `project`、无 `mode`；`/v1/code` 与 `/v1/chat` 结构一致
+- agent 循环测试继续用 `runOnceWithSystem`，不强制扫项目
+- 仓库根目录 `bun run typecheck`
+
+## 影响范围（实现时必须改到）
+
+- `src/cli.ts` — 分发、Usage、`exec`
+- `src/tui-chat.ts`、`src/tui/agent-runner.ts` — 去 mode、首条 prompt
+- `src/agent.ts`、`src/tools/index.ts`、`src/tools/task.ts` — 统一工具与 prompt
+- `src/serve.ts`、`docs/API.md`、`tests/serve.test.ts`
+- `packages/min-agent/README.md`
+- 无新斜杠命令，`slash-commands.ts` / `/help` 仅当文案里还写着 chat/code 时删掉
+
+---
+
+## 自审
+
+- 无 TBD：`exec` 的 stdin 规则、退出码、与 `--resume` 的边界已写死
+- 与「根命令永远 TUI」一致：`exec` 是唯一 CLI 单次出口
+- 范围可一次落地：CLI 分发 + 运行时去 mode + HTTP 文档测试，不拆第二期
+- 「第一个位置参数」与「带值 flag」的跳过规则写明，避免 `min-agent --model x exec hi` 被当成 prompt

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "min-agent",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "type": "module",
   "description": "Minimal AI coding agent with tool use, MCP, and skills support",
   "license": "MIT",
@@ -14,6 +14,7 @@
     "bin",
     "dist",
     "docs",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -32,6 +33,9 @@
     "dev": "bun run src/cli.ts",
     "build": "tsc",
     "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "lint": "biome check src tests",
+    "format": "biome format --write src tests",
     "prepack": "npm run typecheck && npm run build"
   },
   "keywords": [
@@ -46,15 +50,15 @@
     "http-api"
   ],
   "dependencies": {
-    "@ai-sdk/openai": "3.0.53",
-    "@ai-sdk/provider": "3.0.8",
-    "@modelcontextprotocol/sdk": "1.27.1",
-    "ai": "6.0.168",
-    "glob": "13.0.5",
+    "@ai-sdk/openai": "~3.0.53",
+    "@ai-sdk/provider": "~3.0.8",
+    "@modelcontextprotocol/sdk": "~1.27.1",
+    "ai": "~6.0.168",
+    "commander": "14.0.3",
+    "glob": "~13.0.5",
     "ink": "5",
     "ink-spinner": "5",
-    "react": "18",
-    "zod": "^3.25.76"
+    "react": "18"
   },
   "devDependencies": {
     "@types/node": "22.13.9",

package/skills/self-config/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: self-config
+description: >
+  Configures min-agent itself: providers, MCP servers, skills, rules, memory,
+  permission, sandbox, plugins, and files under ~/.min-agent/ and .min-agent/.
+  Use when the user asks to install, enable, disable, or change min-agent settings.
+always-load: true
+version: 1.0.0
+---
+
+# Configure min-agent
+
+This skill is already loaded. Follow it whenever the user asks to change min-agent itself. Do not read README.md for this. Field catalogs: [reference.md](reference.md).
+
+## Scope first
+
+| Scope | Directory | When to use |
+|-------|-----------|-------------|
+| Global | `~/.min-agent/` (`MIN_AGENT_CONFIG_DIR` replaces this) | All projects; API keys live only here |
+| Project | `<cwd>/.min-agent/` | This repo only |
+
+If the user does not say which scope: use **project** when `.min-agent/` exists, otherwise **global**. Never put `apiKey`, `token`, `serperApiKey`, or other secrets in project files.
+
+Config files are **strict JSON** (no comments). Read the file before editing. Prefer the `edit` tool for existing files; `write` only when creating a new file. Keep unrelated keys. Create parent directories when needed.
+
+## What goes where
+
+| Goal | File | Notes |
+|------|------|--------|
+| Providers, keys, search backends, pricing, extra instruction paths, global skill disables | `~/.min-agent/config.json` | Keys only here |
+| Project skill toggles; overlay `activeProvider` / `defaultModel` / `sampling` / `budget` / `permission` / `sandbox` / `compaction` / `agent` | `.min-agent/config.json` | Overlay is field-by-field; `sampling`/`budget`/`sandbox`/`compaction`/`agent` merge keys |
+| MCP servers | `~/.min-agent/mcp.json` or `.min-agent/mcp.json` | Merge by server **name**; project replaces the same name |
+| Memories | `memory.json` in the same dirs | Prefer `memory_save` / `memory_search` tools over editing the file |
+| Global rules | `~/.min-agent/rules.md` | Always loaded |
+| Project rules | `AGENTS.md`, `RULES.md`, or `CLAUDE.md` in cwd (or `.min-agent/AGENTS.md`) | First match wins when walking up from cwd |
+| Extra instruction files | `instructions` array in global `config.json` | Paths or URLs |
+| Custom tools | `.min-agent/tools/*.ts` or `~/.min-agent/tools/*.ts` | See reference.md |
+| Project skills | `.min-agent/skills/<name>/SKILL.md` | Or `min-agent skills new <name>` |
+| Global skills | `~/.agents/skills/<name>/SKILL.md` | `min-agent skills new <name> --global` |
+
+## MCP
+
+Write `{ "mcpServers": { "<name>": { ... } } }`.
+
+- Local: `"command": ["npx", "-y", "@scope/server", "..."]` plus optional `environment`, `enabled`, `connectTimeout`, `callTimeout`.
+- Remote: `"url": "https://..."`. Optional `token`, `headers`, `remoteTransport` (`auto` default, or `streamable-http` / `sse`), `oauth` (`{}` to login in a browser, or `false` to disable).
+- `enabled: false` disables without deleting. Project `.min-agent/mcp.json` wins on the same name.
+
+CLI (user shell, not a substitute for writing the file in this session): `min-agent mcp add|list|info|enable|disable|remove|check` with `--project` for repo scope.
+
+**This session:** editing `mcp.json` is persisted, but connected servers will not change until the user restarts. Say so after you write the file. HTTP `POST /v1/mcp` on a running `min-agent serve` reconnects; a coding session does not.
+
+Connected servers already expose `mcp_list_resources`, `mcp_read_resource`, `mcp_list_prompts`, `mcp_get_prompt`. Do not invent per-resource tools.
+
+## Skills
+
+User-skill roots, later overriding earlier: `~/.agents/skills/` → `.min-agent/skills/` → `.agents/skills/` → `.opencode/skills/` → `.claude/skills/`. Symlinks are followed. `MIN_AGENT_SKILLS_DIRS` (path-delimiter separated) replaces that user list. Built-in skills shipped with min-agent still load and **win on name**; they are not overridden by user copies. `MIN_AGENT_NO_BUILTIN_SKILLS=1` skips built-ins.
+
+Enable/disable:
+
+- Global disable: `disabledSkills` in `~/.min-agent/config.json`
+- Project disable: `disabledSkills` in `.min-agent/config.json` (wins)
+- Re-enable a globally disabled skill in this repo: add the name to project `enabledSkills`
+
+Toggles take effect on the next turn. A **new** `SKILL.md` is invisible until skills are rediscovered (`/skills` in the interactive session, `POST /v1/skills/reload` on serve, or restart).
+
+Scaffold:
+
+```markdown
+---
+name: my-skill
+description: What it does
+---
+Instructions...
+```
+
+`description` may be a YAML `|` / `>` block. Optional: `version`, `allowed-tools`, `always-load`, `metadata.requires.bins`. Do not disable `self-config` unless the user explicitly asks.
+
+## Rules, memory, permission, sandbox
+
+- Rules: edit the files in the table above. `/reload` reloads rules only, not MCP.
+- Memory: use memory tools. Default save scope is project when `.min-agent/` exists. Shape: `{ "content": string, "tags": string[], "created": ISO string }` array.
+- Permission: `ask` (default) | `accept-edits` | `allow-all` in config `permission`. CLI `min-agent permission …` / `--permission` without a message writes config and exits; with a message it is this session only. `--yes` is this session only and does not write config.
+- Sandbox default is **off**. `mode`: `off` | `workspace` | `strict`. Optional `network`, `extraWriteRoots`, `extraReadRoots`. Isolation is independent of permission. `--sandbox` / `--network` without a message write config and exit.
+
+## Providers
+
+Only in global `config.json`: `providers[]` with `name`, `type` (`openai-compatible` | `openai` | `ollama`), `baseURL`, `apiKey`, optional `defaultModel`, `contextWindow`. `activeProvider` selects one. Project config may set `activeProvider` and `defaultModel` (no keys).
+
+After changing keys or MCP connections, tell the user if a restart is required. Do not print full secrets back in chat.

package/skills/self-config/reference.md

@@ -0,0 +1,149 @@
+# self-config field catalog
+
+Read this when you need exact keys. Files are strict JSON.
+
+## Global `~/.min-agent/config.json`
+
+```json
+{
+  "providers": [
+    {
+      "name": "default",
+      "type": "openai-compatible",
+      "baseURL": "https://api.openai.com/v1",
+      "apiKey": "sk-...",
+      "defaultModel": "gpt-5.5",
+      "contextWindow": 1000000
+    }
+  ],
+  "activeProvider": "default",
+  "webSearchURL": "https://searxng.example.com",
+  "webSearchFallbackEngines": "google,bing",
+  "serperApiKey": "your-serper-key",
+  "webFetchURL": "https://firecrawl.example.com",
+  "instructions": ["./docs/rules.md"],
+  "disabledSkills": [],
+  "permission": "ask",
+  "sandbox": {
+    "mode": "off",
+    "network": "allow",
+    "extraWriteRoots": [],
+    "extraReadRoots": []
+  },
+  "pricing": { "gpt-5.5": { "inputPerMillion": 1.25, "outputPerMillion": 10 } },
+  "sampling": { "temperature": 0.7, "maxTokens": 4096, "topP": 1 },
+  "budget": { "maxCostUSD": 5 },
+  "compaction": { "model": "gemini-2.0-flash", "autoContinue": true },
+  "tools": { "bashTimeoutMs": 600000 },
+  "agent": {
+    "maxSteps": 40,
+    "maxContinues": 40,
+    "autoContinue": true,
+    "maxEmptyAttempts": 4,
+    "emptyRetryDelayMs": 1000,
+    "requestTimeoutMs": 180000,
+    "streamIdleTimeoutMs": 90000,
+    "turnTimeLimitMs": 1200000,
+    "softStepLimit": 120,
+    "subAgentMaxSteps": 15,
+    "exploreMaxSteps": 20,
+    "researchSteerAfter": 3,
+    "researchStopAfter": 5,
+    "researchTotalCap": 24
+  }
+}
+```
+
+- `contextWindow`: tokens; omit to query the API, then 512k fallback.
+- `agent.autoContinue` omitted → uses `compaction.autoContinue` (default true).
+- `agent.maxSteps` omitted → no tool-step ceiling.
+- `agent.maxEmptyAttempts` / `agent.emptyRetryDelayMs`: retries when the provider returns an empty stream (HTTP 200, no content). First retry is immediate, later ones back off exponentially, capped at 8s.
+- `agent.requestTimeoutMs` / `agent.streamIdleTimeoutMs`: abort a request that never starts responding, or a stream that goes quiet mid-response; the run then retries it like an empty reply. 0 disables. Env overrides: `MIN_AGENT_REQUEST_TIMEOUT_MS`, `MIN_AGENT_STREAM_IDLE_TIMEOUT_MS`.
+- `agent.turnTimeLimitMs` / `agent.softStepLimit`: budget for one turn. On expiry the model is asked to wrap up once, then the turn stops. 0 disables either half.
+- `agent.subAgentMaxSteps` / `agent.exploreMaxSteps`: step ceilings for the `task` and `explore` sub-agents. Sub-agents share the parent's research budget and cost budget.
+- `agent.researchSteerAfter` / `researchStopAfter`: research *rounds that returned no new source* before steering / dropping `search_web` and `web_fetch`; `researchTotalCap` is the hard number of research calls per turn. Productive research (new URLs or domains each round) is not penalised.
+- `tools.bashTimeoutMs`: default kill timeout for `bash` (10 minutes; the model can override per call, 0 disables).
+- `MIN_AGENT_TRACE=1` logs a request/response summary for every model call (model, message and tool counts, status, time to first byte).
+- Web search/fetch that has not yet produced the requested output still continues even when `autoContinue` is false; further search/fetch calls return a stop-and-write notice instead of new results.
+- Old single-provider configs migrate on first run; write the `providers` array for new files.
+
+## Project `.min-agent/config.json`
+
+Allowed keys (no `providers`, no API keys, no search secrets):
+
+`disabledSkills`, `enabledSkills`, `activeProvider`, `defaultModel`, `sampling`, `budget`, `permission`, `sandbox`, `compaction`, `agent`.
+
+Present keys overlay the global file. Nested objects `sampling` / `budget` / `sandbox` / `compaction` / `agent` merge per field. `defaultModel` overrides the active provider's model without copying keys.
+
+## `mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+      "environment": { "KEY": "VALUE" },
+      "enabled": true,
+      "connectTimeout": 10000,
+      "callTimeout": 30000
+    },
+    "remote": {
+      "url": "https://mcp.example.com/mcp",
+      "remoteTransport": "auto",
+      "token": "bearer-token",
+      "headers": { "X-API-Key": "..." },
+      "oauth": {},
+      "connectTimeout": 15000,
+      "callTimeout": 30000
+    }
+  }
+}
+```
+
+- `command` may be a string plus `args[]` (Claude/opencode shape).
+- `timeout` is the legacy shared value; `connectTimeout` / `callTimeout` override it.
+- `oauth`: object (optional `clientId` / `clientSecret` / `scope`) or `false`.
+- Tokens for OAuth land in `~/.min-agent/mcp-oauth/`.
+
+## Skills frontmatter
+
+Required: `name`, `description`. Optional: `version`, `allowed-tools` (flow `[read, grep]` or a YAML list), `always-load` (`true` injects the body into the system prompt), `metadata.requires.bins`.
+
+Disable lists are string arrays. A project `enabledSkills` name unblocks a globally disabled skill in this repo only.
+
+## Plugins
+
+`.min-agent/tools/*.ts` (or `~/.min-agent/tools/*.ts`). Each exported object:
+
+```typescript
+export const myTool = {
+  description: "...",
+  parameters: { arg: { type: "string", description: "..." } },
+  execute: async ({ arg }) => "result",
+}
+```
+
+Default: confirm before run. `readOnly: true` or `dangerous: false` skips confirm. Plan mode keeps only `readOnly` custom tools. Export name `default` → tool id is the file basename; other exports → `basename_exportName`.
+
+## Memory `memory.json`
+
+Array of `{ "content": string, "tags": string[], "created": string }`. Prefer memory tools.
+
+## Environment overrides
+
+| Variable | Role |
+|----------|------|
+| `MIN_AGENT_CONFIG_DIR` | Replaces `~/.min-agent` |
+| `MIN_AGENT_SKILLS_DIRS` | Replaces user skill roots (path-delimiter separated) |
+| `MIN_AGENT_NO_BUILTIN_SKILLS` | `1` / `true` skips packaged skills |
+| `MIN_AGENT_SANDBOX` / `MIN_AGENT_SANDBOX_NETWORK` | Isolation |
+| `MIN_AGENT_SERPER_API_KEY` | Overrides `serperApiKey` |
+| `MIN_AGENT_SEARXNG_URL` | Overrides `webSearchURL` (SearXNG instead of Serper) |
+| `MIN_AGENT_SEARXNG_FALLBACK_ENGINES` | Default `google,bing`; empty string disables retry |
+| `MIN_AGENT_FIRECRAWL_URL` | Overrides `webFetchURL` |
+| `EXA_API_KEY` | Enables Exa code search |
+| `MIN_AGENT_SERVE_TOKEN` / `MIN_AGENT_SERVE_CORS` | HTTP server |
+
+## HTTP (only if the user is running `min-agent serve`)
+
+Skills: `GET /v1/skills`, `GET /v1/skills/:name`, `POST /v1/skills/reload`, `POST /v1/skills/:name/enable|disable` with `{ "scope": "project"|"global" }`. MCP enable/disable similarly. Full list is `docs/API.md` in the min-agent package; do not treat that file as this skill's replacement.