docs: refresh boundary and contributor guidance (#29)

aallam · web-flow · commit 6def6dd81404 · 2026-05-01T12:11:43.000+02:00
diff --git a/AGENTS.md b/AGENTS.md
@@ -32,7 +32,7 @@
 
 - For most code changes, run `npm run format:check`, `npm run lint`, `npm run typecheck`, `npm test`, and `npm run build`.
 - If you change package exports, manifest fields, or published type-resolution behavior, also run `npm run package:check`.
-- If you change the public API of `@execbox/core`, `@execbox/core/mcp`, `@execbox/core/protocol`, `@execbox/quickjs`, `@execbox/quickjs/runner`, `@execbox/quickjs/runner/protocol-endpoint`, `@execbox/remote`, `@execbox/isolated-vm`, or `@execbox/isolated-vm/runner`, also run `npm run api:check`.
+- If you change the public API of any entrypoint listed in `scripts/workspace-entrypoints.ts`, including `@execbox/core/runtime` and `@execbox/quickjs/remote-endpoint`, also run `npm run api:check`.
 - If you change docs site content, navigation, or VitePress config, also run `npm run docs:build`.
 - If you touch execution boundaries, timeout handling, abort propagation, schema validation, or log/memory controls, also run `npm run test:security`.
 - If you touch `@execbox/isolated-vm` or codepaths guarded by `VITEST_INCLUDE_ISOLATED_VM`, run `npm run test:isolated-vm` or `npm run verify:isolated-vm`.
@@ -48,7 +48,7 @@
 - Use Conventional Commits for git commit messages, for example `docs: add agent and contributor guides` or `fix(worker): handle timeout classification`.
 - Published package releases are managed with Changesets and GitHub Actions.
 - Add a `.changeset/*.md` entry when a change affects published package behavior, public APIs, or release notes for one or more `@execbox/*` packages.
-- If you intentionally change a checked-in API report for `@execbox/core`, `@execbox/core/mcp`, `@execbox/core/protocol`, `@execbox/quickjs`, `@execbox/quickjs/runner`, `@execbox/quickjs/runner/protocol-endpoint`, `@execbox/remote`, `@execbox/isolated-vm`, or `@execbox/isolated-vm/runner`, update it with `npm run api:update` in the same change as the code and changeset.
+- If you intentionally change a checked-in API report for any entrypoint listed in `scripts/workspace-entrypoints.ts`, update it with `npm run api:update` in the same change as the code and changeset.
 - Skip a changeset for docs-only, examples-only, CI-only, or internal maintenance changes that do not affect published package behavior.
 
 ## Useful References
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -27,14 +27,14 @@ 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 `@execbox/core`, `@execbox/core/mcp`, `@execbox/core/protocol`, `@execbox/quickjs`, `@execbox/quickjs/runner`, `@execbox/quickjs/runner/protocol-endpoint`, `@execbox/remote`, `@execbox/isolated-vm`, or `@execbox/isolated-vm/runner`: run `npm run api:check`
+- 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`
 
 ## Changesets
 
 - Add a `.changeset/*.md` file for user-facing changes to published `@execbox/*` packages.
 - Skip changesets for docs-only, examples-only, CI-only, or internal refactors that do not change published package behavior.
 - Keep the changeset summary focused on the externally visible change.
-- If you intentionally change a checked-in API report, update the report baseline with `npm run api:update` and add the corresponding changeset in the same change.
+- If you intentionally change a checked-in API report for an entrypoint listed in `scripts/workspace-entrypoints.ts`, update the report baseline with `npm run api:update` and add the corresponding changeset in the same change.
 
 ## Commits
 
diff --git a/README.md b/README.md
@@ -14,12 +14,12 @@ Execbox turns host tool catalogs into callable guest namespaces, supports MCP wr
 
 ## Package Map
 
-| Package                                           | npm                                                                                                                                   | What it is for                                                                                                 |
-| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| [`@execbox/core`](./packages/core/)               | [![npm](https://img.shields.io/npm/v/%40execbox%2Fcore?style=flat-square)](https://www.npmjs.com/package/@execbox/core)               | Core execution contract, provider resolution, MCP adapters, and the `@execbox/core/protocol` transport subpath |
-| [`@execbox/quickjs`](./packages/quickjs/)         | [![npm](https://img.shields.io/npm/v/%40execbox%2Fquickjs?style=flat-square)](https://www.npmjs.com/package/@execbox/quickjs)         | QuickJS executor for inline, worker, and process hosts                                                         |
-| [`@execbox/remote`](./packages/remote/)           | [![npm](https://img.shields.io/npm/v/%40execbox%2Fremote?style=flat-square)](https://www.npmjs.com/package/@execbox/remote)           | Transport-backed remote executor                                                                               |
-| [`@execbox/isolated-vm`](./packages/isolated-vm/) | [![npm](https://img.shields.io/npm/v/%40execbox%2Fisolated-vm?style=flat-square)](https://www.npmjs.com/package/@execbox/isolated-vm) | `isolated-vm` backend for execbox                                                                              |
+| Package                                           | npm                                                                                                                                   | What it is for                                                                            |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| [`@execbox/core`](./packages/core/)               | [![npm](https://img.shields.io/npm/v/%40execbox%2Fcore?style=flat-square)](https://www.npmjs.com/package/@execbox/core)               | Core execution contract, provider resolution, MCP adapters, and runtime/protocol subpaths |
+| [`@execbox/quickjs`](./packages/quickjs/)         | [![npm](https://img.shields.io/npm/v/%40execbox%2Fquickjs?style=flat-square)](https://www.npmjs.com/package/@execbox/quickjs)         | QuickJS executor for inline, worker, and process hosts                                    |
+| [`@execbox/remote`](./packages/remote/)           | [![npm](https://img.shields.io/npm/v/%40execbox%2Fremote?style=flat-square)](https://www.npmjs.com/package/@execbox/remote)           | Transport-backed remote executor                                                          |
+| [`@execbox/isolated-vm`](./packages/isolated-vm/) | [![npm](https://img.shields.io/npm/v/%40execbox%2Fisolated-vm?style=flat-square)](https://www.npmjs.com/package/@execbox/isolated-vm) | `isolated-vm` backend for execbox                                                         |
 
 ## Examples
 
diff --git a/docs/architecture/README.md b/docs/architecture/README.md
@@ -22,7 +22,7 @@ This doc set is for two audiences:
 ```mermaid
 flowchart LR
     APP["Host application"]
-    CORE["@execbox/core<br/>provider resolution + runner semantics + MCP adapters"]
+    CORE["@execbox/core<br/>provider resolution + MCP adapters + runtime helpers"]
     QJS["@execbox/quickjs<br/>QuickJS executor + reusable runner"]
     REM["@execbox/remote<br/>transport-backed remote executor"]
     IVM["@execbox/isolated-vm<br/>in-process isolated-vm executor + reusable runner"]
diff --git a/docs/architecture/execbox-executors.md b/docs/architecture/execbox-executors.md
@@ -47,7 +47,7 @@ flowchart LR
 
 ## QuickJS
 
-`QuickJsExecutor` is the default reference implementation for execbox. It uses the shared runner semantics from `@execbox/core`: providers are converted to manifests, host tool calls are dispatched through the shared dispatcher helper, and the reusable QuickJS runner turns them back into guest-visible async functions.
+`QuickJsExecutor` is the default reference implementation for execbox. It uses the shared runner semantics from `@execbox/core/runtime`: providers are converted to manifests, host tool calls are dispatched through the shared dispatcher helper, and the reusable QuickJS runner turns them back into guest-visible async functions.
 
 That design gives QuickJS two useful properties:
 
diff --git a/docs/architecture/execbox-mcp-and-protocol.md b/docs/architecture/execbox-mcp-and-protocol.md
@@ -50,15 +50,17 @@ It owns:
 
 The architecture split is:
 
-- `@execbox/core` owns provider resolution, manifest extraction, and host-side tool dispatch semantics
+- `@execbox/core` owns app-facing provider resolution and MCP adapters
+- `@execbox/core/runtime` owns manifest extraction and host-side tool dispatch helpers for runtime implementers
 - `@execbox/core/protocol` owns wire messages, host-session lifecycle, and host-side shell pooling utilities around those semantics
 
 ## How The Packages Fit Together
 
-- `QuickJsExecutor` uses the shared runner semantics from `@execbox/core` directly.
-- `IsolatedVmExecutor` uses the same core runner semantics, but keeps a direct `isolated-vm` bridge instead of transport messages.
+- `QuickJsExecutor` uses the shared runner semantics from `@execbox/core/runtime` directly.
+- `IsolatedVmExecutor` uses the same runtime helper surface, but keeps a direct `isolated-vm` bridge instead of transport messages.
 - `QuickJsExecutor` in `host: "process"` and `host: "worker"` modes uses the shared host session from `@execbox/core/protocol` plus the shared QuickJS protocol endpoint inside the child or worker shell.
 - `RemoteExecutor` uses that same host session across an app-owned transport boundary.
+- The runner side of a remote deployment attaches a runtime-owned endpoint adapter; `@execbox/quickjs/remote-endpoint` is the shipped QuickJS adapter.
 - Pooled process and worker execution reuse only the outer host shell. Each `execute()` call still starts a fresh QuickJS runtime through the shared protocol endpoint.
 
 ```mermaid
@@ -76,16 +78,18 @@ flowchart TB
         PROTO["@execbox/core/protocol<br/>messages + host session + resource pool"]
         HOSTED["QuickJsExecutor host modes"]
         REM["RemoteExecutor"]
-        ENDPOINT["QuickJS protocol endpoint"]
+        QJS_ENDPOINT["QuickJS protocol endpoint<br/>worker/process side"]
+        REMOTE_ENDPOINT["Runtime-owned remote endpoint<br/>QuickJS adapter is shipped"]
     end
 
     CORE --> QJS
     CORE --> IVM
     CORE --> PROTO
     HOSTED --> PROTO
     REM --> PROTO
-    HOSTED --> ENDPOINT
-    REM --> ENDPOINT
+    HOSTED --> QJS_ENDPOINT
+    REM -. runner side .-> REMOTE_ENDPOINT
+    REMOTE_ENDPOINT -. QuickJS example .-> QJS_ENDPOINT
 ```
 
 ## Transport-Backed Execution Flow
diff --git a/docs/architecture/execbox-remote-workflow.md b/docs/architecture/execbox-remote-workflow.md
@@ -53,7 +53,7 @@ sequenceDiagram
     participant Client as Downstream MCP client
     participant Wrapper as Wrapped MCP server
     participant Host as Host execbox session
-    participant Runner as Remote QuickJS runner
+    participant Runner as Remote runner
     participant Upstream as Upstream tools or MCP server
 
     Client->>Wrapper: callTool("mcp_execute_code", { code })
diff --git a/docs/architecture/index.md b/docs/architecture/index.md
@@ -22,7 +22,7 @@ This doc set is for two audiences:
 ```mermaid
 flowchart LR
     APP["Host application"]
-    CORE["@execbox/core<br/>provider resolution + runner semantics + MCP adapters"]
+    CORE["@execbox/core<br/>provider resolution + MCP adapters + runtime helpers"]
     QJS["@execbox/quickjs<br/>QuickJS executor + reusable runner"]
     REM["@execbox/remote<br/>transport-backed remote executor"]
     IVM["@execbox/isolated-vm<br/>in-process isolated-vm executor + reusable runner"]
diff --git a/docs/security.md b/docs/security.md
@@ -11,7 +11,7 @@ Execbox provides defense-in-depth controls for guest code execution. The isolati
 - Timeout and memory controls
 - Abort propagation into in-flight host tool work
 
-## Important boundaries
+## What execbox does not provide
 
 - A hard security boundary for hostile or multi-tenant code by default
 - That in-process runtimes are equivalent to a container, VM, or separate trust domain
diff --git a/packages/quickjs/README.md b/packages/quickjs/README.md
@@ -66,8 +66,8 @@ await executor.prewarm();
 ## Advanced Imports
 
 - `@execbox/quickjs/runner` exports the reusable QuickJS runner
-- `@execbox/quickjs/runner/protocol-endpoint` exports the shared protocol endpoint used by hosted and remote flows
-- `@execbox/quickjs/remote-endpoint` exports the QuickJS runner endpoint adapter for `@execbox/remote` transports
+- `@execbox/quickjs/runner/protocol-endpoint` exports the low-level QuickJS protocol loop used by hosted worker/process integrations
+- `@execbox/quickjs/remote-endpoint` adapts the QuickJS protocol loop to `@execbox/remote` runner ports
 
 ## Operational Notes
 
diff --git a/packages/remote/README.md b/packages/remote/README.md
@@ -14,16 +14,24 @@ Transport-backed executor for execbox. Use it when you want the execbox API on t
 
 ## Install
 
+Host side:
+
 ```bash
 npm install @execbox/core @execbox/remote
 ```
 
+Runner side, when using the shipped QuickJS endpoint:
+
+```bash
+npm install @execbox/quickjs
+```
+
 ## How It Fits
 
 `@execbox/remote` has two sides:
 
 - the host uses `RemoteExecutor` and supplies `HostTransport` instances
-- the runner attaches a protocol endpoint to an app-owned transport port
+- the runner attaches a runtime-owned endpoint adapter to an app-owned transport port
 
 The package stays intentionally small. It does not create servers, own authentication, or prescribe an HTTP or WebSocket framework.
 
@@ -56,7 +64,7 @@ const result = await executor.execute(`await tools.echo({ ok: true })`, [
 console.log(result);
 ```
 
-Runner side:
+Runner side, using the QuickJS endpoint shipped by `@execbox/quickjs`:
 
 ```ts
 import { attachQuickJsRemoteEndpoint } from "@execbox/quickjs/remote-endpoint";
