docs: polish public docs wording (#12)

Align the security and trust-model language across the site, architecture docs, and package READMEs.

Clarify the remote executor setup by separating the host-side and runner-side examples.

Author: aallam

README.md

@@ -2,15 +2,15 @@
 
 # execbox
 
-Secure code execution for [Model Context Protocol](https://modelcontextprotocol.io/) tools and wrapped MCP servers.
+Portable code execution for [Model Context Protocol](https://modelcontextprotocol.io/) tools and wrapped MCP servers.
 
 [![License](https://img.shields.io/github/license/aallam/execbox?style=flat-square)](https://github.com/aallam/execbox/blob/main/LICENSE)
 [![Docs](https://img.shields.io/badge/docs-site-0ea5e9?style=flat-square)](https://execbox.aallam.com)
 [![Packages](https://img.shields.io/badge/packages-7-111827?style=flat-square)](#package-map)
 
 </div>
 
-Execbox turns host tool catalogs into callable guest namespaces, supports MCP wrapping on both sides of the boundary, and lets you choose where guest JavaScript runs: in-process, in a worker, in a child process, or behind your own remote transport.
+Execbox turns host tool catalogs into callable guest namespaces, supports MCP wrapping on both sides of the boundary, and lets you place guest JavaScript where it fits your deployment: in-process, in a worker, in a child process, or behind your own remote transport.
 
 ## Package Map
 

docs/architecture/README.md

@@ -85,7 +85,7 @@ sequenceDiagram
 
 ## Trust Model and Security Posture
 
-Execbox reduces accidental exposure, but it does not claim a hard security boundary for hostile code in its default deployment model.
+Execbox provides defense-in-depth controls around guest execution, but hard isolation still depends on the executor and deployment boundary you choose.
 
 ```mermaid
 flowchart LR
@@ -103,7 +103,7 @@ flowchart LR
 
 Key implications:
 
-- The real capability boundary is the provider/tool surface, not the JavaScript syntax itself.
+- The provider/tool surface is the capability boundary, not the JavaScript syntax itself.
 - Fresh runtimes, schema validation, JSON-only boundaries, timeouts, memory limits, and bounded logs are defense-in-depth features.
 - In-process execution still shares the host process. Use a separate process, container, VM, or similar boundary when the code source is hostile or multi-tenant.
 - Wrapping third-party MCP servers is a separate dependency-trust decision from letting end users author guest code.

docs/architecture/execbox-executors.md

@@ -122,7 +122,7 @@ The four executors expose the same public result shape, but they enforce limits
 
 ## Security and Operational Trade-offs
 
-- All four executors are documented as best-effort isolation, not hard hostile-code boundaries.
+- All four executors provide defense-in-depth measures, not standalone hard hostile-code boundaries.
 - QuickJS is the easiest operational default and has the cleanest shared runtime story.
 - Remote execution keeps the same executor API while moving the runtime behind an app-defined boundary, but execbox deliberately does not ship the network stack for you.
 - Process-backed QuickJS gives a stronger lifecycle split than worker threads, but it is still not equivalent to a container or VM boundary.

docs/architecture/index.md

@@ -56,11 +56,11 @@ At a high level, execbox always follows the same model:
 
 ## Trust model and security posture
 
-Execbox reduces accidental exposure, but it does not claim a hard security boundary for hostile code in its default deployment model.
+Execbox provides defense-in-depth controls around guest execution, but hard isolation still depends on the executor and deployment boundary you choose.
 
 Key implications:
 
-- The real capability boundary is the provider/tool surface, not the JavaScript syntax itself.
+- The provider/tool surface is the capability boundary, not the JavaScript syntax itself.
 - Fresh runtimes, schema validation, JSON-only boundaries, timeouts, memory limits, and bounded logs are defense-in-depth features.
 - In-process execution still shares the host process. Use a separate process, container, VM, or similar boundary when the code source is hostile or multi-tenant.
 - Wrapping third-party MCP servers is a separate dependency-trust decision from letting end users author guest code.

docs/examples.md

@@ -1,6 +1,6 @@
 # Examples
 
-Use the examples when you want a runnable starting point rather than package-by-package reference material.
+Use these examples when you want a runnable starting point instead of reading package-by-package reference material first.
 
 ## Run everything
 
@@ -17,7 +17,7 @@ npm run examples
 | [`execbox-basic.ts`](https://github.com/aallam/execbox/blob/main/examples/execbox-basic.ts) | Resolve a provider and execute guest code with QuickJS. | You want the smallest end-to-end example. |
 | [`execbox-process.ts`](https://github.com/aallam/execbox/blob/main/examples/execbox-process.ts) | Run the same provider flow inside a child-process executor. | You want a stronger lifecycle boundary than in-process execution. |
 | [`execbox-worker.ts`](https://github.com/aallam/execbox/blob/main/examples/execbox-worker.ts) | Run the same provider flow inside a worker-thread executor. | You want QuickJS off the main thread. |
-| [`execbox-remote.ts`](https://github.com/aallam/execbox/blob/main/examples/execbox-remote.ts) | Run the same provider flow through a transport-backed executor. | You already own the remote boundary and want execbox to plug into it. |
+| [`execbox-remote.ts`](https://github.com/aallam/execbox/blob/main/examples/execbox-remote.ts) | Run the same provider flow through a transport-backed executor. | You already own the runtime boundary and want execbox to plug into it. |
 | [`execbox-mcp-provider.ts`](https://github.com/aallam/execbox/blob/main/examples/execbox-mcp-provider.ts) | Wrap MCP tools into a provider and execute against them. | You want guest code to call upstream MCP tools as code. |
 | [`execbox-mcp-server.ts`](https://github.com/aallam/execbox/blob/main/examples/execbox-mcp-server.ts) | Expose `mcp_search_tools`, `mcp_execute_code`, and `mcp_code`. | You want downstream MCP clients to execute code against a wrapped tool namespace. |
 | [`execbox-isolated-vm-basic.ts`](https://github.com/aallam/execbox/blob/main/examples/execbox-isolated-vm-basic.ts) | Run the same provider flow on the `isolated-vm` backend. | You explicitly want the `isolated-vm` runtime. |

docs/getting-started.md

@@ -1,6 +1,6 @@
 # Getting Started
 
-Execbox works best when you start small: define one provider, run one snippet, then choose a stronger boundary only when your deployment needs it.
+Execbox works best when you start with QuickJS, get one provider flow working, and then choose a stronger boundary only when your deployment needs it.
 
 ## Requirements
 
@@ -46,7 +46,7 @@ console.log(result);
 
 ## Which package should I use?
 
-- Use `@execbox/quickjs` first unless you already know you need a stronger boundary.
+- Use `@execbox/quickjs` first unless you already know you need a separate runtime boundary.
 - Use `@execbox/process` when you want QuickJS semantics in a separate child process.
 - Use `@execbox/worker` when you want QuickJS off the main thread with pooled workers.
 - Use `@execbox/remote` when your runtime already lives behind an application-owned transport.

docs/index.md

@@ -6,7 +6,7 @@ titleTemplate: false
 hero:
   name: execbox
   text: Portable code execution for MCP tools
-  tagline: Turn host tool catalogs into callable code, choose the execution boundary that fits your deployment, and keep your security claims honest.
+  tagline: Turn host tool catalogs into callable code, add defense-in-depth controls around guest execution, and choose the boundary that fits your deployment.
   actions:
     - theme: brand
       text: Getting Started
@@ -49,10 +49,10 @@ That split gives you one execution contract across QuickJS, worker-thread, child
 
 ## Security posture
 
-Execbox is intentionally conservative about its claims:
+Execbox provides defense-in-depth controls around guest code execution:
 
 - It provides fresh runtimes, JSON-only boundaries, schema validation, bounded logs, and execution limits.
-- It does **not** claim a hard security boundary for hostile code in its default deployment model.
-- The real capability boundary is the provider/tool surface you expose.
+- Hard isolation depends on the executor and deployment boundary you choose.
+- The provider/tool surface is the capability boundary.
 
 Read [Security](/security) before deciding which executor to use in production.

docs/security.md

@@ -1,6 +1,6 @@
 # Security & Boundaries
 
-Execbox reduces accidental exposure, but it does not market itself as a hard security boundary for hostile code in its default deployment model.
+Execbox provides defense-in-depth controls for guest code execution. The isolation level you get depends on the executor and deployment boundary you choose.
 
 ## What execbox does provide
 
@@ -21,7 +21,7 @@ Execbox reduces accidental exposure, but it does not market itself as a hard sec
 
 The provider/tool surface is the capability boundary.
 
-If guest code can call a dangerous tool, guest code can exercise that authority. Execbox changes how tool access is exposed and controlled; it does not erase the authority behind the tool itself.
+Providers are explicit capability grants. If guest code can call a dangerous tool, guest code can exercise that authority. Execbox changes how tool access is exposed and controlled; it does not erase the authority behind the tool itself.
 
 ## Choosing the right boundary
 

examples/README.md

@@ -5,7 +5,7 @@ Runnable examples for the `@execbox/*` package family.
 [![Examples](https://img.shields.io/badge/examples-runnable-0ea5e9?style=flat-square)](https://github.com/aallam/execbox/tree/main/examples)
 [![CI](https://img.shields.io/github/actions/workflow/status/aallam/execbox/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/aallam/execbox/actions/workflows/ci.yml)
 
-## Run Them
+## Run the examples
 
 ```bash
 npm install
@@ -20,6 +20,8 @@ npm run example:execbox-isolated-vm
 npm run verify:isolated-vm
 ```
 
+See the public [Examples docs](https://execbox.aallam.com/examples) for when to start with each example.
+
 ## Execbox
 
 | File                                                             | What it shows                                                  |

packages/core/README.md

@@ -50,7 +50,7 @@ Swap in `@execbox/remote` when you want the same API but a caller-managed remote
 ## Security Posture
 
 - Execbox gives you fresh execution state, JSON-only tool boundaries, schema validation, timeout handling, memory limits, and bounded logs.
-- Execbox does not give you a hard security boundary for hostile code by itself. The actual boundary depends on which executor you pair it with.
+- Hard isolation depends on the executor and deployment boundary you pair with `@execbox/core`.
 - Providers are explicit capability grants. Every tool you expose is authority you are handing to guest code.
 - In the default deployment model, provider and MCP tool definitions are controlled by the application, not by the end user.
 - Third-party MCP integrations should be reviewed as dependency-trust decisions, not folded into the primary end-user attacker model.