diff --git a/packages/bash-mcp/README.md b/packages/bash-mcp/README.md
index 8200e9d..0ca0f2f 100644
--- a/packages/bash-mcp/README.md
+++ b/packages/bash-mcp/README.md
@@ -1,42 +1,47 @@
 # `Capsule` Bash MCP
 
-An MCP server that gives your AI agent the ability to run bash commands in a secure, persistent, WebAssembly-sandboxed environment.
+[![MCP Server](https://img.shields.io/github/actions/workflow/status/capsulerun/bash/release.yml?branch=main&label=MCP%20Server)](https://github.com/capsulerun/bash/actions/workflows/release.yml)
+
+An MCP server that gives your AI agent the ability to run bash commands in a secure, persistent, sandboxed environment.
 
 ## How It Works
 
-Each session runs inside a WebAssembly sandbox powered by [`@capsule-run/bash-wasm`](https://github.com/capsulerun/bash). The sandbox provides:
+Each session runs inside a WebAssembly sandbox. The sandbox provides:
 
 - **Persistent state**: cwd, env vars, and filesystem changes persist across commands within a session
 - **Filesystem diff**: every `run` response includes a diff of what changed on disk
 - **Isolated memory**: each session gets its own address space, no cross-session leakage
 - **No host access**: the sandbox cannot reach your host filesystem or network
 
+Learn more about [Capsule Bash](https://github.com/capsulerun/bash).
+
 ## Tools
 
 | Tool       | Description                                                                                                                         |
 | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `run`      | Run a bash command in a sandboxed session. Returns stdout, stderr, exit code, filesystem diff, and current shell state (cwd + env). |
-| `reset`    | Reset the filesystem and shell state (cwd, env vars) for a session back to their initial values.                                    |
-| `sessions` | List all active shell sessions.                                                                                                     |
+| `run`      | Run a bash command in a sandboxed session. Returns stdout, stderr, exit code, filesystem diff, and current state (cwd + env). |
+| `reset`    | Reset the filesystem and state (cwd, env vars) for a session back to their initial values.                                    |
+| `sessions` | List all active sessions.                                                                                                     |
 
 ### Sessions
 
-Commands within the same `session_id` share cwd, environment variables, and filesystem state across calls. Each session maps to an isolated sandbox directory under `.capsule/sessions/<session_id>`.
+Commands within the same `session_id` share cwd, environment variables, and filesystem state across calls. 
 
 ### Example
 
 Ask your AI agent:
 
-> _"I have a log file — count how many errors occurred per hour."_
+> _"Write a Python script that averages a list of numbers."_
 
 The agent calls `run` sequentially:
 
 ```json
-{ "command": "mkdir -p /data && echo 'ERROR 10:01\nINFO 10:02\nERROR 10:45\nERROR 11:03' > /data/app.log", "session_id": "analysis" }
-{ "command": "grep 'ERROR' /data/app.log | sed 's/ERROR \\([0-9]*\\):.*/\\1/' | sort | uniq -c", "session_id": "analysis" }
+{ "command": "mkdir -p /data && cd /data", "session_id": "custom_session" }
+{ "command": "echo 'nums = [x for x in [1, 2, 3, []] if isinstance(x, int)]\nprint(sum(nums) / len(nums))' > avg.py", "session_id": "custom_session" }
+{ "command": "python3 avg.py", "session_id": "custom_session" }
 ```
 
-Each call returns `stdout`, `stderr`, `exitCode`, a filesystem `diff`, and the updated shell `state`.
+Each call returns `stdout`, `stderr`, `exitCode`, a filesystem `diff`, and the updated `state` to enrich context and keep trace in conversation history.
 
 ## Setup
 
@@ -55,4 +60,4 @@ Add to your MCP client configuration (e.g. Claude Desktop, Cursor):
 
 ## Limitations
 
-- **Wasm bash** — runs a WASI-compiled bash; some advanced shell features or native binaries may not be available
+- Not all bash commands and options are implemented. Feel free to [open an issue](https://github.com/capsulerun/bash/issues/new) if a command is missing or behaves unexpectedly.