diff --git a/README.md b/README.md
index 02e4f9b..11d2623 100644
--- a/README.md
+++ b/README.md
@@ -1,50 +1,277 @@
 # HyperAgent
 
-An AI agent with a sandboxed JavaScript executor, powered by [Hyperlight](https://github.com/hyperlight-dev/hyperlight) micro-VMs and the [GitHub Copilot SDK](https://github.com/github/copilot-sdk).
+HyperAgent is a sandboxed code-acting AI agent runtime: it writes JavaScript handlers, validates them, and runs them inside hardware-isolated [Hyperlight](https://github.com/hyperlight-dev/hyperlight) micro-VMs using the [GitHub Copilot SDK](https://github.com/github/copilot-sdk).
 
-Ask the agent to compute things, and it writes & runs JavaScript in a hardware-isolated micro-VM — no filesystem, no network, no escape.
+It is built for useful, bounded work: data analysis, document generation, API workflows, secure file output, and tool use through plugins and MCP servers. The model can write code, but the code runs in a sandbox with no direct filesystem, shell, or network access unless you explicitly enable narrowly scoped host capabilities.
 
-> **Warning:** HyperAgent is pre-release software created by AI. Not for production use. Be careful where you run it and what you do with it. Consider running in a container.
+> **Warning:** HyperAgent is pre-release software created by AI. Not for production use. Be careful where you run it and what you do with it. Consider running it in a container.
+>
+> **Platform note:** HyperAgent requires hardware virtualization: Linux with KVM, Azure Linux with MSHV, Windows with WHP, or WSL2 with KVM. It does not currently run on macOS [because of this Hyperlight issue](https://github.com/hyperlight-dev/hyperlight/issues/45).
 
-## Quick Start
+## Why HyperAgent?
 
-### Prerequisites
+Most agent CLIs are powerful because they can touch your machine directly: shell commands, file edits, network calls, local tools, credentials, and long-lived process state. That is useful, but it also means a bad instruction, hallucinated command, or prompt-injected webpage can become real host activity very quickly.
 
-- **Linux with KVM**, **Azure Linux with MSHV**, **Windows with WHP**, or **WSL2 with KVM** (hardware virtualization required)
-- **GitHub authentication** (see [below](#github-authentication))
-- **Docker** (for containerized option)
-- **Node.js 22+** (for npm install / source builds only)
-- **Rust + just** (for source builds only — see [Contributing](#contributing))
+HyperAgent takes a different route. The model acts by writing JavaScript handlers, and those handlers run inside a hardware-isolated Hyperlight micro-VM. By default there is no shell, no filesystem, no network, and no process access. When the task needs host capabilities, they are added deliberately through plugins, profiles, or MCP servers.
 
-**NOTE:** HyperAgent does not currently run on macOS [due to this issue](https://github.com/hyperlight-dev/hyperlight/issues/45).
+What that gets you:
 
-### GitHub Authentication
+| Instead of                | HyperAgent gives you                                                |
+| ------------------------- | ------------------------------------------------------------------- |
+| Shell-first automation    | Code-first handlers that are validated and run in a micro-VM        |
+| Ambient filesystem access | Path-jailed read/write plugins                                      |
+| Ambient network access    | Domain-scoped fetch with SSRF checks                                |
+| Ad hoc tool calls         | Normal JavaScript APIs for approved capabilities                    |
+| One-off generated scripts | Reusable handlers and modules                                       |
+| Hidden agent state        | Explicit shared state, transcript logs, debug logs, and timing logs |
+| Trust-me execution        | Tool gating, code validation, plugin approval, and MCP review       |
+
+The goal is not to make AI automation risk-free. It is to make the boundary obvious: model-generated code runs in the sandbox; host capabilities are explicit decisions.
+
+## What Can You Do With HyperAgent?
+
+Ask HyperAgent for an outcome, not a script. It will plan the workflow, register sandboxed JavaScript handlers, use built-in modules, ask for plugins or MCP servers when needed, and produce files or structured results.
+
+| Ask for          | HyperAgent can                                                                                                             |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Reports          | Fetch data, transform it, summarise it, and write Markdown, JSON, CSV, PDF, PPTX, or other generated outputs               |
+| Presentations    | Build PowerPoint decks with themes, layouts, tables, charts, notes, transitions, and images                                |
+| PDFs             | Generate structured PDF reports with text, tables, charts, callouts, metadata, and visual layout checks                    |
+| Spreadsheets     | Build XLSX workbooks with typed workbook APIs for sheets, styles, pivots, charts, validation, and print settings           |
+| Data pipelines   | Chain fetch, parse, validate, transform, and output steps inside reusable handlers                                         |
+| External systems | Connect approved MCP servers for Microsoft 365, GitHub, databases, internal APIs, SaaS tools, or local business systems    |
+| API exploration  | Discover API shapes, call endpoints through the fetch plugin or MCP tools, normalise results, and create reusable handlers |
+| Safer automation | Keep generated code away from your shell by default; host capabilities are explicit, audited, and gated                    |
+
+## Example Prompts
+
+These are the kinds of jobs HyperAgent is designed to handle.
 
-HyperAgent uses the GitHub Copilot SDK, which requires a GitHub account with Copilot access. Authenticate before running:
+### Build a PowerPoint Deck
 
 ```bash
-# Install the GitHub CLI if you don't have it
-# https://cli.github.com/
+hyperagent --skill pptx-expert --profile web-research \
+  --prompt "Create a visually rich Artemis II mission briefing deck. Use NASA public imagery where available, include mission objectives, crew, Orion/SLS architecture, lunar flyby timeline, key risks, and why the mission matters. Make it dramatic but factual, with strong full-bleed image slides and clean diagrams. Save it as artemis-ii-briefing.pptx."
+```
 
-# Log in to GitHub (select HTTPS, authenticate via browser)
-gh auth login
+The agent can use `ha:pptx`, `ha:pptx-charts`, and `ha:pptx-tables` to create editable PowerPoint files instead of screenshots glued into slides.
+
+The `web-research` profile gives the run enough room for image-heavy work. HyperAgent still has to use approved fetch and file-output capabilities before it can download NASA images or save the deck.
+
+### Create a PDF Report
+
+```bash
+hyperagent --skill pdf-expert --profile file-builder \
+  --prompt "Create a polished PDF report for API latency this month. Include a title page, summary callouts, percentile table, line chart, and recommendations. Save it as latency-report.pdf."
+```
+
+PDF work uses document modules rather than shelling out to arbitrary tools, so the generated code remains inspectable and sandboxed.
+
+### Produce an Excel Workbook
+
+```bash
+hyperagent --skill xlsx-expert --profile file-builder \
+  --prompt "Create an Excel workbook from the quarterly sales data. Include a formatted data sheet, frozen header row, filters, a pivot table by region, a revenue chart, conditional formatting, and validation lists. Save it as sales-analysis.xlsx."
+```
+
+The agent uses `ha:xlsx`, a typed workbook API for sheets, cells, styles, pivots, charts, sparklines, validation, hyperlinks, images, protection, print settings, and named ranges.
+
+### Work With Microsoft 365 Through MCP
+
+```bash
+hyperagent --profile web-research \
+  --prompt "Connect to the Microsoft 365 MCP server, find the latest Teams channel posts about the launch plan, summarise blockers, create a PDF status brief, and draft a follow-up message for the owners. Ask before sending anything."
+```
+
+MCP servers run outside the Hyperlight sandbox, so HyperAgent treats them differently from in-VM code: servers must be configured and approved, tool schemas are exposed as typed `host:mcp-*` modules, and write/destructive actions can be gated.
+
+### Analyse an API and Save the Output
+
+```bash
+hyperagent --profile web-research \
+  --prompt "Call the public GitHub API for this repo, summarise open PRs by risk, generate a Markdown report, and save the raw JSON plus report to disk."
+```
+
+The model can discover plugins, enable `fetch` with a domain allowlist, register handlers, and write outputs through the path-jailed `fs-write` plugin.
+
+Add `--auto-approve` for trusted non-interactive runs. It skips approval prompts, so treat it as yolo mode. Without it, HyperAgent can pause for approval before enabling plugins, connecting MCP servers, or taking write-capable actions.
+
+## How It Works
+
+HyperAgent gives the model custom tools instead of raw shell access. The usual flow is:
+
+1. The model decides what code it needs.
+2. It registers a named JavaScript handler with `register_handler`.
+3. HyperAgent validates the code and compiles it for the sandbox.
+4. The handler runs inside a Hyperlight micro-VM.
+5. If host access is needed, the model must use explicit plugins or MCP modules.
+6. Results come back as structured data or files written through approved paths.
 
-# Verify it worked
+```text
+User prompt
+  -> GitHub Copilot SDK session
+  -> HyperAgent tool gate
+  -> Code validation
+  -> Hyperlight JavaScript sandbox
+  -> Built-in modules + approved plugins + approved MCP tools
+  -> Result, report, workbook, deck, or file output
+```
+
+The sandbox has no direct filesystem, network, shell, or process access. Capabilities are added deliberately:
+
+| Capability       | How it is exposed                                                |
+| ---------------- | ---------------------------------------------------------------- |
+| Files            | `fs-read` and `fs-write` plugins with path jails                 |
+| HTTP             | `fetch` plugin with domain allowlists and SSRF checks            |
+| Reusable code    | `ha:*` system and user modules                                   |
+| External systems | MCP servers exposed as typed `host:mcp-*` modules                |
+| Bigger jobs      | Profiles that raise limits; profile tools can enable plugin sets |
+
+## Built-In Modules
+
+Handlers import system modules with `ha:<name>` specifiers.
+
+| Module                                                   | What it is for                                            |
+| -------------------------------------------------------- | --------------------------------------------------------- |
+| `ha:shared-state`                                        | Cross-handler state preserved across sandbox recompiles   |
+| `ha:zip-format`                                          | ZIP archive creation for document formats                 |
+| `ha:pptx`                                                | PowerPoint deck generation                                |
+| `ha:pptx-charts`                                         | Editable PowerPoint charts                                |
+| `ha:pptx-tables`                                         | PowerPoint table and comparison helpers                   |
+| `ha:xlsx`                                                | Excel workbook generation with sheets, pivots, and charts |
+| `ha:pdf`                                                 | PDF generation                                            |
+| `ha:pdf-charts`                                          | PDF chart rendering                                       |
+| `ha:markdown`                                            | Markdown utilities                                        |
+| `ha:html`                                                | HTML-to-text and link extraction                          |
+| `ha:image`                                               | Image helpers                                             |
+| `ha:base64`, `ha:str-bytes`, `ha:crc32`, `ha:xml-escape` | Binary, encoding, checksum, and XML utilities             |
+
+User modules can also be created at runtime with `register_module` and imported as `ha:<module-name>` in later handlers.
+
+## Skills and Profiles
+
+Skills inject domain guidance into the session. Profiles bundle resource limits and plugin requirements.
+
+On the CLI, `--profile` applies resource limits at startup. It does not silently grant host access. During a run, HyperAgent can use `/profile apply` or the `apply_profile` tool to request the profile's plugin requirements, with approval unless you deliberately use `--auto-approve`.
+
+```bash
+# Presentation specialist with file-building limits
+hyperagent --skill pptx-expert --profile file-builder
+
+# API/data workflow with web-research limits
+hyperagent --skill api-explorer --profile web-research
+
+# Multiple profiles stack by taking the max startup limits
+hyperagent --profile "web-research heavy-compute"
+```
+
+Useful skills include:
+
+| Skill            | Use it for                                    |
+| ---------------- | --------------------------------------------- |
+| `pptx-expert`    | Professional PowerPoint decks                 |
+| `pdf-expert`     | Structured PDF reports                        |
+| `xlsx-expert`    | Excel workbook generation                     |
+| `report-builder` | Multi-format reports and document output      |
+| `data-processor` | Data cleaning, joins, aggregation, and export |
+| `api-explorer`   | Understanding and calling APIs                |
+| `web-scraper`    | Fetching and extracting web content           |
+| `mcp-services`   | Working with configured MCP servers           |
+
+## MCP Servers
+
+HyperAgent can connect to [Model Context Protocol](https://modelcontextprotocol.io/) servers and expose their tools inside sandbox code as typed host modules. MCP is how HyperAgent can reach services such as Microsoft 365, GitHub, databases, internal APIs, SaaS tools, or local business systems without giving the model raw shell access.
+
+Install and authenticate the MCP server you want to use first; HyperAgent does not bundle third-party service servers. After the server is installed, add it to `~/.hyperagent/config.json`:
+
+This example uses a Microsoft 365 MCP server, but the same pattern applies to any configured MCP server:
+
+```json
+{
+  "mcpServers": {
+    "m365": {
+      "command": "node",
+      "args": ["/path/to/your/microsoft-365-mcp-server.js"],
+      "env": {
+        "M365_TOKEN": "${M365_TOKEN}"
+      },
+      "denyTools": ["delete_user", "send_mail"]
+    }
+  }
+}
+```
+
+Then in HyperAgent:
+
+```text
+/mcp list
+/mcp enable m365
+```
+
+Or ask naturally:
+
+```text
+Use the Microsoft 365 MCP server to list unread launch-plan emails, group them by owner, and create a follow-up tracker workbook. Do not send messages without asking me first.
+```
+
+The LLM discovers configured MCP servers with `list_mcp_servers`, connects with `manage_mcp`, reads TypeScript declarations with `mcp_server_info`, and then writes normal handler code like:
+
+```javascript
+import { searchMail, listDriveItems } from "host:mcp-m365";
+
+export function handler() {
+  const mail = searchMail({ query: "launch plan", unreadOnly: true });
+  const docs = listDriveItems({ path: "/Launch" });
+  return { mail, docs };
+}
+```
+
+MCP servers are not Hyperlight-sandboxed; they run as normal host processes. Review MCP server configuration carefully and use `allowTools` / `denyTools` for anything connected to real business systems.
+
+## Security Model
+
+HyperAgent is designed to make generated-code execution less terrifying, not magically safe.
+
+- **Hardware isolation:** JavaScript runs in Hyperlight micro-VMs.
+- **Tool gating:** SDK built-ins like shell, edit, and grep are blocked; the model gets HyperAgent-specific tools.
+- **Code validation:** Generated JavaScript is checked before execution.
+- **No ambient host access:** Files, network, and external systems require explicit plugins or MCP connections.
+- **Plugin auditing:** Plugin code is audited before use.
+- **Path jailing:** File plugins are restricted to configured base directories.
+- **SSRF protection:** The fetch plugin validates domains and resolved IPs.
+- **MCP approval:** MCP servers and potentially write-capable tools require explicit trust decisions.
+
+Read [SECURITY.md](SECURITY.md) and [docs/SECURITY.md](docs/SECURITY.md) before using HyperAgent with sensitive data or real tenant systems.
+
+## Install and Run
+
+### Prerequisites
+
+- Linux with KVM, Azure Linux with MSHV, Windows with WHP, or WSL2 with KVM
+- GitHub account with Copilot access
+- GitHub CLI for authentication, or a `GITHUB_TOKEN`
+- Docker for the container option
+- Node.js 22+ for npm/source installs
+- Rust toolchain and `just` for source development
+
+### GitHub Authentication
+
+```bash
+gh auth login
 gh auth status
 ```
 
-Alternatively, set `GITHUB_TOKEN` directly:
+Or set a token directly:
+
 ```bash
 export GITHUB_TOKEN="ghp_your_token_here"
 ```
 
-### Option 1: Docker (recommended)
+### Docker
 
 ```bash
-# Pull the image
 docker pull ghcr.io/hyperlight-dev/hyperagent:latest
 
-# Run with KVM (Linux / bash)
 docker run -it --rm \
   --device=/dev/kvm \
   --group-add $(stat -c '%g' /dev/kvm) \
@@ -55,25 +282,17 @@ docker run -it --rm \
   -v "$HOME/.hyperagent/tmp:/tmp" \
   -v "$(pwd)":/workspace -w /workspace \
   ghcr.io/hyperlight-dev/hyperagent:latest
-
-# Run with MSHV (Azure Linux / bash)
-docker run -it --rm \
-  --device=/dev/mshv \
-  --group-add $(stat -c '%g' /dev/mshv) \
-  --user "$(id -u):$(id -g)" \
-  -e HOME=/home/hyperagent \
-  -e GITHUB_TOKEN="$(gh auth token)" \
-  -v "$HOME/.hyperagent:/home/hyperagent/.hyperagent" \
-  -v "$HOME/.hyperagent/tmp:/tmp" \
-  -v "$(pwd)":/workspace -w /workspace \
-  ghcr.io/hyperlight-dev/hyperagent:latest
 ```
 
-**Non-interactive mode with environment variables (Linux / bash):**
+For Azure Linux with MSHV, replace `/dev/kvm` with `/dev/mshv`.
+
+For a less manual Docker flow, use [scripts/hyperagent-docker](scripts/hyperagent-docker). It auto-detects the hypervisor, handles auth, and forwards HyperAgent/Hyperlight environment variables.
+
+Non-interactive container run:
 
 ```bash
-# Set a prompt via env var — the container picks up HYPERAGENT_* and HYPERLIGHT_* automatically
-export HYPERAGENT_PROMPT="Create a summary report of today's top tech news"
+export HYPERAGENT_PROMPT="Create a Markdown report from the input data and save it to disk"
+
 docker run -it --rm \
   --device=/dev/kvm \
   --group-add $(stat -c '%g' /dev/kvm) \
@@ -87,259 +306,111 @@ docker run -it --rm \
   ghcr.io/hyperlight-dev/hyperagent:latest --auto-approve --profile file-builder
 ```
 
-**Non-interactive mode (Windows / PowerShell with WSL2 + KVM):**
-
-```powershell
-$env:HYPERAGENT_PROMPT = "Create a summary report of today's top tech news"
-docker run -it --rm `
-  --device=/dev/kvm `
-  -e HOME=/home/hyperagent `
-  -e GITHUB_TOKEN="$(gh auth token)" `
-  -e HYPERAGENT_PROMPT="$env:HYPERAGENT_PROMPT" `
-  -v "$HOME/.hyperagent:/home/hyperagent/.hyperagent" `
-  -v "$HOME/.hyperagent/tmp:/tmp" `
-  -v "${PWD}:/workspace" -w /workspace `
-  ghcr.io/hyperlight-dev/hyperagent:latest --auto-approve --profile file-builder
-```
-
-> **Environment variables:** `COPILOT_MODEL`, `HYPERAGENT_*`, and `HYPERLIGHT_*` env vars control the model, prompt, and sandbox settings. When using `docker run` directly, pass each with `-e VAR_NAME`. The [wrapper script](scripts/hyperagent-docker) forwards them all automatically.
->
-> **Tip:** For convenience, the [wrapper script](scripts/hyperagent-docker) auto-detects the hypervisor, handles auth, and forwards all config env vars.
-
-### Option 2: npm package
+### npm
 
 ```bash
-# Install globally
 npm install -g @hyperlight-dev/hyperagent
-
-# Run (requires KVM/MSHV and GitHub auth)
 hyperagent
 ```
 
-### Option 3: Build from source
-
-Requires Node.js 22+, Rust toolchain, and [just](https://github.com/casey/just) task runner.
+### Build From Source
 
 ```bash
-# Clone the repo
 git clone https://github.com/hyperlight-dev/hyperagent.git
 cd hyperagent
 
-# First-time setup — builds native Rust addons, installs npm packages
 just setup
-
-# Run the agent (tsx transpiles on the fly — no build step needed)
 just start
+```
+
+Build a standalone binary:
 
-# Or build a standalone binary
+```bash
 just binary-release
 dist/bin/hyperagent
 ```
 
-Key `just` commands:
+Key development commands:
 
-| Command | What it does |
-|---------|-------------|
-| `just setup` | First-time setup (build native addons, npm install) |
-| `just build` | Rebuild native addons after Rust changes |
-| `just start` | Run agent with tsx (fast iteration) |
-| `just binary-release` | Build optimised standalone binary to `dist/bin/hyperagent` |
-| `just test` | Run TypeScript test suite |
-| `just check` | Full quality gate (lint + typecheck + test) |
+| Command               | What it does                                                   |
+| --------------------- | -------------------------------------------------------------- |
+| `just setup`          | First-time setup: build native addons and install npm packages |
+| `just build`          | Rebuild native addons after Rust changes                       |
+| `just start`          | Run the agent with `tsx`                                       |
+| `just fmt`            | Format source                                                  |
+| `just lint`           | Formatting check, TypeScript, Rust lint checks                 |
+| `just test`           | Run TypeScript tests                                           |
+| `just check`          | Full quality gate: lints plus TypeScript and Rust tests        |
+| `just binary-release` | Build an optimised standalone binary                           |
 
 See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for the full development guide.
 
-## Usage
+## CLI Reference
 
 ```bash
-# Interactive mod
+# Interactive mode
 hyperagent
 
-# With a specific model
+# Use a specific model
 hyperagent --model gpt-4.1
 
 # Non-interactive mode
 hyperagent --prompt "Calculate the first 100 prime numbers" --auto-approve
 
-# With skills and profiles
+# Load a skill and profile
 hyperagent --skill pptx-expert --profile file-builder
 ```
 
-### Example Session
-
-```
-  ╔════════════════════════════════════════════════╗
-  ║                                                ║
-  ║    H Y P E R A G E N T                         ║
-  ║       v0.0.0-alpha.362+abc1234                 ║
-  ║                                                ║
-  ║    Hyperlight × Copilot SDK Agent              ║
-  ║    Sandboxed JavaScript Execution              ║
-  ║                                                ║
-  ╚════════════════════════════════════════════════╝
+Common options:
 
-  ⚠  WARNING: Pre-release software created by AI.
-     Not for production use. Be careful where you run it and what you do with it.
-
-You: Calculate fibonacci(30)
-
-  🔧 Calling execute_javascript...
-  ✅ Result: 832040
-
-The 30th Fibonacci number is 832040.
-```
+| Flag                | Description                                    |
+| ------------------- | ---------------------------------------------- |
+| `--model <name>`    | LLM model                                      |
+| `--prompt "<text>"` | Run one prompt and exit                        |
+| `--auto-approve`    | Auto-approve interactive prompts for scripting |
+| `--skill <name>`    | Invoke a domain skill                          |
+| `--profile <name>`  | Apply resource profile limits at startup       |
+| `--show-code`       | Log generated JavaScript                       |
+| `--show-timing`     | Show execution timing                          |
+| `--transcript`      | Save session transcript                        |
+| `--version`         | Show version                                   |
+| `--help`            | Show all options                               |
 
-### Try These Out
-
-#### Write a Markdown report:
-
-**Linux (bash):**
-```bash
-export HYPERAGENT_PROMPT="Write a report comparing the latest iPhone and Android phones, with a summary table of specs and pros/cons. Write the report as a markdown file and save it to disk."
-```
-
-**Windows (PowerShell):**
-```powershell
-$env:HYPERAGENT_PROMPT = "Write a report comparing the latest iPhone and Android phones, with a summary table of specs and pros/cons. Write the report as a markdown file and save it to disk."
-```
-
-```shell
-hyperagent --auto-approve --show-code --verbose
-```
-
-#### Build a PPTX presentation:
-
-**Linux (bash):**
-```bash
-export HYPERAGENT_PROMPT="Research the JWT spec (header, payload, signature). Include:
-- Title slide
-- ""What is JWT?"" with bullet list of key points
-- Code block showing a decoded JWT structure
-- Flow diagram slide (use arrows and boxes to show auth flow)
-- Security best practices numbered list
-- Common vulnerabilities comparison table
-- Resources/links slide
-Use 'light-clean' theme, minimal transitions."
-```
-
-**Windows (PowerShell):**
-```powershell
-$env:HYPERAGENT_PROMPT = @"
-Research the JWT spec (header, payload, signature). Include:
-- Title slide
-- "What is JWT?" with bullet list of key points
-- Code block showing a decoded JWT structure
-- Flow diagram slide (use arrows and boxes to show auth flow)
-- Security best practices numbered list
-- Common vulnerabilities comparison table
-- Resources/links slide
-Use 'light-clean' theme, minimal transitions.
-"@
-```
-
-```shell
-hyperagent --auto-approve --show-code --verbose
-```
-
-## CLI Options
-
-Run `hyperagent --help` for full list. See [docs/USAGE.md](docs/USAGE.md) for complete reference.
-
-Key options:
-
-| Flag | Description |
-|------|-------------|
-| `--model <name>` | LLM model (default: `claude-opus-4.6`) |
-| `--prompt "<text>"` | Non-interactive mode: run prompt and exit |
-| `--auto-approve` | Auto-approve all prompts (for scripting) |
-| `--skill <name>` | Load domain expertise (e.g., `pptx-expert`) |
-| `--profile <name>` | Apply resource profile (`file-builder`, `web-research`, etc.) |
-| `--version` | Show version and exit |
-| `--help` | Show all options |
+See [docs/USAGE.md](docs/USAGE.md) for the complete CLI and environment variable reference.
 
 ## Slash Commands
 
-Type `/help` in the REPL for full list. Key commands:
-
-| Command | Description |
-|---------|-------------|
-| `/model <name>` | Switch models mid-conversation |
-| `/plugin enable <name>` | Enable a plugin (fs-read, fs-write, fetch) |
-| `/config` | Show current configuration |
-| `/new` | Start fresh session |
-| `/exit` | Exit |
-
-## Architecture
-
-```
-┌───────────────────────────────────────────────────────┐
-│                  Interactive REPL                     │
-├───────────────────────────────────────────────────────┤
-│              GitHub Copilot SDK Session               │
-│    streaming | infinite sessions | multi-model        │
-├───────────────────────────────────────────────────────┤
-│                  Tool Gating Layer                    │
-│    (blocks all SDK built-in tools like bash/edit)     │
-├───────────────────────────────────────────────────────┤
-│                   Custom Tools                        │
-│    register_handler, execute_javascript, ask_user     │
-│    manage_plugin, apply_profile, sandbox_help ...     │
-├──────────────────────────┬────────────────────────────┤
-│  Hyperlight Sandbox      │  Plugin System (HOST)      │
-│  ┌────────────────────┐  │                            │
-│  │  QuickJS VM        │  │  - fs-read, fs-write       │
-│  │  - No FS/Net       │<-│  - fetch (SSRF-safe)       │
-│  │  - CPU bounded     │  │  - LLM-audited             │
-│  │  - Memory safe     │  │                            │
-│  └────────────────────┘  │  Runs on Node.js host,     │
-│                          │  not inside the VM.        │
-├──────────────────────────┴────────────────────────────┤
-│              Hyperlight Validation Sandbox            │
-│    (validates generated code before execution)        │
-└───────────────────────────────────────────────────────┘
-```
-
-## Plugins
-
-Plugins extend the sandbox with host capabilities:
-
-| Plugin | Description |
-|--------|-------------|
-| `fs-read` | Read files (path-jailed) |
-| `fs-write` | Write files (path-jailed) |
-| `fetch` | HTTPS fetch (domain allowlist, SSRF protection) |
-
-Enable with `/plugin enable <name>` or via profiles.
-
-See [docs/PLUGINS.md](docs/PLUGINS.md) for authoring your own plugins.
-
-## Security
-
-- **Hardware isolation**: JavaScript runs in Hyperlight micro-VMs
-- **Tool gating**: SDK tools (bash, edit, etc.) are blocked
-- **Code validation**: LLM-generated code validated before execution
-- **Plugin auditing**: LLM analyzes plugin code before enabling
-- **Path jailing**: File plugins restricted to configured directories
-- **SSRF protection**: Fetch plugin validates DNS and post-connect IPs
-
-See [SECURITY.md](SECURITY.md) and [docs/SECURITY.md](docs/SECURITY.md) for details.
+Type `/help` in the REPL for the full list.
+
+| Command                 | Description                       |
+| ----------------------- | --------------------------------- |
+| `/model <name>`         | Switch models mid-conversation    |
+| `/models`               | List available models             |
+| `/plugin list`          | List plugins                      |
+| `/plugin enable <name>` | Enable a plugin                   |
+| `/mcp list`             | List configured MCP servers       |
+| `/mcp enable <name>`    | Approve and connect an MCP server |
+| `/config`               | Show current configuration        |
+| `/new`                  | Start a fresh session             |
+| `/resume [id]`          | Resume a saved session            |
+| `/exit`                 | Exit                              |
 
 ## Documentation
 
-| Document | Description |
-|----------|-------------|
-| [How It Works](docs/HOW-IT-WORKS.md) | User-focused system overview |
-| [Usage Guide](docs/USAGE.md) | Complete CLI and feature reference |
-| [Architecture](docs/ARCHITECTURE.md) | System design and components |
-| [Security Model](docs/SECURITY.md) | Detailed security architecture |
-| [Code Validation](docs/VALIDATION.md) | Pre-execution code validation |
-| [Plugins](docs/PLUGINS.md) | Plugin system and authoring guide |
-| [Skills](docs/SKILLS.md) | Domain expertise system |
-| [Patterns](docs/PATTERNS.md) | Code generation patterns |
-| [Modules](docs/MODULES.md) | ES module system |
-| [Profiles](docs/PROFILES.md) | Resource profiles |
-| [Development](docs/DEVELOPMENT.md) | Development environment setup |
-| [Releasing](docs/RELEASING.md) | Release process |
+| Document                             | Description                        |
+| ------------------------------------ | ---------------------------------- |
+| [How It Works](docs/HOW-IT-WORKS.md) | User-focused system overview       |
+| [Usage Guide](docs/USAGE.md)         | Complete CLI and feature reference |
+| [Architecture](docs/ARCHITECTURE.md) | System design and components       |
+| [Security Model](docs/SECURITY.md)   | Detailed security architecture     |
+| [MCP](docs/MCP.md)                   | Model Context Protocol integration |
+| [Plugins](docs/PLUGINS.md)           | Plugin system and authoring guide  |
+| [Skills](docs/SKILLS.md)             | Domain expertise system            |
+| [Patterns](docs/PATTERNS.md)         | Workflow pattern system            |
+| [Modules](docs/MODULES.md)           | Built-in and user module system    |
+| [Profiles](docs/PROFILES.md)         | Resource and plugin profiles       |
+| [Development](docs/DEVELOPMENT.md)   | Development environment setup      |
+| [Releasing](docs/RELEASING.md)       | Release process                    |
 
 ## Contributing
 
@@ -347,10 +418,6 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
 
 For development setup, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
 
-## Releasing
-
-See [docs/RELEASING.md](docs/RELEASING.md) for release process.
-
 ## License
 
-Apache 2.0 — see [LICENSE.txt](LICENSE.txt)
+Apache 2.0 - see [LICENSE.txt](LICENSE.txt).
diff --git a/docs/PROFILES.md b/docs/PROFILES.md
index a876eec..28119a2 100644
--- a/docs/PROFILES.md
+++ b/docs/PROFILES.md
@@ -2,10 +2,17 @@
 
 Profiles bundle resource limits and plugin requirements into named presets. They simplify configuration for common use cases.
 
+There are two ways profiles are used:
+
+- CLI `--profile` applies CPU, wall-clock, heap, and scratch limits at startup.
+- `/profile apply` and the `apply_profile` tool apply resource limits and request the profile's plugin requirements.
+
 ## Using Profiles
 
 ### Via CLI
 
+CLI profiles are useful when a run needs larger heap, scratch space, or timeouts from the start. They do not silently enable plugins, and input/output buffer profile limits are only applied through `/profile apply`, `apply_profile`, or runtime configuration.
+
 ```bash
 # Single profile
 hyperagent --profile file-builder
@@ -20,10 +27,9 @@ hyperagent --profile file-builder --skill pptx-expert
 ### Via Slash Command
 
 ```
-You: /profile file-builder
-  📦 Applied profile: file-builder
-     Heap: 64MB, CPU: 3000ms, Wall: 10s
-     Plugins: fs-write
+You: /profile apply file-builder
+  ✅ Limits applied: heap: 128MB, cpu: 15000ms, wall: 60s
+  📋 Profile applied: file-builder
 ```
 
 ### Via Tool
@@ -31,21 +37,21 @@ You: /profile file-builder
 The LLM can apply profiles:
 
 ```
-LLM calls apply_profile({ name: "web-research" })
+LLM calls apply_profile({ profiles: "web-research" })
 ```
 
 ## Built-in Profiles
 
-| Profile | Heap | CPU | Wall | Plugins | Use Case |
-|---------|------|-----|------|---------|----------|
-| `default` | 16MB | 1000ms | 5s | — | Math, algorithms, data transforms |
-| `file-builder` | 64MB | 3000ms | 10s | fs-write | ZIP, PPTX, CSV, image generation |
-| `web-research` | 32MB | 2000ms | 30s | fetch, fs-write | API calls, web scraping, pipelines |
-| `heavy-compute` | 64MB | 10000ms | 15s | — | Large datasets, crypto, simulations |
+| Profile         | Heap  | CPU     | Wall | Plugins         | Use Case                            |
+| --------------- | ----- | ------- | ---- | --------------- | ----------------------------------- |
+| `default`       | 16MB  | 1000ms  | 5s   | --              | Math, algorithms, data transforms   |
+| `file-builder`  | 128MB | 15000ms | 60s  | fs-write        | ZIP, PPTX, PDF, CSV, images         |
+| `web-research`  | 64MB  | 2000ms  | 120s | fetch, fs-write | API calls, web scraping, pipelines  |
+| `heavy-compute` | 64MB  | 10000ms | 15s  | --              | Large datasets, crypto, simulations |
 
 ## Profile Stacking
 
-When multiple profiles are applied, settings are combined:
+When multiple profiles are applied with `/profile apply` or `apply_profile`, settings are combined:
 
 - **Resource limits**: Maximum of each limit
 - **Plugins**: Union of all plugins
@@ -53,13 +59,14 @@ When multiple profiles are applied, settings are combined:
 ### Example
 
 ```bash
-hyperagent --profile "web-research heavy-compute"
+/profile apply web-research heavy-compute
 ```
 
 Results in:
-- Heap: 64MB (max of 32MB and 64MB)
+
+- Heap: 64MB (max of 64MB and 64MB)
 - CPU: 10000ms (max of 2000ms and 10000ms)
-- Wall: 30s (max of 30s and 15s)
+- Wall: 120s (max of 120s and 15s)
 - Plugins: fetch, fs-write
 
 ## Resource Limits
@@ -67,7 +74,9 @@ Results in:
 ### CPU Timeout
 
 Maximum CPU time per handler execution:
+
 - `default`: 1000ms (1 second)
+- `file-builder`: 15000ms (15 seconds)
 - `heavy-compute`: 10000ms (10 seconds)
 
 Override: `--cpu-timeout <ms>` or `/timeout cpu <ms>`
@@ -75,23 +84,30 @@ Override: `--cpu-timeout <ms>` or `/timeout cpu <ms>`
 ### Wall Timeout
 
 Maximum wall-clock time per execution:
+
 - `default`: 5000ms (5 seconds)
-- `web-research`: 30000ms (30 seconds)
+- `file-builder`: 60000ms (60 seconds)
+- `web-research`: 120000ms (120 seconds)
 
 Override: `--wall-timeout <ms>` or `/timeout wall <ms>`
 
 ### Heap Size
 
 Maximum JavaScript heap:
+
 - `default`: 16MB
-- `file-builder`: 64MB
+- `file-builder`: 128MB
+- `web-research`: 64MB
 
 Override: `--heap-size <MB>`
 
 ### Scratch Size
 
 Scratch space (includes stack):
+
 - `default`: 16MB
+- `file-builder`: 128MB
+- `web-research`: 64MB
 
 Override: `--scratch-size <MB>`
 
@@ -99,12 +115,13 @@ Override: `--scratch-size <MB>`
 
 Profiles can require plugins:
 
-| Profile | Required Plugins |
-|---------|-----------------|
-| `file-builder` | fs-write |
-| `web-research` | fetch, fs-write |
+| Profile        | Required Plugins |
+| -------------- | ---------------- |
+| `file-builder` | fs-write         |
+| `web-research` | fetch, fs-write  |
+
+When a profile is applied with `/profile apply` or `apply_profile`:
 
-When a profile is applied:
 1. Required plugins are enabled if not already
 2. Plugin configuration may be prompted
 3. Approved plugins skip audit
@@ -114,6 +131,7 @@ When a profile is applied:
 ### Default (No Profile)
 
 For pure computation:
+
 - Mathematical calculations
 - Algorithm implementation
 - Data transformation (in memory)
@@ -122,6 +140,7 @@ For pure computation:
 ### file-builder
 
 For generating files:
+
 - ZIP archives
 - PowerPoint presentations
 - CSV/JSON exports
@@ -130,6 +149,7 @@ For generating files:
 ### web-research
 
 For accessing external data:
+
 - API calls
 - Web scraping
 - Data pipelines
@@ -138,6 +158,7 @@ For accessing external data:
 ### heavy-compute
 
 For intensive calculations:
+
 - Large datasets
 - Cryptographic operations
 - Simulations
@@ -148,10 +169,10 @@ For intensive calculations:
 Profiles provide resources, skills provide knowledge:
 
 ```bash
-# Build presentations: need file access + PPTX knowledge
+# Build presentations: start with file-building limits + PPTX knowledge
 hyperagent --profile file-builder --skill pptx-expert
 
-# Web scraping: need network + scraping techniques
+# Web scraping: start with web-research limits + scraping techniques
 hyperagent --profile web-research --skill web-scraper
 ```
 
@@ -179,11 +200,11 @@ Runtime adjustments:
 
 ## Profile vs Manual Configuration
 
-| Approach | Pros | Cons |
-|----------|------|------|
-| Profile | Quick, tested combinations | Less flexible |
-| Manual | Fine-grained control | More typing |
-| Stacked | Best of multiple profiles | Can be overkill |
+| Approach | Pros                       | Cons            |
+| -------- | -------------------------- | --------------- |
+| Profile  | Quick, tested combinations | Less flexible   |
+| Manual   | Fine-grained control       | More typing     |
+| Stacked  | Best of multiple profiles  | Can be overkill |
 
 ## Implementation Details
 
@@ -195,13 +216,13 @@ const profiles: Record<string, Profile> = {
     heapSize: 16,
     cpuTimeout: 1000,
     wallTimeout: 5000,
-    plugins: []
+    plugins: [],
   },
   "file-builder": {
-    heapSize: 64,
-    cpuTimeout: 3000,
-    wallTimeout: 10000,
-    plugins: ["fs-write"]
+    heapSize: 128,
+    cpuTimeout: 15000,
+    wallTimeout: 60000,
+    plugins: ["fs-write"],
   },
   // ...
 };
diff --git a/docs/USAGE.md b/docs/USAGE.md
index a2d0db3..03a3461 100644
--- a/docs/USAGE.md
+++ b/docs/USAGE.md
@@ -4,57 +4,65 @@ Complete reference for HyperAgent configuration, features, and commands.
 
 ## CLI Flags
 
-| Flag                         | Description                                                          |
-| ---------------------------- | -------------------------------------------------------------------- |
-| `--model <name>`             | LLM model (default: `claude-opus-4.6`)                               |
-| `--cpu-timeout <ms>`         | CPU time limit per JS execution (default: 1000)                      |
-| `--wall-timeout <ms>`        | Wall-clock backstop per execution (default: 5000)                    |
-| `--send-timeout <ms>`        | Agent inactivity timeout (default: 300000)                           |
-| `--heap-size <MB>`           | Guest heap size (default: 16)                                        |
-| `--scratch-size <MB>`        | Guest scratch size, includes stack (default: 16)                     |
-| `--profile <name>`           | Apply resource profile at startup (stackable)                        |
-| `--skill <name>`             | Invoke skill(s) before the prompt                                    |
-| `--auto-approve`             | Auto-approve all interactive prompts                                 |
-| `--prompt "<text>"`          | Non-interactive: send prompt, wait for completion, exit              |
-| `--show-code`                | Log generated JS to a timestamped file                               |
-| `--show-timing`              | Log timing breakdown to a timestamped file                           |
-| `--show-reasoning [level]`   | Set reasoning effort (low\|medium\|high\|xhigh, default: high)       |
-| `--verbose`                  | Verbose output mode (scrolling reasoning, turn details)              |
-| `--transcript`               | Record session transcript to `~/.hyperagent/logs/`                   |
-| `--tune`                     | Capture LLM decision/reasoning logs to JSONL                         |
-| `--plugins-dir <path>`       | Custom plugins directory (default: `./plugins`)                      |
-| `--list-models`              | List available models and exit                                       |
-| `--resume [id]`              | Resume a previous session (latest if no ID given)                    |
-| `--debug`                    | Enable debug event/lifecycle logging                                 |
-| `--version`                  | Show version and exit                                                |
-| `--help`                     | Show help message                                                    |
+| Flag                       | Description                                                    |
+| -------------------------- | -------------------------------------------------------------- |
+| `--model <name>`           | LLM model (default: `claude-opus-4.6`)                         |
+| `--cpu-timeout <ms>`       | CPU time limit per JS execution (default: 1000)                |
+| `--wall-timeout <ms>`      | Wall-clock backstop per execution (default: 5000)              |
+| `--send-timeout <ms>`      | Agent inactivity timeout (default: 300000)                     |
+| `--heap-size <MB>`         | Guest heap size (default: 16)                                  |
+| `--scratch-size <MB>`      | Guest scratch size, includes stack (default: 16)               |
+| `--profile <name>`         | Apply resource profile at startup (stackable)                  |
+| `--skill <name>`           | Invoke skill(s) before the prompt                              |
+| `--auto-approve`           | Auto-approve all interactive prompts                           |
+| `--prompt "<text>"`        | Non-interactive: send prompt, wait for completion, exit        |
+| `--prompt-file <path>`     | Read the non-interactive prompt from a file                    |
+| `--show-code`              | Log generated JS to a timestamped file                         |
+| `--show-timing`            | Log timing breakdown to a timestamped file                     |
+| `--show-reasoning [level]` | Set reasoning effort (low\|medium\|high\|xhigh, default: high) |
+| `--verbose`                | Verbose output mode (scrolling reasoning, turn details)        |
+| `--transcript`             | Record session transcript to `~/.hyperagent/logs/`             |
+| `--tune`                   | Capture LLM decision/reasoning logs to JSONL                   |
+| `--plugins-dir <path>`     | Custom plugins directory (default: `./plugins`)                |
+| `--list-models`            | List available models and exit                                 |
+| `--resume [id]`            | Resume a previous session (latest if no ID given)              |
+| `--skip-suggest`           | Skip mandatory suggest_approach/API-discovery enforcement      |
+| `--output-threshold <n>`   | Large output threshold in bytes (default: 20480)               |
+| `--debug`                  | Enable debug event/lifecycle logging                           |
+| `--version`                | Show version and exit                                          |
+| `--help`                   | Show help message                                              |
 
 ## Environment Variables
 
 All configuration is also available via environment variables (overridden by CLI flags):
 
-| Variable                      | Default             | Description                                    |
-| ----------------------------- | ------------------- | ---------------------------------------------- |
-| `COPILOT_MODEL`               | `claude-opus-4.6`   | Model name for the Copilot SDK session         |
-| `HYPERLIGHT_CPU_TIMEOUT_MS`   | `1000`              | Max CPU time per JS execution (ms)             |
-| `HYPERLIGHT_WALL_TIMEOUT_MS`  | `5000`              | Max wall-clock time per execution (ms)         |
-| `HYPERAGENT_SEND_TIMEOUT_MS`  | `300000`            | Agent inactivity timeout (ms)                  |
-| `HYPERLIGHT_HEAP_SIZE_MB`     | `16`                | Guest heap size (megabytes)                    |
-| `HYPERLIGHT_SCRATCH_SIZE_MB`  | `16`                | Guest scratch size, includes stack (megabytes) |
-| `HYPERLIGHT_INPUT_BUFFER_KB`  | `64`                | Input buffer size (kilobytes)                  |
-| `HYPERLIGHT_OUTPUT_BUFFER_KB` | `64`                | Output buffer size (kilobytes)                 |
-| `HYPERAGENT_PROFILE`          | _(none)_            | Profile name(s) to apply at startup            |
-| `HYPERAGENT_AUTO_APPROVE`     | _(none)_            | Set to `1` for auto-approve mode               |
-| `HYPERAGENT_PROMPT`           | _(none)_            | Non-interactive prompt text                    |
-| `HYPERAGENT_SKILL`            | _(none)_            | Skill name(s) to invoke                        |
-| `HYPERAGENT_TUNE`             | _(none)_            | Set to `1` to capture LLM decision logs        |
-| `HYPERAGENT_SHOW_REASONING`   | _(none)_            | Reasoning effort level (low/medium/high/xhigh) |
-| `HYPERAGENT_VERBOSE`          | _(none)_            | Set to `1` for verbose output mode             |
-| `HYPERAGENT_PLUGINS_DIR`      | _(none)_            | Custom plugins directory path                  |
-| `HYPERAGENT_TIMING_LOG`       | _(none)_            | Path to timing log file (default: `~/.hyperagent/logs/`)  |
-| `HYPERAGENT_CODE_LOG`         | _(none)_            | Path to code log file (default: `~/.hyperagent/logs/`)    |
-| `HYPERAGENT_TRANSCRIPT`       | _(none)_            | Set to `1` to record session transcript        |
-| `HYPERAGENT_DEBUG`            | _(none)_            | Set to `1` for debug logging to `~/.hyperagent/logs/`   |
+| Variable                            | Default           | Description                                                      |
+| ----------------------------------- | ----------------- | ---------------------------------------------------------------- |
+| `COPILOT_MODEL`                     | `claude-opus-4.6` | Model name for the Copilot SDK session                           |
+| `HYPERLIGHT_CPU_TIMEOUT_MS`         | `1000`            | Max CPU time per JS execution (ms)                               |
+| `HYPERLIGHT_WALL_TIMEOUT_MS`        | `5000`            | Max wall-clock time per execution (ms)                           |
+| `HYPERAGENT_SEND_TIMEOUT_MS`        | `300000`          | Agent inactivity timeout (ms)                                    |
+| `HYPERLIGHT_HEAP_SIZE_MB`           | `16`              | Guest heap size (megabytes)                                      |
+| `HYPERLIGHT_SCRATCH_SIZE_MB`        | `16`              | Guest scratch size, includes stack (megabytes)                   |
+| `HYPERLIGHT_INPUT_BUFFER_KB`        | `1040`            | Input buffer size (kilobytes)                                    |
+| `HYPERLIGHT_OUTPUT_BUFFER_KB`       | `1040`            | Output buffer size (kilobytes)                                   |
+| `HYPERAGENT_PROFILE`                | _(none)_          | Profile name(s) to apply at startup                              |
+| `HYPERAGENT_AUTO_APPROVE`           | _(none)_          | Set to `1` for auto-approve mode                                 |
+| `HYPERAGENT_PROMPT`                 | _(none)_          | Non-interactive prompt text                                      |
+| `HYPERAGENT_PROMPT_FILE`            | _(none)_          | File containing the non-interactive prompt                       |
+| `HYPERAGENT_SKILL`                  | _(none)_          | Skill name(s) to invoke                                          |
+| `HYPERAGENT_TUNE`                   | _(none)_          | Set to `1` to capture LLM decision logs                          |
+| `HYPERAGENT_SHOW_REASONING`         | _(none)_          | Reasoning effort level (low/medium/high/xhigh)                   |
+| `HYPERAGENT_VERBOSE`                | _(none)_          | Set to `1` for verbose output mode                               |
+| `HYPERAGENT_LIST_MODELS`            | _(none)_          | Set to `1` to list models and exit                               |
+| `HYPERAGENT_RESUME_SESSION`         | _(none)_          | Session ID to resume, or `__last__` for latest                   |
+| `HYPERAGENT_PLUGINS_DIR`            | _(none)_          | Custom plugins directory path                                    |
+| `HYPERAGENT_SKIP_SUGGEST`           | _(none)_          | Set to `1` to disable suggest_approach/API-discovery enforcement |
+| `HYPERAGENT_OUTPUT_THRESHOLD_BYTES` | `20480`           | Large output threshold in bytes                                  |
+| `HYPERAGENT_TIMING_LOG`             | _(none)_          | Path to timing log file (default: `~/.hyperagent/logs/`)         |
+| `HYPERAGENT_CODE_LOG`               | _(none)_          | Path to code log file (default: `~/.hyperagent/logs/`)           |
+| `HYPERAGENT_TRANSCRIPT`             | _(none)_          | Set to `1` to record session transcript                          |
+| `HYPERAGENT_DEBUG`                  | _(none)_          | Set to `1` for debug logging to `~/.hyperagent/logs/`            |
 
 Example:
 
@@ -90,6 +98,10 @@ Toggle options at runtime without restarting. Type `/` and press Tab for complet
 | `/plugin approve <name>`      | Approve a plugin (persists until source changes or unapproved)  |
 | `/plugin unapprove <name>`    | Remove plugin approval                                          |
 | `/plugin audit <name>`        | Force re-audit a plugin (after source changes)                  |
+| `/profile list`               | List available resource profiles                                |
+| `/profile apply <name> ...`   | Apply profile limits and request required plugins               |
+| `/mcp list`                   | List configured MCP servers                                     |
+| `/mcp enable <name>`          | Approve and connect an MCP server                               |
 | `/config`                     | Show current configuration (model, timeouts, buffers, plugins)  |
 | `/help`                       | List available commands                                         |
 | `/exit`                       | Exit the agent (or just type `exit`)                            |
@@ -99,43 +111,58 @@ Toggle options at runtime without restarting. Type `/` and press Tab for complet
 The agent registers custom tools that the LLM can call. All SDK built-in tools
 (bash, grep, edit, etc.) are **blocked** by the tool gating layer.
 
-| Tool                    | Purpose                                                            |
-| ----------------------- | ------------------------------------------------------------------ |
-| `register_handler`      | Register named JavaScript handler code in the sandbox              |
-| `execute_javascript`    | Execute a registered handler with optional event data              |
-| `delete_handler`        | Remove a handler from the sandbox                                  |
-| `reset_sandbox`         | Clear sandbox state, keep handlers registered                      |
-| `configure_sandbox`     | Change resource limits at runtime (heap, scratch, timeouts, buffers) |
-| `register_module`       | Create a reusable ES module (persisted to `~/.hyperagent/modules/`) |
-| `list_modules`          | List available modules (system + user)                             |
-| `module_info`           | Get module exports, JSDoc, and metadata                            |
-| `delete_module`         | Delete a user-created module                                       |
-| `manage_plugin`         | Enable/disable plugins with configuration                          |
-| `list_plugins`          | Discover available plugins                                         |
-| `plugin_info`           | Detailed plugin information and config schema                      |
-| `apply_profile`         | Apply named resource profiles (limits + plugins in one step)       |
-| `sandbox_help`          | On-demand guidance: patterns, state, binary I/O, fetch, debugging  |
-| `ask_user`              | Ask the user structured questions (free-form or multiple choice)   |
-| `llm_thought`           | *(tune mode only)* Log structured reasoning for prompt engineering |
+| Tool                 | Purpose                                                              |
+| -------------------- | -------------------------------------------------------------------- |
+| `register_handler`   | Register named JavaScript handler code in the sandbox                |
+| `execute_javascript` | Execute a registered handler with optional event data                |
+| `delete_handler`     | Remove a handler from the sandbox                                    |
+| `get_handler_source` | Retrieve handler source for inspection or editing                    |
+| `edit_handler`       | Surgically edit an existing handler                                  |
+| `list_handlers`      | List registered handlers with line counts                            |
+| `reset_sandbox`      | Clear sandbox state, keep handlers registered                        |
+| `configure_sandbox`  | Change resource limits at runtime (heap, scratch, timeouts, buffers) |
+| `register_module`    | Create a reusable ES module (persisted to `~/.hyperagent/modules/`)  |
+| `list_modules`       | List available modules (system + user)                               |
+| `module_info`        | Get module exports, JSDoc, and metadata                              |
+| `delete_module`      | Delete a user-created module                                         |
+| `write_output`       | Write text content through the `fs-write` plugin                     |
+| `read_input`         | Read text content through the `fs-read` plugin                       |
+| `read_output`        | Read content previously written as output                            |
+| `manage_plugin`      | Enable/disable plugins with configuration                            |
+| `list_plugins`       | Discover available plugins                                           |
+| `plugin_info`        | Detailed plugin information and config schema                        |
+| `apply_profile`      | Apply named resource profiles (limits + plugins in one step)         |
+| `list_mcp_servers`   | List configured MCP servers and connection status                    |
+| `mcp_server_info`    | Inspect MCP server tools and generated declarations                  |
+| `manage_mcp`         | Connect or disconnect MCP servers                                    |
+| `sandbox_help`       | On-demand guidance: patterns, state, binary I/O, fetch, debugging    |
+| `report_intent`      | Protocol tool used by the model to signal intent                     |
+| `ask_user`           | Ask the user structured questions (free-form or multiple choice)     |
+| `llm_thought`        | _(tune mode only)_ Log structured reasoning for prompt engineering   |
 
 ## Profiles
 
 Profiles bundle resource limits and plugin requirements into named presets.
 Profiles are **additive** — stacking multiple takes the max of each limit
-and the union of all plugins.
+and the union of all plugins when applied during a session.
 
-| Profile          | Heap  | CPU     | Wall   | Plugins              | Use case                            |
-| ---------------- | ----- | ------- | ------ | -------------------- | ----------------------------------- |
-| `default`        | 16MB  | 1000ms  | 5s     | _(none)_             | Math, algorithms, data transforms   |
-| `file-builder`   | 64MB  | 3000ms  | 10s    | fs-write             | ZIP, PPTX, CSV, image generation    |
-| `web-research`   | 32MB  | 2000ms  | 30s    | fetch, fs-write      | API calls, web scraping, data pipelines |
-| `heavy-compute`  | 64MB  | 10000ms | 15s    | _(none)_             | Large datasets, crypto, simulations |
+CLI `--profile` applies CPU, wall-clock, heap, and scratch limits at startup.
+It does not silently enable plugins, and input/output buffer profile limits are
+only applied at runtime. During a run, use `/profile apply` or let the LLM call
+`apply_profile` to request the profile's plugin requirements.
+
+| Profile         | Heap  | CPU     | Wall | Plugins         | Use case                                |
+| --------------- | ----- | ------- | ---- | --------------- | --------------------------------------- |
+| `default`       | 16MB  | 1000ms  | 5s   | _(none)_        | Math, algorithms, data transforms       |
+| `file-builder`  | 128MB | 15000ms | 60s  | fs-write        | ZIP, PPTX, PDF, CSV, image generation   |
+| `web-research`  | 64MB  | 2000ms  | 120s | fetch, fs-write | API calls, web scraping, data pipelines |
+| `heavy-compute` | 64MB  | 10000ms | 15s  | _(none)_        | Large datasets, crypto, simulations     |
 
 ```bash
 # Single profile
 hyperagent --profile file-builder
 
-# Stacked — takes max of each limit, union of plugins
+# Stacked at startup — takes max of each limit
 hyperagent --profile "web-research heavy-compute"
 ```
 
@@ -153,7 +180,6 @@ allowed-tools:
   - register_handler
   - execute_javascript
 ---
-
 # PowerPoint Presentation Expert
 You are an expert at building professional, polished PowerPoint presentations...
 ```
@@ -196,19 +222,26 @@ sessions. They're importable via `import { fn } from "ha:<name>"`.
 
 Builtin ES modules available to handler code via `import { fn } from "ha:<name>"`:
 
-| Module         | Description                                                             |
-| -------------- | ----------------------------------------------------------------------- |
-| `str-bytes`    | String↔binary conversion, uint LE encoding, array concat               |
-| `crc32`        | CRC-32 checksum for ZIP/PNG                                             |
-| `base64`       | Base64 encode/decode                                                    |
-| `xml-escape`   | XML escaping + element builder                                          |
-| `deflate`      | DEFLATE compression (RFC 1951)                                          |
-| `shared-state` | Cross-handler key-value store (auto-preserved across recompiles)        |
-| `zip-format`   | ZIP archive builder (DEFLATE compressed)                                |
-| `ooxml-core`   | EMU conversions, 5 themes, Content_Types, rels XML                      |
-| `pptx`         | PowerPoint builder — 7 layouts, 13 shapes, notes, transitions, images   |
-| `pptx-charts`  | Bar, pie/donut, line, area, combo charts (editable in PowerPoint)       |
-| `pptx-tables`  | Styled tables, key-value lists, comparisons, timelines                  |
+| Module         | Description                                                       |
+| -------------- | ----------------------------------------------------------------- |
+| `shared-state` | Cross-handler state preserved across sandbox recompiles           |
+| `ziplib`       | Native DEFLATE compression/decompression                          |
+| `zip-format`   | ZIP archive builder for document formats                          |
+| `doc-core`     | Shared document themes, colour validation, and input guards       |
+| `ooxml-core`   | Shared OOXML units, colours, themes, content types, and rels      |
+| `pptx`         | PowerPoint presentation generation                                |
+| `pptx-charts`  | Editable PowerPoint charts                                        |
+| `pptx-tables`  | PowerPoint tables, comparisons, and timeline helpers              |
+| `xlsx`         | Excel workbook generation with sheets, pivots, charts, and styles |
+| `pdf`          | PDF document generation                                           |
+| `pdf-charts`   | PDF chart rendering                                               |
+| `markdown`     | Markdown to HTML or plain text conversion                         |
+| `html`         | HTML text and link extraction                                     |
+| `image`        | PNG/JPEG/GIF/BMP dimension reading                                |
+| `base64`       | Base64 encode/decode for binary data                              |
+| `str-bytes`    | String and byte conversion utilities                              |
+| `crc32`        | CRC-32 checksums for ZIP/PNG/gzip                                 |
+| `xml-escape`   | XML escaping and simple element building                          |
 
 ## Model Management
 
@@ -278,7 +311,8 @@ then auto-stripped to clean `.txt` on exit.
 ## Non-Interactive / Scripted Mode
 
 Combine `--prompt`, `--auto-approve`, and `--skill` for fully autonomous
-operation — no interactive prompts, no human in the loop:
+operation — no interactive prompts, no human in the loop. Treat this as yolo
+mode for trusted prompts only:
 
 ```bash
 # Autonomous PPTX generation
@@ -292,6 +326,7 @@ hyperagent --auto-approve \
 ```
 
 In auto-approve mode:
+
 - Plugin enables are approved automatically
 - `ask_user` questions select the first option
 - Config changes are applied without confirmation