Initial commit: shiro-neko 0.1.0-beta.1

Agentic coding CLI on Bun, Ink, and the AI SDK.

Core: streamText loop with SDK-level tool approval so a denied call provably never executes; endpoint fallback for OpenAI reasoning models; retry with backoff.

Tools: read/write/edit/glob/grep/bash, path-jailed, gitignore-aware, ripgrep with a JS fallback, binary rejection, live bash streaming.

Agents: five variants crossing thinking level with tool restriction; plan and review withhold mutating tools from the model.

Extensibility: frontmatter skills with on-demand bodies, plugin host with blocking hooks, MCP stdio and HTTP, read-only subagents.

State: durable per-project memory, session task lists, session persistence, compaction that repairs provider-item dependencies.

Distribution: five-platform cross-compiled binaries with checksums, install scripts, CI on three operating systems.

404 tests, typecheck clean.

docs/mcp.md

@@ -0,0 +1,92 @@
+# MCP
+
+[Model Context Protocol](https://modelcontextprotocol.io) servers contribute tools. Configure
+them in `~/.shiro-neko/config.json` and they appear alongside the builtins.
+
+## Configuration
+
+```json
+{
+  "mcpServers": {
+    "fs": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
+    },
+    "db": {
+      "command": "python",
+      "args": ["-m", "my_mcp_server"],
+      "env": { "DATABASE_URL": "postgres://localhost/dev" },
+      "cwd": "/home/you/tools"
+    },
+    "api": {
+      "url": "http://localhost:3000/mcp",
+      "type": "http",
+      "headers": { "Authorization": "Bearer local-dev-token" }
+    }
+  }
+}
+```
+
+**stdio** servers take `command`, and optionally `args`, `env`, `cwd`. The process is spawned
+at startup and closed on exit.
+
+**Remote** servers take `url`, and optionally `type` (`http` or `sse`, default `http`) and
+`headers`.
+
+## Naming
+
+Tools arrive as `mcp__<server>__<tool>`. A server named `fs` exposing `read_file` becomes
+`mcp__fs__read_file`.
+
+The namespace is not cosmetic. Two servers both exposing `search` would otherwise silently
+shadow each other, and the model would call one believing it was the other.
+
+## Approval
+
+**Every MCP tool requires approval on every call.** They are third-party code with unknown
+side effects, so they are treated like `bash` rather than like `read_file`. `a` whitelists
+one tool for the session.
+
+`--yolo` skips these prompts, as it does for the builtins. Plugin guards still apply.
+
+## Failure handling
+
+A server that fails to start is reported and the session continues:
+
+```
+shiro-neko 0.1.0-beta.1  openai/gpt-5  session 0193ab2c
+mcp: 4 tools
+mcp db failed: spawn python ENOENT
+```
+
+Nothing else is lost — the other servers still load, the builtins still work. A missing
+Python interpreter should not stop you from editing a file.
+
+`--no-mcp` skips them all.
+
+## Inspecting
+
+`/tools` lists everything offered this turn, MCP tools included. The system prompt describes
+them as a group:
+
+```
+- mcp__api__query, mcp__fs__read_file: from MCP servers, named mcp__<server>__<tool>.
+  Each needs approval; read its own description before calling.
+```
+
+Their individual descriptions come from the server, so that is what the model reads before
+calling one.
+
+## Cost
+
+Each tool adds roughly 550 characters of schema to every request. A server exposing twenty
+tools costs about 2,750 tokens per turn, sent whether or not the model uses any of them.
+
+Prefer servers with a focused tool set. If one exposes many tools you never use, it is worth
+finding a narrower server or writing one.
+
+## Writing a server
+
+Any MCP-compliant server works. A minimal stdio one needs three methods: `initialize`,
+`tools/list`, and `tools/call`. The test suite includes one at
+`test/fixtures/mcp-stub.ts` — about 50 lines, and useful as a starting point.