Split kit spec reference and update kit field renames

content/manuals/ai/sandboxes/customize/_index.md

@@ -40,12 +40,12 @@ dependencies — anything you'd rather not reinstall on every sandbox start.
 
 A kit is a YAML artifact applied at sandbox creation. The kit can run
 install commands, drop files into the sandbox, declare network and
-credential rules, and (for agent kits) define which template image the
+credential rules, and (for sandbox kits) define which template image the
 agent runs in. Use kits for things that vary per agent or per team:
 shared linter config, project-specific install steps, credential
 injection for a service the agent talks to.
 
-Templates and kits work together. An agent kit's `agent.image` field
+Templates and kits work together. A sandbox kit's `sandbox.image` field
 points at a template: the template provides the base environment, the
 kit layers config, secrets, and runtime behavior on top. A team can ship
 one heavy template and several thin kits without rebuilding the image
@@ -58,7 +58,7 @@ each time something changes.
 | Pre-install tools and packages into a reusable base image | [Template](templates.md)                                      |
 | Capture a configured running sandbox for reuse            | [Saved template](templates.md#saving-a-sandbox-as-a-template) |
 | Add a tool, credential, or config to agent runs via YAML  | [Kit (mixin)](kits.md)                                        |
-| Define a new agent from scratch                           | [Kit (agent)](kits.md#defining-an-agent)                      |
+| Define a new agent from scratch                           | [Kit (sandbox)](kits.md#define-an-agent)                      |
 
 Templates and kits can be used together. A template bakes heavy tools into
 the image for fast sandbox startup; a kit layered on top adds per-run
@@ -67,4 +67,4 @@ credentials, config, or extra capabilities.
 ## Tutorials
 
 - [Build your own agent kit](build-an-agent.md) — step-by-step walkthrough
-  for packaging [Amp](https://ampcode.com/) as an agent kit.
+  for packaging [Amp](https://ampcode.com/) as a sandbox kit.

content/manuals/ai/sandboxes/customize/build-an-agent.md

@@ -18,8 +18,8 @@ This tutorial walks through building an agent kit for the
 [Amp](https://ampcode.com/) coding agent. Each step explains the decision
 behind a part of the spec, so you can apply the same reasoning to other agents.
 
-For reference on every field, see the [Kits](kits.md) page. This tutorial
-focuses on the journey.
+For reference on every field, see the [Kit spec reference](kit-reference.md).
+This tutorial focuses on the journey.
 
 The finished kit is also published as a runnable sample at
 [docker/sbx-kits-contrib](https://github.com/docker/sbx-kits-contrib/tree/main/amp) —
@@ -28,7 +28,7 @@ useful as a reference while you follow along.
 ## Choose a base image
 
 An agent kit needs a container image that satisfies the
-[base image requirements](kits.md#base-image-requirements): non-root
+[base image requirements](kit-reference.md#base-image-requirements): non-root
 `agent` user at UID 1000, passwordless sudo, `/home/agent/` home, and HTTP
 proxy environment variable forwarding.
 
@@ -65,32 +65,28 @@ substitutes the real key on outbound requests to the API host, so the
 secret never enters the sandbox. A later section walks through the
 specific command for storing the key.
 
-## Write the agent block
+## Write the sandbox block
 
-The `agent:` block tells the sandbox how to launch Amp when the user
+The `sandbox:` block tells the sandbox how to launch Amp when the user
 attaches.
 
 ```yaml {title="amp/spec.yaml"}
 schemaVersion: "1"
-kind: agent
+kind: sandbox
 name: amp
 displayName: Amp
 description: The frontier coding agent.
 
-agent:
+sandbox:
   image: "docker/sandbox-templates:shell-docker"
   aiFilename: AGENTS.md
-  persistence: persistent
   entrypoint:
     run: [amp, --dangerously-allow-all]
 ```
 
 - `aiFilename: AGENTS.md` tells the sandbox to create `AGENTS.md` at launch
-  and append the [`memory`](#prime-amp-with-memory) block to it. Amp reads
+  and append the [`agentContext`](#prime-amp-with-memory) block to it. Amp reads
   this file for instructions.
-- `persistence: persistent` keeps Amp's state (auth tokens, history) in a
-  named volume across sandbox restarts. Without it, you re-authenticate
-  every time.
 - `entrypoint.run` runs `amp` in "YOLO-mode" when the sandbox starts. Adjust if
   you want to pass different args on startup.
 
@@ -157,12 +153,12 @@ pick any name.
 
 ## Prime Amp with memory
 
-The `memory` field appends markdown to `AGENTS.md` at sandbox creation.
+The `agentContext` field appends markdown to `AGENTS.md` at sandbox creation.
 Use it to tell Amp about the sandbox environment so it knows the
 conventions when it starts.
 
 ```yaml
-memory: |
+agentContext: |
   ## Sandbox environment
 
   You are running inside a Docker sandbox. The workspace is mounted at
@@ -180,15 +176,14 @@ Putting it all together:
 
 ```yaml {title="amp/spec.yaml"}
 schemaVersion: "1"
-kind: agent
+kind: sandbox
 name: amp
 displayName: Amp
 description: The frontier coding agent.
 
-agent:
+sandbox:
   image: "docker/sandbox-templates:shell-docker"
   aiFilename: AGENTS.md
-  persistence: persistent
   entrypoint:
     run: [amp, --dangerously-allow-all]
 
@@ -209,7 +204,7 @@ commands:
       user: "1000"
       description: Install Amp
 
-memory: |
+agentContext: |
   ## Sandbox environment
 
   You are running inside a Docker sandbox. The workspace is mounted at
@@ -287,7 +282,7 @@ Two loops help:
 - Edit the spec and re-run `sbx run --kit ./amp/ amp` to pick up changes.
   Remove the sandbox first (`sbx rm <name>`) for a clean start.
 
-Flesh out the `memory` block as you refine how Amp should behave in the
+Flesh out the `agentContext` block as you refine how Amp should behave in the
 sandbox.
 
 ## Publish
@@ -316,7 +311,7 @@ the same decisions for your agent:
   placeholder. If it accepts the env var as-is, declare
   `environment.proxyManaged` in the kit and skip the user-side step.
 
-The rest — memory block, network-policy iteration, packaging — is the
+The rest — agent-context block, network-policy iteration, packaging — is the
 same regardless of agent.
 
 ## Remove the stored secret

content/manuals/ai/sandboxes/customize/kit-examples.md

@@ -1,7 +1,7 @@
 ---
 title: Kit examples
 linkTitle: Examples
-description: Copy-and-adapt spec.yaml snippets for common mixin and agent kit patterns — static files, install commands, background services, initFiles, Claude Code skills, and agent forks.
+description: Copy-and-adapt spec.yaml snippets for common mixin and sandbox kit patterns — static files, install commands, background services, initFiles, Claude Code skills, and agent forks.
 keywords: sandboxes, sbx, kits, mixins, examples, patterns, skills
 weight: 25
 ---
@@ -17,7 +17,7 @@ weight: 25
 Each section below shows one `spec.yaml` snippet that demonstrates a
 single kit pattern. These aren't complete, distributable kits — they're
 small, focused examples you can lift into your own kit. For the full
-spec reference, see [Kits](kits.md).
+spec reference, see [Kit spec reference](kit-reference.md).
 
 ## Drop a shared config file
 
@@ -253,23 +253,22 @@ idempotent. The heredoc pattern overwrites cleanly each time.
 
 ## Fork an existing agent
 
-Agent kits (`kind: agent`) define a full agent from scratch. The most
+Sandbox kits (`kind: sandbox`) define a full agent from scratch. The most
 common variant is a fork of a built-in agent — same image and
 credentials, but a different entrypoint. This example reproduces the
 built-in `claude` agent but drops `--dangerously-skip-permissions` so
 every tool call prompts for approval:
 
 ```yaml {title="claude-safe/spec.yaml"}
 schemaVersion: "1"
-kind: agent
+kind: sandbox
 name: claude-safe
 displayName: Claude Code (with approval prompts)
 description: Claude Code without --dangerously-skip-permissions
 
-agent:
+sandbox:
   image: "docker/sandbox-templates:claude-code-docker"
   aiFilename: CLAUDE.md
-  persistence: persistent
   entrypoint:
     run: [claude]
 
@@ -297,7 +296,7 @@ Launch with the kit's `name:` as the agent argument to `sbx run`:
 $ sbx run claude-safe --kit ./claude-safe
 ```
 
-For a step-by-step walkthrough of building a new agent kit from
+For a step-by-step walkthrough of building a new sandbox kit from
 scratch, see [Build an agent](build-an-agent.md).
 
 ## More examples