feat(docs): add public docs site (#11)

Author: aallam

.github/workflows/ci.yml

@@ -72,3 +72,21 @@ jobs:
 
       - name: Run isolated-vm security lane
         run: npm run test:isolated-vm
+
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js 24
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build docs
+        run: npm run docs:build

.github/workflows/deploy-docs.yml

@@ -0,0 +1,46 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: docs-pages
+  cancel-in-progress: true
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js 24
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build docs
+        run: npm run docs:build
+
+      - uses: actions/configure-pages@v4
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,6 +1,8 @@
 .worktrees/
 node_modules/
 dist/
+docs/.vitepress/cache/
+docs/.vitepress/dist/
 packages/*/dist/
 coverage/
 *.tsbuildinfo

README.md

@@ -5,6 +5,7 @@
 Secure 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-execbox.aallam.com-0ea5e9?style=flat-square)](https://execbox.aallam.com)
 [![Packages](https://img.shields.io/badge/packages-7-111827?style=flat-square)](#package-map)
 
 </div>
@@ -29,5 +30,6 @@ Runnable examples live in [`examples/`](./examples/) and are indexed in [`exampl
 
 ## Docs
 
+- [Public Docs](https://execbox.aallam.com)
 - [Execbox Architecture Overview](./docs/architecture/README.md)
 - [QuickJS Pooling Baseline](./docs/performance/quickjs-pooling-baseline.md)

docs/.vitepress/config.ts

@@ -0,0 +1,63 @@
+import { defineConfig } from "vitepress";
+import { withMermaid } from "vitepress-plugin-mermaid";
+
+export default withMermaid(
+  defineConfig({
+    title: "execbox",
+    description:
+      "Portable code execution for MCP tools and wrapped MCP servers.",
+    base: "/",
+    cleanUrls: true,
+    lastUpdated: true,
+    mermaid: {
+      securityLevel: "loose",
+    },
+    themeConfig: {
+      footer: {
+        copyright: "Copyright © 2026 Mouaad Aallam",
+        message: "Released under the MIT License.",
+      },
+      nav: [
+        { link: "/getting-started", text: "Getting Started" },
+        { link: "/examples", text: "Examples" },
+        { link: "/architecture/", text: "Architecture" },
+        { link: "/security", text: "Security" },
+      ],
+      search: {
+        provider: "local",
+      },
+      sidebar: {
+        "/architecture/": [
+          {
+            items: [
+              { link: "/architecture/", text: "Overview" },
+              { link: "/architecture/execbox-core", text: "Core" },
+              { link: "/architecture/execbox-executors", text: "Executors" },
+              {
+                link: "/architecture/execbox-mcp-and-protocol",
+                text: "MCP And Protocol",
+              },
+              {
+                link: "/architecture/execbox-remote-workflow",
+                text: "Remote Workflow",
+              },
+              {
+                link: "/architecture/execbox-protocol-reference",
+                text: "Protocol Reference",
+              },
+              {
+                link: "/architecture/execbox-runner-specification",
+                text: "Runner Specification",
+              },
+            ],
+            text: "Architecture",
+          },
+        ],
+      },
+      socialLinks: [
+        { icon: "github", link: "https://github.com/aallam/execbox" },
+      ],
+      siteTitle: "execbox",
+    },
+  }),
+);

docs/.vitepress/theme/custom.css

@@ -0,0 +1,10 @@
+:root {
+  --vp-c-brand-1: #0f766e;
+  --vp-c-brand-2: #0d9488;
+  --vp-c-brand-3: #14b8a6;
+  --vp-c-brand-soft: rgba(20, 184, 166, 0.14);
+}
+
+.VPHomeHero .name {
+  max-width: 12ch;
+}

docs/.vitepress/theme/index.ts

@@ -0,0 +1,5 @@
+import DefaultTheme from "vitepress/theme";
+
+import "./custom.css";
+
+export default DefaultTheme;

docs/architecture/index.md

@@ -0,0 +1,66 @@
+# Execbox Architecture Overview
+
+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 pairs with executor packages that decide where and how guest JavaScript runs.
+
+This doc set is for two audiences:
+
+- integrators choosing packages and deployment shapes
+- contributors reasoning about package boundaries, control flow, and trade-offs
+
+## 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, process, worker-thread, and `isolated-vm` trade-offs.
+- Read [MCP And Protocol](/architecture/execbox-mcp-and-protocol) for MCP wrapping and where `execbox-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.
+- Read [Runner Specification](/architecture/execbox-runner-specification) for the normative runner specification for non-TypeScript runners.
+
+## Package map
+
+```mermaid
+flowchart LR
+    APP["Host application"]
+    CORE["@execbox/core<br/>provider resolution + runner semantics + MCP adapters"]
+    QJS["@execbox/quickjs<br/>in-process QuickJS executor + reusable runner"]
+    REM["@execbox/remote<br/>transport-backed remote executor"]
+    PROC["@execbox/process<br/>child-process QuickJS executor"]
+    IVM["@execbox/isolated-vm<br/>in-process isolated-vm executor + reusable runner"]
+    PROTO["@execbox/protocol<br/>transport messages + shared host session"]
+    WORKER["@execbox/worker<br/>worker-thread QuickJS executor"]
+    MCP["MCP sources and wrapped servers"]
+
+    APP --> CORE
+    APP --> QJS
+    APP --> REM
+    APP --> PROC
+    APP --> IVM
+    APP --> WORKER
+    CORE --> MCP
+    REM --> PROTO
+    PROC --> PROTO
+    WORKER --> PROTO
+    PROC --> QJS
+    WORKER --> QJS
+```
+
+## End-to-end execution model
+
+At a high level, execbox always follows the same model:
+
+1. Host code defines or discovers tools.
+2. `@execbox/core` resolves those tools into a deterministic guest namespace.
+3. An executor runs guest JavaScript against that resolved namespace.
+4. Guest tool calls cross a host-controlled boundary and return structured JSON-compatible results.
+
+## 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.
+
+Key implications:
+
+- The real capability boundary is the provider/tool surface, 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

@@ -0,0 +1,29 @@
+# Examples
+
+Use the examples when you want a runnable starting point rather than package-by-package reference material.
+
+## Run everything
+
+```bash
+npm install
+npm run build
+npm run examples
+```
+
+## Example index
+
+| Example | What it shows | When to start here |
+| --- | --- | --- |
+| [`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-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. |
+
+## What to read next
+
+- [Getting Started](/getting-started) for the minimal QuickJS install path
+- [Architecture](/architecture/) for how providers, executors, and protocol layers fit together
+- [Security](/security) before choosing a production boundary

docs/getting-started.md

@@ -0,0 +1,76 @@
+# 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.
+
+## Requirements
+
+- Node.js 22+
+- npm
+
+## Install
+
+```bash
+npm install @execbox/core @execbox/quickjs
+```
+
+## Smallest working example
+
+```ts
+import { resolveProvider } from "@execbox/core";
+import { QuickJsExecutor } from "@execbox/quickjs";
+
+const provider = resolveProvider({
+  name: "tools",
+  tools: {
+    greet: {
+      inputSchema: {
+        type: "object",
+        required: ["name"],
+        properties: {
+          name: { type: "string" },
+        },
+      },
+      execute: async (input) => `Hello, ${(input as { name: string }).name}!`,
+    },
+  },
+});
+
+const executor = new QuickJsExecutor();
+const result = await executor.execute(
+  `await tools.greet({ name: "World" })`,
+  [provider],
+);
+
+console.log(result);
+```
+
+## Which package should I use?
+
+- Use `@execbox/quickjs` first unless you already know you need a stronger 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.
+- Use `@execbox/isolated-vm` only when you explicitly want that runtime and can support `--no-node-snapshot`.
+
+## Run the examples
+
+The repo includes runnable examples for each main deployment shape:
+
+```bash
+npm install
+npm run build
+npm run examples
+```
+
+For the isolated-vm lane:
+
+```bash
+npm run example:execbox-isolated-vm
+npm run verify:isolated-vm
+```
+
+Next:
+
+- [Examples](/examples) for runnable flows
+- [Architecture](/architecture/) for the deeper technical model
+- [Security](/security) before choosing a production boundary