docs: rewrite README to follow the marketing landing page structure

- Lead with Execution, Filesystem, and Orchestration as top-level sections
- Restructure the quickstart into four numbered steps, with per-agent
  install commands and a pointer to agentos-core
- Replace the why/vs-sandbox framing with runtime mechanism and a
  "when to use a sandbox instead" section
- Collapse three benchmark tables into one, linking out for methodology
- Fold the feature list into a documentation index
- Fix dead links: /docs/benchmarks, /docs/js-runtime; drop /docs/webhooks

Author: NathanFlurry

README.md

@@ -3,39 +3,44 @@
 </p>
 
 <p align="center">
-  Give agents an operating system as a library.<br/>92x faster cold starts, 47x less memory, 254x cheaper than sandboxes.<br/>Built-in ACP agents: Pi, Claude Code, Codex, and OpenCode
+  Give agents an operating system as a library.<br/>
+  Each agent gets a POSIX filesystem, real process execution, and orchestration —<br/>
+  inside your existing backend process. No microVMs, no containers, no separate service.
 </p>
 
 <p align="center">
-  <a href="https://agentos-sdk.dev/docs">Documentation</a> | <a href="https://agentos-sdk.dev/docs/quickstart">Quickstart</a> | <a href="https://agentos-sdk.dev/registry">Registry</a> | <a href="https://rivet.dev/discord">Discord</a>
+  <a href="#benchmarks">92x faster cold starts</a> ·
+  <a href="#benchmarks">47x less memory</a> ·
+  <a href="#benchmarks">254x cheaper</a> than sandboxes
 </p>
 
-
-## Why agentOS
-
-- **Runs inside your process**: No microVMs to boot, no containers to pull, no nested virtualization. Warm VM creation takes single-digit milliseconds and each VM costs tens of megabytes.
-- **Embeds in your backend**: Agents call your functions directly via [bindings](https://agentos-sdk.dev/docs/bindings) — ordinary JavaScript calls, not another network service. Credentials stay on the host; agents see only inputs and outputs.
-- **Granular security**: [Permissions](https://agentos-sdk.dev/docs/permissions) gate filesystem, network, process, and environment access, with outward-facing capabilities like network egress denied by default. Guest JavaScript runs in V8 isolates and compiled tools run as WebAssembly, all inside one compact runtime.
-- **Deploy anywhere**: Just an npm package. Run locally with `npx rivetkit dev`, then deploy to [Rivet Cloud](https://agentos-sdk.dev/docs/deployment) for managed infrastructure or self-host on your own.
-- **Open source**: Apache 2.0 licensed.
-
-### agentOS vs Sandbox
-
-agentOS is a lightweight VM that runs inside your process. Sandboxes are full Linux environments. agentOS integrates agents into your backend with [bindings](https://agentos-sdk.dev/docs/bindings) and granular permissions. Sandboxes give you a full OS for browsers, native binaries, and dev servers.
-
-You don't have to choose: agentOS works with sandboxes through [sandbox mounting](https://agentos-sdk.dev/docs/sandbox), spinning up a full sandbox on demand and mounting the sandbox's file system when the workload needs it.
-
-See [agentOS vs Sandbox](https://agentos-sdk.dev/docs/versus-sandbox) for a full comparison.
+<p align="center">
+  <a href="https://agentos-sdk.dev/docs">Documentation</a> |
+  <a href="https://agentos-sdk.dev/docs/quickstart">Quickstart</a> |
+  <a href="https://agentos-sdk.dev/registry">Registry</a> |
+  <a href="https://rivet.dev/discord">Discord</a>
+</p>
 
 ## Quick start
 
+### 1. Install agentOS and the agents you want
+
 ```bash
-npm install @rivet-dev/agentos @agentos-software/pi
+npm install @rivet-dev/agentos
+
+# One package per agent — install as many as you need
+npm install @agentos-software/pi           # Pi
+npm install @agentos-software/claude-code  # Claude Code (beta)
+npm install @agentos-software/codex        # Codex (beta)
+npm install @agentos-software/opencode     # OpenCode
 ```
 
-Common POSIX utilities (coreutils, sed, grep, gawk, findutils, diffutils, tar, gzip) ship out of the box. [Claude Code](https://agentos-sdk.dev/docs/agents/claude), [Codex](https://agentos-sdk.dev/docs/agents/codex), and [OpenCode](https://agentos-sdk.dev/docs/agents/opencode) install the same way as Pi.
+Common POSIX utilities ship in the box. More agents and software in the
+[registry](https://agentos-sdk.dev/registry).
+
+### 2. Set up the server
 
-Create the server:
+Everything you installed gets passed to `software`:
 
 ```ts
 // server.ts
@@ -50,7 +55,9 @@ export const registry = setup({ use: { vm } });
 registry.start();
 ```
 
-Create the client — any public frontend or another backend:
+### 3. Connect to agentOS
+
+The client is any public frontend or another backend:
 
 ```ts
 // client.ts
@@ -79,122 +86,211 @@ await handle.prompt({
   ],
 });
 
-// Read the file the agent created
+// Read the file the agent created.
 const content = await handle.readFile("/workspace/hello.js");
 console.log(new TextDecoder().decode(content));
 ```
 
-Run both:
-
 ```bash
-# Terminal 1: start the server
-npx tsx server.ts
+npx tsx server.ts   # terminal 1
+npx tsx client.ts   # terminal 2
+```
 
-# Terminal 2: run the client
-npx tsx client.ts
+Each VM is a Rivet Actor, which is where persistence, sleep/wake, multiplayer, preview URLs, and
+orchestration come from.
+
+### Alternative: `@rivet-dev/agentos-core`
+
+```bash
+npm install @rivet-dev/agentos-core
 ```
 
-agentOS can run Node.js and shell scripts inside the VM:
+- Direct in-process VM control — `AgentOs.create()` returns a handle you call directly
+- No actor runtime, no server, no client
+- Trades away the Rivet Actor features above
+
+[Direct VM API](https://agentos-sdk.dev/docs/core)
+
+Full walkthrough: [Quickstart](https://agentos-sdk.dev/docs/quickstart) ·
+[Crash Course](https://agentos-sdk.dev/docs/crash-course)
+
+## Execution
+
+- Bash, Node.js, Python, and registry software, all in the same VM
+- Real processes, subprocesses, shells, and in-VM servers
+- JavaScript runs on native V8 with the full JIT — not JavaScript compiled to WebAssembly
 
 ```ts
-// Node.js
 await handle.writeFile("/hello.mjs", 'import fs from "fs"; fs.writeFileSync("/out.txt", "hi")');
 await handle.exec("node /hello.mjs");
 
-// Bash
 const result = await handle.exec("cat /out.txt");
 console.log(result.stdout); // "hi"
 ```
 
-`@rivet-dev/agentos` runs each VM as a Rivet Actor with built-in persistence, sleep/wake, multiplayer, preview URLs, and orchestration. For direct in-process VM control without the actor runtime, use [`@rivet-dev/agentos-core`](https://agentos-sdk.dev/docs/core) standalone: `AgentOs.create()` boots a VM and returns a handle you call directly.
+[Bash](https://agentos-sdk.dev/docs/bash) ·
+[Node.js](https://agentos-sdk.dev/docs/javascript) ·
+[Python](https://agentos-sdk.dev/docs/python) ·
+[Processes & shells](https://agentos-sdk.dev/docs/processes)
 
-See the [Quickstart guide](https://agentos-sdk.dev/docs/quickstart) for the full walkthrough. agentOS is in preview and the API is subject to change — questions and issues welcome on [Discord](https://rivet.dev/discord).
+## Filesystem
 
-## Benchmarks
+- A persistent POSIX filesystem per agent
+- Mount S3-compatible storage, Google Drive, host directories, or in-memory volumes at ordinary paths
+- Attach mounts at boot or dynamically at runtime
+- Normal files and shell tools work against all of it
 
-All benchmarks compare agentOS against the fastest/cheapest mainstream sandbox providers as of March 30, 2026. Methodology and reproduction steps: [Benchmarks](https://agentos-sdk.dev/docs/benchmarks).
+[Filesystem](https://agentos-sdk.dev/docs/filesystem) ·
+[Software](https://agentos-sdk.dev/docs/software) ·
+[Persistence & sleep](https://agentos-sdk.dev/docs/persistence)
 
-### Cold start
+## Orchestration
 
-| Percentile | agentOS | Fastest Sandbox (E2B) | Speedup |
-|---|---|---|---|
-| p50 | 4.8 ms | 440 ms | **92x faster** |
-| p95 | 5.6 ms | 950 ms | **170x faster** |
-| p99 | 6.1 ms | 3,150 ms | **516x faster** |
+- Durable sessions — persist across restarts, sleep when idle, wake with state intact
+- Run recurring jobs on a cron schedule
+- Delegate work from one agent to another
+- Share one live session across many connected clients
+- Pause for human approval before a tool call runs
 
-<sub>agentOS: measured on Intel i7-12700KF. Sandbox baseline: E2B, the fastest mainstream sandbox provider as of March 30, 2026.</sub>
+[Workflows & graphs](https://agentos-sdk.dev/docs/workflows) ·
+[Multiplayer](https://agentos-sdk.dev/docs/multiplayer) ·
+[Agent-to-agent](https://agentos-sdk.dev/docs/agent-to-agent) ·
+[Crons & loops](https://agentos-sdk.dev/docs/cron) ·
+[Approvals](https://agentos-sdk.dev/docs/approvals) ·
+[Apps](https://agentos-sdk.dev/docs/apps)
 
-### Memory per instance
+## Agents
 
-| Workload | agentOS | Cheapest Sandbox (Daytona) | Reduction |
-|---|---|---|---|
-| Full coding agent (Pi + MCP + filesystem) | ~131 MB | ~1,024 MB | **8x smaller** |
-| Simple shell command | ~22 MB | ~1,024 MB | **47x smaller** |
-
-<sub>Sandbox baseline: Daytona minimum instance (1 vCPU + 1 GiB RAM), the cheapest mainstream sandbox provider as of March 30, 2026.</sub>
+[Pi](https://agentos-sdk.dev/docs/agents/pi) ·
+[Claude Code](https://agentos-sdk.dev/docs/agents/claude) (beta) ·
+[Codex](https://agentos-sdk.dev/docs/agents/codex) (beta) ·
+[OpenCode](https://agentos-sdk.dev/docs/agents/opencode) ·
+[custom agents](https://agentos-sdk.dev/docs/agents/custom) ·
+[Vercel Eve](https://agentos-sdk.dev/docs/frameworks/vercel-eve) (beta) ·
+[Flue](https://agentos-sdk.dev/docs/frameworks/flue) (beta) ·
+[Rivet](https://agentos-sdk.dev/docs/frameworks/rivet)
 
-### Cost per execution-second (self-hosted)
+- One API for all of them, over the [Agent Client Protocol](https://agentclientprotocol.com)
+- [One transcript format](https://agentos-sdk.dev/docs/sessions) for debugging, auditing, and comparison
 
-Full coding agent:
+## Runtime
 
-| Host tier | agentOS | Cheapest Sandbox (Daytona) | Difference |
-|---|---|---|---|
-| AWS ARM | $0.00000058/s | $0.000018/s | **32x cheaper** |
-| AWS x86 | $0.00000072/s | $0.000018/s | **26x cheaper** |
-| Hetzner ARM | $0.000000066/s | $0.000018/s | **281x cheaper** |
-| Hetzner x86 | $0.00000011/s | $0.000018/s | **171x cheaper** |
+A trusted sidecar process owns every VM's kernel and brokers every guest syscall:
 
-Simple shell command:
+- Kernel owns the virtual filesystem, process table, pipes, PTYs, and network stack
+- No host filesystem, host sockets, or host processes are reachable from the guest
+- Guest JavaScript runs in V8 isolates; compiled tools run as WebAssembly
+- An additional VM costs an isolate plus kernel state — not an OS process or a microVM
 
-| Host tier | agentOS | Cheapest Sandbox (Daytona) | Difference |
-|---|---|---|---|
-| AWS ARM | $0.000000073/s | $0.000018/s | **254x cheaper** |
-| AWS x86 | $0.000000090/s | $0.000018/s | **205x cheaper** |
-| Hetzner ARM | $0.000000011/s | $0.000018/s | **1738x cheaper** |
-| Hetzner x86 | $0.000000017/s | $0.000018/s | **1061x cheaper** |
+That boundary is where policy is enforced:
 
-<sub>Sandbox baseline: Daytona at $0.0504/vCPU-h + $0.0162/GiB-h (1 vCPU + 1 GiB minimum). Assumes one agent per sandbox and 70% host utilization.</sub>
+- **[Permissions](https://agentos-sdk.dev/docs/permissions)** gate filesystem, network, process,
+  and environment access. Outward-facing capabilities like network egress are denied by default.
+- **[Resource limits](https://agentos-sdk.dev/docs/resource-limits)** cap CPU, memory, processes,
+  files, and sockets per VM.
+- **[Bindings](https://agentos-sdk.dev/docs/bindings)** expose host functions as CLI commands, so
+  credentials stay on the host and the agent sees only inputs and outputs.
 
-## Features
+[Architecture](https://agentos-sdk.dev/docs/architecture) ·
+[Security model](https://agentos-sdk.dev/docs/security-model) ·
+[Networking & previews](https://agentos-sdk.dev/docs/networking)
 
-### Agents
-- **Built-in agents**: Run [Pi](https://agentos-sdk.dev/docs/agents/pi), [Claude Code](https://agentos-sdk.dev/docs/agents/claude) (beta), [Codex](https://agentos-sdk.dev/docs/agents/codex) (beta), and [OpenCode](https://agentos-sdk.dev/docs/agents/opencode) with a unified API, or [bring your own agent](https://agentos-sdk.dev/docs/agents/custom)
-- **[Sessions via ACP](https://agentos-sdk.dev/docs/sessions)**: Create, manage, and resume agent sessions over the [Agent Client Protocol](https://agentclientprotocol.com)
-- **Universal transcript format**: One transcript format across all agents for debugging, auditing, and comparison
-- **[Automatic persistence](https://agentos-sdk.dev/docs/persistence)**: Every conversation is saved and replayable without extra code
-- **Framework integrations**: Use agentOS as the sandbox backend for [Vercel Eve](https://agentos-sdk.dev/docs/frameworks/vercel-eve) (beta) and [Flue](https://agentos-sdk.dev/docs/frameworks/flue) (beta)
-
-### Infrastructure
-- **[Execution](https://agentos-sdk.dev/docs/processes)**: Run Bash, Node.js, Python, and registry software inside the VM with real processes, subprocesses, shells, and in-VM servers
-- **[Mount external storage as a filesystem](https://agentos-sdk.dev/docs/filesystem)**: S3-compatible storage, Google Drive, host directories, or in-memory mounts, attached at boot or dynamically at runtime
-- **[Bindings](https://agentos-sdk.dev/docs/bindings)**: Define JavaScript functions that agents call as CLI commands inside the VM
-- **[Cron](https://agentos-sdk.dev/docs/cron) and [webhooks](https://agentos-sdk.dev/docs/webhooks)**: Schedule tasks with built-in cron jobs, and trigger agents from external webhooks with your own HTTP server
-- **[Browser](https://agentos-sdk.dev/docs/browser)** (beta): Give agents a cloud browser via Browserbase
-- **[Sandbox mounting](https://agentos-sdk.dev/docs/sandbox)** (beta): Pair with full sandboxes (E2B, Daytona, etc.) for heavy workloads like browsers or native compilation
-
-### Orchestration
-- **[Multiplayer](https://agentos-sdk.dev/docs/multiplayer)**: Multiple clients observe and collaborate with the same agent in real time
-- **[Agent-to-agent](https://agentos-sdk.dev/docs/agent-to-agent)**: Agents delegate work to other agents through host-defined bindings
-- **[Workflows](https://agentos-sdk.dev/docs/workflows)**: Chain agent tasks into durable workflows with retries, branching, and resumable execution
-- **[Authentication](https://agentos-sdk.dev/docs/authentication)**: Integrate with your existing auth model (API keys, OAuth, JWTs)
-
-### Security
-- **[Granular permissions](https://agentos-sdk.dev/docs/permissions)**: Control filesystem, network, process, and environment access, with outward-facing capabilities denied by default
-- **[Programmatic network control](https://agentos-sdk.dev/docs/networking)**: Allow or deny any outbound connection with per-host rules, and proxy HTTP into VM services with preview URLs
-- **[Resource limits](https://agentos-sdk.dev/docs/resource-limits)**: Set precise CPU and memory limits per agent
-- **[VM isolation](https://agentos-sdk.dev/docs/security-model)**: Each agent runs in its own VM with no shared state
-
-## Architecture
+## Registry
 
-agentOS runs each agent in a fully virtualized VM. A trusted sidecar process owns every VM's kernel — virtual filesystem, process table, pipes, PTYs, and a virtual network stack — and brokers every guest syscall; nothing the guest does touches the host directly: no real host filesystem, no real host sockets, no real host processes. Guest JavaScript runs on native V8 with its full JIT ([JavaScript runtime](https://agentos-sdk.dev/docs/js-runtime)), and compiled tools run as WebAssembly. Many VMs share one sidecar process, so each additional VM costs a V8 isolate plus kernel state, not an OS process. With `@rivet-dev/agentos`, each VM is a Rivet Actor with durable state.
+- Agents, browsers, and software install from npm under `@agentos-software/*` → `software: [...]`
+- Filesystem plugins need no install → `mounts: [...]`
 
-See the [Architecture docs](https://agentos-sdk.dev/docs/architecture) for details.
+[Browse the registry](https://agentos-sdk.dev/registry)
 
-## Registry
+## Benchmarks
 
-Extend agentOS with agents, filesystems, browsers, and software from one registry. Browse the full catalog at the [agentOS Registry](https://agentos-sdk.dev/registry).
+Measured against the fastest and cheapest mainstream sandbox providers as of March 30, 2026.
 
-Common POSIX utilities ship out of the box. The registry adds agents (`@agentos-software/pi`, `@agentos-software/claude-code`, `@agentos-software/codex`, `@agentos-software/opencode`), command packages (`git`, `ripgrep`, `jq`, `sqlite3`, `duckdb`, `curl`, `vim`, and more), meta-packages (`common`, `build-essential`, `everything`), and integrations like the Browserbase cloud browser. Install any of them from npm and pass them via `software: [...]`.
+| | agentOS | Sandbox | |
+|---|---|---|---|
+| Cold start (p50) | 4.8 ms | 440 ms (E2B) | **92x faster** |
+| Memory per instance | ~22 MB | ~1,024 MB (Daytona) | **47x smaller** |
+| Cost per execution-second | $0.000000073/s | $0.000018/s (Daytona) | **254x cheaper** |
+
+<sub>agentOS cold start measured on Intel i7-12700KF. Memory and cost use the shell workload; a full
+coding agent (Pi + MCP + filesystem) is ~131 MB. Cost is self-hosted on AWS ARM at 70% utilization
+against Daytona's 1 vCPU + 1 GiB minimum.</sub>
+
+Percentiles, per-workload figures, host tiers, and reproduction steps:
+[Performance](https://agentos-sdk.dev/docs/performance)
+
+## When to use a sandbox instead
+
+- **agentOS** — a lightweight VM inside your process, for embedding agents in a backend with
+  bindings and granular permissions
+- **Sandboxes** — full Linux environments, a better fit for native binaries, browsers, and dev servers
+- **Both** — [sandbox mounting](https://agentos-sdk.dev/docs/sandbox) spins up a sandbox on demand
+  and mounts its filesystem into the VM
+
+[agentOS vs Sandbox](https://agentos-sdk.dev/docs/versus-sandbox) ·
+[Limitations](https://agentos-sdk.dev/docs/limitations)
+
+## Documentation
+
+**Getting Started** —
+[Quick Start](https://agentos-sdk.dev/docs/quickstart) ·
+[Crash Course](https://agentos-sdk.dev/docs/crash-course)
+
+**Agents** —
+[Pi](https://agentos-sdk.dev/docs/agents/pi) ·
+[Claude Code](https://agentos-sdk.dev/docs/agents/claude) ·
+[Codex](https://agentos-sdk.dev/docs/agents/codex) ·
+[OpenCode](https://agentos-sdk.dev/docs/agents/opencode) ·
+[Flue](https://agentos-sdk.dev/docs/frameworks/flue) ·
+[Eve](https://agentos-sdk.dev/docs/frameworks/vercel-eve)
+
+**Execution** —
+[Bash](https://agentos-sdk.dev/docs/bash) ·
+[Node.js](https://agentos-sdk.dev/docs/javascript) ·
+[Python](https://agentos-sdk.dev/docs/python)
+
+**Orchestration** —
+[Apps](https://agentos-sdk.dev/docs/apps) ·
+[Multiplayer](https://agentos-sdk.dev/docs/multiplayer) ·
+[Workflows](https://agentos-sdk.dev/docs/workflows) ·
+[Crons](https://agentos-sdk.dev/docs/cron) ·
+[Agent-to-Agent](https://agentos-sdk.dev/docs/agent-to-agent)
+
+**Operating System** —
+[Software](https://agentos-sdk.dev/docs/software) ·
+[Filesystem](https://agentos-sdk.dev/docs/filesystem) ·
+[Networking](https://agentos-sdk.dev/docs/networking) ·
+[Permissions](https://agentos-sdk.dev/docs/permissions) ·
+[Resource Limits](https://agentos-sdk.dev/docs/resource-limits)
+
+**Extension** —
+[Custom Bindings](https://agentos-sdk.dev/docs/bindings) ·
+[Browser Automation](https://agentos-sdk.dev/docs/browser) ·
+[External Sandboxes](https://agentos-sdk.dev/docs/sandboxes)
+
+**Reference** —
+[Deploy](https://agentos-sdk.dev/docs/deployment) ·
+[Custom Software](https://agentos-sdk.dev/docs/custom-software/definition)
+
+**Architecture** —
+[Overview](https://agentos-sdk.dev/docs/architecture) ·
+[Security Model](https://agentos-sdk.dev/docs/security-model) ·
+[Limitations](https://agentos-sdk.dev/docs/limitations)
+
+**More** —
+[Sessions & Transcripts](https://agentos-sdk.dev/docs/sessions) ·
+[Approvals](https://agentos-sdk.dev/docs/approvals) ·
+[Models & Credentials](https://agentos-sdk.dev/docs/models-and-credentials) ·
+[Authentication](https://agentos-sdk.dev/docs/authentication) ·
+[Persistence & Sleep](https://agentos-sdk.dev/docs/persistence) ·
+[Direct VM API](https://agentos-sdk.dev/docs/core) ·
+[Debugging](https://agentos-sdk.dev/docs/debugging)
+
+## Deploy
+
+- **Library** — `npm install` and run in your process. No servers. [Quickstart](https://agentos-sdk.dev/docs/quickstart)
+- **Rivet Cloud** — managed agentOS with BYOC support. [Dashboard](https://dashboard.rivet.dev)
+- **Self-host** — Kubernetes, VMs, or bare metal. [Deployment docs](https://agentos-sdk.dev/docs/deployment)
 
 ## License