docs: improve library user guidance

CONTRIBUTING.md

@@ -27,6 +27,7 @@ This guide is for both humans and coding agents. Agent-specific operating instru
 Choose the smallest verification set that covers your change, and include the commands you ran in your PR or handoff notes when the context would help reviewers.
 
 - Public API changes to any entrypoint listed in `scripts/workspace-entrypoints.ts`, including `@execbox/core/runtime` and `@execbox/quickjs/remote-endpoint`: run `npm run api:check`
+- Put security-focused specs under `packages/*/__tests__/security/`; `npm run test:security` runs those grouped suites.
 
 ## Changesets
 

README.md

@@ -10,7 +10,7 @@ Portable code execution for [Model Context Protocol](https://modelcontextprotoco
 
 </div>
 
-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: inline, behind a worker host, or across 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: inline QuickJS, worker-hosted QuickJS, or a remote runner behind your own transport.
 
 ## Package Map
 
@@ -24,6 +24,12 @@ Execbox turns host tool catalogs into callable guest namespaces, supports MCP wr
 
 Runnable examples live in [`examples/`](./examples/) and are indexed in [`examples/README.md`](./examples/README.md).
 
+## Choosing a Runtime
+
+- Start with `@execbox/quickjs` for trusted code and the smallest setup.
+- Use `new QuickJsExecutor({ host: "worker" })` when you want QuickJS off the main thread with pooled worker shells.
+- Use `@execbox/remote` when your application owns a process, container, VM, or network boundary for the runtime.
+
 ## Docs
 
 - [Public Docs](https://execbox.aallam.com)

docs/architecture/README.md

@@ -2,16 +2,16 @@
 
 Execbox is the code-execution part of the `execbox` workspace. It turns host tool catalogs into callable guest namespaces, lets those namespaces wrap MCP tools, and uses executor backends that decide where and how guest JavaScript runs.
 
-This Concepts section is for two audiences:
+This Concepts section is for library users choosing how to integrate execbox:
 
-- Integrators choosing packages and deployment shapes
-- Contributors reasoning about package boundaries, control flow, and trade-offs
+- Start here when you need the package map, trust model, and overall flow
+- Use the deeper pages when you are choosing a runtime, wrapping MCP tools, or implementing a remote runner
 
 ## Reading Guide
 
 - Start here for the package map, trust model, and overall flow.
 - Read [execbox-core.md](./execbox-core.md) for provider resolution, execution contracts, and error handling.
-- Read [execbox-executors.md](./execbox-executors.md) for QuickJS host modes and remote execution trade-offs.
+- Read [execbox-executors.md](./execbox-executors.md) for inline QuickJS, worker-hosted QuickJS, and remote execution trade-offs.
 - Read [execbox-mcp-and-protocol.md](./execbox-mcp-and-protocol.md) for MCP wrapping and where `@execbox/core/protocol` fits.
 - Read [execbox-remote-workflow.md](./execbox-remote-workflow.md) for the end-to-end remote execution control flow.
 - Read [execbox-protocol-reference.md](./execbox-protocol-reference.md) for the protocol message catalog and session rules.
@@ -99,4 +99,4 @@ Key implications:
 
 ## Architecture In One Paragraph
 
-`@execbox/core` owns the app-facing execution contract, provider resolution, MCP adapters, and the `@execbox/core/protocol` transport surface. Runtime implementers use `@execbox/core/runtime` for shared dispatch, manifest, timeout, log, and normalization helpers. `@execbox/quickjs` exposes the default runtime-specific reusable runner. Hosted `@execbox/quickjs` modes and `@execbox/remote` sit on top of `@execbox/core/protocol`, which owns the transport boundary: message shapes, shared host sessions, and reusable resource pools for transport-backed execution.
+`@execbox/core` owns the app-facing execution contract, provider resolution, MCP adapters, and the `@execbox/core/protocol` transport surface. Runtime implementers use `@execbox/core/runtime` for shared dispatch, manifest, timeout, log, and normalization helpers. `@execbox/quickjs` exposes the default runtime-specific reusable runner. Worker-hosted QuickJS and `@execbox/remote` sit on top of `@execbox/core/protocol`, which owns transport messages, shared host sessions, and reusable resource pools for transport-backed execution.

docs/architecture/execbox-executors.md

@@ -1,6 +1,6 @@
 # Execbox Executors
 
-This page explains how the available executors and QuickJS host modes differ and what trade-offs they make.
+This page explains how the available executors differ and what trade-offs they make.
 
 ## Executor Comparison
 
@@ -40,7 +40,7 @@ flowchart LR
 That design gives QuickJS two useful properties:
 
 - the runtime semantics are centralized in one runner implementation
-- the same guest/tool-call model can be reused behind hosted worker and remote transport boundaries
+- the same guest/tool-call model can be reused behind worker-hosted and remote transport boundaries
 
 ## Worker-Hosted QuickJS
 
@@ -94,7 +94,7 @@ Every `execute()` call still creates a fresh QuickJS runtime/context, reinjects
 Pooling is implemented at the host-shell layer, not at the QuickJS runtime layer.
 
 - `@execbox/core/protocol` exposes a small bounded async `createResourcePool()` helper that owns reusable shells, idle eviction, and `prewarm()` / `dispose()` support.
-- Hosted `QuickJsExecutor` pools `Worker` shells. Each shell owns one long-lived transport wrapper plus one attached QuickJS protocol endpoint.
+- Worker-hosted `QuickJsExecutor` pools `Worker` shells. Each shell owns one long-lived transport wrapper plus one attached QuickJS protocol endpoint.
 - The worker entrypoint only attaches `attachQuickJsProtocolEndpoint(...)` once. That endpoint accepts one active `execute` message at a time and starts a fresh `runQuickJsSession()` for each message.
 - Concurrency therefore comes from pool size, not from multiplexing several executions through one shell.
 
@@ -130,5 +130,5 @@ In pooled mode, a worker can exit before the host session subscribes to close ev
 ## Choosing an Executor
 
 - Choose `QuickJsExecutor` when you want the default backend with the least operational friction.
-- Choose `RemoteExecutor` when you want the same execution API but need the runtime to live behind an application-defined transport boundary.
+- Choose `RemoteExecutor` when you want the same execution API but need the runtime to live behind an application-defined process, container, VM, or network boundary.
 - Choose `QuickJsExecutor` with `host: "worker"` when you want the QuickJS semantics off the main thread with a hard-stop termination path and low-latency pooled reuse by default.

docs/architecture/execbox-mcp-and-protocol.md

@@ -44,7 +44,7 @@ flowchart LR
 It owns:
 
 - the `execute`, `cancel`, `started`, `tool_call`, `tool_result`, and `done` message types
-- the shared host transport session used by hosted `@execbox/quickjs` modes and `@execbox/remote`
+- the shared host transport session used by worker-hosted `@execbox/quickjs` and `@execbox/remote`
 - Node transport bootstrap helpers for worker execution
 - the reusable async resource pool used by pooled worker shells
 
@@ -74,7 +74,7 @@ flowchart TB
 
     subgraph TransportBacked["Transport-backed executors"]
         PROTO["@execbox/core/protocol<br/>messages + host session + resource pool"]
-        HOSTED["QuickJsExecutor host modes"]
+        HOSTED["QuickJsExecutor host: worker"]
         REM["RemoteExecutor"]
         QJS_ENDPOINT["QuickJS protocol endpoint<br/>worker side"]
         REMOTE_ENDPOINT["Runtime-owned remote endpoint<br/>QuickJS adapter is shipped"]
@@ -91,7 +91,7 @@ flowchart TB
 
 ## Transport-Backed Execution Flow
 
-The same host-session model is used for hosted QuickJS and remote execution:
+The same host-session model is used for worker-hosted QuickJS and remote execution:
 
 ```mermaid
 sequenceDiagram

docs/architecture/execbox-protocol-reference.md

@@ -2,7 +2,7 @@
 
 This page is the message-level reference for `@execbox/core/protocol`.
 
-It describes the wire shapes and session semantics used by transport-backed execbox runtimes such as hosted QuickJS and remote execution. It is grounded in the shipped implementation and should be read as a practical reference, not as a formal RFC.
+It describes the wire shapes and session semantics used by transport-backed execbox runtimes such as worker-hosted QuickJS and remote execution. This is an advanced reference for runtime and remote-runner implementers; most application users should start with [Getting Started](../getting-started.md), [Executors](./execbox-executors.md), and [Security & Boundaries](../security.md).
 
 For the higher-level control-flow explanation, read [execbox-remote-workflow.md](./execbox-remote-workflow.md). For the normative runner specification, read [execbox-runner-specification.md](./execbox-runner-specification.md).
 

docs/architecture/execbox-runner-specification.md

@@ -1,6 +1,6 @@
 # Execbox Runner Specification
 
-This page defines the runner specification for transport-backed execbox runners.
+This page defines the runner specification for transport-backed execbox runners. It is an advanced reference for users implementing their own runner boundary.
 
 Use it when you want to implement a non-TypeScript runner, such as a Go remote runner, without reverse-engineering the shipped TypeScript implementation. For the control-flow walkthrough, read [execbox-remote-workflow.md](./execbox-remote-workflow.md). For the message catalog, read [execbox-protocol-reference.md](./execbox-protocol-reference.md).
 

docs/architecture/index.md

@@ -2,16 +2,16 @@
 
 Execbox is the code-execution part of the `execbox` workspace. It turns host tool catalogs into callable guest namespaces, lets those namespaces wrap MCP tools, and uses executor backends that decide where and how guest JavaScript runs.
 
-This Concepts section is for two audiences:
+This Concepts section is for library users choosing how to integrate execbox:
 
-- integrators choosing packages and deployment shapes
-- contributors reasoning about package boundaries, control flow, and trade-offs
+- start here when you need the package map, trust model, and overall flow
+- use the deeper pages when you are choosing a runtime, wrapping MCP tools, or implementing a remote runner
 
 ## Reading guide
 
 - Start here for the package map, trust model, and overall flow.
 - Read [Core](/architecture/execbox-core) for provider resolution, execution contracts, and error handling.
-- Read [Executors](/architecture/execbox-executors) for QuickJS host modes and remote execution trade-offs.
+- Read [Executors](/architecture/execbox-executors) for inline QuickJS, worker-hosted QuickJS, and remote execution trade-offs.
 - Read [MCP And Protocol](/architecture/execbox-mcp-and-protocol) for MCP wrapping and where `@execbox/core/protocol` fits.
 - Read [Remote Workflow](/architecture/execbox-remote-workflow) for the end-to-end remote execution control flow.
 - Read [Protocol Reference](/architecture/execbox-protocol-reference) for the protocol message catalog and session rules.

docs/getting-started.md

@@ -1,6 +1,6 @@
 # Getting Started
 
-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.
+Execbox works best when you start with inline QuickJS, get one provider flow working, and then choose a different runtime placement only when your deployment needs it.
 
 ## Requirements
 
@@ -45,9 +45,11 @@ console.log(result);
 
 ## Which package should I use?
 
-- Use `@execbox/quickjs` first unless you already know you need a separate runtime boundary.
-- Use `new QuickJsExecutor({ host: "worker" })` when you want QuickJS off the main thread with pooled workers.
-- Use `@execbox/remote` only when your runtime already lives behind an application-owned transport.
+- Use `@execbox/quickjs` first for trusted code and the smallest setup.
+- Use `new QuickJsExecutor({ host: "worker" })` when you want QuickJS off the main thread with pooled worker shells.
+- Use `@execbox/remote` when your application owns the process, container, VM, or network boundary for the runtime.
+
+Worker-hosted QuickJS improves local lifecycle control, but it still shares the host process. Read [Security](/security) before treating any runtime placement as a production trust boundary.
 
 ## Run the examples
 

docs/index.md

@@ -19,7 +19,7 @@ features:
   - title: Code-first tool use
     details: Let agents write code against typed tool namespaces instead of serializing every intermediate step back through tool calls.
   - title: Execution boundary choice
-    details: Start with inline QuickJS, move to worker hosts, or push execution behind your own remote transport.
+    details: Start with inline QuickJS, move QuickJS off the main thread, or run behind your own remote transport.
   - title: MCP on both sides
     details: Wrap upstream MCP tools into guest namespaces and expose execbox execution back out as MCP tools for downstream clients.
 ---
@@ -36,11 +36,11 @@ That split gives you one execution contract across inline QuickJS, worker-hosted
 
 ## Choose a backend
 
-| Backend               | Package            | Start here when                                                                  |
-| --------------------- | ------------------ | -------------------------------------------------------------------------------- |
-| In-process QuickJS    | `@execbox/quickjs` | You want the easiest install and the default development path.                   |
-| Worker-backed QuickJS | `@execbox/quickjs` | You want the runtime off the main thread with pooled worker reuse.               |
-| Remote transport      | `@execbox/remote`  | You already own the transport/runtime boundary and want execbox to plug into it. |
+| Backend               | Package            | Start here when                                                                      |
+| --------------------- | ------------------ | ------------------------------------------------------------------------------------ |
+| In-process QuickJS    | `@execbox/quickjs` | You want the easiest install and the default development path.                       |
+| Worker-backed QuickJS | `@execbox/quickjs` | You want the runtime off the main thread with pooled worker reuse.                   |
+| Remote transport      | `@execbox/remote`  | Your application owns the process, container, VM, or network boundary for a runtime. |
 
 ## Security posture