Update README.md

ScriptSmith · ScriptSmith · commit d2ff242b31e0 · 2026-03-25T23:16:35.000+10:00
diff --git a/README.md b/README.md
@@ -2,37 +2,41 @@
 
 *Your computer, served on a platter.*
 
-MCP server that exposes **Read**, **Write**, **Edit**, **Bash**, **Glob**, and **Grep** tools over Stdio and StreamableHTTP transports. Built with [Bun](https://bun.sh), compiles to standalone executables. The **grep** tool requires [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`) to be installed on the host.
+MCP server that exposes **Read**, **Write**, **Edit**, **Bash**, **Glob**, and **Grep** tools over Stdio and StreamableHTTP transports. Built with [Bun](https://bun.sh), compiles to standalone executables.
 
-Designed to be used by browser-based (or any MCP-compatible) agents — like [Hadrian](https://github.com/ScriptSmith/hadrian) — to control a computer.
+Designed to be used by browser-based (or any MCP-compatible) agents, like [Hadrian](https://github.com/ScriptSmith/hadrian), to control a computer.
 
 ## Tools
 
 | Tool | Description |
 |------|-------------|
-| **read** | Read file contents with pagination (offset/limit). Truncates at 2000 lines or 50KB. |
+| **read** | Read file contents with pagination (offset/limit). Detects image files (JPEG, PNG, GIF, WebP) and returns metadata. Truncates text to 2000 lines or 50KB. |
 | **write** | Create or overwrite files. Auto-creates parent directories. |
-| **edit** | Find-and-replace with exact (or fuzzy Unicode) matching. Requires a unique match, or use `replace_all` to replace every occurrence. Returns a unified diff. |
+| **edit** | Find-and-replace with exact or fuzzy matching (normalizes smart quotes, dashes, and Unicode whitespace). Requires a unique match, or use `replace_all` for every occurrence (exact matches only). Returns a unified diff. |
 | **bash** | Execute shell commands with optional timeout. Output truncated to last 2000 lines or 50KB. |
-| **glob** | Fast file pattern matching. Returns paths matching a glob pattern (e.g. `**/*.ts`). |
+| **glob** | Fast file pattern matching. Returns up to 500 paths matching a glob pattern (e.g. `**/*.ts`). |
 | **grep** | Search file contents using [ripgrep](https://github.com/BurntSushi/ripgrep). Supports regex, file filtering, context lines, and multiple output modes. Requires `rg` to be installed. |
 
 ## Quick start
 
 ### From a release binary
 
-Download the binary for your platform from [Releases](https://github.com/ScriptSmith/platter/releases), make it executable, and run:
+Download the latest binary for your platform from [Releases](https://github.com/ScriptSmith/platter/releases), or grab it with `curl`:
 
 ```bash
-chmod +x platter-linux-x64
-./platter-linux-x64                        # stdio mode
-./platter-linux-x64 -t http               # HTTP mode on :3100
+# Download (replace the filename for your platform)
+# Available: platter-linux-x64, platter-linux-arm64, platter-darwin-x64, platter-darwin-arm64
+curl -fsSL https://github.com/ScriptSmith/platter/releases/latest/download/platter-linux-x64 -o platter
+chmod +x platter
+
+./platter          # stdio mode
+./platter -t http  # HTTP mode on :3100
 ```
 
 ### Docker
 
 ```bash
-docker run --rm -i ghcr.io/scriptsmith/platter             # stdio mode
+docker run --rm -i ghcr.io/scriptsmith/platter                                   # stdio mode
 docker run --rm -p 3100:3100 ghcr.io/scriptsmith/platter -t http --host 0.0.0.0  # HTTP mode
 ```
 
@@ -42,21 +46,25 @@ See [Docker](#docker-1) below for mounting paths, networking, installing extra s
 
 ```bash
 bun install
-bun run dev                                # run directly from TypeScript
-bun run compile                            # build standalone binary for current platform
+bun run dev      # run directly from TypeScript
+bun run compile  # build standalone binary for current platform
 ```
 
 ## Usage
 
 ```
-platter [options]
+platter v1.0.0
+
+Your computer, served on a platter.
+
+Usage: platter [options]
 
 Options:
   -t, --transport <stdio|http>   Transport mode (default: stdio)
   -p, --port <number>            HTTP port (default: 3100)
       --host <address>           HTTP bind address (default: 127.0.0.1)
       --cwd <path>               Working directory for tools (default: current directory)
-      --cors-origin <origin>     Allowed CORS origin (default: * — reflects request origin)
+      --cors-origin <origin>     Allowed CORS origin (default: *)
       --auth-token <token>       Bearer token for HTTP auth (auto-generated if omitted)
       --no-auth                  Disable bearer token authentication
 
@@ -72,7 +80,7 @@ Sandbox:
       --sandbox-fs <mode>        Filesystem backend: memory, overlay, readwrite (default: readwrite)
       --sandbox-allow-url <url>  Allow network access to URL prefix (repeatable)
 
-  -h, --help                     Show help message
+  -h, --help                     Show this help message
   -v, --version                  Show version number
 ```
 
@@ -82,11 +90,11 @@ You can limit which tools are registered, which filesystem paths file tools can
 
 #### Tool selection
 
-Only register specific tools — unregistered tools are completely hidden from MCP clients:
+Only register specific tools. Unregistered tools are completely hidden from MCP clients:
 
 ```bash
-platter --tools read,glob,grep              # read-only server
-platter --tools read,write,edit             # no bash/search
+platter --tools read,glob,grep  # read-only server
+platter --tools read,write,edit # no bash/search
 ```
 
 #### Path restrictions
@@ -103,9 +111,9 @@ platter --allow-path /home/user/project --allow-path /tmp
 Only allow bash commands whose **entire** command string matches at least one regex pattern:
 
 ```bash
-platter --allow-command "git( .*)?"                        # git only
-platter --allow-command "git( .*)?" --allow-command "npm( .*)?"  # git or npm
-platter --allow-command "ls( .*)?" --allow-command "cat .*"      # ls or cat
+platter --allow-command "git( .*)?"                             # git only
+platter --allow-command "git( .*)?" --allow-command "npm( .*)?" # git or npm
+platter --allow-command "ls( .*)?" --allow-command "cat .*"     # ls or cat
 ```
 
 Patterns are anchored: `--allow-command "git( .*)?"` compiles to `^(?:git( .*)?)$`, so `git status` matches but `rm -rf / && git status` does not.
@@ -159,9 +167,9 @@ platter -t http -p 3100
 ```
 
 The server exposes a single endpoint at `/mcp` that handles:
-- `POST /mcp` — JSON-RPC messages (initialize, tool calls)
-- `GET /mcp` — SSE notification stream
-- `DELETE /mcp` — session teardown
+- `POST /mcp` - JSON-RPC messages (initialize, tool calls)
+- `GET /mcp` - SSE notification stream
+- `DELETE /mcp` - session teardown
 
 CORS is enabled for all origins by default (reflects the request `Origin`). To restrict to a specific origin:
 
@@ -177,24 +185,24 @@ The server validates the `Host` header to prevent [DNS rebinding attacks](https:
 
 ### Network (HTTP mode)
 
-- **Bearer token authentication** — required by default (RFC 6750). A random 256-bit token is generated at startup unless you provide `--auth-token` or disable auth with `--no-auth`.
-- **Host header validation** — prevents [DNS rebinding attacks](https://github.com/modelcontextprotocol/typescript-sdk/security/advisories/GHSA-w48q-cv73-mx4w). Localhost binds accept only `127.0.0.1`, `localhost`, and `::1`; remote binds accept only the specified `--host`.
-- **Origin validation** — when `--cors-origin` is set to a specific origin, requests with a mismatched `Origin` header are actively rejected with 403 (not just filtered by CORS response headers).
+- **Bearer token authentication** - required by default (RFC 6750). A random 256-bit token is generated at startup unless you provide `--auth-token` or disable auth with `--no-auth`.
+- **Host header validation** - prevents [DNS rebinding attacks](https://github.com/modelcontextprotocol/typescript-sdk/security/advisories/GHSA-w48q-cv73-mx4w). Localhost binds accept only `127.0.0.1`, `localhost`, and `::1`; remote binds accept only the specified `--host`.
+- **Origin validation** - when `--cors-origin` is set to a specific origin, requests with a mismatched `Origin` header are actively rejected with 403 (not just filtered by CORS response headers).
 
 ### Restrictions (best-effort)
 
 `--tools`, `--allow-path`, and `--allow-command` are **defense-in-depth** controls. They raise the bar significantly but are not a sandbox. The limitations below should be understood before relying on them in a threat model.
 
 #### What they do well
 
-- **Tool selection** is enforced at registration time — disabled tools are never exposed via the MCP protocol. There is no way for a client to invoke or discover them.
+- **Tool selection** is enforced at registration time. Disabled tools are never exposed via the MCP protocol. There is no way for a client to invoke or discover them.
 - **Path validation** resolves symlinks via `realpath()` on both the target and each allowed path before comparison, preventing traversal via `../` or symlinked directories. For write targets that don't exist yet, the nearest existing ancestor is resolved instead.
 - **Command validation** anchors regex patterns to match the full command string, preventing trivial bypasses like appending `&& malicious-command`.
 
 #### Known limitations and bypasses
 
 - **Bash is inherently unrestricted.** When the bash tool is enabled, a sufficiently creative command can bypass `--allow-path` entirely (e.g. `cat /etc/passwd`). If you set `--allow-path` without also setting `--allow-command` or removing bash from `--tools`, a warning is printed at startup. For strong file-access control, either disable bash (`--tools read,write,edit,glob,grep`) or pair `--allow-path` with a tight `--allow-command` allowlist.
-- **Command regex operates on the raw string.** It does not parse shell syntax. Patterns like `--allow-command "git( .*)?"` block `rm && git status` (because the full string doesn't match), but a determined attacker could construct commands that the regex matches yet that execute unintended code — for example, if an allowed pattern is too broad. Write patterns as narrowly as possible.
+- **Command regex operates on the raw string.** It does not parse shell syntax. Patterns like `--allow-command "git( .*)?"` block `rm && git status` (because the full string doesn't match), but a determined attacker could construct commands that the regex matches yet that execute unintended code, for example if an allowed pattern is too broad. Write patterns as narrowly as possible.
 - **Symlink TOCTOU.** Path validation resolves symlinks at check time. If a symlink target is changed between the check and the actual file operation, the validation can be bypassed. This is a fundamental limitation of userspace path checking.
 - **Glob/grep search scope.** `--allow-path` validates the search directory for glob and grep, but results within that directory tree may include symlinks pointing outside it. The content of those symlink targets could be returned in grep output or listed by glob.
 - **No process-level sandboxing.** All restrictions are enforced in application code within the platter process. They do not use OS-level mechanisms (seccomp, namespaces, pledge, etc.). A vulnerability in platter itself, Bun, or a dependency could bypass all restrictions.
@@ -203,13 +211,13 @@ For stronger isolation, use the just-bash sandbox, a Docker container, or both.
 
 ### Sandbox mode (just-bash)
 
-Opt into [just-bash](https://github.com/vercel-labs/just-bash) — a TypeScript reimplementation of bash with a virtual filesystem — for true process-level isolation. No native processes are spawned; the shell runs entirely in the Bun runtime.
+Opt into [just-bash](https://github.com/vercel-labs/just-bash), a TypeScript reimplementation of bash with a virtual filesystem, for sandboxed command execution. No native processes are spawned; the shell runs entirely in the Bun runtime.
 
 ```bash
-platter --sandbox                                          # readwrite fs, no network
-platter --sandbox --sandbox-fs memory                      # pure in-memory fs
-platter --sandbox --sandbox-fs overlay                     # reads from disk, writes ephemeral
-platter --sandbox --sandbox-allow-url "https://api.example.com"  # allow network to prefix
+platter --sandbox                                               # readwrite fs, no network
+platter --sandbox --sandbox-fs memory                           # pure in-memory fs
+platter --sandbox --sandbox-fs overlay                          # reads from disk, writes ephemeral
+platter --sandbox --sandbox-allow-url "https://api.example.com" # allow network to prefix
 ```
 
 #### Filesystem modes
@@ -236,13 +244,13 @@ platter --sandbox --sandbox-allow-url "https://api.github.com" --sandbox-allow-u
 
 #### Limitations
 
-- **Not full bash.** just-bash is a TypeScript reimplementation — some edge cases may behave differently from GNU bash.
+- **Not full bash.** just-bash is a TypeScript reimplementation; some edge cases may behave differently from GNU bash.
 - **No native binaries.** Commands like `git`, `node`, `docker`, `rg`, `python` are not available. Only bash builtins and just-bash's built-in command set work.
 - **Beta software.** just-bash is under active development. Test your workflows before relying on it in production.
 
 ### Container isolation (Docker)
 
-Running platter inside a Docker container provides OS-level isolation via Linux namespaces and cgroups. The container boundary limits what the bash tool can access — even unrestricted commands can only reach the filesystems and network that the container exposes.
+Running platter inside a Docker container provides OS-level isolation via Linux namespaces and cgroups. The container boundary limits what the bash tool can access. Even unrestricted commands can only reach the filesystems and network that the container exposes.
 
 ```bash
 # Minimal: no host filesystem, no network
@@ -268,16 +276,16 @@ docker run --rm -p 3100:3100 \
 
 #### Containers vs VMs
 
-Containers share the host kernel — isolation is enforced by kernel features (namespaces, cgroups, seccomp). A kernel vulnerability or a misconfigured container (e.g. `--privileged`) can break the boundary. VMs run a separate kernel on virtualised hardware, so a guest compromise does not directly expose the host. If your threat model includes untrusted code that may attempt kernel exploits, run platter inside a VM (or a VM-backed container runtime like [Kata Containers](https://katacontainers.io/) or [Firecracker](https://firecracker-microvm.github.io/)). For most use cases — limiting blast radius from an AI agent — a properly configured container (non-root, capabilities dropped, `--network none`) is sufficient.
+Containers share the host kernel; isolation is enforced by kernel features (namespaces, cgroups, seccomp). A kernel vulnerability or a misconfigured container (e.g. `--privileged`) can break the boundary. VMs run a separate kernel on virtualised hardware, so a guest compromise does not directly expose the host. If your threat model includes untrusted code that may attempt kernel exploits, run platter inside a VM (or a VM-backed container runtime like [Kata Containers](https://katacontainers.io/) or [Firecracker](https://firecracker-microvm.github.io/)). For most use cases, like limiting blast radius from an AI agent, a properly configured container (non-root, capabilities dropped, `--network none`) is sufficient.
 
 #### Combining sandbox and container
 
 The just-bash sandbox and Docker container address different layers. Used together, they provide defense in depth:
 
 | Layer | Protects against |
 |---|---|
-| **just-bash sandbox** | Arbitrary native process execution — no `git`, `curl`, `rm`, etc. Commands run in a TypeScript interpreter, not the OS shell. |
-| **Docker container** | Host filesystem/network access — even if the sandbox has a bug or is bypassed, the container limits blast radius to mounted paths and allowed networks. |
+| **just-bash sandbox** | Arbitrary native process execution: no `git`, `curl`, `rm`, etc. Commands run in a TypeScript interpreter, not the OS shell. |
+| **Docker container** | Host filesystem/network access: even if the sandbox has a bug or is bypassed, the container limits blast radius to mounted paths and allowed networks. |
 
 ```bash
 # Maximum isolation: sandbox inside a container, overlay fs, no network
@@ -310,8 +318,8 @@ See [Docker](#docker-1) for full usage instructions including mounting paths, ne
 The Docker image is based on Debian Bookworm (slim) and includes ripgrep. Multi-arch images (`linux/amd64`, `linux/arm64`) are published to GitHub Container Registry on every tagged release.
 
 ```bash
-docker pull ghcr.io/scriptsmith/platter           # latest release
-docker pull ghcr.io/scriptsmith/platter:1.0.0      # specific version
+docker pull ghcr.io/scriptsmith/platter        # latest release
+docker pull ghcr.io/scriptsmith/platter:1.0.0  # specific version
 ```
 
 ### Running in stdio mode
@@ -368,7 +376,7 @@ docker run --rm -p 3100:3100 --network host ghcr.io/scriptsmith/platter -t http
 
 ### Installing additional software at runtime
 
-The image uses Debian, so you can install packages with `apt-get` at runtime. This is useful for quick experiments but adds startup latency — for production use, build a custom image instead (see below).
+The image uses Debian, so you can install packages with `apt-get` at runtime. This is useful for quick experiments but adds startup latency. For production use, build a custom image instead (see below).
 
 ```bash
 docker run --rm -p 3100:3100 ghcr.io/scriptsmith/platter \
@@ -419,13 +427,15 @@ docker run --rm -i platter
 
 ```bash
 bun install
-bun run build             # bundle to dist/
-bun run compile           # standalone binary for current platform → ./platter
-bun run compile:all       # cross-compile for linux-x64, linux-arm64, darwin-x64, darwin-arm64
-bun run format            # format with Biome
-bun run format:check      # check formatting
-bun run lint              # lint with Biome
-bun run typecheck         # typecheck with TypeScript
+bun run build        # bundle to dist/
+bun run compile      # standalone binary for current platform -> ./platter
+bun run compile:all  # cross-compile for linux-x64, linux-arm64, darwin-x64, darwin-arm64
+bun run format       # format with Biome
+bun run format:check # check formatting
+bun run lint         # lint with Biome
+bun run lint:fix     # lint and auto-fix with Biome
+bun run typecheck    # typecheck with TypeScript
+bun run test         # run tests
 ```
 
 ## License
