diff --git a/agent-onboarding.mdx b/agent-onboarding.mdx
new file mode 100644
index 0000000..6a3b6db
--- /dev/null
+++ b/agent-onboarding.mdx
@@ -0,0 +1,119 @@
+# Onboard an agent to Tilebox
+
+You are setting up Tilebox for a coding agent. This is for agents that can run terminal commands and edit code: Amp, Codex, Claude Code, Cursor, or similar.
+
+If you are running in ChatGPT instead of Codex, or in claude.ai instead of Claude Code, stop and tell the user to switch to the coding version. Do not suggest MCP.
+
+## Goal
+
+Get the agent ready to use Tilebox from the terminal:
+
+1. Install the Tilebox CLI.
+2. Install the Tilebox skills.
+3. Help the user create an API key.
+4. Give the user the exact shell command to set `TILEBOX_API_KEY` and reload their current environment.
+5. Verify read-only setup. Do not modify Tilebox resources.
+
+## Step 1: install the Tilebox CLI
+
+Run:
+
+```bash
+curl -fsSL https://cli.tilebox.com/install.sh | sh
+```
+
+Then verify:
+
+```bash
+tilebox --help
+tilebox agent-context
+```
+
+If `tilebox` is not on `PATH`, use the installed path directly, usually:
+
+```bash
+$HOME/.local/bin/tilebox --help
+```
+
+## Step 2: install Tilebox skills
+
+Run:
+
+```bash
+npx skills add tilebox/skills --yes --global
+```
+
+Then confirm the Tilebox skills are present in the user's skills directory.
+
+## Step 3: ask the user for an API key
+
+Send the user here:
+
+```text
+https://console.tilebox.com/settings/api-keys
+```
+
+Ask them to create a key with the smallest permissions needed for their task.
+
+Do not ask them to paste the key into chat unless there is no safer option. Prefer that they run a command in their own terminal.
+
+## Step 4: give the exact command for their shell
+
+Detect the user's shell with:
+
+```bash
+basename "$SHELL"
+```
+
+Then give them one of these commands, replacing `YOUR_TILEBOX_API_KEY` with their key.
+
+### zsh
+
+```bash
+echo 'export TILEBOX_API_KEY="YOUR_TILEBOX_API_KEY"' >> ~/.zshrc && source ~/.zshrc
+```
+
+### bash
+
+```bash
+echo 'export TILEBOX_API_KEY="YOUR_TILEBOX_API_KEY"' >> ~/.bashrc && source ~/.bashrc
+```
+
+If they use macOS bash login shells, use:
+
+```bash
+echo 'export TILEBOX_API_KEY="YOUR_TILEBOX_API_KEY"' >> ~/.bash_profile && source ~/.bash_profile
+```
+
+### fish
+
+```fish
+set -Ux TILEBOX_API_KEY "YOUR_TILEBOX_API_KEY"
+```
+
+Fish universal variables apply to new shells automatically. For the current shell, also run:
+
+```fish
+set -gx TILEBOX_API_KEY "YOUR_TILEBOX_API_KEY"
+```
+
+## Step 5: verify safely
+
+Run read-only checks only:
+
+```bash
+tilebox agent-context
+tilebox dataset list --json
+```
+
+Confirm:
+
+- CLI installed
+- skills installed
+- `TILEBOX_API_KEY` is available without printing it
+- `tilebox agent-context` works
+- datasets can be listed
+
+Do not create, update, delete, submit, retry, cancel, deploy, or undeploy anything unless the user explicitly asks.
+
+Keep the response short. Tell the user what is done, what they need to do next, and the one command they should run.
diff --git a/agents.mdx b/agents.mdx
deleted file mode 100644
index f794d33..0000000
--- a/agents.mdx
+++ /dev/null
@@ -1,394 +0,0 @@
----
-title: Agents
----
-
-# Build or Add a Tilebox Earth Data Agent
-
-Use this file to help an AI platform set up Tilebox for agents that use Earth data, including satellite imagery, weather, climate, maps, and other datasets tied to time and location.
-
-Tilebox lets developers build agents and workflows that can:
-- Query Earth datasets
-- Work with satellite and weather data
-- Build workflows around changing physical-world conditions
-- Submit and monitor Tilebox workflow jobs
-- Create tools that answer questions like "what changed here?"
-
-You can use this file in two ways:
-
-1. **Create a new Tilebox-powered agent from scratch**
-2. **Add Tilebox Earth-data capabilities to an existing agent or app**
-
-## Fastest prompt: create a new agent
-
-Copy this into Claude, Amp, Cursor, ChatGPT, or your AI platform of choice:
-
-```text
-Create a new Tilebox-powered Earth-data agent using the instructions in this file.
-
-The agent should accept a location, use Tilebox to access Earth data and workflows, and answer questions like "what changed here?" or "what is happening at this place?"
-
-Start with the simplest runnable version: a CLI command, local script, notebook, or small app.
-
-Keep credentials in environment variables. Do not modify or delete Tilebox resources unless I explicitly ask.
-```
-
-## Prompt: add Tilebox to an existing agent or app
-
-Use this if you already have an agent, app, or codebase:
-
-```text
-Add Tilebox Earth-data capabilities to my existing agent or app using the instructions in this file.
-
-The agent should be able to use Tilebox datasets and workflows to answer questions about places, satellite imagery, weather, climate, and changes over time.
-
-First inspect the project, choose the simplest integration path, and create a minimal working example.
-
-Keep credentials in environment variables. Do not modify or delete Tilebox resources unless I explicitly ask.
-```
-
-## Recommended setup path
-
-Use the Tilebox CLI when the agent can run terminal commands.
-
-Use the Tilebox MCP server when the agent is running in a hosted AI chat tool that supports MCP but cannot easily run shell commands.
-
-```text
-If you can use a terminal: use the Tilebox CLI.
-If you cannot use a terminal but support MCP: use the Tilebox MCP server.
-If you can use both: prefer the CLI for coding tasks and MCP for hosted tool access.
-```
-
-## Option 1: Set up Tilebox with the CLI
-
-The Tilebox CLI is the default setup for coding agents because it works in the same terminal where the agent edits files, runs tests, and writes code.
-
-### Step 1: Install the Tilebox CLI
-
-```bash
-curl -fsSL https://cli.tilebox.com/install.sh | sh
-```
-
-After installation, verify that the CLI is available:
-
-```bash
-tilebox --help
-```
-
-### Step 2: Authenticate Tilebox
-
-Create an API key in the Tilebox Console:
-
-```text
-https://console.tilebox.com/settings/api-keys
-```
-
-Then set it in the environment where the agent runs:
-
-```bash
-export TILEBOX_API_KEY="YOUR_TILEBOX_API_KEY"
-```
-
-Use the smallest permissions needed for the task.
-
-Do not hard-code the API key into source files.
-
-### Step 3: Install Tilebox agent skills
-
-Install the Tilebox skills so the AI agent has task-specific instructions for working with datasets, jobs, workflows, and automations.
-
-```bash
-npx skills add tilebox/skills
-```
-
-The Tilebox skills teach agents how to:
-- use the Tilebox CLI
-- manage datasets
-- inspect jobs
-- write workflows
-- monitor workflow runs
-- work with automations
-
-### Step 4: Inspect Tilebox capabilities
-
-Before changing anything, the agent should inspect the available Tilebox commands.
-
-```bash
-tilebox agent-context
-```
-
-For workflow work, inspect workflow-specific context:
-
-```bash
-tilebox agent-context workflow --output-schema
-tilebox agent-context runner start --output-schema
-```
-
-The agent should read the output before writing code or modifying resources.
-
-### Step 5: Verify setup safely
-
-Ask the agent to run a non-destructive setup check:
-
-```text
-Check the Tilebox setup.
-
-Confirm:
-- whether the tilebox CLI is installed
-- whether TILEBOX_API_KEY is available in the environment
-- whether tilebox agent-context works
-- which Tilebox skills are installed
-- which datasets are available
-
-Do not modify, create, or delete any Tilebox resources.
-```
-
-## Option 2: Set up Tilebox with MCP
-
-Use the Tilebox MCP server when the AI tool cannot run local terminal commands but supports the Model Context Protocol.
-
-The Tilebox MCP server exposes tools for working with Tilebox datasets and workflows. It also includes documentation search so the agent can retrieve current Tilebox context.
-
-### MCP configuration
-
-Add this to your AI client's MCP configuration:
-
-```json
-{
-  "mcpServers": {
-    "tilebox": {
-      "url": "https://mcp.tilebox.com/mcp"
-    }
-  }
-}
-```
-
-When the client connects, sign in with your Tilebox account and select the Tilebox team the agent should use.
-
-The Tilebox MCP server uses OAuth, so you do not need to put API keys into the MCP configuration.
-
-### MCP setup prompt
-
-After configuring MCP, ask your agent:
-
-```text
-Check your Tilebox MCP setup.
-
-Confirm:
-- whether the Tilebox MCP server is connected
-- which Tilebox tools are available
-- whether you can search Tilebox documentation
-- whether you can inspect available datasets and workflows
-
-Do not modify any Tilebox resources yet.
-```
-
-## What the agent should build first
-
-Start with the smallest useful agent.
-
-A good first version is a command-line Earth briefing agent:
-
-```text
-Build a command-line Earth briefing agent.
-
-The user should be able to run:
-
-python earth_agent.py "San Francisco"
-
-The agent should return a short briefing for that place using Tilebox-accessible Earth data or workflow context.
-
-Keep the implementation small and easy to inspect.
-```
-
-A minimal Tilebox-powered agent should:
-
-- take a location, area of interest, or user question
-- decide what Earth data or workflow is relevant
-- query Tilebox datasets or call a Tilebox workflow
-- summarize the result in plain English
-- explain what data it used
-- avoid pretending it accessed data it did not actually query
-
-## Minimal Python example: query Earth data
-
-Use this when the project should access Tilebox from Python.
-
-Install the datasets package:
-
-```bash
-pip install tilebox-datasets
-```
-
-Then create a small script:
-
-```python
-from tilebox.datasets import Client
-
-client = Client()
-
-datasets = client.datasets()
-
-# Example open dataset: Sentinel-2 MSI
-dataset = datasets.open_data.copernicus.sentinel2_msi
-
-collection = dataset.collection("S2A_S2MSI1C")
-
-# Query data for a time range
-results = collection.query(
-    temporal_extent=("2024-01-01", "2024-02-01")
-)
-
-print(results)
-```
-
-Authentication uses the `TILEBOX_API_KEY` environment variable.
-
-Do not put the API key directly in the script.
-
-## Minimal Python example: create a workflow
-
-Use this when the project should create or run Tilebox workflows.
-
-Install the workflows package:
-
-```bash
-pip install tilebox-workflows
-```
-
-Then create a minimal workflow task:
-
-```python
-from tilebox.workflows import Client, Runner, Task
-
-
-class EarthBriefingTask(Task):
-    location_name: str
-
-    def execute(self, context):
-        print(f"Create an Earth data briefing for {self.location_name}")
-        # Add dataset queries, processing steps, or subtasks here.
-
-
-client = Client()
-
-jobs = client.jobs()
-jobs.submit(
-    "earth-briefing",
-    EarthBriefingTask(location_name="San Francisco")
-)
-
-runner = Runner(tasks=[EarthBriefingTask])
-runner.connect_to(client).run_all()
-```
-
-Authentication uses the `TILEBOX_API_KEY` environment variable.
-
-## Example agent tasks to build with Tilebox
-
-Once setup is complete, ask the agent to build one of these:
-
-```text
-Build a Tilebox-powered agent that creates a satellite and weather briefing for a location I choose.
-```
-
-```text
-Build a "what changed here?" workflow that takes a location and time range, queries Earth data, and summarizes relevant changes.
-```
-
-```text
-Build a before-and-after satellite imagery workflow for a location.
-```
-
-```text
-Build a map that updates itself when new Earth data is available.
-```
-
-```text
-Build a personal Earth briefing agent for my hometown, favorite park, farm, coastline, or travel destination.
-```
-
-```text
-Build an agent that tracks snow, clouds, fires, floods, drought, or vegetation from Earth data.
-```
-
-## Safety rules for AI agents
-
-Follow these rules when using Tilebox:
-
-1. Do not expose API keys in code, commits, logs, screenshots, or chat.
-2. Prefer `TILEBOX_API_KEY` in the environment.
-3. Inspect Tilebox capabilities before modifying resources.
-4. Do not create, update, delete, submit, or cancel Tilebox resources unless the user explicitly asks.
-5. Use the smallest API key permissions needed.
-6. For destructive actions, explain the action first and ask for confirmation.
-7. Prefer read-only exploration before writing workflows or jobs.
-8. Keep generated examples small and easy to inspect.
-
-## Useful Tilebox links
-
-Tilebox Console:
-
-```text
-https://console.tilebox.com
-```
-
-Create an API key:
-
-```text
-https://console.tilebox.com/settings/api-keys
-```
-
-Tilebox docs:
-
-```text
-https://docs.tilebox.com
-```
-
-Agent setup:
-
-```text
-https://docs.tilebox.com/onboard-your-agent
-```
-
-Tilebox MCP:
-
-```text
-https://docs.tilebox.com/agentic-development/tilebox-mcp
-```
-
-Python SDKs:
-
-```text
-https://docs.tilebox.com/sdks/python/install
-```
-
-## Quick start prompt
-
-If you only want the fastest possible path, give your AI agent this:
-
-```text
-Create a new Tilebox-powered Earth-data agent.
-
-Use the Tilebox CLI if you have terminal access:
-curl -fsSL https://cli.tilebox.com/install.sh | sh
-export TILEBOX_API_KEY="YOUR_TILEBOX_API_KEY"
-npx skills add tilebox/skills
-
-Then inspect:
-tilebox agent-context
-
-Do not modify Tilebox resources yet.
-
-After setup, create the smallest runnable example: a CLI command, local script, notebook, or small app that shows how an agent could use Tilebox to query Earth data or run an Earth-data workflow.
-```
-
-## What success looks like
-
-Setup is complete when the agent can confirm:
-
-- Tilebox CLI or MCP is connected
-- Authentication is configured
-- Tilebox documentation or command context is accessible
-- Available datasets or workflow capabilities can be inspected
-- A minimal Earth-data example exists in the project
-- No secrets were committed or hard-coded