diff --git a/docs/architecture.md b/docs/architecture.md
index d17fa1d2..bdd75414 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -504,7 +504,7 @@ independently, then returns the final content as the tool result.
 - **task_agent**: uses `self._task_tools` (`TASK_AGENT_TOOLS` + MCP tools)
 - **plan_agent**: uses `self._agent_tools` (`AGENT_TOOLS` + MCP tools). Writes output
   to `.plan-<ws_id>.md` — unique per `ChatSession` so concurrent workstreams
-  don't collide. On repeat invocations the prior `plan` tool call and its result
+  don't collide. On repeat invocations the prior `plan_agent` tool call and its result
   are forwarded from `self.messages` so the agent refines the existing plan rather
   than starting over. Planning instructions are injected as a developer message
   prepended to the agent's conversation.
diff --git a/docs/sdk.md b/docs/sdk.md
index 4306b967..0304cd05 100644
--- a/docs/sdk.md
+++ b/docs/sdk.md
@@ -71,9 +71,9 @@ Both `TurnstoneServer` (sync) and `AsyncTurnstoneServer` (async) expose:
 | | `dashboard()` | `DashboardResponse` |
 | | `create_workstream(*, name, model, auto_approve, skill, initial_message, attachments)` | `CreateWorkstreamResponse` |
 | | `close_workstream(ws_id)` | `StatusResponse` |
-| **Attachments** | `upload_attachment(ws_id, file, filename, mime_type)` | `UploadAttachmentResponse` |
+| **Attachments** | `upload_attachment(ws_id, filename, data, *, mime_type=...)` | `UploadAttachmentResponse` |
 | | `list_attachments(ws_id)` | `ListAttachmentsResponse` |
-| | `download_attachment(ws_id, attachment_id)` | `bytes` |
+| | `get_attachment_content(ws_id, attachment_id)` | `bytes` |
 | | `delete_attachment(ws_id, attachment_id)` | `StatusResponse` |
 | **Chat** | `send(message, ws_id)` | `SendResponse` |
 | | `approve(*, ws_id, approved, feedback, always)` | `StatusResponse` |
@@ -182,8 +182,8 @@ Upload files to a workstream and attach them to the next user turn:
 ```python
 # Upload separately, then send a message — attachments auto-attach
 with open("screenshot.png", "rb") as f:
-    att = client.upload_attachment(ws.ws_id, f.read(),
-                                   filename="screenshot.png",
+    att = client.upload_attachment(ws.ws_id, "screenshot.png",
+                                   f.read(),
                                    mime_type="image/png")
 client.send("What's wrong in this screenshot?", ws.ws_id)
 
diff --git a/docs/security.md b/docs/security.md
index 46311464..fa2c68c6 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -39,7 +39,7 @@ Claims:
 |-------|-------------|
 | `sub` | User ID |
 | `scopes` | Comma-separated scope list (`read,write,approve`) |
-| `src` | Token source (`password`, `api_token`, `oidc`, or a service origin like `console` / `cli`) |
+| `src` | Token source (`password`, `database`, `oidc`, or a service origin like `console`, `cli`, or `channel`) |
 | `iss` | Issuer — always `turnstone` |
 | `aud` | Audience — `turnstone-server` or `turnstone-console` |
 | `iat` | Issued-at timestamp |
diff --git a/docs/settings.md b/docs/settings.md
index 96376db0..501102dd 100644
--- a/docs/settings.md
+++ b/docs/settings.md
@@ -67,8 +67,8 @@ autonomous loops:
 
 | Setting | Purpose |
 |---------|---------|
-| `model.plan_model` | Alias used for `plan_agent` sub-sessions. Falls back to `[model].plan_model` in config.toml, then `[model].agent_model`, then the session's active model. |
-| `model.task_model` | Alias used for `task_agent` sub-sessions. Same fallback chain as `plan_model`. |
+| `model.plan_alias` | Alias used for `plan_agent` sub-sessions. Falls back to `[model].plan_model` in config.toml, then `[model].agent_model`, then the session's active model. |
+| `model.task_alias` | Alias used for `task_agent` sub-sessions. Same fallback chain as `plan_alias`. |
 | `model.plan_effort` | Reasoning effort for `plan_agent` (`none` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max`). Defaults to `high`. |
 | `model.task_effort` | Reasoning effort for `task_agent`. Empty string means "inherit from the session". |
 
@@ -95,7 +95,7 @@ initialization:
 
 | Section | Settings |
 |---------|----------|
-| `model` | default_alias, temperature, max_tokens, reasoning_effort, plan_model, task_model, plan_effort, task_effort |
+| `model` | default_alias, temperature, max_tokens, reasoning_effort, plan_alias, task_alias, plan_effort, task_effort |
 | `session` | instructions, retention_days, compact_max_tokens, auto_compact_pct |
 | `tools` | timeout, truncation, agent_max_turns, skip_permissions, search, search_threshold, search_max_results |
 | `server` | workstream_idle_timeout, max_workstreams |
diff --git a/docs/tools.md b/docs/tools.md
index 7808e663..a09bdb40 100644
--- a/docs/tools.md
+++ b/docs/tools.md
@@ -170,7 +170,7 @@ Every tool defines a `primary_key`. The mapping is:
 | `web_fetch`  | `url`       |
 | `web_search` | `query`     |
 | `task_agent` | `prompt`    |
-| `plan_agent` | `prompt`    |
+| `plan_agent` | `goal`      |
 | `memory`     | `name`      |
 | `recall`     | `query`     |
 | `notify`     | `message`   |
@@ -572,7 +572,7 @@ pre-configure skills at workstream creation.
 | `web_fetch`  | Info       | No           | Yes   | Yes        | `url`       |
 | `web_search` | Info       | No           | Yes   | Yes        | `query`     |
 | `task_agent` | Agent      | No           | No    | No         | `prompt`    |
-| `plan_agent` | Agent      | No           | No    | No         | `prompt`    |
+| `plan_agent` | Agent      | No           | No    | No         | `goal`      |
 | `memory`     | Memory     | Yes          | No    | No         | `name`      |
 | `recall`     | Memory     | Yes          | No    | No         | `query`     |
 | `notify`     | Notify     | Yes          | Yes   | Yes        | `message`   |