@evolvingmachines/evolve 0.0.55-project-sable.20260916.db0bc0bb → 0.0.56

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolvingmachines/evolve",
-  "version": "0.0.55-project-sable.20260916.db0bc0bb",
+  "version": "0.0.56",
   "keywords": [
     "ai",
     "agents",
@@ -33,8 +33,6 @@
     "dist",
     "LICENSE",
     "spec",
-    "docs-evals",
-    "docs-agents",
     "skills",
     "hosted-error-codes.json",
     "harness-capabilities.json"
@@ -131,9 +129,9 @@
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "^0.5.1",
-    "@evolvingmachines/daytona": "0.0.55-project-sable.20260916.db0bc0bb",
-    "@evolvingmachines/e2b": "0.0.55-project-sable.20260916.db0bc0bb",
-    "@evolvingmachines/modal": "0.0.55-project-sable.20260916.db0bc0bb",
+    "@evolvingmachines/daytona": "0.0.56",
+    "@evolvingmachines/e2b": "0.0.56",
+    "@evolvingmachines/modal": "0.0.56",
     "ajv": "^8.17.1",
     "p-map": "^7.0.2",
     "smol-toml": "^1.7.0",

package/skills/evolve/SKILL.md

@@ -10,6 +10,8 @@ Hosted evals and the SDK, from the `evolve` command.
 
 Install: `npm i -g @evolvingmachines/evolve`, then `export EVOLVE_API_KEY=<your key>` (create a key at https://dashboard.evolvingmachines.ai/api-keys).
 
+Python SDK: `pip install evolvingmachines-evolve` (`import evolve`). The manual still comes from the `evolve` command.
+
 ## Start here
 
 This file is a pointer, not the manual. The manual ships inside the CLI and always matches the installed version. Before running any `evolve` command, load it:
@@ -25,15 +27,14 @@ Read the index first, then the page for your topic, then write the command. Ever
 ## The other skills
 
 ```bash
-evolve skills get agents           # the SDK: run agents (Claude, Codex, Gemini, ...) in sandboxes from TypeScript or Python
 evolve skills get create-task      # write a new task in the Harbor format, verifier included
 evolve skills get rewardkit        # write a task's verifier with Reward Kit
 evolve skills get create-adapter   # convert an existing benchmark into a folder of Harbor-format tasks
 evolve skills get publish          # publish a dataset of tasks, or upload a job you ran elsewhere
 ```
 
-`evolve skills list` names everything the installed version serves; `--full` on any skill adds its pages.
+`evolve skills list` names everything the installed version serves; `--full` on any skill adds its pages. The SDK skill (run agents in sandboxes from TypeScript or Python) is not served by the command; install it from the repository: `npx skills add evolving-machines-lab/evolve --skill evolve-agents`.
 
 ## Inside the evolve repository
 
-An agent working in a checkout of https://github.com/evolving-machines-lab/evolve reads the same content directly: `docs-evals/SKILL.md` (the evals index; the pages sit beside it), `docs-agents/SKILL.md`, and `skills/<name>/SKILL.md` for the others; nothing needs to be installed.
+An agent working in a checkout of https://github.com/evolving-machines-lab/evolve reads the same content directly from `skills/<name>/SKILL.md` (`evolve-evals` is the evals index, its pages under `references/`); nothing needs to be installed.

package/skills/evolve-evals/SKILL.md

@@ -0,0 +1,112 @@
+---
+# Generated by scripts/generate-skills.ts from docs-evals/. Do not edit; edit the source and run npm run generate:skills.
+name: evolve-evals
+description: "Evolve hosted evals: run any model on any agent harness against datasets of Harbor-format tasks, in cloud sandboxes, from the evolve CLI and the TypeScript and Python SDKs. Use when the user wants to: (1) start, watch, or read a hosted eval job (evolve run, evolve job, jobs()), (2) browse the dataset catalog or publish their own dataset (evolve dataset), (3) check task quality (evolve check) or analyze trial traces (evolve analyze), (4) inspect or download trials, artifacts and traces (evolve trial, trials()), (5) register their own agent, mount skills, attach secrets, or choose models and sandbox providers, (6) upload a job run elsewhere (evolve upload), (7) use the dashboard's jobs, datasets, checks, traces and trial viewer pages. For running agents in sandboxes from code (the SDK's run(), Swarm, Pipeline) install the SDK skill: `npx skills add evolving-machines-lab/evolve --skill evolve-agents`."
+metadata:
+  internal: true
+---
+
+# Evolve hosted evals
+
+Hosted evaluation for agents: datasets of Harbor-format tasks, jobs that run any model on any agent harness against them in cloud sandboxes, and the trials, checks and analyses they produce — from the `evolve` CLI and the TypeScript and Python SDKs.
+
+The pages under `references/` are the documentation site's pages, byte for byte, at the site's paths: a site link to `/core-concepts/tasks` is `references/core-concepts/tasks.mdx`, and `evolve skills get evals core-concepts/tasks` prints it. An `import` of `/snippets/<file>` is `references/snippets/<file>`.
+
+## How to use this skill
+
+1. Find the topic in the index below and read that page before writing any command or code: `evolve skills get evals <page>` prints it, the page named by its site path; `evolve skills get evals --full` prints every page.
+2. Every CLI verb is documented from its own `--help`; run `evolve <verb> --help` to confirm the flags of the installed version.
+3. Every command and every SDK client reads `EVOLVE_API_KEY`; the Installation page says where the key comes from.
+
+## Topic index
+
+## Docs
+
+### Getting started
+
+| Page | What it covers |
+| --- | --- |
+| [Evolve documentation](references/index.mdx) | Environment-driven agent evaluations: any model, any harness, any sandbox, one API key. Every task versioned and checked, every trajectory analyzed. |
+| [Installation](references/getting-started/installation.mdx) | Install the evolve command and the SDKs, and set your API key. |
+| [Quick start](references/getting-started/quick-start.mdx) | Start your first job, watch it run, and download a trial. |
+
+### Core concepts
+
+| Page | What it covers |
+| --- | --- |
+| [Core concepts](references/core-concepts/index.mdx) | How a dataset becomes trials, rewards, analyses and results. |
+| [Tasks](references/core-concepts/tasks.mdx) | The task format: one directory with an instruction, an environment, a verifier, and an optional reference solution. |
+| [Datasets](references/core-concepts/datasets.mdx) | The catalog, and publishing your own dataset. |
+| [Jobs](references/core-concepts/jobs.mdx) | Start a job, watch it, read its results, and derive new jobs from it. |
+| [Trials](references/core-concepts/trials.mdx) | One agent's attempt at one task: its record, its trace, and its artifacts. |
+| [Trial outputs](references/core-concepts/trial-outputs.mdx) | What a finished trial gives you, file by file, and in which formats. |
+| [Agents](references/core-concepts/agents.mdx) | The built-in harnesses, how to configure an arm, and how to register your own agent. |
+| [Models](references/core-concepts/models.mdx) | How a model is named on -m, and why one API key covers every provider. |
+| [Sandboxes](references/core-concepts/sandboxes.mdx) | Where trials run: e2b, daytona, or modal. |
+| [Analyze](references/core-concepts/analyze.mdx) | Judge every trial's trace against a rubric, on the platform. |
+| [Check](references/core-concepts/check.mdx) | Check the quality of tasks against a rubric before you spend a job on them. |
+| [Skills](references/core-concepts/skills.mdx) | Mount skills into every agent run, from a git source or from your uploads. |
+| [Secrets](references/core-concepts/secrets.mdx) | Store env secrets once and attach them to jobs by name. |
+| [Upload a job](references/core-concepts/upload.mdx) | Bring a job you ran elsewhere onto the platform as a finished job. |
+
+### Dashboard
+
+| Page | What it covers |
+| --- | --- |
+| [Datasets](references/dashboard/datasets.mdx) | Browse the catalog, and each dataset's tasks and versions, in the dashboard. |
+| [Jobs](references/dashboard/jobs.mdx) | Start a job from the browser, follow it, and read its results. |
+| [Trial viewer](references/dashboard/trial-viewer.mdx) | Read one trial's trace event by event, its tool calls, its spend, and download its artifacts. |
+| [Checks](references/dashboard/checks.mdx) | Read a job's task quality checks in the dashboard. |
+| [Traces](references/dashboard/traces.mdx) | Every recorded run in one list. |
+
+### SDK
+
+| Page | What it covers |
+| --- | --- |
+| [TypeScript SDK](references/sdk/typescript.mdx) | Start a job, wait for it, read the result, and download it from TypeScript. |
+| [Python SDK](references/sdk/python.mdx) | Start a job, wait for it, read the result, and download it from Python. |
+
+## CLI reference
+
+### The evolve command
+
+| Page | What it covers |
+| --- | --- |
+| [CLI reference](references/cli-reference/index.mdx) | Every verb of the evolve command, from its own help output. |
+| [evolve run](references/cli-reference/run.mdx) | Start a job, and optionally follow it to the end. |
+| [evolve analyze](references/cli-reference/analyze.mdx) | Analyze a finished job's trial traces against a rubric, on the platform. |
+| [evolve check](references/cli-reference/check.mdx) | Check task quality against a rubric, and read checks back. |
+| [evolve upload](references/cli-reference/upload.mdx) | Upload a job directory as a finished job. |
+
+### Command groups
+
+| Page | What it covers |
+| --- | --- |
+| [evolve job](references/cli-reference/job.mdx) | Start, follow, and derive jobs. |
+| [evolve trial](references/cli-reference/trial.mdx) | Inspect, download, and act on single trials. |
+| [evolve analysis](references/cli-reference/analysis.mdx) | List, inspect, and download trace-analysis runs. |
+| [evolve dataset](references/cli-reference/dataset.mdx) | Browse and publish the dataset catalog. |
+| [evolve skill](references/cli-reference/skill.mdx) | Upload and manage platform-stored skills. |
+| [evolve skills](references/cli-reference/skills.mdx) | The skills the CLI serves to coding agents. |
+| [evolve agent](references/cli-reference/agent.mdx) | Register and manage your own agents. |
+| [evolve auth](references/cli-reference/auth.mdx) | Identity, API keys, and your organizations. |
+| [evolve secrets](references/cli-reference/secrets.mdx) | Store and manage env secrets. Values are write-only; reads return metadata. |
+
+## SDK reference
+
+### Clients
+
+| Page | What it covers |
+| --- | --- |
+| [Clients](references/sdk-reference/index.mdx) | How the hosted clients are built and configured. |
+| [jobs](references/sdk-reference/jobs.mdx) | Start, follow, and derive jobs. |
+| [trials](references/sdk-reference/trials.mdx) | Read, download, and act on single trials. |
+| [datasets](references/sdk-reference/datasets.mdx) | The catalog: list, read, publish, download, activate, delete. |
+| [analyses](references/sdk-reference/analyses.mdx) | Read trace-analysis runs. |
+| [checks](references/sdk-reference/checks.mdx) | Start and read task quality checks. |
+| [skills](references/sdk-reference/skills.mdx) | Upload and manage platform-stored skills. |
+| [agents](references/sdk-reference/agents.mdx) | Register and manage your own agents. |
+| [auth and orgs](references/sdk-reference/auth.mdx) | Who you are, and your organizations. |
+| [meta](references/sdk-reference/meta.mdx) | The platform's capability document, no key needed. |
+| [Types](references/sdk-reference/types.mdx) | Every field of the objects the clients return: name, type, meaning, and when it is null. |
+| [Errors](references/sdk-reference/errors.mdx) | The error class every refused request raises, and every code it can carry. |

package/{docs-evals → skills/evolve-evals/references}/cli-reference/run.mdx

@@ -15,7 +15,7 @@ Start a job. `evolve run` is the short form of `evolve job start`, and both take
 evolve run \
   -d terminal-bench-4@4.0 \
   -a codex \
-  -m gpt-5.5 \
+  -m gpt-6-astra \
   -k 2 \
   -l 5 \
   --watch

package/{docs-evals → skills/evolve-evals/references}/cli-reference/skills.mdx

@@ -9,7 +9,7 @@ import GlobalOptions from '/snippets/global-options.mdx';
 evolve skills <command> [options]
 ```
 
-The skills ship with the CLI and match its version. `skills get evals` is the index of these docs and `skills get evals <page>` one page of them. The `evolve` pointer skill that `skills install` writes is served but never listed. `EVOLVE_SKILLS_DIR` names another checkout or package root to serve.
+The skills ship with the CLI and match its version. `skills get evals` is the index of these docs and `skills get evals <page>` one page of them. The `evolve` pointer skill that `skills install` writes is served but never listed. The SDK skill is not served; it installs from the repository with `npx skills add evolving-machines-lab/evolve --skill evolve-agents`. `EVOLVE_SKILLS_DIR` names another skills directory to serve.
 
 ## skills list
 
@@ -26,10 +26,10 @@ evolve skills get <name> [name...]
 evolve skills get <name> <page>
 ```
 
-Print one or more skills, or one page. A second word that is not a skill name is a page of the first skill: this site's own path without the suffix (`core-concepts/tasks`), or a file under `references/` for a task-authoring skill.
+Print one or more skills, or one page. A second word that is not a skill name is a page of the first skill: its path under `references/` without the suffix, as this site spells it (`core-concepts/tasks`).
 
 <ParamField path="--full">
-  Also print every page of the skill (a docs folder's pages, or `references/` and `templates/`), each behind a `--- <path> ---` line.
+  Also print every file under `references/` and `templates/`, each behind a `--- <path> ---` line.
 </ParamField>
 
 <ParamField path="--all">
@@ -48,7 +48,7 @@ evolve skills get create-task --full
 evolve skills path [name]
 ```
 
-Print the root the skills are served from, or one skill's folder.
+Print the skills directory, or one skill's folder.
 
 ## skills install
 

package/{docs-evals → skills/evolve-evals/references}/core-concepts/agents.mdx

@@ -34,7 +34,7 @@ These flags apply to every arm of the job.
 evolve run \
   -d terminal-bench-4@4.0 \
   -a codex \
-  -m gpt-5.5 \
+  -m gpt-6-astra \
   -l 5 \
   --effort high \
   --preset no-internet \
@@ -56,7 +56,7 @@ evolve agent add acme-cli --install-script ./install.sh --run "acme-cli --headle
 evolve run \
   -d terminal-bench-4@4.0 \
   -a acme-cli \
-  -m gpt-5.5 \
+  -m gpt-6-astra \
   -l 5 \
   --watch
 ```

package/{docs-evals → skills/evolve-evals/references}/core-concepts/analyze.mdx

@@ -15,7 +15,7 @@ Or arm it when you start the job, so each trial is analyzed the moment it settle
 evolve run \
   -d terminal-bench-4@4.0 \
   -a codex \
-  -m gpt-5.5 \
+  -m gpt-6-astra \
   --analyze \
   -l 5 \
   --watch

package/{docs-evals → skills/evolve-evals/references}/core-concepts/jobs.mdx

@@ -9,7 +9,7 @@ A job runs every task of its datasets with every agent arm, a fixed number of at
 evolve run \
   -d terminal-bench-4@4.0 \
   -a codex \
-  -m gpt-5.5 \
+  -m gpt-6-astra \
   -k 2 \
   -l 5 \
   --watch
@@ -25,7 +25,7 @@ evolve run \
 evolve run \
   -d terminal-bench-4@4.0 \
   -a codex \
-  -m gpt-5.5 \
+  -m gpt-6-astra \
   -i 'auth-*' \
   -x 'auth-legacy' \
   -l 20 \
@@ -119,7 +119,7 @@ datasets:
     version: "1.0"
 agents:
   - name: codex
-    model_name: gpt-5.5
+    model_name: gpt-6-astra
   - name: claude
     model_name: fable
 n_attempts: 2

package/{docs-evals → skills/evolve-evals/references}/core-concepts/models.mdx

@@ -15,7 +15,7 @@ evolve run \
 evolve run \
   -d terminal-bench-4@4.0 \
   -a codex \
-  -m gpt-5.5 \
+  -m gpt-6-astra \
   -m gpt-5.6-terra \
   -l 5 \
   --watch

package/{docs-evals → skills/evolve-evals/references}/core-concepts/sandboxes.mdx

@@ -13,7 +13,7 @@ Every trial runs in its own sandbox on one of three providers. Pick the provider
 evolve run \
   -d terminal-bench-4@4.0 \
   -a codex \
-  -m gpt-5.5 \
+  -m gpt-6-astra \
   -e modal \
   -l 5 \
   --watch
@@ -34,7 +34,7 @@ Three refusals appear in the verdicts: multi-container tasks run on `e2b` and `d
 | Provider | Max vCPUs | Max memory | Disk |
 | --- | --- | --- | --- |
 | `e2b` | 8 | 8192 MB | fixed, 20 GB |
-| `daytona` | 4 | 8192 MB | sized per task, up to 10 GB |
+| `daytona` | 4 | 8192 MB | sized per task, up to 25 GB |
 | `modal` | 16 | 32768 MB | fixed, 512 GB |
 
 Two limits show only when the sandbox is created, as an `INFRASTRUCTURE_ERROR` with the reason in the trial's failure detail. On `daytona` an `allowlist` holds one kind of entry: IP addresses and CIDRs for a single-container task (at most 10), hostnames for a multi-container task (at most 20, `*.` covering a domain). `e2b` and `modal` take both kinds.

package/{docs-evals → skills/evolve-evals/references}/core-concepts/secrets.mdx

@@ -24,7 +24,7 @@ evolve secrets delete GITHUB_TOKEN --label staging
 evolve run \
   -d terminal-bench-4@4.0 \
   -a codex \
-  -m gpt-5.5 \
+  -m gpt-6-astra \
   --secret GITHUB_TOKEN \
   -l 5 \
   --watch

package/{docs-evals → skills/evolve-evals/references}/core-concepts/trial-outputs.mdx

@@ -74,7 +74,7 @@ Its top-level fields are `schema_version`, `agent` with the harness's name, vers
 ```json
 {
   "schema_version": "ATIF-v1.7",
-  "agent": {"name": "codex", "version": "0.31.0", "model_name": "gpt-5.5"},
+  "agent": {"name": "codex", "version": "0.31.0", "model_name": "gpt-6-astra"},
   "steps": [
     {"step_id": 1, "source": "user", "message": "Create hello.txt containing Hello."},
     {

package/{docs-evals → skills/evolve-evals/references}/getting-started/quick-start.mdx

@@ -34,7 +34,7 @@ This page takes you from an empty terminal to a downloaded trial: one API key, a
     evolve run \
       -d terminal-bench-4@4.0 \
       -a codex \
-      -m gpt-5.5 \
+      -m gpt-6-astra \
       -l 5 \
       --watch
     ```

package/{docs-evals → skills/evolve-evals/references}/index.mdx

@@ -15,7 +15,7 @@ export EVOLVE_API_KEY="<your key>"   # from https://dashboard.evolvingmachines.a
 evolve run \
   -d terminal-bench-4@4.0 \
   -a codex \
-  -m gpt-5.5 \
+  -m gpt-6-astra \
   -l 5 \
   --watch
 ```

package/{docs-evals → skills/evolve-evals/references}/sdk/python.mdx

@@ -23,7 +23,7 @@ evals = jobs()
 ```python
 job = await evals.start(
     datasets=[{"name": "terminal-bench-4", "version": "4.0", "n_tasks": 5}],
-    agents=[{"name": "codex", "model_name": "gpt-5.5"}],
+    agents=[{"name": "codex", "model_name": "gpt-6-astra"}],
     n_attempts=1,
     n_concurrent_trials=4,
     max_trial_spend_usd=25,

package/{docs-evals → skills/evolve-evals/references}/sdk/typescript.mdx

@@ -20,7 +20,7 @@ const evals = jobs();
 ```ts
 const job = await evals.start({
   datasets: [{ name: "terminal-bench-4", version: "4.0", n_tasks: 5 }],
-  agents: [{ name: "codex", model_name: "gpt-5.5" }],
+  agents: [{ name: "codex", model_name: "gpt-6-astra" }],
   n_attempts: 1,
   n_concurrent_trials: 4,
   max_trial_spend_usd: 25,

package/{docs-evals → skills/evolve-evals/references}/sdk-reference/errors.mdx

@@ -24,7 +24,7 @@ A refused request raises one class. Branch on its `code`, never on the message.
 
     ```ts
     try {
-      await jobs().start({ datasets: [{ name: "terminal-bench-4" }], agents: [{ name: "codex", model_name: "gpt-5.5" }], sandbox_provider: "modal" });
+      await jobs().start({ datasets: [{ name: "terminal-bench-4" }], agents: [{ name: "codex", model_name: "gpt-6-astra" }], sandbox_provider: "modal" });
     } catch (err) {
       if (err instanceof EvolveApiError && err.code === "provider_unsupported") {
         const { refused_tasks } = err.details as { refused_tasks: { task_name: string; reason: string }[] };
@@ -50,7 +50,7 @@ A refused request raises one class. Branch on its `code`, never on the message.
 
     ```python
     try:
-        await jobs().start(datasets=[{"name": "terminal-bench-4"}], agents=[{"name": "codex", "model_name": "gpt-5.5"}], sandbox_provider="modal")
+        await jobs().start(datasets=[{"name": "terminal-bench-4"}], agents=[{"name": "codex", "model_name": "gpt-6-astra"}], sandbox_provider="modal")
     except EvolveAPIError as err:
         if err.code == "provider_unsupported":
             refused = (err.details or {}).get("refused_tasks", [])

package/{docs-evals → skills/evolve-evals/references}/sdk-reference/jobs.mdx

@@ -23,7 +23,7 @@ description: "Start, follow, and derive jobs."
     ```ts
     const job = await jobs().start({
       datasets: [{ name: "terminal-bench-4", version: "4.0", n_tasks: 5 }],
-      agents: [{ name: "codex", model_name: "gpt-5.5" }],
+      agents: [{ name: "codex", model_name: "gpt-6-astra" }],
     });
     ```
   </Tab>
@@ -57,7 +57,7 @@ description: "Start, follow, and derive jobs."
     ```python
     job = await jobs().start(
         datasets=[{"name": "terminal-bench-4", "version": "4.0", "n_tasks": 5}],
-        agents=[{"name": "codex", "model_name": "gpt-5.5"}],
+        agents=[{"name": "codex", "model_name": "gpt-6-astra"}],
     )
     ```
   </Tab>

package/docs-agents/SKILL.md

@@ -1,138 +0,0 @@
----
-# Generated by scripts/generate-skills.ts from docs-agents/SKILL.source.md. Do not edit; edit the source and run npm run generate:skills.
-name: docs-agents
-description: "Evolve SDK development for TypeScript and Python. Use when building applications with Evolve to run AI agents (Claude, Codex, Gemini, Qwen, Kimi, OpenCode, Droid) in secure sandboxes. Triggers: (1) Creating Evolve applications, (2) Configuring agents with skills, Integrations, MCP servers, (3) Using Swarm abstractions (map, filter, reduce, bestOf/best_of, verify), (4) Building Pipelines, (5) Structured output with schemas, (6) Session management, streaming, observability, (7) Checkpointing, storage & StorageClient, (8) Cost tracking (per-run and per-session spend), (9) Historical sessions & trace download via sessions() client. For hosted evals (datasets, jobs, trials, checks, analyses, the evolve CLI) read `evolve skills get evals`."
-metadata:
-  internal: true
----
-
-# Evolve SDK
-
-Build applications that run CLI agents in secure cloud sandboxes.
-
-**Repo:** https://github.com/evolving-machines-lab/evolve
-
-Hosted evals — datasets, jobs, trials, checks, analyses and the `evolve` CLI — are `evolve skills get evals`, not this skill.
-
-## Language Detection
-
-Determine the language from (in priority order):
-
-1. **User specification** — if the user states a language, use it
-2. **Project signals** — imports, file extensions, package.json vs pyproject.toml
-3. **Ask** — if ambiguous, ask the user
-
-- **TypeScript** (`@evolvingmachines/evolve`) — read from [typescript/](typescript/)
-- **Python** (`evolvingmachines-evolve`) — read from [python/](python/)
-
-## Required Reading
-
-Always read these three references **for the detected language** before writing any Evolve code:
-
-**TypeScript:**
-- [01-getting-started.md](typescript/01-getting-started.md) — Installation, authentication (Gateway, managed BYO provider keys, direct provider-key mode), core lifecycle, streaming basics, agent reference table
-- [02-configuration.md](typescript/02-configuration.md) — Sandbox providers, full builder API, agent skills catalog, Managed integrations, MCP servers
-- [03-runtime.md](typescript/03-runtime.md) — run(), executeCommand(), upload/download files, session controls, workspace layout, structured output, session management, storage & checkpointing, StorageClient, sessions() client, cost tracking, observability, error handling
-
-**Python:**
-- [01-getting-started.md](python/01-getting-started.md) — Installation, authentication (Gateway, managed BYO provider keys, direct provider-key mode), core lifecycle, streaming basics, agent reference table
-- [02-configuration.md](python/02-configuration.md) — Sandbox providers, full constructor API, agent skills catalog, Managed integrations, MCP servers
-- [03-runtime.md](python/03-runtime.md) — run(), execute_command(), upload/download files, session controls, workspace layout, structured output, session management, storage & checkpointing, StorageClient, sessions() client, cost tracking, observability, error handling
-
-## Critical Constraints
-
-- **Model names** — Only use exact names from the Agent Reference table. Do not invent or guess model identifiers.
-  - [TS](typescript/01-getting-started.md#agent-reference) | [PY](python/01-getting-started.md#agent-reference)
-- **Cleanup** — Always call `kill()` when done. Sandboxes bill until destroyed.
-  - [TS](typescript/01-getting-started.md#core-lifecycle) | [PY](python/01-getting-started.md#core-lifecycle)
-
-## Additional References
-
-Read on demand when the user's task requires them:
-
-| When to read | TypeScript | Python |
-|-------------|-----------|--------|
-| Building a UI, handling real-time events | [04-streaming.md](typescript/04-streaming.md) | [04-streaming.md](python/04-streaming.md) |
-| Parallel agents (map/filter/reduce/bestOf/verify), Pipeline chaining | [05-swarm-pipeline.md](typescript/05-swarm-pipeline.md) | [05-swarm-pipeline.md](python/05-swarm-pipeline.md) |
-
-## Topic Index
-
-### Getting Started
-
-| Topic | TypeScript | Python |
-|-------|-----------|--------|
-| Installation & requirements | [TS](typescript/01-getting-started.md#installation) | [PY](python/01-getting-started.md#installation) |
-| Quick start (3 steps) | [TS](typescript/01-getting-started.md#quick-start) | [PY](python/01-getting-started.md#quick-start) |
-| Core lifecycle (run, output, kill) | [TS](typescript/01-getting-started.md#core-lifecycle) | [PY](python/01-getting-started.md#core-lifecycle) |
-| Streaming basics | [TS](typescript/01-getting-started.md#streaming) | [PY](python/01-getting-started.md#streaming) |
-| Gateway, managed BYO provider keys, and direct provider-key mode | [TS](typescript/01-getting-started.md#authentication) | [PY](python/01-getting-started.md#authentication) |
-| BYO subscriptions (Claude Max, Codex, Gemini) | [TS](typescript/01-getting-started.md#byo-claude-max-subscription) | [PY](python/01-getting-started.md#byo-claude-max-subscription) |
-| Supported agents, models & defaults | [TS](typescript/01-getting-started.md#agent-reference) | [PY](python/01-getting-started.md#agent-reference) |
-| Harness and model pairing (per-harness constraints) | [TS](typescript/01-getting-started.md#harness-and-model-pairing) | [PY](python/01-getting-started.md#harness-and-model-pairing) |
-
-### Configuration
-
-| Topic | TypeScript | Python |
-|-------|-----------|--------|
-| Sandbox providers (E2B, Modal, Daytona) | [TS](typescript/02-configuration.md#sandbox-providers) | [PY](python/02-configuration.md#sandbox-providers) |
-| Provider auto-resolution from env | [TS](typescript/02-configuration.md#auto-resolution) | [PY](python/02-configuration.md#auto-resolution) |
-| Sandbox create options (image, network, user, homeDir) | [TS](typescript/02-configuration.md#sandbox-create-options) | [PY](python/02-configuration.md#sandbox-create-options) |
-| Workspace modes (knowledge / swe) | [TS](typescript/02-configuration.md#workspace-modes) | [PY](python/02-configuration.md#workspace-modes) |
-| Full builder/constructor API | [TS](typescript/02-configuration.md#evolve-instance) | [PY](python/02-configuration.md#evolve-instance) |
-| Browser automation guide (setup, live view, replay) | [TS](typescript/02-configuration.md#browser-automation) | [PY](python/02-configuration.md#browser-automation) |
-| Browser credentials (saved website logins) | [TS](typescript/02-configuration.md#browser-credentials) | [PY](python/02-configuration.md#browser-credentials) |
-| Agent plugins/extensions | [TS](typescript/02-configuration.md#agent-plugins) | [PY](python/02-configuration.md#agent-plugins) |
-| Agent skills catalog | [TS](typescript/02-configuration.md#agent-skills) | [PY](python/02-configuration.md#agent-skills) |
-| Managed secrets (Dashboard-stored env secrets) | [TS](typescript/02-configuration.md#managed-secrets) | [PY](python/02-configuration.md#managed-secrets) |
-| Managed integrations (auth paths, tool filtering, types) | [TS](typescript/02-configuration.md#managed-integrations) | [PY](python/02-configuration.md#managed-integrations) |
-| MCP server config (STDIO / HTTP / SSE) | [TS](typescript/02-configuration.md#evolve-instance) | [PY](python/02-configuration.md#evolve-instance) |
-
-### Runtime
-
-| Topic | TypeScript | Python |
-|-------|-----------|--------|
-| run() options (timeout, background, checkpoint) | [TS](typescript/03-runtime.md#run) | [PY](python/03-runtime.md#run) |
-| executeCommand() / execute_command() | [TS](typescript/03-runtime.md#executecommand) | [PY](python/03-runtime.md#execute_command) |
-| Upload files to sandbox | [TS](typescript/03-runtime.md) | [PY](python/03-runtime.md) |
-| Download output files | [TS](typescript/03-runtime.md) | [PY](python/03-runtime.md) |
-| Session controls (interrupt, pause, resume, kill) | [TS](typescript/03-runtime.md#session-controls) | [PY](python/03-runtime.md#session-controls) |
-| Port forwarding | [TS](typescript/03-runtime.md#gethost) | [PY](python/03-runtime.md#get_host) |
-| Workspace filesystem layout | [TS](typescript/03-runtime.md) | [PY](python/03-runtime.md) |
-| Structured output (Zod / Pydantic / JSON Schema) | [TS](typescript/03-runtime.md#structured-output) | [PY](python/03-runtime.md#structured-output) |
-| Multi-turn conversations | [TS](typescript/03-runtime.md#session-management) | [PY](python/03-runtime.md#session-management) |
-| Pause, resume, reconnect, switch sandboxes | [TS](typescript/03-runtime.md#session-management) | [PY](python/03-runtime.md#session-management) |
-| Storage & checkpointing (gateway mode) | [TS](typescript/03-runtime.md#storage--checkpointing) | [PY](python/03-runtime.md#storage--checkpointing) |
-| StorageClient (list, get, download checkpoints) | [TS](typescript/03-runtime.md#listing--browsing-checkpoints) | [PY](python/03-runtime.md#listing--browsing-checkpoints) |
-| Checkpoint lineage & restore | [TS](typescript/03-runtime.md#checkpoint-lineage) | [PY](python/03-runtime.md#checkpoint-lineage) |
-| Historical sessions & trace download | [TS](typescript/03-runtime.md#historical-sessions--trace-download) | [PY](python/03-runtime.md#historical-sessions--trace-download) |
-| Cost tracking (per-run & per-session spend) | [TS](typescript/03-runtime.md#cost-tracking) | [PY](python/03-runtime.md#cost-tracking) |
-| Observability (dashboard + local logs) | [TS](typescript/03-runtime.md#observability) | [PY](python/03-runtime.md#observability) |
-| Error handling | [TS](typescript/03-runtime.md#error-handling) | [PY](python/03-runtime.md#error-handling) |
-
-### Streaming
-
-| Topic | TypeScript | Python |
-|-------|-----------|--------|
-| Event listeners (content, lifecycle, stdout, stderr) | [TS](typescript/04-streaming.md#event-listeners) | [PY](python/04-streaming.md#event-listeners) |
-| LifecycleEvent & LifecycleReason | [TS](typescript/04-streaming.md#lifecycleevent) | [PY](python/04-streaming.md#lifecycleevent-typeddict-shape) |
-| OutputEvent & SessionUpdate types | [TS](typescript/04-streaming.md#sessionupdate-types) | [PY](python/04-streaming.md#event-types-summary) |
-| Tool events (ToolCall, ToolCallUpdate, ToolKind) | [TS](typescript/04-streaming.md#tool-events) | [PY](python/04-streaming.md#toolkind-reference) |
-| Browser lifecycle event fields | [TS](typescript/04-streaming.md#browser-automation-streaming) | [PY](python/04-streaming.md#browser-automation-streaming) |
-| UI integration example | [TS](typescript/04-streaming.md#ui-integration-example) | [PY](python/04-streaming.md#ui-integration-example) |
-
-### Swarm & Pipeline
-
-| Topic | TypeScript | Python |
-|-------|-----------|--------|
-| Swarm setup (config, concurrency, retry) | [TS](typescript/05-swarm-pipeline.md) | [PY](python/05-swarm-pipeline.md) |
-| Input types (FileMap, folders) | [TS](typescript/05-swarm-pipeline.md#input-types) | [PY](python/05-swarm-pipeline.md#input-types) |
-| bestOf / best_of (N candidates + judge) | [TS](typescript/05-swarm-pipeline.md#bestof) | [PY](python/05-swarm-pipeline.md#best_of) |
-| map (parallel processing) | [TS](typescript/05-swarm-pipeline.md#map) | [PY](python/05-swarm-pipeline.md#map) |
-| filter (evaluate + threshold) | [TS](typescript/05-swarm-pipeline.md#filter) | [PY](python/05-swarm-pipeline.md#filter) |
-| reduce (synthesize many to one) | [TS](typescript/05-swarm-pipeline.md#reduce) | [PY](python/05-swarm-pipeline.md#reduce) |
-| verify (quality gate with feedback loop) | [TS](typescript/05-swarm-pipeline.md#verify-quality-gate) | [PY](python/05-swarm-pipeline.md#verify-quality-gate) |
-| Result types (SwarmResult, ReduceResult, BestOfResult) | [TS](typescript/05-swarm-pipeline.md#result-types) | [PY](python/05-swarm-pipeline.md#result-types) |
-| Chaining operations | [TS](typescript/05-swarm-pipeline.md#chaining-operations) | [PY](python/05-swarm-pipeline.md#chaining-operations) |
-| Pipeline (fluent chaining, events, terminal) | [TS](typescript/05-swarm-pipeline.md#pipeline) | [PY](python/05-swarm-pipeline.md#pipeline) |
-
-The installed CLI serves the current version of this skill: `evolve skills get agents --full`.

package/docs-agents/index.md

@@ -1,81 +0,0 @@
-## Documentation
-
-- [TypeScript SDK](./typescript/)
-- [Python SDK](./python/)
-- [Cookbooks](https://github.com/evolving-machines-lab/evolve/tree/main/cookbooks)
-- [Changelog](https://github.com/evolving-machines-lab/evolve/blob/main/CHANGELOG.md)
-
-The SDK has two halves. One runs a CLI agent in a sandbox you control — that is the quickstart below. The other scores agents against datasets of tasks on Evolve's own infrastructure: you start a job, and read back per-trial rewards. Hosted evals are documented at https://docs.evolvingmachines.ai: `jobs()`, `datasets()`, and the `evolve` CLI.
-
-## Get Started
-
-### 1. Install the SDK
-
-```bash
-npm install @evolvingmachines/evolve    # TypeScript
-pip install evolvingmachines-evolve     # Python
-```
-
-**Note:** Requires [Node.js 18+](https://nodejs.org/) (the Python SDK uses a lightweight Node.js bridge).
-
-### 2. Run your first agent
-
-Get your Evolve API key at [dashboard.evolvingmachines.ai](https://dashboard.evolvingmachines.ai) ([see 3. below](#evolve-gateway)):
-```bash
-# .env - Gateway
-EVOLVE_API_KEY=sk-...
-```
-
-To bring your own provider billing while keeping gateway features, save an Anthropic or OpenAI key in Dashboard → Secrets → BYO Provider Keys — those are the two providers this route serves today. Your app still uses only `EVOLVE_API_KEY`.
-
-For fully local direct provider keys:
-```bash
-# .env - Direct Provider Key Mode (local BYOK)
-ANTHROPIC_API_KEY=sk-ant-...         # or CLAUDE_CODE_OAUTH_TOKEN (Claude Max), OPENAI_API_KEY, GEMINI_API_KEY
-E2B_API_KEY=e2b_...                  # sandbox provider, get at https://e2b.dev
-```
-
-Then run:
-```typescript
-import { Evolve } from "@evolvingmachines/evolve";
-
-const evolve = new Evolve();  // auto-resolves env variables
-await evolve.run({ prompt: "Create hello.txt with 'Hello World'" });
-const output = await evolve.getOutputFiles();  // output.files
-```
-
-```python
-from evolve import Evolve
-
-evolve = Evolve()  # auto-resolves env variables
-await evolve.run(prompt="Create hello.txt with 'Hello World'")
-output = await evolve.get_output_files()  # output.files
-```
-
-<a id="evolve-gateway"></a>
-
-### 3. Unlock full power with Evolve API key
-
-Sign up at [dashboard.evolvingmachines.ai](https://dashboard.evolvingmachines.ai/) and get your **Evolve API key** for:
-- Agent execution traces, observability and analytics
-- Centralized billing across all providers
-- Mix any model with any CLI agent
-- $10 FREE CREDITS, no CC required
-
-### 4. Learn more
-
-Check out the [documentation](https://github.com/evolving-machines-lab/evolve/tree/main/docs) and [cookbooks](https://github.com/evolving-machines-lab/evolve/tree/main/cookbooks).
-
-## Support + Talk with Founders
-
-- [Community Discord](https://discord.gg/Q36D8dGyNF)
-- [Schedule Demo](https://cal.com/brando-magnani/evolve-1-1-onboarding-chat)
-- Email: [brandomagnani@evolvingmachines.ai](mailto:brandomagnani@evolvingmachines.ai)
-
-## Reporting Bugs
-
-We welcome your feedback. File a [GitHub issue](https://github.com/evolving-machines-lab/evolve/issues) to report bugs or request features.
-
-## License
-
-See the [LICENSE](https://github.com/evolving-machines-lab/evolve/blob/main/LICENSE) file for full terms and conditions.