diff --git a/apps/docs/content/docs/cli/cli-reference.mdx b/apps/docs/content/docs/cli/cli-reference.mdx
index a0619b5b1c7..233d76abc1f 100644
--- a/apps/docs/content/docs/cli/cli-reference.mdx
+++ b/apps/docs/content/docs/cli/cli-reference.mdx
@@ -489,6 +489,63 @@ superset workspaces delete ws_a ws_b ws_c
 
 ---
 
+### agents
+
+Agents are terminal-agent rows configured on a host (the same rows shown in
+Settings → Agents on that machine). Each row stores a `command`, `args`,
+prompt-transport mode, and environment used to launch the agent in a fresh
+terminal session inside a workspace.
+
+<Command
+	name="superset agents list"
+	options={[
+		{ flag: "--host <id>", description: "Target host machineId." },
+		{ flag: "--local", description: "Target this machine. Mutually exclusive with --host; exactly one is required." },
+	]}
+	output={`Array<{
+  id: string;
+  presetId: string;
+  label: string;
+  command: string;
+  args: string[];
+  promptTransport: "argv" | "stdin";
+  promptArgs: string[];
+  env: Record<string, string>;
+  order: number;
+}>`}
+	humanColumns={["LABEL", "PRESET", "COMMAND", "ID"]}
+	quiet="agent instance IDs"
+>
+List agents configured on a host. First call on a fresh host seeds the
+bundled defaults.
+
+```bash
+superset agents list --local
+superset agents list --host host_…
+```
+</Command>
+
+<Command
+	name="superset agents run"
+	options={[
+		{ flag: "--workspace <id>", required: true, description: "Workspace UUID to run the agent in." },
+		{ flag: "--agent <preset|uuid>", required: true, description: "Agent preset id (e.g. `claude`, `codex`) or HostAgentConfig instance UUID." },
+		{ flag: "--prompt <text>", required: true, description: "Prompt sent to the agent." },
+		{ flag: "--attachment-id <uuid>", description: "Host-scoped attachment UUID; pass repeatedly for multiple attachments." },
+	]}
+	output={`{ sessionId: string; label: string }`}
+>
+Launch an agent inside an existing workspace. Resolves the host that owns the
+workspace and starts the named preset (or HostAgentConfig instance) in a
+fresh terminal session on that host.
+
+```bash
+superset agents run --workspace ws_… --agent claude --prompt "Audit the login flow"
+```
+</Command>
+
+---
+
 ### tasks (alias: `t`)
 
 Tasks are units of work in your organization's task tracker.
diff --git a/apps/docs/content/docs/mcp.mdx b/apps/docs/content/docs/mcp.mdx
index 87c0b27c362..b597c49e6aa 100644
--- a/apps/docs/content/docs/mcp.mdx
+++ b/apps/docs/content/docs/mcp.mdx
@@ -244,6 +244,13 @@ API keys grant full access to your organization. Keep them secret and never comm
 | `workspaces_create` | Create a workspace on a host (branch-scoped git worktree) |
 | `workspaces_delete` | Delete a workspace by UUID; idempotent |
 
+### Agents
+
+| Tool | Description |
+|------|-------------|
+| `agents_list` | List agents configured on a host |
+| `agents_run` | Launch an agent inside an existing workspace |
+
 ### Automations
 
 | Tool | Description |
@@ -265,7 +272,6 @@ API keys grant full access to your organization. Keep them secret and never comm
 | Tool | Description |
 |------|-------------|
 | `projects_list` | List projects (checked-out repos) in the active organization |
-| `projects_create` | Register a project on a host: clone a Git URL or import an existing local repo |
 
 ### Hosts
 
diff --git a/apps/docs/content/docs/sdk/advanced.mdx b/apps/docs/content/docs/sdk/advanced.mdx
index 24983b34708..9230b960f0b 100644
--- a/apps/docs/content/docs/sdk/advanced.mdx
+++ b/apps/docs/content/docs/sdk/advanced.mdx
@@ -11,10 +11,6 @@ The SDK's individual methods are simple. The interesting part is what you compos
 
 ## Sentry webhook → agent on the bug
 
-<Callout type="info">
-**TODO** — the `agents: [{ prompt }]` shorthand below is the API we're aiming for. Today the SDK sends a minimal `agentConfig: { id: 'claude', kind: 'terminal' }`; the host service still needs full launch info (`command`, `promptCommand`, …) to actually start the agent. We'll bake in defaults for built-in presets in a follow-up. Until then you can pass a full `agentConfig` per agent — crib one from `(await client.automations.list())[0].agentConfig`.
-</Callout>
-
 When Sentry fires an alert, file a task and spawn an agent to investigate — all in two SDK calls. (In production, verify the Sentry signature header before trusting any payload — that part is omitted here for clarity.)
 
 ```ts title="sentry-webhook.ts"
diff --git a/apps/docs/content/docs/sdk/reference.mdx b/apps/docs/content/docs/sdk/reference.mdx
index b1aa82768b4..1055591e37a 100644
--- a/apps/docs/content/docs/sdk/reference.mdx
+++ b/apps/docs/content/docs/sdk/reference.mdx
@@ -119,9 +119,7 @@ Returns `Array<Workspace>`.
 
 Create a worktree on a specific host. Optionally spawn one or more agents inside it as soon as the worktree is ready. Goes through the relay tunnel — the host must be online.
 
-<Callout type="info">
-**TODO** — the `agents` shorthand is the surface we're aiming for. The SDK currently sends a minimal `agentConfig: { id: 'claude', kind: 'terminal' }`; the host service still needs full launch info (`command`, `promptCommand`, …) to actually start the agent. We'll bake in defaults for built-in presets in a follow-up. Until then, pass a full `agentConfig` (crib one from `(await client.automations.list())[0].agentConfig`).
-</Callout>
+Each entry in `agents` takes a preset id (e.g. `"claude"`) or a `HostAgentConfig` instance UUID — the host service resolves it against its configured rows and copies their stored `command`, `args`, and `env`. Use [`agents.list({ hostId })`](#agentslist-hostid-) to enumerate what's installed.
 
 ```ts
 const ws = await client.workspaces.create({
@@ -177,6 +175,42 @@ const online = hosts.filter((h) => h.online);
 
 ---
 
+## agents
+
+Terminal-agent rows configured on a specific host (the same rows shown in
+Settings → Agents on that machine). Reads route through the relay tunnel —
+the target host must be online.
+
+### `agents.list({ hostId })`
+
+List configured agents on a host in persisted display order. First call on a
+fresh host seeds the bundled defaults. Returns `Array<HostAgentConfig>` —
+each row carries `id`, `presetId`, `label`, `command`, `args`, `env`, and
+prompt-transport fields used to launch the agent.
+
+```ts
+const agents = await client.agents.list({ hostId: '<machineId>' });
+```
+
+### `agents.run({ workspaceId, agent, prompt, attachmentIds? }, { hostId? })`
+
+Launch an agent inside an existing workspace. By default looks up the host
+that owns the workspace via the cloud index; pass an explicit `hostId` to
+skip the lookup.
+
+`agent` accepts either a preset id (e.g. `"claude"`) or a `HostAgentConfig`
+instance UUID. Returns `{ sessionId, label }`.
+
+```ts
+const { sessionId } = await client.agents.run({
+  workspaceId: '<uuid>',
+  agent: 'claude',
+  prompt: 'Audit the login flow for race conditions.',
+});
+```
+
+---
+
 ## automations
 
 Recurring agent runs scheduled by RRULE. Requires a Pro subscription on the org for `create` / `update` / `delete`.
diff --git a/skills/superset/SKILL.md b/skills/superset/SKILL.md
index ba4a9c25935..f46ea9e514d 100644
--- a/skills/superset/SKILL.md
+++ b/skills/superset/SKILL.md
@@ -42,7 +42,6 @@ Provide exactly one of `--branch` or `--pr`. With `--pr`, the host runs `gh pr c
 ```bash
 superset agents list --host <id>                 # Configured agents on a host (LABEL, PRESET, COMMAND, ID)
 superset agents list --local                     # Same, for this machine
-superset agents list --local --presets           # Available presets you could add
 superset agents run --workspace <id> --agent claude --prompt "..."
 ```