mini-coder 0.1.0 → 0.1.1

package/README.md

@@ -6,194 +6,76 @@
 
 > _Small. Fast. Gets out of your way._
 
-[📖 Read the Full Manual](https://sacenox.github.io/mini-coder/)
+[📖 Read the Full Manual](docs/mini-coder.1.md)
 
-Hey there! I'm **mini-coder** — a CLI coding agent built for developers who want a sharp tool, not a bloated IDE plugin. Think of me as the pocket knife of AI coding assistants: lightweight, reliable, and always ready.
-
----
-
-## 🤙 Who Am I?
-
-I'm `mc` — your new terminal companion. I live in your shell, speak to large language models, and help you explore, understand, and modify code at the speed of thought.
-
-I was built with a simple philosophy: **dev flow first**. No slow startup. No clunky GUI. No vendor lock-in. Just you, your terminal, and an AI that keeps up.
+A terminal coding agent for developers who want a sharp tool, not a bloated IDE plugin. Shell-first, multi-provider, minimal tool surface. Just you, your terminal, and an AI that keeps up.
 
 ![Minicoder Preview](./assets/preview.gif)
 
 ---
 
-## 🛠️ What Can I Do?
-
-My toolkit is lean on purpose — every tool earns its spot, no passengers:
-
-| Tool            | What it does                                                               |
-| --------------- | -------------------------------------------------------------------------- |
-| 🐚 `shell`      | Run shell commands, inspect the repo, and use `mc-edit` for targeted edits |
-| 🤖 `subagent`   | Spawn a focused mini-me for parallel subtasks                              |
-| 🧰 `listSkills` | List discovered skills without loading full skill bodies                   |
-| 📘 `readSkill`  | Load one `SKILL.md` on demand                                              |
-| 🌐 `webSearch`  | Search the web when `EXA_API_KEY` is set                                   |
-| 📄 `webContent` | Fetch full page content from URLs when `EXA_API_KEY` is set                |
-
-mini-coder is intentionally **shell-first**: inspect with shell, edit with `mc-edit`, verify with shell.
-
-Need more firepower? I also connect to **MCP servers** over HTTP or stdio — attached MCP tools show up dynamically whenever the job calls for them.
-
----
-
-## ⚡ Key Features
-
-- **Multi-provider** — set `OPENCODE_API_KEY` for Zen, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY` or `GEMINI_API_KEY`, or just run Ollama locally (`OLLAMA_BASE_URL` optional). I auto-discover whatever's available.
-- **Built-in web search** — set `EXA_API_KEY` and I expose `webSearch` + `webContent` tools.
-- **Session memory** — conversations are saved in a local SQLite database. Resume where you left off with `-c` or pick a specific session with `-r <id>`.
-- **Shell integration** — prefix with `!` to run shell commands inline. Use `@` to reference files in your prompt (with Tab completion).
-- **Slash commands** — `/model` or `/models` to list/switch models, `/model effort <low|medium|high|xhigh|off>` for reasoning effort, `/reasoning [on|off]` to toggle reasoning display, `/context` to inspect or tune pruning/tool-result caps, `/cache` to configure prompt caching, `/review` for a code review (global custom command, auto-created at `~/.agents/commands/review.md`), `/agent [name]` to set or clear an active primary agent, `/undo` to remove the last conversation turn (it does not revert filesystem changes), `/new` for a clean session, `/mcp list|add|remove` to manage MCP servers, and `/exit` (`/quit`, `/q`) to leave. See all with `/help`.
-
-- **Custom commands** — drop a `.md` file in `.agents/commands/` and it becomes a `/command`. Claude-compatible `.claude/commands/` works too. Supports argument placeholders (`$ARGUMENTS`, `$1`…`$9`) and shell interpolation (`` !`cmd` ``). Global commands live in `~/.agents/commands/` and `~/.claude/commands/`. Custom commands take precedence over built-ins. → [docs/custom-commands.md](docs/custom-commands.md)
-- **Custom agents** — drop a `.md` file in `.agents/agents/` or `.claude/agents/` (or `~/.agents/agents/` / `~/.claude/agents/` globally) and activate it with `/agent [name]`. Agent definitions are also exposed to subagent delegation unless `mode: primary`. → [docs/custom-agents.md](docs/custom-agents.md)
-- **Skills** — place a `SKILL.md` in `.agents/skills/<name>/` and inject it into any prompt with `@skill-name`. Claude-compatible `.claude/skills/<name>/SKILL.md` works too. Skills are _never_ auto-loaded — always explicit. → [docs/skills.md](docs/skills.md)
-- **Beautiful, minimal output** — compact tool output, formatted trees for file searches, a live status bar with model, git branch, and token counts.
-- **16 ANSI colors only** — my output inherits _your_ terminal theme. Dark mode, light mode, Solarized, Gruvbox — I fit right in.
-
----
-
-## 🧠 Interesting Things About Me
-
-- **I eat my own dog food.** I was built _by_ a mini-coder agent. It's agents all the way down. 🐢
-- **I'm tiny but mighty.** The whole runtime is [Bun.js](https://bun.com) — fast startup, native TypeScript, and a built-in SQLite driver.
-- **I respect existing conventions.** Context lives in `AGENTS.md` or `CLAUDE.md`, commands in `.agents/commands/`, agents in `.agents/agents/`, skills in `.agents/skills/` — I follow the ecosystem instead of inventing new standards.
-- **I spin while I think.** ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏ (It's the little things.)
-- **I can clone myself.** The `subagent` tool lets me spin up parallel instances of myself to tackle independent subtasks simultaneously. Divide and conquer! (Up to 10 levels deep.)
-
----
-
-## 📁 Config folders
-
-I follow the [`.agents` convention](https://github.com/agentsmd/agents) — the shared standard across AI coding tools — and I also understand `.claude` layouts for **commands**, **skills**, and **agents**.
-
-| Path                             | What it does                                          |
-| -------------------------------- | ----------------------------------------------------- |
-| `.agents/commands/*.md`          | Custom slash commands (`/name`)                       |
-| `.claude/commands/*.md`          | Claude-compatible custom commands                     |
-| `.agents/agents/*.md`            | Custom agents                                         |
-| `.claude/agents/*.md`            | Alternate `.claude` path for custom agents            |
-| `.agents/skills/<name>/SKILL.md` | Reusable skill instructions (`@name`)                 |
-| `.claude/skills/<name>/SKILL.md` | Claude-compatible skills                              |
-| `.agents/AGENTS.md`              | Preferred local project context                       |
-| `CLAUDE.md`                      | Local fallback context if `.agents/AGENTS.md` is absent |
-| `AGENTS.md`                      | Local fallback context if `.agents/AGENTS.md` and `CLAUDE.md` are absent |
-| `~/.agents/AGENTS.md`            | Preferred global context, prepended before local context |
-| `~/.agents/CLAUDE.md`            | Global fallback context if `~/.agents/AGENTS.md` is absent |
-
-Global commands, agents, and skills also work from `~/.agents/...` and `~/.claude/...`.
-
-For commands, skills, and agents: local overrides global, and `.agents` overrides `.claude` at the same scope. Context files are combined differently: global context is injected first, then local context. → [docs/configs.md](docs/configs.md)
-
----
-
-## 🚀 Getting Started
+## ⚡ Quick Start
 
-One thing before you dive in: **I run on Bun**. You can install me via npm just fine, but [Bun](https://bun.com) still needs to be on your machine — no way around it.
+I run on [Bun](https://bun.com) — install me via bun or npm, but Bun needs to be on your machine.
 
 ```bash
-# Install globally
-bun add -g mini-coder
-# or: npm install -g mini-coder
-
-# Set a provider key (pick one — or run Ollama locally)
-export OPENCODE_API_KEY=your-zen-key    # recommended
-export ANTHROPIC_API_KEY=your-key       # direct Anthropic
-export OPENAI_API_KEY=your-key          # direct OpenAI
-export GOOGLE_API_KEY=your-key          # direct Gemini
-# or: export GEMINI_API_KEY=your-key
-
-# Optional extras
-export OLLAMA_BASE_URL=http://localhost:11434
-export EXA_API_KEY=your-exa-key         # enables webSearch/webContent
-
-# Launch
-mc
-```
-
-Or drop me a prompt straight away for one-shot mode (runs once, then exits):
+# Install
+bun add -g mini-coder   # or: npm install -g mini-coder
 
-```bash
-mc "Refactor the auth module to use async/await"
-```
+# Set one API key (pick any)
+export OPENCODE_API_KEY=your-key     # recommended
+export ANTHROPIC_API_KEY=your-key    # direct Anthropic
+export OPENAI_API_KEY=your-key       # direct OpenAI
+export GOOGLE_API_KEY=your-key       # direct Gemini (or GEMINI_API_KEY)
 
-Useful flags:
+# Optional
+export OLLAMA_BASE_URL=http://localhost:11434   # local models
+export EXA_API_KEY=your-key                     # web search tools
 
-```bash
-mc -c                           # continue last session
-mc -r <id>                      # resume a specific session
-mc -l                           # list recent sessions
-mc -m zen/claude-sonnet-4-6     # pick a model
-mc --cwd ~/src/other-project    # set working directory
-mc -h                           # show help
+# Go
+mc
 ```
 
----
-
-## 🗃️ App data
-
-Everything I remember lives in `~/.config/mini-coder/` — here's what I'm holding onto:
+One-shot mode: `mc "refactor auth to use async/await"` — runs once, then exits.
 
-- `sessions.db` — your full session history, MCP server config, and model metadata, all in one tidy SQLite file
-- `api.log` — a request/response log for every provider call this run, if you want to peek under the hood
-- `errors.log` — anything that went sideways, caught and written down so you can actually debug it
+Useful flags: `-c` continue last session, `-r <id>` resume, `-l` list sessions, `-m <model>` pick a model, `-h` help.
 
 ---
 
-## 📚 Go Deeper
+## 🔑 OAuth Login
 
-The README hits the highlights — the docs have the full story:
-
-- [docs/custom-commands.md](docs/custom-commands.md)
-- [docs/custom-agents.md](docs/custom-agents.md)
-- [docs/skills.md](docs/skills.md)
-- [docs/configs.md](docs/configs.md)
-
-## 🗂️ Project Structure
-
-```
-src/
-  index.ts          # Entry point + CLI arg parsing
-  agent/            # Main REPL loop + tool registry
-  cli/              # Input, output, slash commands, markdown rendering
-  llm-api/          # Provider factory + streaming turn logic
-  tools/            # shell, subagent, skill tools
-                    #   + webSearch, webContent
-  internal/         # shared internals, including the mc-edit helper implementation
-  mcp/              # MCP server connections
-  session/          # SQLite-backed session & history management
-```
+Use `/login` inside the REPL to authenticate via browser-based OAuth (currently Anthropic). No need to manage API keys manually.
 
 ---
 
-## 🔮 Tech Stack
+## 🛠️ Features
 
-- **Runtime:** [Bun.js](https://bun.com) — fast, modern, all-in-one
-- **LLM routing:** [AI SDK](https://ai-sdk.dev) — multi-provider with streaming
-- **Colors:** [yoctocolors](https://github.com/sindresorhus/yoctocolors) — tiny and terminal-theme-aware
-- **Schema validation:** [Zod](https://zod.dev)
-- **Linting/formatting:** [Biome](https://biomejs.dev)
-- **Storage:** `bun:sqlite` — zero-dependency local sessions
+- **Multi-provider** — auto-discovers Anthropic, OpenAI, Gemini, Ollama, or any OpenAI-compatible endpoint
+- **Session memory** — SQLite-backed. Resume with `-c` or `-r <id>`
+- **Shell integration** — `!` prefix for inline commands, `@` to reference files with tab completion
+- **Subagents** — spawn parallel mini-coder instances for independent subtasks
+- **Web search** — `webSearch` + `webContent` tools when `EXA_API_KEY` is set
+- **MCP support** — connect external tool servers over HTTP or stdio
+- **Custom commands** — drop `.md` files in `.agents/commands/` → instant `/slash` commands
+- **Custom agents** — `.agents/agents/*.md` for specialized personas, usable as primary or via subagent
+- **Skills** — `.agents/skills/<name>/SKILL.md`, inject with `@name`
+- **`mc-edit`** — safe, exact-text file editing (no full-file rewrites)
+- **16 ANSI colors** — inherits your terminal theme. Always looks right.
 
 ---
 
-## 💬 Philosophy
+## 📚 Getting Deeper
 
-> Accurate. Fast. Focused on the conversation.
+The README is the highlight reel. For the full story — slash commands, config folders, context files, app data, and everything else:
 
-I believe the best tools disappear into your workflow. I don't want to be the star of the show — I want _you_ to ship great code, faster.
+**[📖 Read the Full Manual](docs/mini-coder.1.md)**
 
 ---
 
-## 💬 What People Are Saying
+## 🔮 Tech Stack
 
-> "sean this is fucking sick"
-> — [vpr99](https://github.com/vpr99)
+[Bun.js](https://bun.com) · [AI SDK](https://ai-sdk.dev) · [yoctocolors](https://github.com/sindresorhus/yoctocolors)
 
----
+## 📄 License
 
-_Built with ❤️ and a healthy obsession with terminal aesthetics._
+MIT — [github.com/sacenox/mini-coder](https://github.com/sacenox/mini-coder)

package/dist/mc.js

@@ -9,7 +9,7 @@ import * as c23 from "yoctocolors";
 import * as c12 from "yoctocolors";
 
 // src/cli/load-markdown-configs.ts
-import { existsSync as existsSync4, readdirSync as readdirSync2, readFileSync as readFileSync3, statSync as statSync2 } from "fs";
+import { existsSync as existsSync4, readdirSync as readdirSync3, readFileSync as readFileSync3, statSync as statSync2 } from "fs";
 import { homedir as homedir4 } from "os";
 import { basename, join as join5 } from "path";
 
@@ -99,16 +99,58 @@ ${content}
 }
 
 // src/cli/error-log.ts
-import { mkdirSync, writeFileSync } from "fs";
+import { writeFileSync } from "fs";
+
+// src/cli/log-paths.ts
+import { mkdirSync, readdirSync, unlinkSync } from "fs";
 import { homedir } from "os";
 import { join as join2 } from "path";
+var LOGS_DIR = join2(homedir(), ".config", "mini-coder", "logs");
+function getLogsDir() {
+  mkdirSync(LOGS_DIR, { recursive: true });
+  return LOGS_DIR;
+}
+function pidLogPath(prefix) {
+  return join2(getLogsDir(), `${prefix}-${process.pid}.log`);
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var LOG_FILE_RE = /^(api|errors)-(\d+)\.log$/;
+function cleanStaleLogs() {
+  let entries;
+  try {
+    entries = readdirSync(LOGS_DIR);
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    const m = LOG_FILE_RE.exec(name);
+    if (!m)
+      continue;
+    const pidStr = m[2];
+    const pid = Number.parseInt(pidStr, 10);
+    if (pid === process.pid)
+      continue;
+    if (!isProcessAlive(pid)) {
+      try {
+        unlinkSync(join2(LOGS_DIR, name));
+      } catch {}
+    }
+  }
+}
+
+// src/cli/error-log.ts
 var writer = null;
 function initErrorLog() {
   if (writer)
     return;
-  const dirPath = join2(homedir(), ".config", "mini-coder");
-  const logPath = join2(dirPath, "errors.log");
-  mkdirSync(dirPath, { recursive: true });
+  const logPath = pidLogPath("errors");
   writeFileSync(logPath, "");
   writer = Bun.file(logPath).writer();
   process.on("uncaughtException", (err) => {
@@ -295,7 +337,7 @@ import {
   closeSync,
   existsSync as existsSync2,
   openSync,
-  readdirSync,
+  readdirSync as readdirSync2,
   readFileSync as readFileSync2,
   readSync,
   statSync
@@ -384,7 +426,7 @@ function listSkillCandidates(skillsDir, source, rootPath) {
     return [];
   let entries;
   try {
-    entries = readdirSync(skillsDir).sort((a, b) => a.localeCompare(b));
+    entries = readdirSync2(skillsDir).sort((a, b) => a.localeCompare(b));
   } catch {
     return [];
   }
@@ -1761,7 +1803,7 @@ async function renderTurn(events, spinner, opts) {
 
 // src/cli/output.ts
 var HOME = homedir3();
-var PACKAGE_VERSION = "0.1.0";
+var PACKAGE_VERSION = "0.1.1";
 function tildePath(p) {
   return p.startsWith(HOME) ? `~${p.slice(HOME.length)}` : p;
 }
@@ -1984,7 +2026,7 @@ function loadMarkdownConfigs(opts) {
       return configs;
     let entries;
     try {
-      entries = readdirSync2(dir);
+      entries = readdirSync3(dir);
     } catch {
       return configs;
     }
@@ -2124,7 +2166,7 @@ async function connectMcpServer(config) {
 
 // src/session/db/connection.ts
 import { Database } from "bun:sqlite";
-import { existsSync as existsSync5, mkdirSync as mkdirSync2, unlinkSync } from "fs";
+import { existsSync as existsSync5, mkdirSync as mkdirSync2, unlinkSync as unlinkSync2 } from "fs";
 import { homedir as homedir5 } from "os";
 import { join as join6 } from "path";
 function getConfigDir() {
@@ -2255,7 +2297,7 @@ function getDb() {
       } catch {}
       for (const path of [dbPath, `${dbPath}-wal`, `${dbPath}-shm`]) {
         if (existsSync5(path))
-          unlinkSync(path);
+          unlinkSync2(path);
       }
       db = new Database(dbPath, { create: true });
       configureDb(db);
@@ -3538,17 +3580,13 @@ async function getAccessToken(providerId) {
 }
 
 // src/llm-api/api-log.ts
-import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync2 } from "fs";
-import { homedir as homedir6 } from "os";
-import { join as join9 } from "path";
+import { writeFileSync as writeFileSync2 } from "fs";
 var writer2 = null;
 var MAX_ENTRY_BYTES = 8 * 1024;
 function initApiLog() {
   if (writer2)
     return;
-  const dirPath = join9(homedir6(), ".config", "mini-coder");
-  const logPath = join9(dirPath, "api.log");
-  mkdirSync3(dirPath, { recursive: true });
+  const logPath = pidLogPath("api");
   writeFileSync2(logPath, "");
   writer2 = Bun.file(logPath).writer();
 }
@@ -3969,24 +4007,31 @@ async function fetchOpenAIModels() {
     free: false
   }));
 }
-async function getAnthropicApiKey() {
+async function getAnthropicAuth() {
   const envKey = process.env.ANTHROPIC_API_KEY;
   if (envKey)
-    return envKey;
-  if (isLoggedIn("anthropic"))
-    return getAccessToken("anthropic");
+    return { key: envKey, oauth: false };
+  if (isLoggedIn("anthropic")) {
+    const token = await getAccessToken("anthropic");
+    if (token)
+      return { key: token, oauth: true };
+  }
   return null;
 }
 async function fetchAnthropicModels() {
-  const key = await getAnthropicApiKey();
-  if (!key)
+  const auth = await getAnthropicAuth();
+  if (!auth)
     return null;
-  const payload = await fetchJson(`${ANTHROPIC_BASE}/v1/models`, {
-    headers: {
-      "x-api-key": key,
-      "anthropic-version": "2023-06-01"
-    }
-  }, 6000);
+  const headers = {
+    "anthropic-version": "2023-06-01"
+  };
+  if (auth.oauth) {
+    headers.Authorization = `Bearer ${auth.key}`;
+    headers["anthropic-beta"] = "oauth-2025-04-20";
+  } else {
+    headers["x-api-key"] = auth.key;
+  }
+  const payload = await fetchJson(`${ANTHROPIC_BASE}/v1/models`, { headers }, 6000);
   return processModelsList(payload, "data", "id", (item, modelId) => {
     const displayName = typeof item.display_name === "string" && item.display_name.trim().length > 0 ? item.display_name : modelId;
     return {
@@ -5523,8 +5568,8 @@ function getMostRecentSession() {
 
 // src/agent/system-prompt.ts
 import { existsSync as existsSync6, readFileSync as readFileSync4 } from "fs";
-import { homedir as homedir7 } from "os";
-import { join as join10 } from "path";
+import { homedir as homedir6 } from "os";
+import { join as join9 } from "path";
 function tryReadFile(p) {
   if (!existsSync6(p))
     return null;
@@ -5535,11 +5580,11 @@ function tryReadFile(p) {
   }
 }
 function loadGlobalContextFile(homeDir) {
-  const globalDir = join10(homeDir, ".agents");
-  return tryReadFile(join10(globalDir, "AGENTS.md")) ?? tryReadFile(join10(globalDir, "CLAUDE.md"));
+  const globalDir = join9(homeDir, ".agents");
+  return tryReadFile(join9(globalDir, "AGENTS.md")) ?? tryReadFile(join9(globalDir, "CLAUDE.md"));
 }
 function loadLocalContextFile(cwd) {
-  return tryReadFile(join10(cwd, ".agents", "AGENTS.md")) ?? tryReadFile(join10(cwd, "CLAUDE.md")) ?? tryReadFile(join10(cwd, "AGENTS.md"));
+  return tryReadFile(join9(cwd, ".agents", "AGENTS.md")) ?? tryReadFile(join9(cwd, "CLAUDE.md")) ?? tryReadFile(join9(cwd, "AGENTS.md"));
 }
 var AUTONOMY = `
 
@@ -5581,7 +5626,7 @@ var FINAL_MESSAGE = `
 - If verification could not be run, say so clearly.`;
 var SUBAGENT_DELEGATION = `You are running as a subagent. Complete the task you have been given directly using your tools. Do not spawn further subagents unless the subtask is unambiguously separable and self-contained.`;
 function buildSystemPrompt(sessionTimeAnchor, cwd, extraSystemPrompt, isSubagent, homeDir) {
-  const globalContext = loadGlobalContextFile(homeDir ?? homedir7());
+  const globalContext = loadGlobalContextFile(homeDir ?? homedir6());
   const localContext = loadLocalContextFile(cwd);
   const cwdDisplay = tildePath(cwd);
   let prompt = `You are mini-coder, a small and fast CLI coding agent.
@@ -6130,7 +6175,7 @@ import { z as z2 } from "zod";
 
 // src/internal/file-edit/command.ts
 import { existsSync as existsSync7 } from "fs";
-import { dirname as dirname2, extname, join as join11 } from "path";
+import { dirname as dirname2, extname, join as join10 } from "path";
 import { fileURLToPath } from "url";
 function quoteShellArg(value) {
   return `'${value.replaceAll("'", `'\\''`)}'`;
@@ -6142,7 +6187,7 @@ function resolveSiblingFileEditScript(scriptPath) {
   const mainDir = dirname2(scriptPath);
   const mainBase = scriptPath.slice(mainDir.length + 1);
   if (mainBase === `index${ext}` || mainBase === `mc${ext}`) {
-    return join11(mainDir, `mc-edit${ext}`);
+    return join10(mainDir, `mc-edit${ext}`);
   }
   return null;
 }
@@ -6151,7 +6196,7 @@ function resolveModuleLocalFileEditScript(moduleUrl) {
   const ext = extname(modulePath);
   if (!ext)
     return null;
-  const helperPath = join11(dirname2(modulePath), "..", "..", `mc-edit${ext}`);
+  const helperPath = join10(dirname2(modulePath), "..", "..", `mc-edit${ext}`);
   return existsSync7(helperPath) ? helperPath : null;
 }
 function resolveFileEditCommand(execPath, mainModule, argv1, moduleUrl = import.meta.url) {
@@ -6617,9 +6662,9 @@ ${c13.bold("Examples:")}`);
 }
 
 // src/cli/bootstrap.ts
-import { existsSync as existsSync8, mkdirSync as mkdirSync4, writeFileSync as writeFileSync3 } from "fs";
-import { homedir as homedir8 } from "os";
-import { join as join12 } from "path";
+import { existsSync as existsSync8, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "fs";
+import { homedir as homedir7 } from "os";
+import { join as join11 } from "path";
 import * as c14 from "yoctocolors";
 var REVIEW_COMMAND_CONTENT = `---
 description: Review recent changes for correctness, code quality, and performance
@@ -6639,17 +6684,17 @@ Perform a sensible code review:
 Output a small summary with only the issues found. If nothing is wrong, say so.
 `;
 function bootstrapGlobalDefaults() {
-  const commandsDir = join12(homedir8(), ".agents", "commands");
-  const reviewPath = join12(commandsDir, "review.md");
+  const commandsDir = join11(homedir7(), ".agents", "commands");
+  const reviewPath = join11(commandsDir, "review.md");
   if (!existsSync8(reviewPath)) {
-    mkdirSync4(commandsDir, { recursive: true });
+    mkdirSync3(commandsDir, { recursive: true });
     writeFileSync3(reviewPath, REVIEW_COMMAND_CONTENT, "utf-8");
     writeln(`${c14.green("\u2713")} created ${c14.dim("~/.agents/commands/review.md")} ${c14.dim("(edit it to customise your reviews)")}`);
   }
 }
 
 // src/cli/file-refs.ts
-import { join as join13 } from "path";
+import { join as join12 } from "path";
 async function resolveFileRefs(text, cwd) {
   const atPattern = /@([\w./\-_]+)/g;
   let result = text;
@@ -6677,7 +6722,7 @@ ${content}
       result = result.slice(0, match.index) + replacement + result.slice((match.index ?? 0) + match[0].length);
       continue;
     }
-    const filePath = ref.startsWith("/") ? ref : join13(cwd, ref);
+    const filePath = ref.startsWith("/") ? ref : join12(cwd, ref);
     if (isImageFilename(ref)) {
       const attachment = await loadImageFile(filePath);
       if (attachment) {
@@ -7606,6 +7651,9 @@ function writeJsonLine(write2, payload) {
 registerTerminalCleanup();
 initErrorLog();
 initApiLog();
+if (!process.env.MC_SUBAGENT_DEPTH || process.env.MC_SUBAGENT_DEPTH === "0") {
+  cleanStaleLogs();
+}
 initModelInfoCache();
 pruneOldData();
 refreshModelInfoInBackground().catch(() => {});

package/docs/mini-coder.1.md

@@ -1,156 +1,275 @@
 # MINI-CODER(1)
 
 ## NAME
-**mini-coder** (executable: `mc`) - A small, fast CLI coding agent built for developers.
+
+**mini-coder** — a small, fast CLI coding agent (executable: `mc`)
 
 ## SYNOPSIS
-`mc [options] [prompt]`
+
+`mc` \[*options*\] \[*prompt*\]
 
 ## DESCRIPTION
-**mini-coder** is a developer-focused CLI coding agent. It prioritizes developer flow with no slow startup, no clunky GUI, and no vendor lock-in. It uses a minimalist terminal UI restricted to 16 ANSI colors to inherit the user's terminal theme, and is built entirely on Bun.js for maximum performance.
+
+Developer-focused CLI coding agent. Prioritizes dev flow — no slow startup, no GUI, no vendor lock-in. Uses 16 ANSI colors to inherit terminal theme. Built on Bun.js.
 
 ## OPTIONS
-**-m, --model <id>**
-:   Specify the model to use (e.g., `zen/claude-sonnet-4-6`).
 
-**-c, --continue**
-:   Continue the most recent session.
+`-m`, `--model` *id*
+: Model to use (e.g. `zen/claude-sonnet-4-6`).
+
+`-c`, `--continue`
+: Continue most recent session.
 
-**-r, --resume <id>**
-:   Resume a specific session by its ID.
+`-r`, `--resume` *id*
+: Resume a specific session.
 
-**-l, --list**
-:   List recent sessions.
+`-l`, `--list`
+: List recent sessions.
 
-**--cwd <path>**
-:   Set the working directory (defaults to current directory).
+`--cwd` *path*
+: Set working directory.
 
-**-h, --help**
-:   Display help information.
+`-h`, `--help`
+: Display help.
 
-**[prompt]**
-:   Optional one-shot prompt text. Runs once, then exits.
+*prompt*
+: Optional one-shot prompt. Runs once then exits.
 
 ## INTERACTIVE COMMANDS
-Inside the interactive session, the following slash commands are available:
 
-**/model**
-:   List all available models, indicating free models and context sizes.
+`/model`
+: List all available models.
 
-**/model <id>**
-:   Switch to a specific model.
+`/model` *id*
+: Switch model.
 
-**/model effort <low|medium|high|xhigh|off>**
-:   Configure reasoning effort levels for models that support it.
+`/model effort` *low|medium|high|xhigh|off*
+: Set reasoning effort.
 
-**/reasoning [on|off]**
-:   Toggle the display of the model's reasoning/thought process.
+`/reasoning` \[*on|off*\]
+: Toggle reasoning display.
 
-**/context prune <off|balanced|aggressive>**
-:   Configure context window pruning strategies.
+`/context prune` *off|balanced|aggressive*
+: Pruning strategy.
 
-**/context cap <off|bytes|kb>**
-:   Set a hard payload cap size for tool results to avoid blowing out context.
+`/context cap` *off|bytes|kb*
+: Tool result payload cap.
 
-**/cache <on|off>**
-:   Toggle prompt caching globally.
+`/cache` *on|off*
+: Toggle prompt caching globally.
 
-**/cache openai <in_memory|24h>**
-:   Set OpenAI prompt cache retention policies.
+`/cache openai` *in_memory|24h*
+: OpenAI cache retention.
 
-**/cache gemini <off|cachedContents/...>**
-:   Attach Google Gemini cached content.
+`/cache gemini` *off|cachedContents/...*
+: Gemini cached content.
 
-**/undo**
-:   Remove the last conversation turn. This does not revert filesystem changes.
+`/undo`
+: Remove last turn (does NOT revert filesystem).
 
-**/new**
-:   Clear context and start a fresh session.
+`/new`
+: Start a fresh session.
 
-**/mcp list**
-:   List configured MCP servers.
+`/verbose`
+: Toggle output truncation.
 
-**/mcp add <name> http <url>**
-:   Add an MCP server over HTTP.
+`/mcp list`
+: List MCP servers.
 
-**/mcp add <name> stdio <cmd> [args...]**
-:   Add an MCP server over stdio.
+`/mcp add` *name* `http` *url*
+: Add HTTP MCP server.
 
-**/mcp remove <name>** (or **rm**)
-:   Remove an MCP server.
+`/mcp add` *name* `stdio` *cmd* \[*args...*\]
+: Add stdio MCP server.
 
-**/agent [name]**
-:   Set or clear an active primary custom agent.
+`/mcp remove` *name*
+: Remove MCP server.
 
-**/review**
-:   Custom command that reviews the current session's changes (defined via `.agents/commands/`).
+`/agent` \[*name*\]
+: Set or clear active primary agent.
 
+`/review`
+: Review changes (custom command, auto-created globally).
 
-**/help**
-:   Display command help.
+`/login`
+: Show OAuth login status.
 
-**/exit, /quit, /q**
-:   Leave the session.
+`/login` *provider*
+: Login via OAuth (opens browser for device flow). Currently supports `anthropic`.
+
+`/logout` *provider*
+: Clear saved OAuth tokens.
+
+`/help`
+: Command help.
+
+`/exit`, `/quit`, `/q`
+: Leave session.
 
 ## INLINE FEATURES
-**Shell Integration**
-:   Prefix user prompts with `!` to run shell commands inline directly into the context.
 
-**File & Skill Referencing**
-:   Prefix words with `@` to reference files or skills within prompts (supports tab completion).
+`!` prefix
+: Runs shell commands inline.
+
+`@` prefix
+: References files or skills (with tab completion).
 
 ## BUILT-IN TOOLS
-The agent has access to the following tools:
-*   **shell**: Execute bash commands and capture output. Repo inspection and targeted file edits are typically done here via `mc-edit`.
-*   **subagent**: Spawn a focused mini-agent with a prompt.
-*   **listSkills**: List discovered skills without loading full skill bodies.
-*   **readSkill**: Load one `SKILL.md` on demand.
-*   **webSearch**: Search the internet (requires EXA key).
-*   **webContent**: Fetch full page content from a URL (requires EXA key).
-*   **MCP tools**: Connected external tools attached dynamically from configured MCP servers.
-
-## FILE EDIT HELPER
-**mc-edit**
-:   Helper command used from shell for one exact-text edit on an existing file. On success it prints a human-readable plain unified diff to stdout followed by a short metadata block (`ok`, `path`, `changed`). If the edit is a no-op, it prints `(no changes)` plus the same metadata. Errors are written to stderr.
 
-## ENVIRONMENT
-**OPENCODE_API_KEY**
-:   OpenCode Zen API key (Recommended provider).
+**shell**
+: Execute bash commands; repo inspection and `mc-edit` edits happen here.
+
+**subagent**
+: Spawn a focused mini-agent for parallel subtasks.
+
+**listSkills**
+: List discovered skills (metadata only).
+
+**readSkill**
+: Load one SKILL.md on demand.
+
+**webSearch**
+: Search the web (requires `EXA_API_KEY`).
+
+**webContent**
+: Fetch page content (requires `EXA_API_KEY`).
+
+MCP tools are connected dynamically from configured MCP servers.
+
+## FILE EDITING — mc-edit
+
+`mc-edit` is the helper for targeted file edits, invoked from **shell**.
+
+```
+mc-edit <path> (--old <text> | --old-file <path>) [--new <text> | --new-file <path>] [--cwd <path>]
+```
+
+- Applies one exact-text edit to an existing file.
+- The old text must match exactly once.
+- Omit `--new`/`--new-file` to delete the matched text.
+- Success: prints unified diff + metadata (`ok`, `path`, `changed`).
+- No-op: prints `(no changes)` + metadata.
+- Errors go to stderr.
+
+Workflow: inspect with **shell** → edit with **mc-edit** → verify with **shell**.
+
+## CUSTOM COMMANDS
+
+Drop a `.md` file in `.agents/commands/` (local) or `~/.agents/commands/` (global) and it becomes a `/command`. Filename equals command name (`standup.md` → `/standup`).
+
+`.claude/commands/*.md` is also supported.
+
+**Frontmatter fields:**
+
+`description`
+: Shown in `/help`.
+
+`model`
+: Override model (only with `context: fork`).
+
+`context`
+: `fork` to run as isolated subagent; default is inline.
+
+`subtask`
+: `true` forces subagent (OpenCode-compatible alias).
+
+`agent`
+: Run under named agent's system prompt (only with `context: fork`).
+
+**Argument substitution:**
 
-**ANTHROPIC_API_KEY**
-:   Direct Anthropic API key.
+`$ARGUMENTS` expands to the full argument string; `$1`–`$9` expand to positional tokens.
+
+**Shell interpolation:**
+
+`` !`cmd` `` injects shell output at expansion time (10 s timeout).
+
+**Precedence:** custom commands shadow built-ins. Local overrides global.
+
+## CUSTOM AGENTS
+
+Drop a `.md` file in `.agents/agents/` (local) or `~/.agents/agents/` (global). Filename equals agent name. Activate with `/agent <name>`.
+
+`.claude/agents/*.md` is also supported.
+
+**Frontmatter fields:**
+
+`description`
+: Shown in `/help`.
+
+`model`
+: Override active model.
+
+`mode`
+: `primary` excludes from subagent tool; `subagent`/`all`/omitted keeps it available.
+
+Body is the agent system prompt. Non-primary agents are exposed to the **subagent** tool for delegation.
+
+## SKILLS
+
+Skills are reusable instruction files at `.agents/skills/<name>/SKILL.md`.
+
+`.claude/skills/<name>/SKILL.md` is also supported.
+
+**Frontmatter (both required):**
+
+`name`
+: Lowercase alphanumeric + hyphens, 1–64 chars.
+
+`description`
+: Help text.
+
+Skills are never auto-loaded. Load explicitly:
+
+- `@skill-name` in prompts (injects body wrapped in `<skill>` XML).
+- **listSkills** / **readSkill** tools at runtime.
+
+Local discovery walks up from cwd to the git worktree root.
+
+## CONFIGURATION
+
+Supports `.agents` and `.claude` layouts for commands, skills, agents, and context.
+
+Config roots: `.agents/`, `.claude/` — local (repo) or global (`~/`).
+
+**Context files** (one global + one local loaded):
+
+- Global: `~/.agents/AGENTS.md` → `~/.agents/CLAUDE.md`
+- Local: `./.agents/AGENTS.md` → `./CLAUDE.md` → `./AGENTS.md`
+
+**Precedence:**
+
+1. Local overrides global.
+2. Same scope: `.agents` wins over `.claude`.
+3. Skills: nearest ancestor directory wins.
+
+## ENVIRONMENT
 
-**OPENAI_API_KEY**
-:   Direct OpenAI API key.
+`OPENCODE_API_KEY`
+: OpenCode Zen (recommended).
 
-**GOOGLE_API_KEY** (or **GEMINI_API_KEY**)
-:   Direct Google Gemini API key.
+`ANTHROPIC_API_KEY`
+: Direct Anthropic.
 
-**OLLAMA_BASE_URL**
-:   Ollama local base URL (Defaults to `http://localhost:11434`).
+`OPENAI_API_KEY`
+: Direct OpenAI.
 
-**EXA_API_KEY**
-:   Enables built-in `webSearch` and `webContent` tools.
+`GOOGLE_API_KEY` / `GEMINI_API_KEY`
+: Direct Gemini.
 
-## FILES & DIRECTORIES
-**~/.config/mini-coder/**
-:   Application data directory. Contains `sessions.db` (SQLite database for session history, MCP server configs, and model metadata), `api.log`, and `errors.log`.
+`OLLAMA_BASE_URL`
+: Ollama local (defaults to `http://localhost:11434`).
 
-**.agents/ or .claude/ (Local or Global in ~/)**
-:   Configuration directories for advanced features:
-    *   **commands/*.md**: Custom slash commands.
-    *   **agents/*.md**: Custom behavioral wrappers or subagents.
-    *   **skills/<name>/SKILL.md**: Isolated context/instruction snippets.
+`EXA_API_KEY`
+: Enables **webSearch** / **webContent**.
 
-**AGENTS.md / CLAUDE.md**
-:   Auto-loaded system context files for project-specific instructions.
+## FILES
 
-## CORE FEATURES & ARCHITECTURE
-*   **Multi-Provider LLM Routing**: Automatically discovers API keys to route to OpenCode (Zen), Anthropic, OpenAI, Google/Gemini, or local Ollama instances.
-*   **Session Memory**: Persists conversation history in a local SQLite database, allowing users to resume past sessions effortlessly.
-*   **Subagent Delegation**: Includes a tool to spawn parallel instances of itself to tackle independent subtasks simultaneously (up to 10 levels deep).
-*   **Model Context Protocol (MCP)**: Native support for connecting external tools via MCP servers over HTTP or stdio.
-*   **Prompt Caching**: Configurable caching behaviors for supported providers (OpenAI, Gemini).
-*   **Undo Functionality**: Remove the last conversation turn from the current session history. It does not restore filesystem changes.
+`~/.config/mini-coder/`
+: App data directory (sessions.db, api.log, errors.log).
 
+`.agents/` or `.claude/`
+: Config directories for commands, agents, skills.
 
+`AGENTS.md` / `CLAUDE.md`
+: Project context files.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mini-coder",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"description": "A small, fast CLI coding agent",
 	"module": "src/index.ts",
 	"type": "module",

package/docs/configs.md

@@ -1,118 +0,0 @@
-# Config conventions
-
-mini-coder supports both its native `.agents` convention and `.claude` layouts for commands, skills, and agents.
-
-Only commands, skills, agents, and context files are loaded from these roots. Hook directories are ignored.
-
-Discovery is not identical for every config type:
-
-- **Commands** and **agents** are loaded from the current working directory and the home directory only.
-- **Skills** are loaded from the home directory plus local directories discovered by walking up from the current working directory to the git worktree root.
-- **Context files** are only loaded from the current working directory and the home directory.
-
-## Supported config roots
-
-| Root | Purpose |
-|---|---|
-| `.agents/` | mini-coder native config |
-| `.claude/` | Alternate config layout supported by mini-coder |
-
-Each root can exist in:
-
-- **Local (repo):** `./.agents`, `./.claude`
-- **Global (home):** `~/.agents`, `~/.claude`
-
-## Commands
-
-Supported locations:
-
-- `./.agents/commands/*.md`
-- `~/.agents/commands/*.md`
-- `./.claude/commands/*.md`
-- `~/.claude/commands/*.md`
-
-Format:
-
-```md
----
-description: Optional help text
-model: optional/model-override
----
-
-Prompt template body with $ARGUMENTS and $1..$9 support.
-```
-
-Filename becomes the command name (`review.md` => `/review`).
-
-## Skills
-
-Supported locations:
-
-- local: `./.agents/skills/<skill-name>/SKILL.md` and `./.claude/skills/<skill-name>/SKILL.md`
-- global: `~/.agents/skills/<skill-name>/SKILL.md` and `~/.claude/skills/<skill-name>/SKILL.md`
-
-For local skills, mini-coder searches not just the current working directory, but each ancestor directory up to the git worktree root.
-
-Format:
-
-```md
----
-name: required-skill-name
-description: Required help text
----
-
-Skill instructions/content.
-```
-
-Both `name` and `description` are required. Invalid skills are skipped with a warning.
-
-## Agents
-
-Supported locations:
-
-- `./.agents/agents/*.md`
-- `~/.agents/agents/*.md`
-- `./.claude/agents/*.md`
-- `~/.claude/agents/*.md`
-
-Format:
-
-```md
----
-description: Optional help text
-model: optional/model-override
-mode: optional agent mode
----
-
-Agent system prompt.
-```
-
-## Context files
-
-mini-coder loads at most one global context file and at most one local context file, then includes both when present.
-
-Global lookup order:
-
-1. `~/.agents/AGENTS.md`
-2. `~/.agents/CLAUDE.md`
-
-Local lookup order:
-
-1. `./.agents/AGENTS.md`
-2. `./CLAUDE.md`
-3. `./AGENTS.md`
-
-Injection order:
-
-1. Global context (if found)
-2. Local context (if found)
-
-## Precedence and conflicts
-
-Precedence rules for commands, skills, and agents:
-
-1. **Local overrides global**
-2. At the **same scope** (both local or both global), if `.agents` and `.claude` define the same name, **`.agents` wins**
-3. For **skills only**, when the same skill name exists in multiple local ancestor directories, the skill nearest to the current working directory wins
-
-When same-scope `.agents` / `.claude` conflicts are detected for commands, skills, or agents, mini-coder prints a warning and uses the `.agents` version.

package/docs/custom-agents.md

@@ -1,69 +0,0 @@
-# Custom Agents
-
-A custom agent is a reusable system prompt with an optional model override.
-You can activate one with `/agent <name>`, and non-`primary` agents are also exposed to the `subagent` tool.
-
-mini-coder is shell-first, so custom agents should assume repo inspection and verification happen through shell, with targeted edits done via `mc-edit` invoked from shell.
-
-## Where to put them
-
-| Location | Scope |
-|---|---|
-| `.agents/agents/*.md` | Current repo only |
-| `~/.agents/agents/*.md` | All projects (global) |
-| `.claude/agents/*.md` | Current repo only (`.claude` layout) |
-| `~/.claude/agents/*.md` | All projects (global, `.claude` layout) |
-
-Local agents override global ones with the same name. At the same scope, `.agents` wins over `.claude`.
-
-## Create an agent
-
-The filename becomes the agent name.
-
-`~/.agents/agents/reviewer.md`:
-
-```md
----
-description: Strict code reviewer focused on bugs and structure
-model: zen/claude-sonnet-4-6
----
-
-You are a senior engineer doing a code review. Be direct and specific.
-Cite file and line number for every finding. Flag bugs first, then
-structure issues, then style — only if they violate project conventions.
-No flattery. End with a one-line verdict.
-```
-
-Then in the REPL:
-
-```
-/agent reviewer
-review the auth module for race conditions
-```
-
-## Frontmatter fields
-
-| Field | Required | Description |
-|---|---|---|
-| `description` | No | Shown in `/help`. Defaults to filename. |
-| `model` | No | Override the active model for this agent. |
-| `mode` | No | Controls whether the agent is exposed through the `subagent` tool. `primary` excludes it from that tool and is intended for `/agent`. `subagent`, `all`, and an omitted value all keep it available to the `subagent` tool. Any loaded agent can currently still be selected with `/agent <name>`. |
-
-The markdown body (after frontmatter) is the agent's system prompt.
-
-## Combining with files
-
-File references are resolved before the prompt is sent:
-
-```
-/agent reviewer
-@src/auth/session.ts check this file for issues
-```
-
-## Listing agents
-
-```
-/help
-```
-
-Agents are listed in magenta, tagged `(local)` or `(global)`.

package/docs/custom-commands.md

@@ -1,141 +0,0 @@
-# Custom Commands
-
-Custom commands let you define reusable prompts that run as `/command` in the mini-coder REPL.
-
-mini-coder is shell-first: when a command needs repo inspection or verification, tell it to use shell. When it needs a targeted file edit, tell it to invoke `mc-edit` from shell rather than relying on old local file-edit tools.
-
-## Where to put them
-
-| Location | Scope |
-|---|---|
-| `.agents/commands/*.md` | Current repo only |
-| `~/.agents/commands/*.md` | All projects (global) |
-| `.claude/commands/*.md` | Current repo only (Claude-compatible) |
-| `~/.claude/commands/*.md` | All projects (global, Claude-compatible) |
-
-Local commands override global ones with the same name. At the same scope, `.agents` wins over `.claude`.
-
-## Create a command
-
-Create a markdown file. The filename becomes the command name.
-
-`.agents/commands/standup.md`:
-
-```md
----
-description: Summarise what changed since yesterday
-model: zen/claude-haiku-4-5
----
-
-Run `!`git log --oneline --since=yesterday`` and summarise the changes
-as a short standup update. Group by theme, skip merge commits.
-```
-
-Then in the REPL:
-
-```
-/standup
-```
-
-## Frontmatter fields
-
-| Field | Required | Description |
-|---|---|---|
-| `description` | No | Shown in `/help`. Defaults to the command name. |
-| `model` | No | Override the active model for this command (only applies when `context: fork`). |
-| `context` | No | Set to `fork` to run the command as an isolated subagent; default runs inline. |
-| `subtask` | No | Set to `true` to force subagent execution (OpenCode-compatible alias for `context: fork`). |
-| `agent` | No | Run the command under a named agent's system prompt (only applies when `context: fork`). |
-
-## Arguments
-
-Use `$ARGUMENTS` for the full argument string, or `$1`, `$2`, … `$9` for individual tokens.
-
-`.agents/commands/search.md`:
-
-```md
----
-description: Search the codebase for a topic
-model: zen/claude-haiku-4-5
----
-
-Search the codebase for: $ARGUMENTS
-
-Use shell and skill-loading tools as needed to explore thoroughly. Report all
-relevant files, key code snippets with line numbers, and a short summary.
-Be exhaustive but concise. No edits.
-```
-
-```
-/search session management
-/search error handling in providers
-```
-
-Positional tokens:
-
-```md
----
-description: Create a new component
----
-
-Create a React component named $1 in the $2 directory.
-Use TypeScript, include prop types and a default export.
-```
-
-```
-/component Button src/ui
-```
-
-## Shell interpolation
-
-Use `` !`cmd` `` to inject shell output into the prompt at expansion time.
-Commands time out after 10 seconds.
-
-```md
----
-description: Review failing tests
----
-
-The following tests are currently failing:
-
-!`bun test 2>&1 | grep "fail\|✗" | head -20`
-
-Investigate the failures and suggest fixes. Read the relevant source
-files before drawing conclusions.
-```
-
-```
-/fix-tests
-```
-
-## Model override
-
-Specify a model in frontmatter to use a faster or cheaper model for
-lightweight tasks regardless of what the session is currently set to.
-
-```md
----
-description: Quick symbol search
-model: zen/claude-haiku-4-5
----
-
-Find all usages of $ARGUMENTS across the codebase using shell.
-List each occurrence with file path and line number. No explanations needed.
-```
-
-Large models for deep analysis, small models for search and lookup.
-
-## Precedence
-
-Custom commands shadow built-ins. The global `/review`
-command (auto-created at `~/.agents/commands/review.md` on first run) works
-the same way — a local `.agents/commands/review.md` will override it.
-
-## Listing commands
-
-```
-/help
-```
-
-Custom commands are listed at the bottom under **custom commands**, tagged
-with `(local)` or `(global)`.

package/docs/skills.md

@@ -1,83 +0,0 @@
-# Skills
-
-Skills are reusable instruction files discovered automatically from local and global directories.
-
-When a skill tells mini-coder how to work with files, prefer shell for inspection/search/verification and `mc-edit` from shell for targeted edits.
-
-- The model sees **skill metadata only** by default (name, description, source).
-- Full `SKILL.md` content is loaded **on demand**:
-	- when explicitly requested with the runtime skill tools (`listSkills` / `readSkill`), or
-	- when you reference `@skill-name` in your prompt.
-
-## Discovery locations
-
-Skills live in folders containing `SKILL.md`:
-
-| Location | Scope |
-|---|---|
-| `.agents/skills/<name>/SKILL.md` | Local |
-| `.claude/skills/<name>/SKILL.md` | Local (Claude-compatible) |
-| `~/.agents/skills/<name>/SKILL.md` | Global |
-| `~/.claude/skills/<name>/SKILL.md` | Global (Claude-compatible) |
-
-Local discovery walks up from the current working directory to the git worktree root.
-
-## Precedence rules
-
-If multiple skills share the same `name`, precedence is deterministic:
-
-1. Nearest local directory wins over farther ancestor directories.
-2. Any local skill wins over global.
-3. At the same scope/path level, `.agents` wins over `.claude`.
-
-## Frontmatter
-
-`SKILL.md` frontmatter supports:
-
-- `name` (**required**)
-- `description` (**required**)
-
-`name` constraints:
-
-- lowercase alphanumeric and hyphen format (`^[a-z0-9]+(?:-[a-z0-9]+)*$`)
-- 1–64 characters
-
-Unknown frontmatter fields are allowed.
-
-If either `name` or `description` is missing, mini-coder skips the skill and prints a warning.
-
-
-## Create a skill
-
-`.agents/skills/conventional-commits/SKILL.md`:
-
-```md
----
-name: conventional-commits
-description: Conventional commit message format rules
----
-
-# Conventional Commits
-
-Use:
-<type>(<scope>): <short summary>
-```
-
-## Use a skill explicitly
-
-```text
-@conventional-commits write a commit message for my staged changes
-```
-
-`@skill-name` injects the raw skill body wrapped as:
-
-```xml
-<skill name="conventional-commits">
-...
-</skill>
-```
-
-## Tab completion and help
-
-- Type `@` then `Tab` to complete skill names.
-- Run `/help` to list discovered skills with `(local)` / `(global)` tags.